Interface with Matlab/Scilab

Scilab is a scientific software for numerical computations. Developed since 1990 by researchers from INRIA and ENPC, it is now maintained and developed by Scilab Consortium since its creation in May 2003. Scilab includes hundreds of mathematical functions with the possibility to add interactively programs from various languages (C, Fortran...). It has sophisticated data structures (including lists, polynomials, rational functions, linear systems...), an interpreter and a high level programming language. Scilab works on most Unix systems (including GNU/Linux) and Windows (9X/2000/XP).

Matlab is a numerical computing environment and programming language. Created by The MathWorks, Matlab allows easy matrix manipulation, plotting of functions and data, implementation of algorithms, creation of user interfaces, and interfacing with programs in other languages. Although it specializes in numerical computing, an optional toolbox interfaces with the Maple symbolic engine, allowing it to be part of a full computer algebra system. As of 2004, MATLAB was used by more than one million people in industry and academia.

The goal of the ProActive Interface is to equip Scilab and Matlab with a generic interface to Grid computing. This extension allows the deployment of Scilab/Matlab instances on several nodes of the grid (and to use these instances like computing engines) and submitting of Scilab/Matlab tasks over the grid. These engines are monitored by a central ProActive API. A natural condition is to deploy an application (based on this interface) strictly on hosts where the Scilab or Matlab software is installed.

The interface with Matlab and Scilab inside ProActive comes in three different ways:

This ProActive interface supports Scilab's release 4.1.2 and manipulates the following types: Double, String, Double Matrix, String Matrix, Complex, Complex Matrix.

First, scilab needs to be installed or compiled, the instructions are in the file PROACTIVE/examples/scilab/README :

                    ProActive GUI for Matlab/Scilab.

Before being able to use the extension and launch the GUI (scilab.sh or scilab.bat), please follow
 these installations steps.

---------------------------------------------  SCILAB
 --------------------------------------------------
For every machines that you will be using:

STEP 1:

You have 3 options for installing Scilab and make it work with ProActive, if you are in a 64 bits
 architecture only the first option will work :

1) BINARY installation from Scilab 4.1.2:
If you're machine is a 32 bit Linux or Windows, download Scilab 4.1.2 or above BINARY Version

Important : The Scilab Java interface doesn't work properly in 64 bits mode. But you can still use
 it on a 64 bits-architecture in 32 bits-mode.

  In order to do that use the 4.1.2 BINARY version or compile a source version on a similar 32 bit
 similar OS distribution.

2) SOURCE installation from Scilab 4.1.2:
If you want to compile the library from a source version :

  Download Scilab 4.1.2 SOURCE Version.

  make binaries of Scilab (procedure is explained  in SCILAB/Readme_Linux or SCILAB/Readme_Windows)

  After the build, make sure that you find libjavasci.so or javasci.dll in the SCILAB/bin directory

3) SOURCE installation from Scilab 4.1 or Scilab 4.1.1:
If you can't have access to Scilab 4.1.2 or want to use an earlier version, download Scilab SOURCE
 version 4.1 or 4.1.1 (lower versions are not supported)

copy javasci_Scilab2.h and javasci_Scilab2.c from folder c_sources to SCILAB/routines/Javasci/

make binaries of Scilab (procedure is explained  in SCILAB/Readme_Linux or SCILAB/Readme_Windows)

After the build, make sure that you find libjavasci.so or javasci.dll in the SCILAB/bin directory

STEP 2:
After you install Scilab, you need to install it into your PATH.

In Windows systems, this will be done automatically by the Scilab installer.

Under linux, wou will have to run the following command on the Scilab directory after STEP 1:

> make install

---------------------------------------------- MATLAB
 ---------------------------------------------------
For every machines that you will be using:

STEP 1: If you plan to use Matlab, you must have Matlab installed and a valid licence.

STEP 2: IMPORTANT ! you need to compile and install Matlab Java Interface libraries, in order to do
 that, follow the guidelines in PROACTIVE/examples/matlab/README


--------------------------------------------- For Both
 ---------------------------------------------------
STEP 3:
Edit paths to your SCILAB installation in the scilab_env.sh or scilab_env.bat file

Comment out the following line if present in the SCILAB/scilab.star file (should be around line
 190):
show_startupinfo();

To comment out just insert "//" in the beginning of the line like in Java.

STEP 4:
If you use a source version of ProActive, compile ProActive by the following (PROACTIVE refers to
 the directory where you installed ProActive):
> cd PROACTIVE/scripts/[unix|windows]/scilab
> build.[sh|bat] compile

