ae6382 extending matlab. ae6382 using matlab matlab can be used as a mathematical scripting language...

AE6382

Extending MATLAB

AE6382

Using MATLAB

• MATLAB can be used as a mathematical scripting language (.m files)

• Stand-alone MATLAB applications– MATLAB code can be converted to a stand-alone form

• requires a MATLAB Compiler toolbox license to compile• no license required for the stand-alone file

• Extending MATLAB– MATLAB can access shared libraries written in C/C++ and Fortran in

both Windows (DLL) and Unix/Linux

– MATLAB can access functions written in C/C++ and Fortran as MATLAB functions, the so-called MEX files

– MATLAB and Java have a very close relationship• MATLAB can use Java classes• MATLAB and Java can exchange data using Java classes

AE6382

Using MATLAB

• Accessing MATLAB from other programs– C/C++ and Fortran programs can access MATLAB

• Using the MATLAB Engine API (Windows and Unix/Linux)• Using COM functions in Windows

– As an extension of the Standalone Application, a C/C++/Fortran callable library that encapsulates a set of m-files can be built

– MATLAB and Excel can inter-operate (Excel can use MATLAB objects)

• Data Exchange applications– C/C++ and Fortran can read and write MAT-files - files that contain

native MATLAB data

– MATLAB is able to read and write data in a variety of other formats

AE6382

Why

• You can create a standalone application based on MATLAB that can be freely distributed – no license required to run it

• You have a complex application written in C/C++/Fortran that you would like to access from within MATLAB. Compile and link as a MATLAB function.

• You need to load a large data set into MATLAB. Use either the native text input functions of MATLAB or use MAT-Files. This will require C/C++ or Fortran programming. The COM interface can also be used when using Windows.

• You have an m-function that you would like to use in Excel. The MATLAB Excel Builder will create a COM object that can be used from Excel. This capability is similar to the MATLAB Compiler functionality.

AE6382

Why

• You would like to make use of some feature that MATLAB provides in a program that you currently have or are developing. The MATLAB Engine API can be used for this purpose. It allows the control of MATLAB from another process. This API is intended for C/C++ and Fortran programmers, however, the COM Automation interface can be used on Windows from a script. There are also add-on modules for Python and Perl that provide Engine access from those languages.

• You would like to combine MATLAB with a Java program• You would like to create a Java GUI with MATLAB

AE6382

External MATLAB

The MATLAB manual that describes the Compiler toolbox that enables the creation of standalone executables for use on other systems that do have have MATLAB installed.

AE6382

External MATLAB

• The MATLAB manual that describes the available external interfaces that are available in MATLAB.

• MAT-Files• Calling external libraries• Calling C/Fortran from MATLAB

– MEX files (C/C++/Fortran)

• Calling MATLAB from C/Fortran– Matlab Engine

• Calling Java from MATLAB• COM interfaces in MATLAB (Windows)• Web Services

AE6382

External MATLAB

The MATLAB manual that describes the interface designed for Excel. It turns M functions into COM objects that can be accessed from with Excel using VBA.

AE6382

External MATLAB

The MATLAB manual that describes the interface to Java. It converts MATLAB m-functions into Java classes that can be used from within a Java program.

AE6382

External MATLAB

The MATLAB manual that describes the API functions that can be used by C/C++ and Fortran programs to interact with MATLAB.

• MAT-File • MX Array Manipulation• MEX-Files• MATLAB Engine

AE6382

Standalone MATLAB Application

• Use MATLAB Compiler to generate a standalone application, library, or component

• Requires the Compiler toolbox be licensed and installed on your system

• Requires that an MCR (MATLAB Component Runtime) file be installed on the target system

• Applications created using the MATLAB compiler are versions specific and require the correct MCR file, it must match the MATLAB version used to create the application

AE6382

Using MATLAB Compiler

• Use the MATLAB compiler to include the user supplied m-files in the CTF file

• Create a wrapper C file and compile into an executable program• Terms

