Download
extending matlab n.
Skip this Video
Loading SlideShow in 5 Seconds..
Extending MATLAB PowerPoint Presentation
Download Presentation
Extending MATLAB

Extending MATLAB

457 Views Download Presentation
Download Presentation

Extending MATLAB

- - - - - - - - - - - - - - - - - - - - - - - - - - - E N D - - - - - - - - - - - - - - - - - - - - - - - - - - -
Presentation Transcript

  1. Extending MATLAB AE6382

  2. 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

  3. 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

  4. 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

  5. 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

  6. 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

  7. 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

  8. 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

  9. 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

  10. 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

  11. 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

  12. 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

  13. 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

  14. Setting Up MATLAB Compiler • 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

  15. Setting Up MATLAB Compiler • mbuild on Windows R2007A AE6382

  16. Creating the MCR • Windows R2007A AE6382

  17. 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

  18. 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

  19. 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

  20. MATLAB Application Example • 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

  21. MATLAB Application Example • 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

  22. MATLAB Application Example • 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

  23. MATLAB Application Example • 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

  24. MATLAB Application Example • 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

  25. MATLAB Application Example • 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

  26. MATLAB Application Example • Example performed on Linux R2007B • Installing the MCR AE6382

  27. MATLAB Application Example • 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

  28. MATLAB Application Example • 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. Elapsed time is 0.287423 seconds. [app1]$ AE6382

  29. MATLAB Application Example • 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. Elapsed time is 27.418982 seconds. Elapsed time is 0.281665 seconds. [app1]$ AE6382

  30. MATLAB Application Example • The following slides demonstrate the same procedure under earlier versions of MATLAB • This example was also performed on Linux using MATLAB R2006A AE6382

  31. MATLAB Application Example • MATLAB R2006A Linux • Compile into a standalone version • cd /home/latham/matlab/app1 • 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

  32. MATLAB Application Example • 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

  33. MATLAB Application Example • 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

  34. MATLAB Application Example • 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

  35. MATLAB Application Example • 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

  36. MATLAB Application Example • 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

  37. MATLAB Excel Component AE6382

  38. 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

  39. 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/ AE6382

  40. 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

  41. 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/ AE6382

  42. MATLAB Builder for Java AE6382

  43. 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

  44. 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 architectures import javax.swing.* J=JFrame(‘Hi there’) L=JLabel(‘A Label’); P=J.getContentPane P.add(L) J.setSize(200,200); J.setVisible(1) AE6382

  45. Add External Function to MATLAB AE6382

  46. 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