lumapi.putv - Python API method

A Python function that puts a variable from the local Python environment into an active Lumerical session via the Python API.

 A quick reference guide for translated datatypes.

String

When putv() is executed in Python, with the name of a Lumerical variable, and a string variable passed as the arguments; a string variable with the desired name and string value is created in the Lumerical session.

with lumapi.FDTD(hide = True) as fdtd:
    #Strings
    Lumerical = 'Lumerical Inc'
    fdtd.putv('Lum_str',Lumerical)
    print(type(fdtd.getv('Lum_str')),str(fdtd.getv('Lum_str')))

<class 'str'> Lumerical Inc

Real Number

When putv() is executed in python, with the name of a Lumerical variable, and a real number passed as the arguments; a variable with the desired name and real value is created in the Lumerical session. Integer types are not supported in Lumerical and will be returned as type float.

 with lumapi.FDTD(hide = True) as fdtd:
    #Real Number
    n = int(5)
    fdtd.putv('num',n)
    print('Real number n is returned as ',type(fdtd.getv('num')),str(fdtd.getv('num')))

Real number n is returned as <class 'float'> 5.0

Complex Number

One may pass a complex numpy array to the putv() method to pass a complex number. Passing complex numbers between sessions requires that they be encapsulated in a single element array since the complex class is not supported in the API.  For more information see lumapi.getv(). Alternatively one can use the lumapi.eval() method to define a complex variable.

 with lumapi.FDTD(hide = True) as fdtd:
    #Complex Numbers 
    z = 1 + 1.0*1j
    Z = np.zeros((1,1),dtype=complex) + z
    fdtd.putv('Z',Z[0])
    fdtd.eval('z = 1 +1i;')
    print('Complex number Z is returned as ',type(fdtd.getv('Z')),str(fdtd.getv('Z')))
    print('Complex number z is returned as ',type(fdtd.getv('z')),str(fdtd.getv('z')))

Complex number Z is returned as  <class 'numpy.ndarray'> [[1.+1.j]]
Complex number z is returned as  <class 'numpy.ndarray'> [[1.+1.j]]

NOTE: the different imaginary unit conventions. In python complex numbers are initialized using ‘j’ and in Lumerical this accomplished using ‘i’.

Numpy array

When putv() is executed in Python, with the name of a Lumerical variable name, and a numpy array passed as the arguments; a Lumerical matrix with the desired name and values is created in the Lumerical session. As we saw previously these support complex data. This useful when defining vectors, and matrices. 

 with lumapi.FDTD(hide = True) as fdtd:
    ##      Vector
    rad = np.linspace(1,11)*1e-6 #np array
    height = np.arange(1,3,0.1)*1e-6 #np array
    #Pass to Lumerical
    fdtd.putv('rad',rad)
    fdtd.putv('height',height)
    #Get from Lumerical
    rad_rt=fdtd.getv('rad')
    height_rt=fdtd.getv('height')
    print('After round trip rad is ', type(rad_rt))
    print('After round trip height is ', type(height_rt))

    ###     Matrix
    M1 = np.matrix([[0,0.5,0.3,0.4,0.5,0.6], [0,2,3,4,5,6],[0,2.2,3.5,4.4,5.5,6.5]])
    M2 = np.zeros((2,2),dtype=complex)
    #Pass to Lumerical
    fdtd.putv('M1',M1)
    fdtd.putv('M2',M2)
    #Get from Lumerical
    M1_rt=fdtd.getv('M1')
    M2_rt=fdtd.getv('M2')
    print('The matrix M is ', type(M1_rt), str(M1_rt))
    print('The np array M2 is ', type(M2_rt),  str(M2_rt))

    #       Return from Lumerical
    A = fdtd.randmatrix(2,3)
    B = fdtd.zeros(1,5)
    print('The matrix A is ', type(A),  str(A))
    print('The matrix B is ', type(B),  str(B))

Returns

After round trip rad is  <class 'numpy.ndarray'>
After round trip height is  <class 'numpy.ndarray'>
The matrix M is  <class 'numpy.ndarray'> [[0.  0.5 0.3 0.4 0.5 0.6]
 [0.  2.  3.  4.  5.  6. ]
 [0.  2.2 3.5 4.4 5.5 6.5]]
The np array M2 is  <class 'numpy.ndarray'> [[0.+0.j 0.+0.j]
 [0.+0.j 0.+0.j]]
The matrix A is  <class 'numpy.ndarray'> [[0.806134   0.99917605 0.23325807]
 [0.69062098 0.53113442 0.18275802]]
The matrix B is  <class 'numpy.ndarray'> [[0. 0. 0. 0. 0.]]

List

When putv() is executed in python, with a Lumerical variable name, and a list passed as the arguments; a Lumerical cell array with the desired name and values is created in the Lumerical session. 

Cell arrays are ordered and can include any type of data already mentioned above, themselves and structs. Similarly, Python lists are ordered and can include numerous classes as elements. These datatypes are logically equivalent.

with lumapi.FDTD(hide = True) as fdtd:
    #Cells
    C1 = [ i for i in range(11)] #list
    C2 = [[1,2,3],[4,5,6]] #list of lists
    C3 = [C1,C2,'string', 3.59]
    #Pass to Lumerical
    fdtd.putv('C_1',C1)
    fdtd.putv('C_2',C2)
    fdtd.putv('C_3',C3)
    #Get from Lumerical
    C1_rt=fdtd.getv('C_1')
    C2_rt=fdtd.getv('C_2')
    C3_rt=fdtd.getv('C_3')
    print('The cell C1 is ', type(C1_rt),  str(C1_rt))
    print('The cell C2 is ', type(C2_rt),  str(C2_rt))
    print('The cell C3 is ', type(C3_rt),  str(C3_rt))

The cell C1 is  <class 'list'> [0.0, 1.0, 2.0, 3.0, 4.0, 5.0, 6.0, 7.0, 8.0, 9.0, 10.0]
The cell C2 is  <class 'list'> [[1.0, 2.0, 3.0], [4.0, 5.0, 6.0]]
The cell C3 is  <class 'list'> [[0.0, 1.0, 2.0, 3.0, 4.0, 5.0, 6.0, 7.0, 8.0, 9.0, 10.0], [[1.0, 2.0, 3.0], [4.0, 5.0, 6.0]], 'string', 3.59]

Dict

When putv() is executed in Python, with a Lumerical variable name, and a Python dictionary passed as the arguments; a Lumerical struct with the desired name and values is created in the open Lumerical session.

Structures are indexed by fields, but not ordered and can include any data type mentioned above and themselves as members. Similarly, Python dictionaries are indexed by keys and can include numerous classes as elements. When getv() is executed in Python, with the name of a struct lsf variable passed as the argument, this function will return the cell to the python environment as a list.  

with lumapi.FDTD(hide = True) as fdtd:
    #Struct
    D = {'greeting' : 'Hello World',                      # String data
          'pi' : 3.14,                                     # Double data 
          'm' : np.array([[1.,2.,3.],[4.,5.,6.]]), # Matrix data   
          'nested_struct' : { 'e' : 2.71 } }               # Struct 
    fdtd.putv('Dict', D)
    D_rt = fdtd.getv('Dict')
    print('The dictionary D is ', type(D_rt),  str(D_rt))

 Returns

The dictionary D is  <class 'dict'> {'greeting': 'Hello World', 'm': array([[1., 2., 3.],

Datasets

When Lumerical datasets are returned to the Python environment they are converted into Python dictionaries. For more information see Passing data - Python API.