Session management

Starting a local session

The Python API interacts with Lumerical products through sessions. The simplest way to create a session is by calling the relevant constructor for the Lumerical product and storing it in an object. These constructors construct objects derived from the Lumerical class.

Example

# Starting a local Lumerical FDTD session

fdtd = lumapi.FDTD()

Parameters

Product	Derived Class
Ansys Lumerical FDTD™	FDTD
Ansys Lumerical MODE™	MODE
Ansys Lumerical Multiphysics™	DEVICE
Ansys Lumerical INTERCONNECT™	INTERCONNECT

You can also create multiple sessions, even if they’re for the same product.

Example

# Starting two Lumerical MODE sessions one one Lumerical Multiphysics session
mode1 = lumapi.MODE()
mode2 = lumapi.MODE()
device = lumapi.DEVICE()

Each of the product’s constructor supports various parameters and keyword arguments. For more information, see API reference.

Example

# Loads and runs script.lsf while hiding the application window

inc = lumapi.INTERCONNECT(filename="script.lsf", hide=True)

Advanced session management

Wrapping the session in a function

In Python, you can use functions if you need to run numerous similar instances. For example, when sweeping over some optional parameters. For more information on how Lumerical sessions return results, see Passing data and Working with simulation objects.

Example

def myFunction(someOptionalParameter):
    fdtd = lumapi.FDTD()
    ...
    return importantResult

Using the “with” context manager

PyLumerical support Python “with” statement by giving well-defined entrance and exit behavior to Lumerical session objects in Python. If there are any errors within the “with” code block, the session still closes successfully, unlike in a function. Any error message you typically see in a Lumerical script environment is also displayed in the Python exception.

Example

with lumapi.FDTD(hide=True) as fdtd:
    fdtd.addfdtd()
    fdtd.setnamed("bad name") # you will see
LumApiError: "in setnamed, no items matching the name 'bad name' can be found."
    ...
# fdtd still successfully closes

Passing in command line arguments

Starting a session using PyLumerical is identical to running the solutions command line executable, as seen in these articles - Windows / Linux. When starting a session using Python, use the serverArgs parameter to specify command line arguments.

Example

fdtd = lumapi.FDTD(serverArgs = {
                    'use-solve':True,
                    'platform':'offscreen',
                    'threads': '2’}
            )

The Python code above is equivalent to running the following command:

fdtd-solutions -threads 2 -platform offscreen -use-solve

Closing the session

When the variables local to the function or context manager go out of scope, they are automatically deleted. Lumerical sessions automatically closes when all variable references pointing to it are deleted.

The Lumerical session also automatically terminate after the python script reaches the end.

Python automatically deletes variables as they removed from scope, so most of the time you don’t need to close a session manually. However, you can also do so explicitly using the following command.

inc.close() # inc is the name of the active session