– CTF is the Component Technology File• this is an encrypted copy of your m-files and all dependencies (toolbox, …)• once created it cannot be modified• contains a copy of your preferences files

– MCR is the MATLAB Component Runtime• this is a complete set of MATLAB runtime libraries that enables the

application to run• supplied by MATLAB, usually ~200MB in size

– application executable• this is the compiled wrapper code generated by MATLAB• it contains the encryption keys that allow the CTF file to execute

AE6382

Setting Up MATLAB Compiler

• Before you can create your application the MATLAB compiler must be configured – only required once per installation

• Determine what C/C++ compilers exist on your system• Windows – supported compilers

– Lcc C is the built-in C compiler

– Microsoft Visual C/C++ (MSVC) Versions 6.0, 7.1, and 8.0

• Linux – supported compilers– gcc and g++

• Setup environment– mbuild –setup– for Windows execute from a cmd.exe window

– creates the options file that is used by the mcc command

AE6382


• mbuild on Linux R2007B[matlab2007b]$ bin/mbuild -setup

Options files control which compiler to use, the compiler and link command

options, and the runtime libraries to link against.

Using the 'mbuild -setup' command selects an options file that is

placed in ~/.matlab/R2007b and used by default for 'mbuild'. An options

file in the current working directory or specified on the command line

overrides the default options file in ~/.matlab/R2007b.

To override the default options file, use the 'mbuild -f' command

(see 'mbuild -help' for more information).

The options files available for mbuild are:

1: /usr/local/matlab2007b/bin/mbuildopts.sh :

Build and link with MATLAB C-API or MATLAB Compiler-generated library via the system ANSI C/C++ compiler

0: Exit with no changes

/usr/local/matlab2007b/bin/mbuildopts.sh is being copied to

/home/latham/.matlab/R2007b/mbuildopts.sh

[matlab2007b]$

AE6382


• mbuild on Windows R2007A

AE6382

Creating the MCR

• Windows R2007A

AE6382

Creating the MCR

• For MATLAB R2007A and before the buildmcr process is required• Beginning with MATLAB R2007B the toolbox/deploy/<arch> directory

will contain the appropriate MCRInstaller file for that system architecture– Windows – MCRInstaller.exe

– Linux – MCRInstaller.bin

AE6382

Deploying the Application

• Deploying your standalone MATLAB application consists of copying the CTF file, the MCR file, and the application executable to the target system– The target must be the same architecture of the system that built the

application• win32 – 32-bit Windows• glnx86 – 32-bit Linux• glnxa64 – 64-bit Linux• sol2 – Solaris• mac – OS/X

– Installation of the MCR is not required if that version of MATLAB is already installed on the target system

– Having MATLAB and/or multiple MCR files requires care to ensure the right libraries are loaded (see Compiler manual for all details)

AE6382

MATLAB Application Example

• There are two examples following– They are compiled m-files that perform a matrix multiplication

– They are both compiled for Linux

– One is R2007B the other is R2006A

• Starting with R2007B the compile process has been altered slightly– Rather than creating an MCRInstaller.zip file the installation includes

• MCRInstaller.exe for Windows• MCRInstaller.bin for Linux

– The buildmcr is deprecated

• R2007A still includes buildmcr but it appears that the installer files are present in the installation

• Performing this process in Windows is similar• Graphics are allowed

AE6382


• Example performed on Linux R2007B[app1]$ ls

app1.m

[app1]$ cat app1.m

a=rand(1000,1000);

b=rand(1000,1000);

tic

for i=1:1000

for j=1:1000

c(i,j)=0.;

for k=1:1000

c(i,j)=c(i,j)+a(i,k)*b(k,j);

end

end

end

toc

tic

a*b;

toc

[app1]$

AE6382


• Example performed on Linux R2007B• Use the MATLAB Compiler (mcc) to create an application for the

app1.m script

• The ls shows that mcc created several files

[app1]$ mcc -m app1.m

sh: ifconfig: command not found

[app1]$ ls

app1 app1_main.c mccExcludedFiles.log

