Python interface

To control EMode directly from a Python script, we supply a Python package called emodeconnection. This has been tested with Python versions 3.9, and 3.10, including the Anaconda distribution and iPython terminals. Tested Python IDEs include Notepad++/Command Prompt, PyCharm, Spyder, and Visual Studio Code.

The source code can be viewed here: emodeconnection

For more information about Python, see these links:

Setup

Install the emodeconnection Python package from the command line.

pip install emodeconnection

EMode Login

Open a Python session and run the following. 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.

import emodeconnection as emc
emc.EModeLogin()

The EMode class

class EMode(simulation_name='emode', license_type='default', save_path='.', verbose=False, roaming=False, open_existing=False, new_name=False, priority='pN', emode_cmd=None)

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, this will prompt for a username and password. To reset the user profile, run EModeLogin from the the start menu.

An existing file can be opened for further analysis by specifying the input argument open_existing = True. This opened file can be copied to a new file name by specifying the input argument new_name = 'new_filename'.

Note

All EMode functions are accessible as methods of this class instance using keyword arguments for each funtion input parameter.

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’.
emode_cmd (list[str]) – Set the EMode executable command. For standard installations, this can be ignored. Only use this if the EMode executable has been moved to a custom location.

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.

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.

open_file(simulation_name='emode')

Opens an EMode simulation file with the extension ‘.eph’ or ‘.mat’ and returns a dictionary with the file contents.

Parameters:: simulation_name (str) – Name of the simulation file. The ‘.eph’ or ‘.mat’ extension is optional to include with the name.
Returns:: Dictionary with all keys and data from the specified EMode simulation file.
Return type:: dict

get(variable, simulation_name='emode')

Returns the contents of a specified variable from an EMode simulation file with the extension ‘.eph’ or ‘.mat’.

Parameters:

variable (str) – Name of the variable to return from EMode.
simulation_name (str) – Name of the simulation file. The ‘.eph’ or ‘.mat’ extension is optional to include with the name.

Returns:

Requested item from EMode.

Return type:

int, float, str, or array-like

inspect(simulation_name='emode')

Get the names of all variables from EMode simulation file with the extension ‘.eph’ or ‘.mat’.

Parameters:: simulation_name (str) – Name of the simulation file. The ‘.eph’ or ‘.mat’ extension is optional to include with the name.
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 classes of the emodeconnection package.

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.

class 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 pointing to a material in the Material Database, or a MaterialProperties object. 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 in materials without this parameter. Must be between 0 and 1.
loss (Optional[float]) – The absorption loss of the material in dB/m.

Exceptions

The emodeconnection.types module also contains the following exception classes. All errors in EMode are raised and passed back to the user as one of these errors.

class EModeError(*args, **kwargs): Base class for all EMode exceptions.

class ArgumentError(msg, function=None, argument=None)

Invalid value passed to function.

Parameters:

msg (str) – Human-readable explanation.
function (str) – Function name.
argument (str) – Name of the offending argument.

class EPHKeyError(msg, filename, key)

Missing dataset or attribute key in the given EPH file.

Parameters:

msg (str) – Details of the failure.
filename (str) – Path to the EPH file.
key (str) – Absent key.

class FileError(msg, filename)

Generic file-system or I/O problem.

Parameters:

msg (str) – Description of the error.
filename (str) – File path involved.

class LicenseError(msg, license_type)

Operation not permitted under license_type.

Parameters:

msg (str) – Explanation of the denial.
license_type (LicenseType) – Active or required licence class.

class ShapeError(msg, shape_name)

Unexpected tensor or geometry shape.

Parameters:

msg (str) – Explanation of the mismatch.
shape_name (str) – Symbolic name of the offending shape.

class NameError(msg, type, name)

Forbidden name within the given type category.

Parameters:

msg (str) – Reason for the failure.
type (str) – Category being searched (e.g. "section" or "label").
name (str) – Forbidden identifier.

class NotImplementedError(msg)

Feature is recognised but not yet implemented.

Parameters:: msg (str) – Description of the missing capability.

Updating the Python Interface

Update the emodeconnection Python package to the latest version with:

pip install -U emodeconnection