STEP 5:
Read documentation on http://proactive.inria.fr/scilab.htm on how to use the GUI

Edit paths inside the ProActiveScilab.xml descriptor if you want to use it to deploy on remote
 machines, if you want to deploy locally use the ProActiveScilabLocal.xml descriptor


STEP 6:
Run scilab.sh or scilab.bat.



ATTENTION :

If you want to use the extension without the script, remember that the environment variables of the
 JVM used to launch Scilab/Matlab engines must be set according to the scilab_env.[sh|bat] script




                

This ProActive interface supports many Matlab releases (from 7.1 on) and manipulates the following types: Double Matrixes, String Matrixes, Complex Matrixes, Integer Matrixes, Cells and Structs.

For Matlab use, Matlab's link to Java (from the ptolemy project ) needs to be compiled, the instructions for compiling it are described in the file PROACTIVE/dev/matlab/README :

                !---------------------------------------------!
!        Matlab interface to ProActive        !
!---------------------------------------------!

The Matlab interface to ProActive allows you to schedule Matlab scripts on a distributed
 environment using either:

1) The standalone Matlab/Scilab ProActive GUI
2) The ProActive scheduler

You need to compile a native library called Ptolemy that will link against the native libraries of
 your Matlab installation.

The scripts in this directory can be run on Linux or Cygwin(Windows)

In order to build the libraries, first set the MATLAB environment variable to the full path of your
 Matlab command.

Make sure that the "javac" command from a Java JDK (and not JRE) is accessible in the Path.

Under Cygwin you need to set the right Path and the MATLAB environment variable by System
 Properties > Advanced > Environment Variables (don't define them directly under Cygwin).

On the prompt run:

> configure
> make

This will copy the Ptolemy library to Proactive's "lib" directory. Please note that this library
 depends on two things:
1) The Matlab version
2) Your architecture (Linux, 32 or 64 bit, Windows, Sun Solaris, etc...)

Therefore:
1) If you want to connect ProActive to another Matlab version you'll need to provide a MATLAB
 variable that will point to this other version and re-launch the scripts.
2) If you want to connect ProActive to a Matlab installed on a different architecture, you'll need
 to re-launch the scripts on this architecture.

Please note that after you've run the scripts for each version/architecture you will be able to
 launch Matlab jobs that can run on heterogeneous systems.

            

For both Scilab and Matlab, a configuration step is required, this step is described in PROACTIVE/examples/scilab/README above.

To launch the application, you have to execute the script:

On Unix:

cd examples/scilab scilab.sh

On Windows:

cd examples\scilab scilab.bat

if you use a local version of Matlab or Scilab, you must declare the environment variables in the file:

examples/scilab/scilab_env.[sh|bat]

Once the application is started, the main frame is displayed. This frame is composed in three parts:

Figure 40.1. Main frame

The first step is to deploy the topology of the application. A dialog enables to choice the descriptor and to select the virtual node. The button deploy launches the deployment of Matlab/Scilab engines over the nodes.

Figure 40.2. Deployment of the application

The next step is the task launching. A dialog enables to select the script and possibly to define the script initialization, the return values, and the task priority. The button start creates and sends the task.

Figure 40.3. Creation of a task

The last step is the display of results. A double click on a task in the table of terminated tasks sets visible a dialog. This dialog displays the tasks properties and the result (with the possibility to save it in a file)

Figure 40.4. Display a result

In the main frame, several tables of tasks (pending, executing , terminated) allow to monitor the application. These tables allows to show just for each task the relevant informations. A double click on a task in these tables sets visible a dialog. This dialog displays the tasks properties (path, script initialization, results).

In the main frame, a tree describes all nodes used by the application. Over the execution of the application, if a task is aborted, the engine of this task may be unstable ( this one is displayed with a red foreground). A rigth-click on it show a popup menu to restart it.

Figure 40.5. State of Engines

The toolkit requires a connection to the ProActive Scheduler andResource Manager. In consequence the scheduler needs to be installed and running. Explanation on how to install and use the ProActive Scheduler and Resource Manager are detailed in the Scheduler documentation. When a parallel script is executed, the toolkit wraps the scripts inside a job definition and submits it to the running scheduler. Execution of the job can therefore be monitored using the Scheduler SWT client interface described. The scheduler will run Matlab engines in order to parallelize scripts. In consequence, these engines will need a Matlab licence (up to 4 engines running on the same computer will take only one licence though). Finally, the Scheduler will need to have acces to the native Java interface to Matlab in order to launch the Matlab engines. It's already compiled for a set of Matlab versions and architectures as shown in the following list (it's not compatible with Matlab versions prior to 7.1):

