MATLAB script integration configuration guide

This article describes how to set up MATLAB script integration features with Lumerical products.

Notes

Lumerical does not 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.
Only the 64-bit version of MATLAB is supported.
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 2022a.

Lumerical to MATLAB script integration

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.

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 details below for configuration instructions for your operating system.

Windows

Step 1

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

Open the Matlab integration status window from the Help menu.
Use the Select button to manually locate the MATLAB system libraries.
Restart the Product for the change to take effect.

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 the desired version, e.g. if the MATLAB license of one version is not available.

Administrator access is required 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 
```
The ! operator in MATLAB just executes the remainder of the line at the command prompt, so this is equivalent to running a command below from the Windows command prompt as Administrator.
Where: <version> is the Matlab version number/folder installation on your computer.
```
"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 within MATLAB by running;
```
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 sends the plot command from the original MATLAB session to the new MATLAB session. You should see a simple plot window.

Linux

Notes

Starting with Lumerical 2024 R1, MATLAB Linux libraries are no longer packaged with the Lumerical Applications
MATLAB plugin still works and can be used for all existing MATLAB functionality
If using the MATLAB plugin on Linux, this can be manually configured using a start-up script for LD_LIBRARY_PATH. See step 3 below for details.

The following two configuration steps are often required to set up the MATLAB script integration on Linux. Occasionally, the third step will be required.

Step 1

The matlab command must be in the path, so if you type 'Matlab' at the terminal, the MATLAB application will start. 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.

$  sudo ln -s /usr/local/MATLAB/<version>/bin/matlab  /usr/bin/matlab

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.

Open the Matlab integration status window from the Help menu.
Use the Select button to manually locate the MATLAB system libraries.
Restart the Product for the change to take effect.

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.

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, Lumerical can be started with a command new shell file.

(shell file for FDTD)

$ sudo cat /opt/lumerical/[[verpath]]/bin/fdtd-matlab.sh 
##(Add the following lines into the file)
    #!/bin/bash
    export LD_LIBRARY_PATH=/opt/MATLAB/<version>/sys/os/glnxa64/
    /opt/lumerical/[[verpath]]/bin/fdtd-solutions-app $@
##(make the file executable)
$ sudo chmod +x /opt/lumerical/[[verpath]]/bin/fdtd-matlab.sh

(shell file for MODE)

$ sudo cat /opt/lumerical/[[verpath]]/bin/mode-matlab.sh 
##(Add the following lines into the file)
    #!/bin/bash
    export LD_LIBRARY_PATH=/opt/MATLAB/<version>/sys/os/glnxa64/
    /opt/lumerical/[[verpath]]/bin/mode-solutions-app $@
##(make the file executable)
$ sudo chmod +x /opt/lumerical/[[verpath]]/bin/mode-matlab.sh

(shell file for CHARGE / HEAT / FEEM & DGTD)

$ sudo cat /opt/lumerical/[[verpath]]/bin/device-matlab.sh
##(Add the following lines into the file)
    #!/bin/bash
    export LD_LIBRARY_PATH=/opt/MATLAB/<version>/sys/os/glnxa64/
    /opt/lumerical/[[verpath]]/bin/device-app $@
##(make the file executable)
$ sudo chmod +x /opt/lumerical/[[verpath]]/bin/device-matlab.sh

(shell file for INTERCONNECT)

$ sudo cat /opt/lumerical/[[verpath]]/bin/interconnect-matlab.sh 
##(Add the following lines into the file)
    #!/bin/bash
    export LD_LIBRARY_PATH=/opt/MATLAB/<version>/sys/os/glnxa64/
    /opt/lumerical/[[verpath]]/bin/interconnect-app $@ 
##(make the file executable)
$ sudo chmod +x /opt/lumerical/[[verpath]]/bin/interconnect-matlab.sh

Run Lumerical using the new shell file

 /opt/lumerical/[[verpath]]/bin/interconnect-matlab.sh &
 /opt/lumerical/[[verpath]]/bin/device-matlab.sh &
 /opt/lumerical/[[verpath]]/bin/mode-matlab.sh &
 /opt/lumerical/[[verpath]]/bin/fdtd-matlab.sh &

MATLAB to Lumerical API integration

The MATLAB API functions allow Lumerical applications and scripts to be called from MATLAB. The Lumerical install and Matlab API paths need to be added to your system and Matlab paths.

Notes

A more convenient way to add the Lumerical install path is in MATLAB's path is to add them to the MATLAB's 'startup.m' file, which runs automatically each time MATLAB starts or add Lumerical's product installation folder into your MATLAB's search path. See your MATLAB documentation for more information.

Windows

Include Lumerical installation in the system and MATLAB paths.

Add the Matlab install path and the Lumerical and Matlab API install paths to your system. See this post for details.
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\[[verpath]]\api\matlab')
```

Linux

Include Lumerical installation in the system path.

The Lumerical installation bin directory must be added to the system path.
This is done automatically as part of the product configuration script.
It is necessary to add each Lumerical product to the system path.
Change directory to your home directory

Append your .bash_profile with the Lumerical installation path (default install path shown)

$ cd ~ 
$ vi .bash_profile

# add the following at the end of you .bash_profile
PATH=$PATH:/opt/lumerical/[[verpath]]/bin
export PATH

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

Manually add this path to the MATLAB path,

path(path,'/opt/lumerical/[[verpath]]/api/matlab')Test API functions

In MATLAB run the following,

Confirm that the Lumerical installation directory is included in the system path as seen by MATLAB
```
!echo $PATH
```
Confirm that the Lumerical installation directory is included in the MATLAB path,
```
path
```
Use the MATLAB 'appopen' function to start Lumerical (e.g. FDTD),
```
appopen('fdtd')
```

Notes

Lumerical to MATLAB script integration

Check feature status

Windows

Step 1

Step 2

Linux

Notes

Step 1

Step 2

Step 3

(shell file for FDTD)

(shell file for CHARGE / HEAT / FEEM & DGTD)

(shell file for INTERCONNECT)

Run Lumerical using the new shell file

MATLAB to Lumerical API integration

Notes

Windows

Linux

In MATLAB run the following,

Associated files

Related articles