• Description
• Install
• Lumerical script usage
  • Constructing a simulation
  • Analyzing a simulation
• Remote-host execution
  • Lumerical dispatch
  • Remote-host queueing and execution
• MATLAB script usage
  • Generating Lumerical scripts with MATLAB
  • Analysis of Lumerical sweeps
• MATLAB templating system for Lumerical script construction and analysis

This repository consists of a set of:

• Lumerical scripts for rapid geometry and simulation definition.
• Bash scripts for remote-host execution on a dedicated server running Linux.
• MATLAB scripts for parametrically sweeping and analyzing Lumerical structures.

These three components can be used separately or in combination, and are not interdependent for most functionality.

Note: this library is fully functional, but the documentation has not been thoroughly checked and may be missing a few options.

• Clone this repository.
• Lumerical
  • Either add the common folder to your Lumerical path, or prepend all files using it with addpath('/path/to/common');.
  • Update the first line of all files in the common folder that contain addpath('/home/nickersonm/lumerical/common'); to the correct path, if different from /home/nickersonm/lumerical/common and you have not added it to your Lumerical path.
  • Sample Lumerical scripts are in common/templates/.
• Remote-host execution
  • Copy remote-dedicated to the selected Linux remote host and mark as executable.
  • Dependencies
    • PuTTY is used in the provided batch files for Windows client Lumerical dispatch, but can be easily customized.
    • xvnc is required if using remote-side script execution; a common and standalone variant is TigerVNC.
    • pueue is required if using remote-side queuing instead of local Lumerical queue management, and requires pueue groups "cad", "engine", and "fdtd-engine" with execution limits as desired.
  • Verify the remote host has Lumerical installed and correctly licensed.
• MATLAB
  • Add the MATLAB folder to your MATLAB path.
  • Dependencies
    • appendstruct, figureSize, figureTitle, smoothGrid, and titlewrap functions from my MATLAB-utilities repository.
    • 3rd party smoothn and subplot_tight functions.
  • Sample data collection routines are present in the ./routines/ folder.

The set of Lumerical scripts in common/ interacts with eachother to build epitaxy, etch geometry, and simulation entities given a brief description. With etchDef and epitaxy variables provided, lum_setup can then be called and the appropriate geometry and simulation will be created. The minimum required variables are:

• etchDef: cell list of etches, each element being a structure with fields:
  • .depth etch depth from top of epitaxy
  • .width width of the etch region, unused if .start is specified
  • .length length of the etch region, unused if .end is specified
• epitaxy: cell list of epitaxial layers, top-down, each element being a structure with fields:
  • .material epitaxial material; currently supported: any built-in, 'AlGaAs', 'SiO2', 'SiN' , 'InGaP', 'InGaAs', 'GaAsP', 'LiNbO3_x', 'LiNbO3_z', 'AlOx', 'Au', 'Si'
  • .thickness layer thickness

Details can be found below or in the script and template headers. Of special note is that the epitaxy can include quantum well or MQW definitions with thicknesses specified by .qw instead of .thickness, and the MQW gain results will be calculated and substituted into a material covering the MQW region.

Some minimal examples are:

A varFDTD simulation of a Si waveguide surrounded by SiN:

addpath('/home/nickersonm/lumerical/common');   # Replace as necessary, optionally adding multiple potential locations for different environments

# Define 220 nm SOI epitaxy
#   'guiding' hints to center simulation on that layer
epitaxy = {
    {'material': 'Si', 'thickness': 0.220, 'guiding': 1},
    {'material': 'SiO2', 'thickness': 2}
};

# Define waveguide with s-curve
#   This is an etch definition, 'wgspace' automatically treats it as a waveguide definition and generates left and right etches
etchDef = {
    {'depth': 0.5, 'wgspace': 10, 'start': [0, -2, 1], 'end': [20, 2, 1]}
};

# Background and etch material is SiO2
etchMat = 'SiO2';

# Change wavelength to 1300 nm, default 1030 nm is below Si bandgap
lambda = 1.3;

# Restrict to top instead of full epitaxy
simZ = [-1, 0.2]; 

# Reduce simulation Y-extent; default is full etch extents
simY = 8;

