Analysis Groups - Simulation object

Analysis objects allow you to group monitors (similar to structure groups) and to analyze that monitor data. For example, a set of monitors can be grouped together to form a closed box. From the raw monitor data, the group can calculate quantities like cross sections and far field projections. 

The files in this section were created using FDTD, but the same set up can be created using MODE Solution's propagator. Lumerical provides many built in analysis groups in our object library. Please press this button to open the online library of analysis groups, or see object library for more details.

 Analysis groups are container objects that can contain any simulation object and associated script functions which can be used to customize data analysis. For example, an absorption monitor group can be created with a power monitor, an index monitor, and the script function that calculates absorption from these objects. One can also automate an optimization/parameter sweep procedure using an analysis group made of structures/simulation regions/sources/monitors, and use the script function to update each parameter accordingly.

Analysis groups are created using the ADD ANALYSIS GROUP button in the layout editor. If you choose to edit an analysis object, then you will see that there are two tabs in the edit dialog box

• the SETUP TAB contains all the information about the monitors
• the ANALYSIS TAB contains the analysis routine and input and output parameters to the analysis routine.

 The figure above shows this example simulation file. The box of monitors will be used to measure the power absorbed in the particle.

Using Analysis Groups

Some important script functions which can be used in script files or the script prompt are:

set("object","parameter",value);         # to set the values of the group parameters
runanalysis;   # to run the analysis routines
getdata();     # to obtain raw matrix data from the monitors. 

Once an analysis routine has been run, any variables that were defined in the analysis script AND included in the results section of the VARIABLES tab can be obtained using the following commands:

getresults;  # get packaged dataset

Datasets are a way to package the result data (such as transmitted power) together with any associated information (such as the frequency vector).

Example:

Begin by opening and running the associated simulation, usr_transmission_box.fsp. Select the analysis group. Then enter the following script commands in the script prompt. The commands disable the option for the analysis object to create its own plots, runs the analysis routine, gets the results, finally sends them to the visualizer.

setnamed("trans_box","plot results",0);
runanalysis;
Pabs = getresult("trans_box","T");
?Pabs;
?Pabs.T;
?Pabs.f;
visualize(Pabs);

There is one result from this object: the power transmission out of the box (T) as a function of frequency.

You can also access the analysis object results through the graphical interface, as shown below:

Setup - Variables

The Setup - VARIABLES tab contains user properties, which are input parameters for the script that is located in the SCRIPT tab. The screenshot above shows the VARIABLES tab for the scattering box analysis group in the usr_transmission_box.fsp file. The scattering box consists of a rectangular box of power monitors. The widths of the monitors are given by the user properties x span, y span, and z span.

Setup - Script

Script commands are written in the Setup - SCRIPT tab. To find a list of script commands, see the Scripting Language.

Note that:

• the setup script can only be used to add, delete, edit or get the properties of objects in the group. For example, the command selectall; selects all of the monitors located inside of the group, while ignoring those outside.

• objects are created relative to the origin of the group. For example, if the origin was set to (5,0,0) microns in the variables tab, then the following commands would add a power monitor centered at (10,0,0) microns.

• the script uses the input parameters to set up the structure (the % operator allows you to use variables with spaces in their name)

• the setup script does not have access to workspace variables (those defined in the script prompt or in a script file). In addition, any variables defined in the setup script cannot be obtained from the script prompt or from a script file.
• the script can be debugged by pressing the TEST button. If there are no syntax errors or break commands in the script, you will see the line <script complete> in the script output. If there is a syntax error, the location of the error will be given in the script output. An example of an error message is: syntax error: prompt line: 38.
• the script is also run every time the OK button is pressed or a property of the analysis group is changed from the command line
• it is only possible to edit information in the SETUP tab in layout mode, the edited information will not be saved.
• usage of the "construction group" option means that objects are added from the script and changes to child objects will not be saved.

Analysis - Variables

The Analysis - VARIABLES tab contains all input parameters in the top half, and the output parameters (named results) in the bottom half. Parameters can be added and removed using the respective buttons. The screenshot above depicts the VARIABLES tab for the scattering box analysis group in the usr_transmission_box.fsp file. The VARIABLES tab contains two sets of variables and two buttons.

• PARAMETERS: This section contains all the input parameters
• RESULTS: The results section includes all the output parameters of the script. Once the analysis script that has been run, only the parameters that are both defined in the results section and initialized in the analysis script can be obtained from outside the analysis object.
• SAVE ANALYSIS button: Saves any changes made in the analysis tab (only in analysis mode)
• RUN ANALYSIS button: Runs the analysis script (only in analysis mode)

Analysis - Script

The Analysis - SCRIPT tab contains a customized analysis routine. The script has access to the input parameters defined in the VARIABLES tab, and can get data from any of the monitors located in the group. However, it cannot get data from monitors or sources not located inside that group. Scripts in analysis groups do not use the global variable space from the script prompt and script file editor. The results from the script can be obtained in the script prompt by setting up output parameters in the variables tab.

 The following buttons and regions are available in the SCRIPT tab:

• ANALYSIS SCRIPT: This is where the script commands are written. To find a list of script commands, see the Scripting Language section of the Reference Guide.
• ANALYSIS SCRIPT OUTPUT: Press the RUN ANALYSIS button to run the script. If there are no syntax errors in the script the SCRIPT OUTPUT will read <script complete>. In addition, the analysis script output will contain any results from the "?" script command.
• RUN ANALYSIS: Pressing the run analysis prompt runs the analysis script and saves the results. This button can only be pressed when the simulation is in analysis mode.
• SAVE ANALYSIS: Pressing this button saves changes made to the analysis script (even when in analysis mode). 

The SCRIPT tab of an analysis object is shown below. The note highlighted in yellow at the top of the dialog window says it is now in analysis mode.

Note that,

• entries in the ANALYSIS tab can be edited in both the layout and the analysis modes. In layout mode, there are two buttons in the lower right hand corner of the screen: OK and CANCEL. In analysis mode, any changes to the variables can be saved using the SAVE ANALYSIS button at the bottom of the tab. The RUN ANALYSIS button runs the analysis script located in the SCRIPT tab.
• once an analysis routine has run, the results (output parameters) become monitor data, which can be accessed from the script prompt or a script file in the same manner that monitor data is accessed for simple monitors. However, the analysis script can only obtain monitor data from the monitors in the group. It is not possible to select the monitors and get their properties or use variables defined in the setup tab.
• the analysis script does not have access to workspace variables (those defined in the script prompt or in a script file). In addition, any variables defined in the analysis script cannot be obtained from the script prompt or from a script file.
• if the RUN ANALYSIS button is pressed, the ANALYSIS SCRIPT OUTPUT will contain the results of the analysis script. Once the script has run to completion, if there are no syntax errors or break commands in the script, you will see the line <script complete> in the script output. If there is a syntax error, the location of the error will be given in the script output. An example of an error message is: syntax error: prompt line: 38.
• the analysis script makes use of the parameters, for example

• the results variables are defined in the script, for example

• print variables or comments to the analysis script output by prefacing the lines with the ? operator, the value computed for the output parameter is printed in the Analysis Script Output portion of the window. If you run the analysis from the script prompt or a script file, these lines are not printed to the script prompt. For example, the first comment in the analysis script output comes from the following line in the analysis code:

• if you need to stop a script while it is running, press the ESC key on the keyboard. This will stop the analysis script from running, and close the edit dialog window.

Results

Various custom results are returned by the analysis group objects.

See also

Monitors and analysis groups, addanalysisgroup (script command), Structure groups, Object Library