Using JSON files with Lumerical's software

Lumerical's software supports the use of the JSON file format to save and transfer data between products.  The JSON is a popular file format with customers using Lumerical's Python API. JSON files can be saved and loaded with the following commands: jsonload, jsonsave, jsonread, jsonwrite, jsonloads, jsonsaves, jsonreads, jsonwrites. See an example of loading data from JSON in the MQW Edge Emitting Laser application example. 

Lumerical JSON file format specifications

The following section defines Lumerical's JSON file format. Data that will be loaded into Lumerical's software must conform to these specifications. The JSON file format encoder is defined by the lumjson.py module located within the /api/python/ folder of the installation directory.

Lumerical JSON file notation

Following are some examples of the JSON format of type "cell" and "matrix".

Example: Cell

The jsonsave and jsonsaves commands save Lumerical cell into JSON object. The command jsonsave saves the cell to a file, whereas the jsonsaves command outputs it as a string.

a = {10, 20, 30};
b1 = jsonsaves(a);

The above command generates the following JSON object b1:

{
 "a" : 
 {
   "_data" : [ 10.0, 20.0, 30.0 ],
   "_type" : "cell"
 }
}

The jsonwrite and jsonwrites commands save Lumerical cell into JSON list, e.g., the command

a = {10, 20, 30};
b2 = jsonwrites(a);

generates the following JSON list b2:

 [ 10, 20, 30 ]

Example: Matrix

Use the “matrix” under the _type field.

Number

{
     _type: "matrix"
     _data: [42]
}

Complex numbers

Complex numbers are always written as real and imaginary pairs. For example, a 1x1 matrix of the complex number 2+4i is written as follows.

{
     _type: "matrix"
     _complex = true
     _data: [2, 4]
}

Matrix

Option 1: specify the size and data is a single array. This option offers direct mapping to Lumerical matrix. The "_size" matches dimlist and "_data" is in real/imaginary pairs if "_complex" is true. The "_size" matches the dimension list in Lumerical and "_data" is in real/imaginary pairs if "_complex" is true. The data is grouped into 2-D matrices, iterating over the remaining dimensions if it is larger than 2D.

2D Complex Matrix Example:

{
     _type: "matrix"
     _size: [2, 3]
     _complex = true
     _data: [1, 2, 3, 4, 5, 6, 7, 8, 9, 10, 11, 12]
}

and the data is:

[1+2i, 5+6i, 9+10i
3+4i, 7+8i, 11+12i]

3D Real Matrix Example:

{
   "_complex" : false,
   "_data" : [ 1.0, 4.0, 2.0, 5.0, 3.0, 6.0, 7.0, -1.0, 8.0, -2.0, 9.0, -3.0 ],
   "_size" : [ 2, 3, 2 ],
   "_type" : "matrix"
 }

and the data is:

result(i,j,1):
1  2  3  
4  5  6  
result(i,j,2):
7  8  9  
-1  -2  -3  

4D Real Matrix Example:

{
   "_complex" : false,
   "_data" : 
   [
     1.0, 4.0, 2.0, 5.0, 3.0, 6.0, 7.0, -1.0, 8.0, -2.0, 9.0, -3.0, -1.0, -4.0, -2.0, -5.0, -3.0, -6.0, -7.0, 1.0, -8.0, 2.0, -9.0, 3.0
   ],
   "_size" : [ 2, 3, 2, 2 ],
   "_type" : "matrix"
 }

and the data is:

result(i,j,1,1):
1  2  3  
4  5  6  
result(i,j,2,1):
7  8  9  
-1  -2  -3  
result(i,j,1,2):
-1  -2  -3  
-4  -5  -6  
result(i,j,2,2):
-7  -8  -9  
1  2  3  

Option 2: omit "_size" and data filed is nested arrays. Data format matches that of nested numpy arrays.

2D Matrix Example:

{
     _type: "matrix"
     _data: [[1, 2, 3], [4, 5, 6]]
}

and the data is:

[1, 2, 3
 4, 5, 6]

3D Matrix Example:

  {
   "_complex" : false,
   "_data" : [[[1,2,3],[4,5,6]],[[7,8,9],[-1,-2,-3]]],
   "_type" : "matrix"
 }

and the data is

result(i,j,1):
1  2  3  
4  5  6  
result(i,j,2):
7  8  9  
-1  -2  -3