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
fdtd = lumapi.FDTD()
Parameters
|
Product |
Derived Class |
|---|---|
| Ansys Lumerical FDTD™ | FDTD |
| Ansys Lumerical MODE™ | MODE |
| Ansys Lumerical Multiphysics™ | DEVICE |
| Ansys Lumerical INTERCONNECT™ | INTERCONNECT |
Multiple sessions can also be created. Sessions may be for the same product.
Example
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 the Lumerical Python API Reference.
Example
# loads and runs script.lsf while hiding the application window
inc = lumapi.INTERCONNECT(filename="script.lsf", hide=True)
Starting a Remote Session using the Interop Server
Since the 2023 R1.2 release, the Python API can be used remotely on a Linux machine running the interop server (see Interop Server - Remote API to configure and run the interop server). To use the remote API, an additional parameter is required when starting a session, to specify the IP address and port to use to connect to the interop server. This port must be the starting port defined for the interop server.
This parameter is a dictionary with 2 fields, "hostname" and “port”.
Example
remoteArgs = { "hostname": "192.168.215.129",
"port": 8989 }
fdtd = lumapi.FDTD(hide=True, remoteArgs=remoteArgs)
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 the important results are returned see the Knowledge Base articles on Passing data and Working with Simulation Objects.
Example
def myFunction(someOptionalParameter):
fdtd = lumapi.FDTD()
...
return importantResult
Using the "with" context manager
We 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). Also note that any error message you typically see in a Lumerical script environment would be displayed in the Python exception.
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 the Python is identical to running the solutions command line executable (Windows/Linux). When starting a session using Python, the serverArgs parameter can be used to specify parameters.
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 will be deleted automatically, and Lumerical sessions will automatically close when all variable references pointing to it are deleted. The Lumerical session will also automatically terminate after the python script reaches the end.
Python will automatically delete variables as they removed from scope, so most of the time you will not 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
See Also
Python API Overview, Working with Simulation Objects – Python API, Script Commands as Methods – Python API. Installation and Getting Started – Python API