MATLAB interface

To control EMode directly from a MATLAB script (version R2016b or higher), we supply a class file called emodeconnection.m that is automatically installed alongside EMode.

For more information about MATLAB, check out this link:

Setup

Windows

The standard installation for Windows automatically includes this step. This is only necessary for Windows users during a manual emodeconnection update or if MATLAB is installed after installing EMode.

Run the following in your MATLAB command window.

addpath(fullfile('C:', 'Program Files', 'EMode Photonix', 'EMode')); savepath;

MacOs and Linux

The setup for macOS and Linux platforms first requires downloading emodeconnection.m.

Next, run the following to add emodeconnection.m to the MATLAB path.

addpath(fullfile(getenv('HOME'), 'Downloads')); savepath;

EMode Login

Open MATLAB and run the following in the MATLAB command line. This will open the EMode Login GUI to login to your EMode Photonix account and view the active license subscriptions. Alternatively, you can run emode from the command line to launch the login GUI. Once logged in, click the exit button to close the GUI and save the login credentials.

emodeconnection.EModeLogin()

The EMode class

class emodeconnection(name, value)

Opens the EMode software and initializes a local simulation file. The user’s account must have an active license available to successfully run EMode. If the user has not previously logged in, initializing this class will prompt for the user credentials. To reset the user profile, see EMode Login.

An existing file can be opened for further analysis by specifying the input name-value pair 'open_existing', true. This opened file can be copied to a new file name by specifying the input name-value pair 'new_name', 'new_filename'.

By default, calling the close() method saves the simulation file as a MATLAB-style .mat file. Adding optional input parameters can override this behavior to either delete the simulation file or save it as a .eph file.

Note

All EMode functions are accessible as methods of this class instance using name-value pair input arguments for each funtion input parameter, in the format of (“name 1”, value_1, “name 2”, value_2, “name 3”, value_3, …).

Parameters:

  • simulation_name (str) – Name of the simulation file. The extension ‘.eph’ will be added to this name. Default: ‘emode’.

  • license_type (str) – The requested license type, either ‘2D’, ‘3D’, or ‘default’. When running with ‘default’ license type, a ‘3D’ license will be initialized if it is available, otherwise a ‘2D’ license will be initialized if it is available. The ‘2D’ or ‘3D’ options will only request that specific license type if it is available. Default: ‘default’.

  • save_path (str) – Name of the path where the simulation file will be created and saved. Default: ‘.’.

  • verbose (bool) – Whether to run EMode in verbose mode for debugging. Default: False.

  • roaming (bool) – Set the license manager to roaming mode. Normal mode (roaming = False) re-checks the license connection every 30 minutes, allowing licenses to reset after 30 minutes if the internet connection fails. Roaming mode (roaming = True) can be used to extend the license re-check to 3 days to support long simulations without continuously re-checking the license. Default: False.

  • open_existing (bool) – Whether to open an existing file or to start a new simulation. Default: False.

  • new_name (bool or str) – New name of opened existing file so the original file does not get modified. If False the original name is used. The extension ‘.eph’ will be added to this name. Default: False.

  • priority (str) – Set the CPU process priority. ‘pH’: High; ‘pAN’: Above normal; ‘pN’: Normal; ‘pBN’: Below normal; ‘pI’: Idle. Default: ‘pN’.

Functions

The emodeconnection package provides access to EMode Login GUI and to the EMode simulation files without using an active EMode license. This is helpful for analyzing simulation data without checking out an EMode license or for sharing the EMode simulation results with a collaborator who does not have an EMode license.

static EModeLogin()

Opens the EMode Login GUI to input your EMode Photonix account credentials and view active license subscriptions. Once logged in, click the exit button to close the GUI and save the login credentials.

static open_file(simulation_name)

Returns an EMode simulation file name with the extension “.mat” to be passed to the MATLAB load() function.

Parameters:

simulation_name (str) – Name of the simulation file. The “.mat” extension is optional to include with the name. Default: ‘emode’.

Returns:

Name of the specified EMode simulation file if it is available.

Return type:

char array

static get_(variable, simulation_name)

Returns the contents of a specified variable from an EMode simulation file with the extension “.mat”.

Parameters:

  • variable (str) – Name of the variable to return from EMode. Default: ‘emode’.

  • simulation_name (str) – Name of the simulation file. The “.mat” extension is optional to include with the name.

Returns:

Requested item from EMode.

Return type:

int, float, str, or array-like

static inspect_(simulation_name)

Get the names of all variables from EMode simulation file with the extension “.mat”.

Parameters:

simulation_name (str) – Name of the simulation file. The “.mat” extension is optional to include with the name. Default: ‘emode’.

Returns:

List of names of all variables available in the EMode simulation file. Any of these variables can be extracted to the user with the get_() function.

Return type:

list

Types

Two types that can be used for specifying material properties are available as struct attributes of the emodeconnection class.

MaterialProperties

A container for linear and non-linear electromagnetic material parameters. At least one of n or eps must be supplied in any valid instance.

Parameters:

  • n (Optional[float | list[float] | list[list[float]]]) – Scalar or tensor refractive index. Accepts None (unspecified), a float, a list of 3 floats (for x,y,z), or a 3 x 3 list of list of floats for an anisotropic material.

  • eps (Optional[float | list[float] | list[list[float]]]) – Relative permittivity tensor εᵣ. Accepts None (unspecified), a float, a list of 3 floats (for x,y,z), or a 3 x 3 list of list of floats for a fully anisotropic material.

  • mu (Optional[float | list[float] | list[list[float]]]) – Relative permeability tensor μᵣ. Same shape conventions as eps. Default: None (μᵣ = 1).

  • d (Optional[~DTensorType]) – Second-order nonlinear susceptibility d. Expected shape is 3x6. Use None when the material is linear. Default: None.

MaterialSpec

A container that defines the adjustable properties of a material being used. All properties default to the materials defaults (typically 0).

Parameters:

  • material (Union[str, ~MaterialProperties]) – Either a str of a material in the Material Database, or a MaterialProperties struct. Required.

  • theta (Optional[float]) – The angle of rotation around y for the material in radians.

  • phi (Optional[float]) – The angle of rotation around z for the material in radians. This is applied after the theta rotation.

  • x (Optional[float]) – The mole fraction for ternary materials such as AlGaAs and InGaAs. This is ignored for materials without this parameter. Must be between 0 and 1. Default: 0.

  • loss (Optional[float]) – The absorption loss of the material in dB/m.

Updating the MATLAB Interface

The latest version of emodeconnection.m can also be downloaded at the following link, which must be added to the EMode executable directory (or another directory in the MATLAB path). This is not necessary to setup EMode with MATLAB, and it is only intended for updating this connection package without re-installing EMode.

emodeconnection.m