app1.ctf app1_mcc_component_data.c readme.txt

app1.m app1.prj run_app1.sh

[app1]$

AE6382


• Example performed on Linux R2007B• Copy the created files to the target system

– use tar to create an archive

– send tar file to remote system

– un-tar archive at target system

ON BUILD SYSTEM:

[app1]$ tar cf app1.tar .

tar: ./app1.tar: file is the archive; not dumped

[app1]$ tar tf app1.tar

./

./readme.txt

./app1.prj

./run_app1.sh

./app1.ctf

…

./mccExcludedFiles.log

./app1_main.c

./app1

[app1]$

ON TARGET SYSTEM:

[app1]$ tar xf app1.tar .

[app1]$

AE6382


• Example performed on Linux R2007B• If the local system already has the version of MATLAB installed

– this is the case for the build system

– to test the program

– no need to install the MCR files

– use files at /usr/local/matlab2007b

AE6382


• Example performed on Linux R2007B• Installing the MCR

– not required on build system

– not required on target if same version already installed

• Within a shell window, find the MCRInstaller.bin in the MATLAB installation directory

– /usr/local/matlab2007b/toolbox/compiler/deploy/glnxa64/MCRInstaller.bin– The underlined portion is determined by where the MATLAB distribution has been

installed– The glnxa64 is the architecture, 64-bit Linux– Copy to the target system

• Execute the installer program

[app1]$ ./MCRInstaller.bin

AE6382


• Example performed on Linux R2007B

• Installing the MCR• This requires write access to

the /opt directory in this case• The location can be moved but

the run scripts will need to be altered

AE6382


• Example performed on Linux R2007B

• Installing the MCR

AE6382


• Example performed on Linux R2007B• Installing the MCR• The MCR files were installed into

/opt/matlab/MATLAB_Component_Runtime/v77 (the default)• This requires 469MB of disk in this case

AE6382


• Example performed on Linux R2007B• Test on build system or target where appropriate MATLAB is already

installed• Using run_app1.sh to execute the application

– This script takes care of all library path settings

[app1]$ ./run_app1.sh /usr/local/matlab2007b

------------------------------------------

Setting up environment variables

---

Found MCR Java JRE version: 1.6.0

LD_LIBRARY_PATH is .:/usr/local/matlab2007b/runtime/glnxa64:/usr/local/matlab2007b/bin/glnxa64:/usr/local/matlab2007b/sys/os/glnxa64:/usr/local/matlab2007b/sys/java/jre/glnxa64/jre1.6.0/lib/amd64/native_threads:/usr/local/matlab2007b/sys/java/jre/glnxa64/jre1.6.0/lib/amd64/server:/usr/local/matlab2007b/sys/java/jre/glnxa64/jre1.6.0/lib/amd64/client:/usr/local/matlab2007b/sys/java/jre/glnxa64/jre1.6.0/lib/amd64

Elapsed time is 27.425378 seconds.


[app1]$

AE6382


• Example performed on Linux R2007B• On target system with MCR runtime files• Using run_app1.sh to execute the application

– This script takes care of all library path settings[app1]$ ./run_app1.sh /opt/MATLAB/MATLAB_Component_Runtime/v77

------------------------------------------

Setting up environment variables

---

Found MCR Java JRE version: 1.6.0

LD_LIBRARY_PATH is .:/opt/MATLAB/MATLAB_Component_Runtime/v77/runtime/glnxa64:/opt/MATLAB/MATLAB_Component_Runtime/v77/bin/glnxa64:/opt/MATLAB/MATLAB_Component_Runtime/v77/sys/os/glnxa64:/opt/MATLAB/MATLAB_Component_Runtime/v77/sys/java/jre/glnxa64/jre1.6.0/lib/amd64/native_threads:/opt/MATLAB/MATLAB_Component_Runtime/v77/sys/java/jre/glnxa64/jre1.6.0/lib/amd64/server:/opt/MATLAB/MATLAB_Component_Runtime/v77/sys/java/jre/glnxa64/jre1.6.0/lib/amd64/client:/opt/MATLAB/MATLAB_Component_Runtime/v77/sys/java/jre/glnxa64/jre1.6.0/lib/amd64