If your architecture/version is not in the list, you'll need to compile the interface as described in Section 40.2.2, “Installation for Matlab”. The compilation process will put the generated native library inside the ProActive library directory. You can then launch the Scheduler : it will have access to the native libraries you've compiled.

Once the Scheduler and Resource Mananger are running, here is the procedure to use the toolkit :

The interface architecture is based on the Master-Workers model. In this communication model, the master entity monitors the workers entities. In our case:

There are four classes which are intented for the user:

The Class MSService implements all functionalities to deploy engines, to distribute tasks, and to retrieve results (of computed tasks).

The Class GenTaskInfo contains all informations about a Matlab/Scilab task. Among these informations, there are:

The class SciTask describes a scilab task. It defines In and Out data, the job and the job initialization. A job is a scilab script (*.sce), it contains all instructions executed by a remote engine. In data and the job initialization allow to customize the execution and Out data define the values to return after the execution.

The class MatlabTask describes a matlab task. It defines similar data as the scilab task. A job is a scilab script (*.m).

The class GeneralResult describes a result of a Scilab or Matlab task. A result is the list of return values (defining in the task).

The following example Example 40.1, “Example: Interface Matlab/Scilab” presents how to compute a basic scilab task and to display the result. In our case the task initializes the variable "n" and increments it. The next example shows a possibly deployment descriptor Example 40.2, “Descriptor deployment” .

                    package org.objectweb.proactive.extensions.scilab.test;

import java.util.List;

import org.objectweb.proactive.extensions.scilab.AbstractData;
import org.objectweb.proactive.extensions.scilab.AbstractGeneralTask;
import org.objectweb.proactive.extensions.scilab.GeneralResult;
import org.objectweb.proactive.extensions.scilab.SciTask;
import org.objectweb.proactive.extensions.scilab.monitor.GenTaskInfo;
import org.objectweb.proactive.extensions.scilab.monitor.MSEvent;
import org.objectweb.proactive.extensions.scilab.monitor.MSEventListener;
import org.objectweb.proactive.extensions.scilab.monitor.MSService;


public class SciTest2 {
    private MSService scilab;

    public void displayResult(GenTaskInfo scitaskInfo) {
        GeneralResult sciResult = scitaskInfo.getResult();
        List<AbstractData> listResult = sciResult.getList();

        for (AbstractData data : listResult) {
            System.out.println(data);
        }

        scilab.exit();
        System.exit(0);
    }

    public SciTest2(String nameVN, String pathVN) throws Exception {
        scilab = new MSService();
        scilab.deployEngine(nameVN, pathVN, new String[] { "Scilab" });

        scilab.addEventListenerTask(new MSEventListener() {
            public void actionPerformed(MSEvent evt) {
                GenTaskInfo sciTaskInfo = (GenTaskInfo) evt.getSource();

                if (sciTaskInfo.getState() == GenTaskInfo.SUCCEEDED) {
                    displayResult(sciTaskInfo);
                    return;
                }
            }
        });

        AbstractGeneralTask task = new SciTask("id");
        task.setJobInit("n = 10;");
        task.addDataOut("n");
        task.setJob("n = n+1;");
        System.out.println("Job : " + task.getJob());
        scilab.sendTask(task);
    }

    public static void main(String[] args) throws Exception {
        if (args.length != 2) {
            System.out.println("Invalid number of parameter : " + args.length);
            return;
        }

        new SciTest2(args[0], args[1]);
    }
}

                

                    <?xml version="1.0" encoding="UTF-8"?>
<ProActiveDescriptor xmlns="urn:proactive:deployment:3.3"
    xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
    xsi:schemaLocation="urn:proactive:deployment:3.3
 http://www-sop.inria.fr/oasis/ProActive/schemas/deployment/3.3/deployment.xsd">
    <variables>
        <descriptorVariable name="REMOTE_HOME"
            value="/user/amangin/home" /><!--CHANGE ME!!!! -->
        <descriptorVariable name="PROACTIVE_HOME"
            value="${REMOTE_HOME}/ProActive" /><!--CHANGE ME!!!! -->
        <descriptorVariable name="JAVA_HOME"
            value="${REMOTE_HOME}/bin/jdk1.5.0" /><!-- Path of the remote JVM , CHANGE ME!!!!
 -->

        <descriptorVariable name="SCILAB_HOME"
            value="${REMOTE_HOME}/scilab/" /><!-- Path to Scilab on the remote machines , CHANGE
 ME!!!! -->
        <descriptorVariable name="MATLAB_DIR"
            value="/usr/local/matlab2006b" /><!-- Path to Matlab on the remote machines , CHANGE
 ME!!!! -->
        <descriptorVariable name="MATLAB" value="matlab2006b" /><!-- Name of the Matlab
 command on the remote machines , CHANGE ME!!!! -->
        <descriptorVariable name="LD_LIBRARY_PATH"
            value="${SCILAB_HOME}/bin:${MATLAB_DIR}/bin/glnx86:${MATLAB_DIR}/sys/os/glnx86" />
