# Knowledge Base

 Matlab Integration and API setup

This page describes how to set up the MATLAB integration features with Lumerical's photonic design software.

### Associated Files

environment.plist

## Matlab script integration (Lumerical to MATLAB)

The Matlab script integration feature allows MATLAB script functions to be called from within Lumerical's scripts via the matlab, matlabput and matlabget script functions.

### General Requirements

Lumerical is not able to guarantee that all versions of our products will be compatible with all MATLAB versions on all operating systems (the number of permutations is very large!), although we have found that it works for most customers.

32 and 64 bit applications can't be mixed.  For example, if you are using the 32-bit version of MATLAB, you must use the 32-bit version of Lumerical's products.
Please note that the student edition of MATLAB is only available as a 32-bit application.

Some releases of MATLAB include newer versions of system libraries than are provided by the operating system.  The new libraries are saved in a private location that only MATLAB can 'see'.  This creates problems for the Matlab script integration, since the Lumerical application will use the standard version of the system library while MATLAB will use its private version of the same library.  This creates a conflict, which stops the script integration from working.  See below for possible solutions.

The Matlab script integration feature requires MATLAB version 2006b to 2016a.

### Check feature status

To check the status of the MATLAB script integration feature, go to the Help menu and select Matlab integration status.  See the instructions below if the status is not active.

If you have problems enabling the Matlab script integration feature, please visit the Support Center for technical support.

### Windows

Step 1

Our software must be able to locate the MATLAB libraries.  If they are not in the system library path, you must manually specify their location.

1.Open the Matlab integration status window from the Help menu.

2.Use the select button to manually locate the MATLAB system libraries.

Step 2

MATLAB must be registered as an automation server on your system before the script integration feature will work. Registration normally occurs during the MATLAB install process, but occasionally the registration fails or is lost.  In such cases, manual registration is required. Manual registration may also be required when you have multiple versions of MATLAB installed and would like to register MATLAB for a desired version, eg, if the MATLAB license of one version is not available. Note, users may need administration access for these configurations. For more information, please refer to MATLAB documentation.

To register MATLAB, open a MATLAB session and type the following command:

!matlab /regserver

Note: the ! operator in MATLAB just executes the remainder of the line at the command prompt, so this is equivalent to running a command like the following from the Command prompt:

"C:\Program Files\MATLAB\<version>\bin\win64\matlab" /regserver

To test the registration, open Lumerical and use one of the Matlab script integration functions.  You can also test the registration from MATLAB (i.e. without using any Lumerical software) with the following commands:

h = actxserver('Matlab.Application')

h.Execute('plot(1:10)')

The first command starts a second background instance of MATLAB, very similar to the way our software starts a MATLAB session. The second command send the plot command from the original MATLAB session to the new MATLAB session. You should see a simple plot window.

As mentioned above, the MATLAB script integration status is sometimes reported incorrectly.  If the status utility reports 'inactive' after the above configuration, it is still possible that the integration script functions will work properly.  Try a command like the following:

matlab("plot(1:10)");

### Linux

The following two configuration steps are often required to setup the Matlab script integration on Linux operating systems. Occasionally, the third step will be required.

Step 1

The matlab command must be in the path, so if you type matlab at the command prompt the MATLAB application will start. This is suggested by the MATLAB installer, but doesn’t necessarily happen. To do this you can either add the folder where you installed MATLAB to your path, or you can create a symbolic link to the matlab command in another folder that is already in the path (the MATLAB installer suggests this).

Step 2

Your Lumerical Product must be able to locate the MATLAB libraries.  If they are not in the system library path, you must manually specify their location.

1.Open the Matlab integration status window from the Help menu.

2.Use the select button to manually locate the MATLAB system libraries.

Step 3

Some versions of MATLAB include newer versions of system libraries than the standard version provided by the OS.  The newer libraries are saved in a private location that only MATLAB can access.  This creates problems for the Matlab script integration, since your Lumerical Product will load the standard version of the system library, while MATLAB will load it's private version of the same library.  This creates a conflict, which stops the script integration from working.

The easiest way to avoid this is to roll back to an older version of MATLAB, such as MATLAB 2006-2008a.

Alternatively, you can try to configure your Lumerical Product to work with your current version of MATLAB. This requires configuring our software to use the newer system libraries provided by MATLAB, so both products load the same version of the libraries.  This can be setup by creating a simple shell file that configures the library paths.  Once this file is created, your Lumerical Product can be started with a command. For example:

cat /opt/lumerical/2019b/bin/fdtd-matlab

#!/bin/bash

export LD_LIBRARY_PATH=/opt/MATLAB/R2010b/sys/os/glnxa64/

/opt/lumerical/2019b/bin/fdtd-solutions $@ cat /opt/lumerical/2019b/bin/mode-matlab #!/bin/bash export LD_LIBRARY_PATH=/opt/MATLAB/R2010b/sys/os/glnxa64/ /opt/lumerical/2019b/bin/mode-solutions$@

cat /opt/lumerical/2019b/bin/device-matlab

#!/bin/bash

export LD_LIBRARY_PATH=/opt/MATLAB/R2010b/sys/os/glnxa64/

/opt/lumerical/2019b/bin/device $@ cat /opt/lumerical/2019b/bin/interconnect-matlab #!/bin/bash export LD_LIBRARY_PATH=/opt/MATLAB/R2010b/sys/os/glnxa64/ /opt/lumerical/2019b/bin/interconnect$@

As mentioned above, the MATLAB script integration status is sometimes reported incorrectly.  If the status utility reports 'inactive' after the above configuration, it is still possible that the integration script functions will work properly.  Try a command like the following:

matlab("plot(1:10)");

