Lumerical Python API Reference

==Start of tab1 content=========================================

Lumerical Class

The Lumerical class is the common base class for all classes representing interactive sessions with the Lumerical products.

Constructor

Instantiation

The Lumerical class is not intended to be directly instantiated; to create a session for a specific Lumerical product, create an instance of the derived class (FDTD, MODE, DEVICE, and INTERCONNECT) corresponding to the desired product session. 

Example

fdtd = lumapi.FDTD() #Launches an FDTD session called “fdtd”

Constructor

Signature

class FDTD(filename = None, key = None, hide = False, serverArgs = {}, remoteArgs = {}, **kwargs)
class MODE(filename = None, key = None, hide = False, serverArgs = {}, remoteArgs = {}, **kwargs)
class DEVICE(filename = None, key = None, hide = False, serverArgs = {}, remoteArgs = {}, **kwargs)
class INTERCONNECT(filename = None, key = None, hide = False, serverArgs = {}, remoteArgs = {}, **kwargs)

Parameters

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

remoteArgs = { "hostname": "192.168.215.129",
    "port": 8989 }

Keyword Arguments

Attributes

Lumerical objects do not have user modifiable attributes. In addition to the class methods defined below, Lumerical objects dynamically define methods corresponding to Lumerical script commands when instantiated. This is explained in the following section.

Methods

Script Commands as Methods

All Lumerical scripting commands are valid methods of the Lumerical class and its derived classes. These script commands can be used to directly setup and conduct simulations. For example, addrect is a method that can be used to add a rectangle geometry object. Using the Python API, the command can be called, with attributes directly set in the constructor as keyword arguments using the following line.  

fdtd.addrect(x=1e-6,y=0,z=0)

As another example, the script command getfdtdindex can be used to obtain the frequency-dependent material index.

#FDTD Session already open
c = 2.99792458e8
f_range = np.linspace(c/1100e-9, c/400e-9, 1000)
au_index = fdtd.getfdtdindex("Au (Gold) - CRC", f_range, np.min(f_range), np.max(f_range))
#au_index contains the index of gold from 400nm to 700nm wavelength

For more information, see the Knowledge Base article on Script Commands as Methods and Working with Simulation Objects.

Default Methods

These default methods are commonly used for interaction with Lumerical sessions through Python.

• close : Close the current Lumerical session.
• getObjectById: Get a specific object by their ID.
• getObjectBySelection: Get the currently selected object.
• getAllSelectedObjects: Get all currently selected object as a list.

Low Level Script Workspace Methods

These methods are used to directly interact with the Lumerical scripting workspace. It is not recommend to use these methods unless a specific function needs to be achieved.

• eval : Evaluate a string containing Lumerical Scripting Language code.
• getv : Obtain Lumerical variable and place into Python workspace.
• putv: Put Python variable into Lumerical workspace.

==End of tab1 content=========================================

==Start of tab2 content=========================================

SimObject Class

The SimObject class represents a simulation object in the Objects Tree.

Attributes

The object has attributes that match the properties of the simulation object.

The attribute names are the same as the property names in the Lumerical application, except that spaces are replaced with underscores characters. All attributes can also be set like a Python dict using the subscripting operator []. When accessing using the subscripting operator, these attributes retain their original name including spaces. Attributes can be read and set. Attributes that are set will immediately update the object in the Lumerical application.

Example

fdtd = lumapi.FDTD()
#Initialize position and x span using keyword arguments
rect_obj = fdtd.addrect(x=0,y=0,z=0, x_span = 2e-6)
#Set y span as an attribute 
rect_obj.y_span = 2e-6
#Set z span like a dict, note that there is now a space since the original Lumerical attribute has a space
rect_obj["z span"] = 0.5e-6

#Read and print out the x-span of the rectangle set earlier
print(f"{rect_obj.x_span =} \n")

Returns

Attribute Access: rect_obj.x_span =2e-06 
Dict Access: rect_obj['x span']=2e-06

The 'results' attribute is an object that contains all the results of the object.

fdtd = lumapi.FDTD()
rect_bot =fdtd.addrect(name = "Rect",x_span = 1e-6, z_span = 0.25e-6, z=0) #Create a bottom rectangle, Rect1
rect_top = fdtd.addrect(name = "Rect", x_span = 1e-6, z_span = 0.25e-6, z=0.5e-6) #Create a top rectange, Rect 2

#The following code will change the x_span of the BOTTOM rectangle!
rect_top.x_span = 2e-6

Methods

• getParent: Get the parent of the current object.
• getChildren: Get all children of the current object as a list.

==End of tab2 content=========================================

==Start of tab3 content=========================================

SimObjectResults Class

The SimObjectResults class contains all results of a simulation object. This object can be accessed by accessing the results attribute of a SimObject class.

Attributes

The object has attributes that match each of the results of the simulation object in Lumerical products. The attribute names are the same as the result names, except that spaces are replaced with underscores characters. These attributes can also be accessed like a Python dict using the subscripting operator []. When accessing using the subscripting operator, attributes retain their original name including spaces.

Result data is retrieved each time the attribute is read. Therefore, for results with a large amount of data, you should avoid repeatedly accessing the attribute. Instead, the result should be first stored in a local variable.

Writing to results is not supported and will have no effect on the simulation object in the Lumerical environment.

==End of tab3 content=========================================

==Start of tab4 content=========================================

SimObjectId Class

The SimObjectID class is a weak reference to a simulation object.

==End of tab4 content=========================================