<!-- Path of the matlab and scilab libraries , CHANGE ME!!!! -->
    </variables>
    <componentDefinition>
        <virtualNodesDefinition>
            <virtualNode name="ScilabVN" property="multiple" />
        </virtualNodesDefinition>
    </componentDefinition>
    <deployment>
        <mapping>
            <map virtualNode="ScilabVN">
                <jvmSet>
                    <vmName value="Jvm0" />
                    <vmName value="Jvm1" />
                    <vmName value="Jvm2" />
                    <vmName value="Jvm3" />
                    <vmName value="Jvm4" />
                </jvmSet>
            </map>
        </mapping>
        <jvms>
            <jvm name="Jvm0">
                <creation>
                    <processReference refid="localJVM" />
                </creation>
            </jvm>
            <jvm name="Jvm1">
                <creation>
                    <processReference refid="rsh_predadab" />
                </creation>
            </jvm>
            <jvm name="Jvm2">
                <creation>
                    <processReference refid="rsh_trinidad" />
                </creation>
            </jvm>
            <jvm name="Jvm3">
                <creation>
                    <processReference refid="rsh_apple" />
                </creation>
            </jvm>
            <jvm name="Jvm4">
                <creation>
                    <processReference refid="localJVM" />
                </creation>
            </jvm>
        </jvms>
    </deployment>
    <infrastructure>
        <processes>
            <processDefinition id="localJVM">
                <jvmProcess
                    class="org.objectweb.proactive.core.process.JVMNodeProcess">
                    <classpath>
                        <absolutePath value="${PROACTIVE_HOME}/lib/*" />
                        <absolutePath
                            value="${PROACTIVE_HOME}/classes/Core" />
                        <absolutePath
                            value="${PROACTIVE_HOME}/classes/Extensions" />
                    </classpath>
                    <javaPath>
                        <absolutePath value="${JAVA_HOME}/bin/java" />
                    </javaPath>
                    <policyFile>
                        <absolutePath
                            value="${PROACTIVE_HOME}/dist/proactive.java.policy" />
                    </policyFile>
                    <log4jpropertiesFile>
                        <absolutePath
                            value="${PROACTIVE_HOME}/dist/proactive-log4j" />
                    </log4jpropertiesFile>
                </jvmProcess>
            </processDefinition>
            <processDefinition id="rsh_predadab">
                <rshProcess
                    class="org.objectweb.proactive.core.process.rsh.RSHProcess"
                    hostname="predadab">
                    <environment>
                        <variable name="SCIDIR" value="${SCILAB_HOME}" />
                        <variable name="SCI" value="${SCILAB_HOME}" />
                        <variable name="MATLAB" value="${MATLAB}" />
                        <variable name="LD_LIBRARY_PATH"
                            value="${LD_LIBRARY_PATH}" />
                    </environment>
                    <processReference refid="localJVM" />
                </rshProcess>
            </processDefinition>
            <processDefinition id="rsh_trinidad">
                <rshProcess
                    class="org.objectweb.proactive.core.process.rsh.RSHProcess"
                    hostname="trinidad">
                    <environment>
                        <variable name="SCIDIR" value="${SCILAB_HOME}" />
                        <variable name="SCI" value="${SCILAB_HOME}" />
                        <variable name="MATLAB" value="${MATLAB}" />
                        <variable name="LD_LIBRARY_PATH"
                            value="${LD_LIBRARY_PATH}" />
                    </environment>
                    <processReference refid="localJVM" />
                </rshProcess>
            </processDefinition>
            <processDefinition id="rsh_apple">
                <rshProcess
                    class="org.objectweb.proactive.core.process.rsh.RSHProcess"
                    hostname="apple">
                    <environment>
                        <variable name="SCIDIR" value="${SCILAB_HOME}" />
                        <variable name="SCI" value="${SCILAB_HOME}" />
                        <variable name="MATLAB" value="${MATLAB}" />
                        <variable name="LD_LIBRARY_PATH"
                            value="${LD_LIBRARY_PATH}" />
                    </environment>
                    <processReference refid="localJVM" />
                </rshProcess>
            </processDefinition>
        </processes>
    </infrastructure>
</ProActiveDescriptor>