### MacOS

Step 1

Your Lumerical Product must be able to locate the MATLAB libraries.  If they are not in the system library path, you must manually specify their location.

1.Open the Matlab integration status window from the Help menu.

2.Use the select button to manually locate the MATLAB system libraries.

3.Restart your Lumerical Product for the change to take effect.

Step 2

It may be necessary to create the following symbolic link to the MATLAB executable.

sudo ln –s /Applications/MATLAB_2009b.app/bin/matlab /usr/bin/matlab

Note: The exact command will depend on your MATLAB version and install directory.  The above example command is appropriate for MATLAB 2009B installed in the default location.

As mentioned above, the MATLAB script integration status is sometimes reported incorrectly.  If the status utility reports 'inactive' after the above configuration, it is still possible that the integration script functions will work properly.  Try a command like the following:

matlab("plot(1:10)");

## Matlab API integration (MATLAB to Lumerical)

The Matlab API functions allow Lumerical applications and scripts to be called from MATLAB.

### Windows

Include Lumerical installation in MATLAB path

MATLAB must be configured to know the location of the Lumerical API functions.  The API functions are located in the \api\matlab subdirectory of the Lumerical product installation folder. To manually add this location to the MATLAB path, run the following commands in MATLAB:

path(path,'C:\Program Files\Lumerical\2019b\api\matlab');

A more convenient solution is to permanently add the path to MATLAB's startup.m file, which runs automatically each time MATLAB starts.

Test API functions properly

In MATLAB, run the following tests

1.Confirm that the Lumerical installation directory is included in the MATLAB path:

path

2.Use the MATLAB appopen function to start a Lumerical product (eg FDTD):

appopen('fdtd')

Note: For users with multiple Lumerical products, it is only necessary to provide the path for one product.

### Linux

Include Lumerical installation in system path

The Lumerical software installation bin directory must be added to the system path.  This is done automatically as part of the product configuration script.  For example, the FDTD config utility can be run with the following command.  Each Lumerical product installation folder will contain a similar configuration shell file. It is necessary to add each Lumerical product to the system path.

sh /opt/lumerical/2019b/bin/fdtd-config.sh

Include Lumerical installation in MATLAB path

MATLAB must be configured to know the location of the Lumerical API functions.  The API functions are located in the /api/matlab subdirectory of the Lumerical product installation folder. To manually add this location to the MATLAB path, use the following command:

path(path,'/opt/lumerical/2019b/api/matlab');

A more convenient solution is to permanently add the path to MATLAB's startup.m file, which runs automatically each time MATLAB starts.

Test API functions properly

In MATLAB, run the following tests

1.Confirm that the Lumerical installation directory is included in the system path seen my MATLAB:

!echo $PATH 2.Confirm that the Lumerical installation director is included in the MATLAB path: path 3.Use the MATLAB appopen function to start a Lumerical product (eg FDTD): appopen('fdtd') Note: For users with multiple Lumerical products, it is only necessary to provide the path for one product. ### MacOS Include Lumerical installation in system path NOTE: You may need to specify a different path depending on the version of MATLAB installed on your computer. The following example uses MATLAB version R2015a. 1.Open Terminal 2.Edit the info.plist file, located in the MATLAB Contents sub-directory, as described below: cd /Applications/MATLAB_R2015a.app/Contents sudo chmod +w Info.plist sudo vim Info.plist 3.Find the following section in the file: <key>LSEnvironment</key> <dict> <key>MATLAB_USE_USERWORK</key> <string>1</string> </dict> 4.Make the following modification, by adding the additional <key> and <string> lines: <key>LSEnvironment</key> <dict> <key>MATLAB_USE_USERWORK</key> <string>1</string> <key>PATH</key> <string>/usr/local/bin:/usr/bin:/bin:/usr/sbin:/sbin:/Applications/Lumerical\ 2019b.app/Contents/Applications/FDTD\ Solutions.app/Contents/MacOS:/Applications/Lumerical\ 2019b.app/Contents/Applications/MODE\ Solutions.app/Contents/MacOS:/Applications/Lumerical\ 2019b.app/Contents/Applications/DEVICE.app/Contents/MacOS:/Applications/Lumerical\ 2019b.app/Contents/Applications/INTERCONNECT.app/Contents/MacOS</string> </dict> 5.Execute the following line in Terminal: /System/Library/Frameworks/CoreServices.framework/Frameworks/LaunchServices.framework/Support/lsregister -v -f /Applications/MATLAB_R2015a.app 6.Close Terminal and open and launch Matlab from the LauchPad. If you open Matlab from Terminal, be sure to add Lumerical installation path to your shell. 1.Open Terminal 2.add the Lumerical installation to your current shell (i.e. adding the FDTD install path) export PATH=$PATH:/Applications/Lumerical\ 2019b.app/Contents/Applications/FDTD\ Solutions.app/Contents/MacOS

3.run Matlab from your current Terminal

/Applications/MATLAB<version>.app/bin/matlab

Include Lumerical installation in MATLAB path

Open the MATLAB application and add the Lumerical MATLAB API file locations to the MATLAB path with the following commands.

path(path,'C:\Program Files\Lumerical\2019b\api\matlab');

A more convenient solution is to add these commands to the MATLAB's startup.m file, which runs automatically each time MATLAB starts.  See the MATLAB documentation for more information on the startup.m file.

Test the API function

In MATLAB, run the following commands

1.Confirm that the Lumerical installation directory is included in the system path seen by MATLAB:

!echo \$PATH

2.Confirm that the Lumerical installation directory is included in the MATLAB path:

path

3.Use the MATLAB appopen function to start a Lumerical product:

appopen('fdtd')