# Build simulation
lum_setup;

A MODE simulation of GaAs deep ridge waveguide:

addpath('/home/nickersonm/lumerical/common');   # Replace as necessary, optionally adding multiple potential locations for different environments

# Define basic AlGaAs/GaAs epitaxy
epitaxy = {
    {'material': 'AlGaAs', 'x':0.3, 'thickness': 1},
    {'material': 'GaAs', 'thickness': 1, 'guiding': 1},
    {'material': 'AlGaAs', 'x': 0.2, 'thickness': 2},
    {'material': 'GaAs', 'thickness': 10, 'name': 'Substrate'}
};

# Define simple ridge waveguide
#   This is an etch definition, 'wgspace' automatically treats it as a waveguide definition and generates left and right etches
etchDef = {
    {'depth': 3, 'wgspace': 10, 'width': 2, 'length': 10}
};

# Run as YZ MODE simulation
sim2D = 1;

# Restrict to guiding layer ±1 µm instead of full epitaxy
simZ = 1; 

# Reduce simulation Y-extent; default is full etch extents
simY = 4;

# Build simulation
lum_setup;

Execute the script files in the appropriate Lumerical environment - in the case of these examples, Lumerical MODE.

After constructing the simulation and geometry, and optionally executing it, the lum_analyze script can be run to characterize a number of metrics and export the results to a MATLAB file. If the simulation does not yet have results calculated, it will be run before export. Details can be found below and in the lum_analyze script header, but a minimal nontrivial example is:

addpath('/home/nickersonm/lumerical/common');   # Replace as necessary, optionally adding multiple potential locations for different environments

# Compare MODE results to a 2 µm MFD gaussian, e.g. for coupling overlap
outField = {'pol': 0, 'mfd': 2};

# Save results to MATLAB file
matFile = 'mode_test.mat';

# Run analysis
lum_analyze;

# Look at overlap with output field, reported as [mode#, overlap, loss]
?[results.modeN, results.Pout, results.modeL];

Further examples can be found in the common/templates/ folder.

Note: remote-slurm is not in a cohesive state and is not currently documented here. It should be functional with some customization to your environment, and is provided as a template. Comments describing the purpose and usage are provided in the assorted scripts.

The remote-dedicated set of scripts simplifies the execution of Lumerical simulations on remote hosts. This can work via:

• Simple dispatch from a local Lumerical instance executing work files. Batch files for Windows are provided.
• Remote queueing and execution of script definitions tied in to the common/ Lumerical scripts.
  • This can be combined with the MATLAB scripts for easy parameter search execution and analysis.

The scripts should all be copied to ~/lumerical/ on the remote host, or the path can be altered in the headers of each script.

Note: lumerical_setup.sh is not used during execution, but provides an optional brief guide to installing Lumerical and pueue on a Debian host.

The run_<solver>.sh set of bash scripts will execute simulation files for the appropriate solver. Verify that the paths for the CAD and ENG variables are correct. To use, copy a simulation file to the remote host and run, e.g.:

./run_fde.sh test.lms

A set of dispatch-<solver>.cmd files are also provided to automate the dispatch, execution, and retrieval from Lumerical clients on Windows. Before use, modify them to use the appropriate PuTTY session in the login variable, or otherwise change the SSH command. A few-line shell script can provide equivalent functionality on Linux clients.

To dispatch jobs directly to the remote host from a Lumerical instance running, add a a new remote 'Resource' with the 'Custom' job preset. Select 'bypass mpi on localhost' and 'no default options', entering in the appropriate dispatch-<solver>.cmd file. Press 'Run tests' to verify functionality.

The Lumerical client will now treat the remote host as a valid solver, and queue jobs on it when executing a local batch.

For further flexibility including automated simulation file generation from scripts in the common/ Lumerical scripts, Q_parallel.sh and Q_selected.sh can be used to submit entire directories of script files for generation, execution, and analysis at once. These use the pueue daemon with pueue groups "cad", "engine", and "fdtd-engine" - set group execution limits as desired. pueue_remaining.sh is provided for easily monitoring queue progress.

This integrates nicely with the MATLAB scripts for executing large sweeps at once, or overnight, on a dedicated solver machine.