Extracting CTF archive. This may take a few seconds, depending on the

size of your application. Please wait...

...CTF archive extraction complete.



[app1]$

AE6382


• The following slides demonstrate the same procedure under earlier versions of MATLAB

• This example was also performed on Linux using MATLAB R2006A

AE6382


• MATLAB R2006A Linux• Compile into a standalone version

1. cd /home/latham/matlab/app1

2. mcc –m m2.m

This results in the following files being created in this directory• m2 (this is the executable program)• m2_main.c• m2_mcc_component_data.c• m2.ctf (the component technology file)• mccExcludedFiles.log

The two files displayed in bold text are the important files

AE6382


• MATLAB R2006A Linux• Test the executable just created

– Find where MATLAB is installed on the system. In this case MATLAB is installed in /usr/local/matlab_2006a

– Now setup the library path

export LD_LIBRARY_PATH=/usr/local/matlab_2006a/sys/os/glnx86:/usr/local/matlab_2006a/bin/glnx86

• The m2 executable can now be run

./m2

AE6382


• MATLAB R2006A Linux• Once the program is working it can be exported to another

computer. – The target system must have the same architecture

– The same OS (compatible version in case of Linux)

– The correct version of the MCR

• Copy the generated files to the remote system– scp m2 user@target:matlab/– scp m2.ctf user@target:matlab/– Note that the matlab directory already exists on the target system

AE6382


• MATLAB R2006A Linux• Setting up the target system requires that the MATLAB runtime

library be available– the correct version of MATLAB is already installed on the target

– the MCRInstaller files are installed

• Older versions of MATLAB require that the MCRInstaller.zip file be created on the system where the application is compiled– use buildmcr command to create file

• Copy this file to the target

AE6382


• MATLAB R2006A Linux• On the target system and unpack the file.

– cd /home/latham/matlab– unzip MCRInstaller.zip

• This will create a directory tree for the version of MATLAB used. In this case the directory is named v74.

• To execute the m2 program on this remote system setup the library paths with– export LD_LIBRARY_PATH=/home/latham/matlab/v74/sys/os/glnx86:/home/latham/matlab/v74/runtime/glnx86

• Now execute• ./m2

AE6382

MATLAB Excel Component

AE6382

MATLAB Excel Component

• MATLAB compiler can be used to create components for use in Excel

• As for the Standalone application– the MCR runtime files are required on the target system

– the m-files are encased in the CTF file

– a VBA (Visual Basic for Applications) wrapper is created that provides access

– a DLL (Windows shared library) is created that contains the compiled component code

• The component is made available to Excel using the Microsoft Component Object Model (COM)

• The component is accessible through Excel macros• No example currently available

AE6382

MATLAB Excel Interaction

• The Windows version of MATLAB also has access to other COM components installed on a Windows system

• Using the Automation capability of COM– an instance of Excel can be created by a MATLAB m-file

– cells, worksheets, etc can be manipulated by the MATLAB script

• Requires knowledge of the Excel object model– This information can be found in the Office CD and at

http://msdn.microsoft.com

– also some documents also at http://www.ae.gatech.edu/classes/ae6382/documents/MS_scripting/

• For code and output see– http://www.ae.gatech.edu/classes/ae6382/samples/matlab/excel-1/

http://msdn.microsoft.com/

http://www.ae.gatech.edu/classes/ae6382/documents/MS_scripting/

http://www.ae.gatech.edu/classes/ae6382/samples/matlab/excel-1/

AE6382

MATLAB Excel Interaction% Create a COM server running Microsoft Excel

e = actxserver ('Excel.Application')

% e =

% COM.excel.application

% Make the Excel frame window visible

e.Visible = 1;

% Use the get method on the Excel object "e"

% to list all properties of the application:

e.get

% ans =

