ESD Software Engineering

 

Matlab:  PEPII, NLC Development, SPEAR


Table of Contents

Production PEPII Matlab

Production SPEAR RF Matlab

Production NLCTA Matlab

Matlab Channel Access

Matlab Archiver Retrieval

TroubleShooting

Access to Matlab 6

Calling Java from Matlab

Production PEPII Matlab

The PEPII matlab source files are located in the directory /u1/pepii/ioc/matlab using the file extension ".m". All matlab data files are saved in MAT-file format in /u1/pepii/ioc/matlab with file extension ".mat".

Production SPEAR RF Matlab

SPEAR RF uses the SLAC shared Matlab maintained by Bob Boeninger. The Electronic Design web page has additional detail.

The SPEAR RF matlab scripts are located in the directory /afs/slac/g/spear3/llrf/matlab/script. The compiled matlab standalones are installed in /afs/slac/g/spear3/llrf/matlab/bin/solaris. The CVS reference area for all matlab files is /afs/slac/g/spear3/llrf/matlab.

Before using Matlab, environment variables must be set as follows:
source /afs/slac/g/spear/epics/epicsReset

Production NLCTA Matlab

The NLCTA RF matlab source files are located in the directory /afs/slac/g/cd/soft/ref/matlab/src/tarf using the file extension ".m". Currently matlab files are not saved for NLCTA on the gateway, but are instead generated on opi00gtw04 and saved in SCS NFS Toaster space before being moved to the NT disk V. The temporary matlab data files in MAT-file format are saved in /nfs/slac/g/nlcdev/tarf/acsensor/mat with the file extension ".mat".
NLCTA
Description Source Path Data Files
Generated
 Account  Host Contact
Acoustic Sensor /afs/slac/g/cd/soft/ref/matlab/src/tarf
Ac_brkdwn_creat.m
Ac_brkdwn_index.m
/nfs/slac/g/nlcdev/tarf/acsensor/
T53raf_<version>.mat
Index_<version_start>_<version_stop>.doc
Individual User Accounts  opi00gtw04 Frederic
Lepimpec

Matlab Channel Access

The Matlab Channel Access (MCA) facility allows access to Channel Access calls through Matlab and Matlab scripts. Information regarding this facility may be found in a presentation at the EPICS May 2002 Conference: MCA Presentation. Another source of information is a paper written by the original developer of Matlab Channel Access, Andrei Terebilo: Channel Access Client Toolbox for Matlab. The MCA facility is a Matlab extension; technical information regarding Matlab extensions (and Matlab itself) may be found at the web site Matlab Mathworks.

User Information

The MCA facility consists of a number of function calls that may be made through the Matlab API. Before using these calls, an EPICS setup file must be sourced either explicitly by the user or through the use of an account which performs this operation during the login process. More detail is found on the EPICS Setup Scripts web page.

After an EPICS setup file is sourced, the MCA matlab scripts in $EPICS_EXTENSIONS/matlab are available for use. Help information may be obtained by entering "help" followed by the function call of interest. Examples of MCA function calls may be found in the example matlab scripts in /afs/slac/g/cd/soft/ref/matlab/src/example.

Matlab Compiler User Documentation

