This article illustrates the set up process for the Python API integration with Lumerical.
- Automation API license
- Lumerical products release 2019a R3 or later
- gnome-terminal running bash shell for supported Linux systems
- Python 2.7 or Python 3 (64-bit version)
- NumPy package installed (minimum version 1.4)
- The bundled Python includes a copy of NumPy and SciPy libraries.
- In macOS Mojave, when running Python scripts from a Lumerical product for the first time, the users will be prompted by a dialog warning informing them that the software wants access to control "Terminal.app". Allow access by clicking "OK". If "Don't allow" is chosen, the Python integration will not work and the access to terminal has to be allowed by editing the the Privacy Settings.
- Python version compatibility - Lumerical is not able to guarantee compatibility with all Python versions and distributions for this feature although most versions should work fine.
Python script integration
The Python script integration feature allows Python scripts to be read, modified and run from within the script editor. This means that users can read/write edit and run (.py) files directly from the script editor window of the products in the same way as the Lumerical script files (.lsf)
Checking integration status
- To check the status of the Python script integration feature, go to the Help menu and select Python integration status.
- An 'active' status means that a python installation has been successfully found and linked to the product for python script execution.
- The path to the python executable and environment variable corresponding to the integrated Python installation are also shown in the window.
- Users have the option to choose their own Python distribution by unchecking the "Use Python provided by Lumerical" option and adding the path to their Python distribution to the PATH environment variable.
Running Python scripts
- This will allow running Python scripts from within the product's script file editor.
- To enable this feature, Lumerical products come bundled with a copy of Python 3.6. which is placed within the installation directory.
- When running a Python script from within Lumerical products, the Python session will be launched in a terminal emulator (command prompt in Windows, gnome-terminal in Linux and terminal in Mac) using the bundled Python interpreter.
- After the Python script is complete, the Python interpreter prompt is left open in case the user wants to investigate any variables or objects.
- To exit the interpreter, quit() or sys.exit() commands can be used which will also close the terminal emulator window with the following prior configuration,
Under Preferences > Profiles > (Select a Profile) > Shell, for 'When the shell exits' the option 'Close the window' is selected
Under Edit > Profile Preferences > Title and Command, for 'When command exits' the option 'Exit the terminal' is chosen
The command prompt will always close and no setting is required
Python API integration
Python API intergration enables Lumerical applications and scripts to be called from Python. Lumerical comes packaged with a Python module 'lumapi.py', in the following locations,
Once this module, 'lumapi.py', is imported into your Python environment you are ready to go.
At a minimum this requires the following two steps, which may differ depending on your Python environment.
- Tell Python where to find the Lumerical module.
- Import the module into the environment.
In Linux, the code snippet below will import the Lumerical module as lumapi from the given path.
>>> import imp
>>> lumapi = imp.load_source("lumapi", "/opt/lumerical/2019b/api/python/lumapi.py")
The PYTHONPATH variable on your machine can also be modified to include the module, 'lumapi.py', path directly. See the <Python documentation> for more details. For other tools like SciPy, see Python.org manuals for adding custom modules.
- When driving and passing data between multiple Lumerical products, to ensure full feature support, all Lumerical products should be from the same release version.
- If you need to install Lumerical on a different location, please do not change the version hierarchy folder name. e.g. '2019b' version shown.
# custom path