% Application: [1x1Interface.Microsoft_Excel_9.0_

%Object_Library._Application]

% Creator: 'xlCreatorCode'

% Workbooks: [1x1 Interface.Microsoft_Excel_9.0_

%Object_Library.Workbooks]

% Caption: 'Microsoft Excel - Book1'

% CellDragAndDrop: 0

% ClipboardFormats: {3x1 cell}

% Cursor: 'xlNorthwestArrow'

% .

% .

% Create an interface "eWorkBooks"

eWorkbooks = e.Workbooks

% eWorkbooks =

% Interface.Microsoft_Excel_9.0_Object_Library.Workbooks

% List all methods for that interface

eWorkbooks.invoke

% ans =

% Add: 'handle Add(handle, [Optional]Variant)'

% Close: 'void Close(handle)'

% Item: 'handle Item(handle, Variant)'

% Open: 'handle Open(handle, string, [Optional]Variant)'

% OpenText: 'void OpenText(handle, string, [Optional]Variant)'

% Add a new workbook "w",

% also creating a new interface

w = eWorkbooks.Add

% w =

% Interface.Microsoft_Excel_9.0_Object_Library._Workbook

% Close Excel and delete the object

e.Quit;

e.delete;

AE6382

MATLAB Excel Interaction

• The Windows version of MATLAB also has access to other COM components installed on a Windows system

• Using the Automation capability of COM– an instance of Excel can be created by a MATLAB m-file

– cells, worksheets, etc can be manipulated by the MATLAB script

• Requires knowledge of the Excel object model– This information can be found in the Office CD and at

http://msdn.microsoft.com

– also some documents also at http://www.ae.gatech.edu/classes/ae6382/documents/MS_scripting/

• For code and output see– http://www.ae.gatech.edu/classes/ae6382/samples/matlab/excel-1/

http://msdn.microsoft.com/

http://www.ae.gatech.edu/classes/ae6382/documents/MS_scripting/

http://www.ae.gatech.edu/classes/ae6382/samples/matlab/excel-1/

AE6382

MATLAB Builder for Java

AE6382

MATLAB Builder for Java

• The MATLAB Builder for Java is an extension of the MATLAB Compiler that will wrap m-files as Java classes

• The wrapped classes can then be used (without a MATLAB license) by any Java program

• Requires the MCR files on the system where the classes will be used

AE6382

MATLAB Java Interaction

• Java and MATLAB are tightly bound together – rich environment• There is a Java Runtime Environment (JRE) included as part of the

MATLAB installation– need to be aware of what version of Java MATLAB is using

• version -java

• MATLAB can use Java classes• MATLAB can call Java methods internally• A simple example of what can be done

– accessing the Java Swing classes to create a GUI with MATLAB

– works in all architecturesimport javax.swing.*

J=JFrame(‘Hi there’)

L=JLabel(‘A Label’);

P=J.getContentPane

P.add(L)

J.setSize(200,200);

J.setVisible(1)

AE6382

Add External Function to MATLAB

AE6382

Add External Function to MATLAB

The MEX-Files capability is used to create a custom C/C++ or Fortran coded function that can be used in MATLAB.

The process can be tedious. It requires creating a gateway function,

void mexFunction(int nlhs, mxArray *plhs[], int nrhs, const mxArray *prhs[])

that is called by MATLAB. This function is passed two variables that indicate the number of input and output arrays. In addition, two other C arrays are passed that contain pointers to the mxArray’s in the case input. These pointers are used to access the data provided to the function by the MATLAB call. The output array contains mxArray pointers for the results. The result arrays are allocated by the C program using the MATLAB API and their addresses passed back to MATLAB. The mxArray type defines an array in MATLAB, it include size, type (numeric, cell, …) and location.

ae6382 extending matlab. ae6382 using matlab matlab can be used as a mathematical scripting language...

Documents

matlab slide

matlab functions

native matlab data matlab

matlab manual

unixlinux matlab

control of matlab

ae6382 external matlab

java classes matlab