Script Commands as Methods - Python API – Ansys Optics 2025/5/5 18:20

Products  Solutions  Learn  Sign in Evaluate for Free

⌂ Ansys Optics > Interoperability > Automation ! Search KB and APP

API

In this article
Script Commands as Methods - Python
Built-In Scripting Commands Related
articles
API
Importing Custom Script
Commands Python API
Non-Constructor Script overview
Commands
FDTD MODE DGTD CHARGE HEAT FEEM INTERCONNECT Lumerical
Unsupported Methods scripting
Local DocumentationAutomation API language -
Alphabetical
TOP ⬆
list
At the most basic level, the Lumerical Python API can be used to directly invoke
Lumerical script commands and interact with the product as the Lumerical Scripting Passing Data
- Python API
Language would.
Session
This article will describe the basic use case for using scripting commands as Management
methods, and common best practices. - Python API

Lumerical
scripting
Built-In Scripting Commands language -
By category
Overview
Recently
Almost all script commands in the Lumerical Scripting Language can be used as viewed
methods on your session object in Python. The lumapi methods and the Lumerical articles
script commands share the same name and can be called directly on the session
Session
once it's been created.
Management
- Python API
For more information on the Lumerical Scripting Language, please see:
Python API
Lumerical Scripting Learning Track on Ansys Innovation Courses (AIC) overview

Lumerical Scripting Language - Alphabetical list Lumerical

Lumerical Scripting Language - By category Python API
Reference
Two simple examples are show below. In the first example, the Lumerical commands Using the
getfdtdindex and stackrt is used in conjunction with typical math and plotting Python API
libraries in Python to simulate and visualize the transmission of a gold thin film in the
illuminated by a plane wave. In the second example, a simple simulation with a nanowire
application
gaussian source and a frequency domain monitor is set up and executed.
example
Example

For more information on how to import lumapi, see the Knowledge Base article on
Installation and Getting Started for Lumerical Python API.

https://optics.ansys.com/hc/en-us/articles/360041579954-Script-Commands-as-Methods-Python-API 第1/8⻚
Script Commands as Methods - Python API – Ansys Optics 2025/5/5 18:20

import lumapi #Ensure lumapi has already been added to path

import numpy as np
import matplotlib.pyplot as plt

with lumapi.FDTD() as fdtd:

lambda_range = np.linspace(300e-9, 1100e-9, 500)
c=2.99792458e8
f_range = c/lambda_range
au_index = fdtd.getfdtdindex("Au (Gold) - CRC", f_range, np.min(f_range)

stackRT_result = fdtd.stackrt(np.transpose(au_index), np.array([10e-9]),

#Visualize using matplotlib
fig, ax = plt.subplots()
ax.plot(lambda_range*1e9, stackRT_result["Ts"], label="Transmission")
ax.set_xlabel("Wavelength [nm]")
ax.set_ylabel("Transmission")
ax.legend()
plt.show()

Example

import os,sys
import numpy as np
sys.path.append("C:\\Program Files\\Lumerical\\v251\\api\\python\\") # locat
import lumapi
import matplotlib.pyplot as plt

with lumapi.FDTD() as fdtd:

# Set up simulation region

fdtd.addfdtd()
fdtd.set("x",0)
fdtd.set("x span",8e-6)
fdtd.set("y",0)
fdtd.set("y span",8e-6)
fdtd.set("z",0.25e-6)
fdtd.set("z span",0.5e-6)

# Set up source
fdtd.addgaussian()
fdtd.set("injection axis","z")
fdtd.set("direction","forward")
fdtd.set("x",0)
fdtd.set("x span",16e-6)
fdtd.set("y",0)
fdtd.set("y span",16e-6)
fdtd.set("z",0.2e-6)

https://optics.ansys.com/hc/en-us/articles/360041579954-Script-Commands-as-Methods-Python-API 第2/8⻚
Script Commands as Methods - Python API – Ansys Optics 2025/5/5 18:20

fdtd.set("use scalar approximation",1)

fdtd.set("waist radius w0",2e-6)
fdtd.set("distance from waist",0)
fdtd.setglobalsource("wavelength start",1e-6)
fdtd.setglobalsource("wavelength stop",1e-6)

# Set up monitor
fdtd.addpower()
fdtd.set("monitor type","2D Z-normal")
fdtd.set("x",0)
fdtd.set("x span",16e-6)
fdtd.set("y",0)
fdtd.set("y span",16e-6)
fdtd.set("z",0.3e-6)

# Run simulation
fdtd.save("fdtd_tutorial.fsp")
fdtd.run()

Constructor Script Commands

Many Lumerical script commands are used to add simulation objects such simulation
regions or geometric regions. These commands typically start with “add”, for
example, addrect or addfdtd.

In the Lumerical Python API, simulation objects can be created in many different
ways. At a fundamental level, objects can be created and have their properties set
like how it is done in a Lumerical script using set and setnamed.

In addition, the lumapi also supports assigning properties to object in a pythonic

way, either by creating a dictionary and assigning it to the properties attribute during
initialization or using keyword arguments directly. When constructing objects using
these methods, some properties may need to be initialized in order or may overwrite
other properties. Therefore, it is recommended to use an ordered dictionary to
ensure that these properties are set as intended.

The examples below show various methods on object construction. For more
information regarding adding and manipulating simulation objects, including best
practices, see the Knowledge Base article on Working with Simulation Objects in
Python API . Property names where a space is present (e.g. “x span”) is replaced by
an underscore when using keyword arguments (e.g. “x_span”).

Example

These examples create a 3D FDTD region centered at the origin and with a span of
1µm.

Firstly, using the Lumerical script commands:

fdtd = lumapi.FDTD()

https://optics.ansys.com/hc/en-us/articles/360041579954-Script-Commands-as-Methods-Python-API 第3/8⻚
Script Commands as Methods - Python API – Ansys Optics 2025/5/5 18:20

fdtd.addfdtd()
fdtd.set(“x”,0)
fdtd.set(“y”,0)
fdtd.set(“z”,0)
fdtd.set(“x span”,1e-6)
fdtd.set(“y span”,1e-6)
fdtd.set(“z span”,1e-6)

The following code creates the FDTD region uses an ordered dictionary to set its
properties.

from collections import OrderedDict #Ensure OrderedDict is imported

…
fdtd = lumapi.FDTD()
props = OrderedDict([("x", 0),("y",0), ("z", 0), ("x span", 1e-6), ("y span"
fdtd.addfdtd(properties = props)

The following code creates the FDTD region using keyword arguments

fdtd = lumapi.FDTD()
fdtd.addfdtd(x=0,y=0,z=0,x_span=1e-6, y_span=1e-6, z_span=1e-6) #Note that t

For more information regarding adding and manipulating simulation objects,

including other ways to interact with these objects and best practices see the
Knowledge Base article on Working with Simulation Objects in Python API.

Importing Custom Script Commands

In addition to default script commands, you can also take advantage of the auto-
syncing function feature in lumapi and import functions that are pre-defined in a
Lumerical script file (.lsf file). To import these functions, you can either execute the
scripts while constructing the session (using the script keyword argument), or
manually evaluating the file using the eval method.

Example

The following two .lsf files contains custom functions.

MyFunctions.lsf

function helloWorld(){
return "helloworld";
}

function customAdd(a,b){
return a+b;
}

https://optics.ansys.com/hc/en-us/articles/360041579954-Script-Commands-as-Methods-Python-API 第4/8⻚
Script Commands as Methods - Python API – Ansys Optics 2025/5/5 18:20

MyFunctions2.lsf

function customMultiply(a,b){
return a*b;
}

The following script imports functions from both custom script files upon session
creation.

with lumapi.FDTD(script = ["MyFunctions.lsf", "MyFunctions2.lsf"]) as fdtd:

#From MyFunctions.lsf
print(fdtd.helloWorld())
print(fdtd.customAdd(1,2))
#From MyFunctions2.lsf
print(fdtd.customMultiply(4,5))

Returns

helloworld
3.0
20.0

Non-Constructor Script Commands

Script commands that do not create simulation objects where input arguments are
required can only be used with positional arguments and is not compatible with
keyword arguments.

For example the following code will result in an error, even though the set script
command takes property and value as input arguments.

Example

fdtd.addfdtd()
fdtd.set(property = "x span", value = 1e-6)

The correct usage would be the following.

fdtd.addfdtd()
fdtd.set("x span", 1e-6)

This applies also to methods defined in other scripting files that are loaded by first
evaluating the script file.

Example

function constructFDTDandRect(x_input,y_input,z_input){

https://optics.ansys.com/hc/en-us/articles/360041579954-Script-Commands-as-Methods-Python-API 第5/8⻚
Script Commands as Methods - Python API – Ansys Optics 2025/5/5 18:20

#This function creates an FDTD and a rectangle region with center coordi
addfdtd;
set("x",x_input);
set("y",y_input);
set("z",z_input);

addrect;
set("x",x_input);
set("y",y_input);
set("z",z_input);
}

The following Python driver script will cause an error, even though the function
defined in the script file have arguments named x_input, y_input, and z_input.

fdtd = lumapi.FDTD()
custom_code = open("MyConstructor.lsf", "r").read()#This assumes the current
fdtd.eval(custom_code)
fdtd.constructFDTDandRect(x_input =0,y_input = 0, z_input = 0)

In contrast, the following driver script will execute without error, and add both the
FDTD region as well as the rectangle.

fdtd = lumapi.FDTD()
custom_code = open("MyConstructor.lsf", "r").read()#This assumes the current
fdtd.eval(custom_code)
fdtd.constructFDTDandRect(0,0,0)

Unsupported Methods
While most script commands are available, there are a few categories of commands
that are not available for use in the Python API. For example, certain reserved
keywords (such as “c” for the speed of light) are unavailable in Python. If you
requires access to these variables, it is best to either define them in Python, or to
use the eval() method. However, if the eval() method is used, you should be mindful
that the variables in the Python and Lumerical scripting environments are not
automatically shared.

Operators

Script operators that are used in the Lumerical Scripting Language cannot be
overloaded and used “as-is” using the same syntax in Python, therefore, they are not
available, and you should use alternatives in Python. The unavailable operators
include:

Algebraic – For example, * , / , + , - , ^

https://optics.ansys.com/hc/en-us/articles/360041579954-Script-Commands-as-Methods-Python-API 第6/8⻚
Script Commands as Methods - Python API – Ansys Optics 2025/5/5 18:20

Logical – For example, >= , < , > , & , and , | , or , ! , ~

The ? (print, display) operator used to screen and query available results

When algebraic or logical operators are needed, you should use the native Python
operators to manipulate variables, even though some syntax differences would exist
between Python and Lumerical Scripting Language. For example, one way to
implement the exponent operator ^ in Lumerical scripts in Python is through the
** operator.

When the ? (print, display) operator is required, your should use the Python print
function to display and querynamed method, queryanalysisprop method, and etc.
to access simulation object properties in Lumerical.

Local Documentation

For information on the lumapi methods from within the environment we support
Python docstrings for Lumerical session objects. This is the simplest way to
determine the available script commands, and syntax. This contains information that
is similar to the Alphabetical List of Script Commands . You can view the docstring
by using the Python built-in function "help" or most ways rich interactive Python
shells display docstrings (e.g. IPython, Jupyter Notebook):

help(fdtd.addfdtd)
Help on method addfdtd in module lumapi:
addfdtd(self, *args) method of lumapi.FDTD instance
Adds an FDTD solver region to the simulation environment. The extent of
the solver region determines the simulated volume/area in FDTD
Solutions.
+-----------------------------------+-----------------------------------
| Syntax | Description
+-----------------------------------+-----------------------------------
| o.addfdtd() | Adds an FDTD solver region to the
| | simulation environment.
| |
| | This function does not return any
| | data.
+-----------------------------------+-----------------------------------
See Also
set(), run()
https://kb.lumerical.com/en/ref_scripts_addfdtd.html

Note: We still support previous version of the Python API, yet we strongly
recommend to use the newer Python API.

See Also
Python API Overview, Working with Simulation Objects – Python API, Script
Commands as Methods – Python API, Installation and Getting Started – Python
API

https://optics.ansys.com/hc/en-us/articles/360041579954-Script-Commands-as-Methods-Python-API 第7/8⻚
Script Commands as Methods - Python API – Ansys Optics 2025/5/5 18:20

Products Resources Corporate

FDTD Learn About Lumerical

MODE Support Careers
CHARGE Solutions News Releases
HEAT Ansys Innovation Courses  In the Literature
DGTD Ideas Exchange  Contact Us
FEEM Ansys Learning Forum 
MQW Knowledge Base 
STACK Application Gallery 
INTERCONNECT
CML Compiler
Photonic Verilog-A
Downloads

Stay in the know Copyright 2024 Ansys Canada Ltd.

Subscribe to Spotlight Newsletter

Terms of Service Cookie Policy Privacy Policy

Legal Notices Sitemap
   

https://optics.ansys.com/hc/en-us/articles/360041579954-Script-Commands-as-Methods-Python-API 第8/8⻚