The Matlab Compiler (User's Guide) may be used to compile Matlab scripts that use MCA functions into standalone executable programs. In this way scripts may compiled and executed without the use of a Matlab runtime license.

As an example, suppose the following Matlab script named mcatest.m is to be compiled:

    function mcatest
    pvName = 'myFavoritePVname';
    pvH = mcaopen( pvName );
    val = mcaget( pvH );
    disp( val );
    if val < 2,
    mcaput( pvH, 2 );
    else
    mcaput( pvH, 1 );
    end % if val < 2;
    val = mcaget( pvH );
    disp( val );
    mcaclose( pvH );
    return

As described in the User Information section above, it is assumed that an EPICS setup file has been sourced. The first step is to copy the files libMca.h and libMca.mlib (or provide symbolic links) to the current working directory where the Matlab script to be compiled is located:

    cp $EPICS_EXTENSIONS/lib/solaris/libMca.h .
    cp $EPICS_EXTENSIONS/lib/solaris/libMca.mlib .

The next step is to compile the Matlab script:

    /afs/slac/package/matlab/13/bin/mcc -nocache -v -f $EPICS_EXTENSIONS/config/mbuildopts.sh -m mcatest libMca.mlib
Warning messages resulting from this command may be ignored.

One of the output files generated from the above command is the standalone executable (e.g., mcatest). If the current working directory is in PATH, it may be invoked to perform the actions requested by the script:

    mcatest

System Administrator Documentation

The source files for the Matlab Channel Access subsystem are under CVS control on the development system and are located in

  1. $EPICS_EXTENSIONS/src/mca
  2. $EPICS_EXTENSIONS/src/mcalib
The source files include the Matlab ".m" files mca*.m, my_db_access.h, and mcamain.cpp in $EPICS_EXTENSIONS/src/mca. This directory also includes other files that were included in the distribution of MCA obtained from the Spallation Neutron Source (SNS) on 6/13/2002 (the latest SNS version of MCA at that time obtained from Carl Lionberger-- no version number provided). These other files are not used in the Solaris version of MCA used at SLAC.

Installation of MCA consists of compiling and linking using source file mcamain.cpp (which includes my_db_access.h), creating a Matlab extension Solaris shared object library (mcamain.mexsol). The first step in this process was the creation of the template options file mexopts.sh:

  1. matlab
  2. mex -setup
The generated file was then edited to specify EPICS include files and libraries needed for compilation and linking. The template file consists of various sections, each corresponding to one of the possible target operating systems. The area of the template mexopts.sh file modified was the section for the Solaris operating system ("sol2" in this file).

Two versions of mexopts.sh were produced for compilation and linking with EPICS versions 3.13.2 and 3.13.6: mexopts.sh_3.13.2 and mexopts.sh_3.13.6. The symbolic link mexopts.sh in the development system source files directory points to one of these files depending upon which version of EPICS is being used (this symbolic link is also specified in the file .cvsignore, located in this same directory).

The file mcamain.mexsol is generated as follows:

  1. cd $EPICS_EXTENSIONS/src/mca
  2. matlab
  3. mex mcamain.cpp
The Matlab mex facility looks first in the current working directory for the options file mexopts.sh. The shared object library file mcamain.mexsol must be regenerated after any changes to the source files my_db_access.h or mcamain.cpp.

Other than removing a control character found at the end of lines in the my_db_access.h and mcamain.cpp files, the only changes that were made to the sources obtained from the SNS distribution were the replacement of calls in mcamain.cpp to mxCreateScalarDouble, which is not supported under Matlab version 5.3.1. Since initial testing using Matlab version 5.3.1, Matlab version 6.1 has been installed and these modifications are no longer necessary.

The MCA facility works by invoking the mca*.m file corresponding to a called MCA function (e.g. mcaopen.m for MCA function mcaopen). The invoked mca*.m file calls a routine in mcamain.cpp (passing arguments) to perform most of its functionality. The mca*.m source files as well as the shared object library mcamain.mexsol must be located in directories found using the MATLABPATH path variable (set as a result of sourcing an EPICS setup file). Makefile and Makefile.Host have been added to the mca directory so that the mca*.m files are installed in $EPICS_EXTENSIONS/matlab when gmake is invoked. However, the mcamain.mexsol file must be manually copied to $EPICS_EXTENSIONS/lib/solaris. Both these directories are included in MATLABPATH.

To support the operation of the Matlab compiler, $EPICS_EXTENSIONS/src/mcalib is created to contain additional matlab scripts developed by Jim Sebek and Makefile and Makefile.Host files needed to build the MCA shareable object library (libMca.so) and related files. When gmake is invoked in this directory, the *.m files are installed in $EPICS_EXTENSIONS/matlab and libMca.* files are created and installed in $EPICS_EXTENSIONS/lib/solaris. The MBUILD options file used in the build resides in $EPICS_EXTENSIONS/config/mbuildopts.sh and is modified slightly to enforce the use of a newer Solaris compiler and add an additional library needed in the link. The libMca build log resides in $EPICS_EXTENSIONS/src/mcalib/O.solaris/libMca.log.

Further information regarding the Matlab compiler may be found from a document written by Jim Sebek on Nov. 19, 2002: MATLAB compiler notes for Solaris at SLAC.

After building mca and mcalib, $EPICS_EXTENSIONS/matlab and $EPICS_EXTENSIONS/lib/solaris must be updated in production (ie, opi00gtw00 for PEPII).

Matlab Archiver Retrieval

The Matlab Archiver Retrieval (MAR) facility allows retrieval of Channel Archiver data through Matlab and Matlab scripts. The MAR facility is a Matlab extension: technical information regarding Matlab extensions (and Matlab itself) may be found at the web site Matlab Mathworks.

User Information

The MAR facility consists of a number of function calls that may be made through the Matlab API. Before using these calls, an EPICS setup file must be sourced either explicitly by the user or through the use of an account which performs this operation during the login process. More detail is found on the EPICS Setup Scripts web page.

After an EPICS setup file is sourced, the MAR matlab scripts in $EPICS_EXTENSIONS/matlab are available for use. Help information may be obtained by entering "help" followed by the function call of interest.

The marsetsys, marsetstart, and marsetend functions should be called before retrieving data with a call to margetdata. The marsetsys function sets the system (nlcta, pepii, or pack) from which Channel Archiver data will be retrieved. The marsetstart function sets the retrieval start time and the marsetend function sets the retrieval end time. The margetsys, margetstart, and margetend functions may be called at any time to get the currently set system, retrieval start time, and retrieval end time. Once these items are set the function margetdata may be used to retrieve timestamps (seconds relative to the specified retrieval start time) and values for a specified PV name.

The following shows an example of call to each of these functions:

    marsetsys('nlcta');
    marsetstart('02/27/2003 10:00:00');
    marsetend('02/28/2003 10:00:00');
    asys = margetsys;
    astart = margetstart;
    aend = margetend;
    [timesecs_1, value_1] = margetdata('TA01:ASTS:VP9184');

Matlab Compiler User Documentation

The Matlab Compiler may be used to compile Matlab scripts that use MAR functions into standalone executable programs. In this way scripts may compiled and executed without the use of a Matlab runtime license.

As an example, suppose the following Matlab script named martest.m is to be compiled:

    function martest
    marsetsys('nlcta');
    marsetstart('03/24/2003 08:00:00');
    marsetend('03/24/2003 09:00:00');
    [a, b] = margetdata('TA01:ASTS:VP9122');
    fprintf(1, 'a = %g\n', a);
    fprintf(1, 'b = %g\n', b);
    return

As described in the User Information section above, it is assumed that an EPICS setup file has been sourced. The first step is to copy the files libMar.h and libMar.mlib (or provide symbolic links) to the current working directory where the Matlab script to be compiled is located:

    cp $EPICS_EXTENSIONS/lib/solaris/libMar.h .
    cp $EPICS_EXTENSIONS/lib/solaris/libMar.mlib .

The next step is to compile the Matlab script:

    /afs/slac/package/matlab/13/bin/mcc -nocache -v -f $EPICS_EXTENSIONS/config/mbuildopts.sh -m martest libMar.mlib
Warning messages resulting from this command may be ignored.

One of the output files generated from the above command is the standalone executable (e.g., test1). If the current working directory is in PATH, it may be invoked to perform the actions requested by the script:

    martest
System Administrator Documentation

The source files for the Matlab Archiver Retrieval subsystem are under CVS control on the development system and are located in

  1. $EPICS_EXTENSIONS/src/mar
The source files include the Matlab ".m" files mca*.m and marmain.cpp.

Installation of MCA consists of compiling and linking using source file marmain.cpp, creating a Matlab extension Solaris shared object library (marmain.mexsol). The first step in this process was the creation of the template options file mexopts.sh:

  1. matlab
  2. mex -setup
The generated file was then edited to specify EPICS include files and libraries needed for compilation and linking. The template file consists of various sections, each corresponding to one of the possible target operating systems. The area of the template mexopts.sh file modified was the section for the Solaris operating system ("sol2" in this file).

Two versions of mexopts.sh were produced for compilation and linking with EPICS versions 3.13.2 and 3.13.6: mexopts.sh_3.13.2 and mexopts.sh_3.13.6. The symbolic link mexopts.sh in the development system source files directory points to one of these files depending upon which version of EPICS is being used.

The file marmain.mexsol is generated as follows:

  1. cd $EPICS_EXTENSIONS/src/mar
  2. matlab
  3. mex marmain.cpp
The Matlab mex facility looks first in the current working directory for the options file mexopts.sh. The shared object library file marmain.mexsol must be regenerated after any changes to the source file marmain.cpp.

The MAR facility works by invoking the mar*.m file corresponding to a called MAR function (e.g. marsetsys.m for MAR function marsetsys). The invoked mar*.m file calls a routine in marmain.cpp (passing arguments) to perform most of its functionality. The mar*.m source files as well as the shared object library marmain.mexsol must be located in directories found using the MATLABPATH path variable (set as a result of sourcing an EPICS setup file). Makefile and Makefile.Host in the $EPICS_EXTENSIONS/src/mar directory installs mar*.m files in $EPICS_EXTENSIONS/matlab when gmake is invoked. However, the marmain.mexsol file must be manually copied to $EPICS_EXTENSIONS/lib/solaris. Both these directories are included in MATLABPATH.

To support the operation of the Matlab compiler, the Makefile.Host file in $EPICS_EXTENSIONS/src/mar also builds the MAR shareable object library (libMar.so) and related files. When gmake is invoked in this directory, the *.m files are installed in $EPICS_EXTENSIONS/matlab and libMar.* files are created and installed in $EPICS_EXTENSIONS/lib/solaris. The MBUILD options file used in the build resides in $EPICS_EXTENSIONS/config/mbuildopts.sh and is modified slightly to enforce the use of a newer Solaris compiler and add an additional library needed in the link. The libMar build log resides in $EPICS_EXTENSIONS/src/marlib/O.solaris/libMar.log.

Further information regarding the Matlab compiler may be found from a document written by Jim Sebek on Nov. 19, 2002: MATLAB compiler notes for Solaris at SLAC.

After building mar, $EPICS_EXTENSIONS/matlab and $EPICS_EXTENSIONS/lib/solaris must be updated in production (ie, opi00gtw00 for PEPII).

TroubleShooting

Runaway Matlab Process on a Unix Host
A know problem with exiting a matlab process is that the user license is not released and the process continues to run. Sometimes the process beings to use a large percentage of the available host cpu. To determine if you have a matlab process running after you have exited matlab, logon to the host where you started matlab and execute the following command:

luchini@slcs2 $ ps -ef  | grep -i "luchini"
 luchini  3504     1  0 15:51:48 pts/2    0:00 ttsession -s -d slcs2:11.0
 luchini 10584  2251  0 20:33:44 pts/3    0:00 more vxitest.c
 luchini 19504  2251  0 10:45:18 pts/3    0:00 grep -i luchini
 luchini  5315     1 41   Jan 25 ?       1054:21 /afs/slac.stanford.edu/package/matlab/531/bin/sol2/matlab
 luchini 17159 17123  0                    0:03 <defunct>
 luchini  3468  3467  0 15:50:37 pts/2    0:01 tcsh
 luchini  3911  3468  0 16:29:45 pts/2    0:00 more base.dbd
 luchini  2251  2248  0 14:20:58 pts/3    0:01 -tcsh
 luchini  3977  3954  0 16:30:30 pts/2    0:03 /bin/tcsh
 luchini  5356     1  0   Jan 25 ?        0:01 windu_registryd41 -d /u/cd/luchini -vers 2 -prog 805505755
 luchini  3954  3468  0 16:30:23 pts/2    0:00 /bin/tcsh
 luchini  5351  5315  0           &n bsp;       0:05 <defunct>
 luchini 20031     1  0   Jan 28 ?        0:01 caRepeater
 luchini  3467  2251  0 15:50:37 pts/3    0:11 xterm -font 9x15 -sb
 luchini 17123     1 40   Jan 28 ?       1013:26 /afs/slac.stanford.edu/package/matlab/531/bin/sol2/matlab

The above example checks that if users "luchini" has a matlab process running on the Unix host slcs2.  The green lines show that two matlab processes are running under the user account "luchini", with the process id 5315 and 17123.  To stop these two processes execute the following command:

luchini@slcs2 $ kill -9 5315
luchini@slcs2 $ kill -9  17123

Access to Matlab 6

The latest available Matlab version at SLAC is Matlab 6, release 12.1, which is available on public UNIX machines (such as flora).

One method of setting up the environment needed to run matlab is by sourcing one of the EPICS setup files. The command "matlab" may then be invoked to run Matlab. This method must be used for Matlab Channel Access.

Another method is to source the following file:

  1. source /afs/slac/package/ecad/custom/util/cae_aliases
After this command, the command "matlab121" may be invoked to run Matlab.

Either of the above methods may be used to bring up Matlab 6, release 12.1. There is no advantage to using one method over the other except that the first method (sourcing one of the EPICS setup files) must be used if one is using EPICS facilities, such as Matlab Channel Access.

Calling Java from Matlab

Every installation of Matlab includes a Java Virtual Machine (JVM), so that one can use the Java interpreter via Matlab commands. One may create and run programs that create and access Java objects.

To learn about this capability:

  1. Start Matlab
  2. Click on Help and then select MATLAB Help.
  3. Follow the path: MATLAB -> Using MATLAB -> External Interfaces/API -> Calling Java from MATLAB.

To find out which version of the JVM is being used by Matlab, type the following at the Matlab prompt:

  1. version -java
The default version of the JVM shipped with Matlab 6 is 1.1.8. In order to have Matlab use a newer version of the JVM the environment variable MATLAB_JAVA needs to be set to the path of this newer JVM version.

Usually a JVM is installed in one of two ways: (1) a Java Runtime Engine (JRE), or (2) a Java Development Kit (JDK), which consists of a runtime plus a development environment. The MATLAB_JAVA environment variable should only be set to the root of the JRE, which may be in a subdirectory of the JDK.

To discover the root of the JRE, first find the file name "rt.jar" in the Java installation directories. The MATLAB_JAVA variable may be set to the directory level up from the directory that contains "rt.jar." For example, if one wants Matlab to use Java 1.4 in the AFS area you will discover that the "rt.jar" file for this distribution is in /afs/slac/package/java/sun4x_58/jdk1.4/jre/lib. Therefore, the MATLAB_JAVA environment variable should be set as follows before running Matlab.

  1. setenv MATLAB_JAVA /afs/slac/package/java/sun4x_58/jdk1.4/jre
Running Matlab with a different version of the JVM than the default may consume additional X Window resources to the extent that Matlab will not run from less powerful PC systems. In this case, the alternative JVM version may still run if Matlab is brought up with the "-nodesktop" option.

ESD Software Engineering | SLAC Computing | SLAC Detailed Home
PEPII Controls | NLC Dev Control | SPEAR EPICS | EPICS at SLAC
Owner:  Bob Hall
Last modified:  Tuesday, Nov 4, 2003