The Lumerical Python API is a powerful interoperability tool that integrates Lumerical tools with the Python language, allowing you to develop complex automated workflows and perform advanced data processing operations.
In this article, installation of the Lumerical Python API is explained.
System Requirements
- Lumerical product version 2019a R3 or later
- Gnome or Mate desktop environment for supported Linux systems when running from the Lumerical CAD/GUI.
- A graphical interface/connection to the machine running the API
- A Lumerical GUI license – a GUI license is required as the Python API interfaces with the Lumerical GUI
Installation and Importing Modules
The Python API can be used either with the built-in script editor to the Lumerical CAD, or with an external Python editor.
Using Python API with the CAD Script Editor
All Lumerical products since 2019a R3 are shipped with a basic Python 3 distribution, and Python can be directly edited and executed with the built-in CAD script editor. To add a Python file, you can click on the arrow beside the “New Lumerical Script” button and click on “New Python Script”.
In this editor, the Python API can be imported and used like any other Python module:
import lumapi
Using Python API with External Editor
To use the Python API with an external editor, it is necessary to add the file path of the Python API from the Lumerical installation directory to the search path prior to importing it in script.
This can be achieved in many ways, and a few common methods will be detailed here. For more information, please see the Python documentation for modifying Python’s search path.
Permanently Adding lumapi to Search Path
One way to permanently add Lumerical to Python’s search path is to add a .pth file to the site-packages directory of the Python distribution installation. This .pth file should contain the Lumerical directory in a line where the lumapi.py file is located. This file is automatically parsed by Python.
The .pth file is a simple text file containing the location of the lumapi files, which are by default the following:
Windows
C:\\Program Files\\Lumerical\\[[verpath]]\\api\\python\\
C:\\Program Files\\Ansys Inc\\[[verpath]]\\Lumerical\\api\\python\\
Linux
Lumerical Installer (RedHat/Rocky Linux, SUSE Linux Enterprise Server, Ubuntu)
/opt/lumerical/[[verpath]]/api/python/
~/Ansys/ansys_inc/[[verpath]]/Lumerical/api/python/
Temporarily Adding lumapi to Search Path
Alternatively, you can also add lumapi to the python search path temporarily by appending it to the sys.path variable. This method is also useful in adding other directories, such as the current working directory of the Python file to the search path so that CAD and other Lumerical script files can be easily found.
The following code adds both the lumapi folder and the current working folder to the Python search path.
Windows
import sys, os
#default path for current release
sys.path.append("C:\\Program Files\\Lumerical\\[[verpath]]\\api\\python\\") #lumapi directory
sys.path.append(os.path.dirname(__file__)) #Current directory
Linux
import sys, os
#default path for current release
sys.path.append("/opt/lumerical/[[verpath]]/api/python/")
sys.path.append(os.path.dirname(__file__)) #Current directory
Using Explicit Import
In addition to the method described above, you can also use the importlib.util() function from Python to specify the path to your lumapi distribution. This may be useful for when you need to compare different lumapi versions.
The following code explicitly adds the lumapi module.
Windows
import importlib.util
#default path for current release
spec_win = importlib.util.spec_from_file_location('lumapi', 'C:\\Program Files\\Lumerical\\[[verpath]]\\api\\python\\lumapi.py')
#Functions that perform the actual loading
lumapi = importlib.util.module_from_spec(spec_win) #windows
spec_win.loader.exec_module(lumapi)
Linux
import importlib.util
#default path for current release
spec_lin = importlib.util.spec_from_file_location('lumapi', "/opt/lumerical/[[verpath]]/api/python/lumapi.py")
#Functions that perform the actual loading
lumapi = importlib.util.module_from_spec(spec_lin)
spec_lin.loader.exec_module(lumapi)
After adding the lumapi directory to Python’s search path, the module can be imported and loaded like any other Python module using the following command:
import lumapi
For more information on how to work with the lumapi module, please see the Knowledge Base article on Session Management, Working with Simulation Objects, and Script Commands as Methods.
See Also
Python API Overview, Session Management – Python API, Working with Simulation Objects – Python API, Script Commands as Methods – Python API.