Verify that the paths for the CAD and ENG variables are correct in the run_<solver>.sh scripts, that pueue is installed successfully with the groups "cad", "engine", and "fdtd-engine", that xvnc is a valid command, and that Lumerical is installed and properly licensed. Copy the common/ scripts to the remote host's /home/nickersonm/lumerical/common directory.

With one or more .lsf Lumerical scripts on the remote machine, the scripts can then be used simply:

# Run one FDE simulation defined with a script
~/lumerical/Q_selected.sh fde ~/lumerical/tmp/test.lsf

# Build the simulation file, but don't execute or prepare analysis files
BUILDONLY=1 ~/lumerical/Q_selected.sh fde ~/lumerical/tmp/test.lsf

# Build the simulation file, don't execute, but prepare analysis files
PREBUILD=1 ~/lumerical/Q_selected.sh fde ~/lumerical/tmp/test.lsf

# Manually execute the one simulation file
~/lumerical/run_fde.sh ~/lumerical/tmp/test.lms

# Analyze previously prepared and executed script
POSTBUILD=1 ~/lumerical/Q_selected.sh fde ~/lumerical/tmp/test.lsf

# Run a bunch of scripts forming a sweep of a parameter
~/lumerical/Q_parallel.sh fde ~/lumerical/tmp/sweeps/test_*.lsf

# Also run a CHARGE analysis of the same scripts
#   Temporary *_working_<solver>.lsf Lumerical scripts will have been created by the previous command, so don't queue those
~/lumerical/Q_parallel.sh charge ~/lumerical/tmp/sweeps/test_(^*_fde).lsf

# Watch remaining task count
~/lumerical/pueue_remaining.sh

Dependencies are appendstruct, figureSize, figureTitle, smoothGrid, and titlewrap functions from my MATLAB-utilities repository and the 3rd party smoothn and subplot_tight functions.

The set of MATLAB functions and scripts in MATLAB/ provide both a script-construction template for parameter searches and various utilities for analyzing results:

• General photonics utility functions
  • fieldModeArea: effective modal area of a given field
  • fieldMsq: M^2 calculations for x-normal fields, computed by the method in https://doi.org/10.1109/JLT.2005.863337
  • fieldOverlap: complex overlap between two fields
  • analyticalModelGaAs: GaAs phase modulation and optical absorption model given an optical and electrical field. Assumes pure GaAs.
• Utility functions for dealing with lum_analyze results:
  • plotMQW: plot results from a mqw structure that is generated by specifying .qw layers in the epitaxy
  • plotResultYZ: plot FDE and/or CHARGE results, optionally both simultaneously
  • plotResult3D: plot x-propagation results from EME, varFDTD, or FDTD simulations
• A set of scripts to generate many Lumerical scripts sweeping specified parameters, optionally enqueue to a remote host, and analyze the results: buildScriptAndEnqueue, buildSweepAndEnqueue, retrieveCompleted, and sweepPlots_Base

The first two categories are fairly self explanatory, with further documentation provided in the function headers.

First make sure to update the dirCommon variable in the header of buildScriptAndEnqueue.

The functions buildScriptAndEnqueue and buildSweepAndEnqueue enable easy sweeping of any parameter(s) defined in a Lumerical script by generating many variants of such script. Simply pass a sweep name, the script contents as a string, and a cell list consisting of variable name and value pairs, such as:

% Sweep the "x" variable in "myscript.lsf"
script = string(fileread("myscript.lsf"));
buildSweepAndEnqueue("test_sweep", script, ["x", linspace(0,10,101)], 'submitjob', 1, 'session', 'PuTTY-session-name');

Optionally alter the default session parameter to point to the correct PuTTY session, or even change the plink and pscp parameters to use SSH instead.

For large sweeps, it may be faster to simply generate the script variants locally:

buildSweepAndEnqueue("test_sweep", script, ["x", linspace(0,10,101)], 'submitjob', 0);

Then copy the files to the remote host and queue them all at once:

~/lumerical/Q_parallel.sh fde ~/lumerical/tmp/sweeps/test_sweep/*.lsf

For either method, the completed results (.mat files) can either be manually moved back to the original sweep directory, or retrieveCompleted() can be used to read the locally-generated log of submitted files, submitted.log.

Analysis can be performed in MATLAB on many .mat file results of Lumerical sweeps with sweepPlots_Base.m. Optional variables are described in the file header, but required variables are:

• componentName: the name of the test, for use in plots
• outDir: the directory to write results to
• resFiles: the list of result files as an array of strings, without extensions
• resExts: the extension(s) of result files
  • These two are combined to look for actual files; for combined electro-optical results incorporating analyticalModelGaAs, a list of files without the typical _<solver>.mat tail can be provided for resFiles and ["_FDE.mat", "_CHARGE.mat"] can be set for resExts
• params: a list of simulation parameters via strings to eval, typically based on the results which are loaded into variable R, such as R.wWG and R.outField.pol
• metrics: a list of result metrics via strings to eval, in the same manner, such as min(R.results.modeL) for the lowest mode loss or R.results.modeL(find(R.results.Pout == max(R.results.Pout), 1)) for the loss of the highest-output-overlap mode.

Each file will be analyzed for all params and metrics, and results will be plotted for any that vary across the group. FDE results have additional default processing added, visible in the loadDataFile function of sweepPlots_Base.m.

Included in the MATLAB/template/ folder are a set of sample scripts for a MATLAB-based Lumerical script templating system for geometry construction and analysis. A typical Lumerical script has been broken into several parts, several of which can be easily swapped out to define alternate components. This allows easy assembly of a set of related simulations, such as multiple components based on the same process and epitaxy.

The provided Lumerical script pieces are in the MATLAB/template/lsf/ folder, and include:

• 10_header_template.lsf to provide a standard header.
• 20_etch_<material>_WG.lsf to provide a standard initial waveguide definition and defaults for a given epitaxy; this is something that is likely to be typical across an entire process.
• 22_etch_<material>_<component>.lsf to provide specific component definitions that either build on or replace the _WG definition.
• 30_epi_<epi>.lsf to define the specific epitaxy.
• 40_inst_<material>.lsf to define typical 'instrumentation' used in an epitaxy, e.g. ports or common variations of options.
• 90_footer_template.lsf to provide a standard conclusion to the script, including calling lum_setup;.

Each component is assigned a directory, and then consists of 3 MATLAB files:

• def_<material>_<component>_<epi>.m to define the component by assembling the whole script file and setting default variables for buildSweepAndEnqueue.
• sweep_<material>_dev_<epi>.m that loads the definition, sets custom sweep parameters, and then calls buildSweepAndEnqueue to create a sweep of Lumerical scripts, that can then be processed with the remote-host execution scripts on a remote host.
• plot_<material>_dev_<epi>.m that loads the definition, sets analysis variables, and then calls sweepPlots_Base.m to load all resulting .mat files and analyze the sweep results.

In my usage, the sweep_*.m files are fairly short with most lines being commented out past sweeps for easy reference, and the remainder defining the most recent sweep, such as:

sweep = {"sim2D", 2, ...
         "wWG1", [1.5, 2.0, 3.0], ...
         "wgBR", linspace(50, 300, 51)};
sweepName = "AR8_dev_Sbend_varFDTD_1";
buildSweepAndEnqueue(scriptName, script, sweep, 'allvars', setVars, 'sweepname', sweepName, ...
                     'submitjob', 0, 'randomize', 0*0.02);

By convention, directories starting with dev are 3D photonic devices or components like MMIs and s-bends, analyzed with varFDTD and 3D FDTD, while directories starting with wg are waveguide cross-sections analyzed with MODE and sometimes CHARGE.

With this templating system, the workflow for developing a new epitaxy, process, and PIC component becomes:

1. For active epitaxies, possibly develop MQWs with MQW_peaks.
2. Define possible epitaxy and basic waveguide structure.
3. Develop epitaxy with epi1D or similar to determine the optimal epitaxy parameters.
4. Optimize etch depths and cross sections with wgPassive, wgMod, and wgActive.
5. Develop waveguide components by creating a new 22_etch_<material>_<dev>.lsf definition and dev<Component> set of MATLAB scripts for each one and sweep parameters.

Simply exploring the provided scripts may be helpful for a better understanding.