Accessing data

getresult - Script command

FDTD MODE DGTD CHARGE HEAT FEEM INTERCONNECT

Get results from simulation objects. Results will be returned as datasets.

Syntax	Description
?getresult("monitor_name");	Returns the names of all the results for the monitor. All the dataset and scalar matrix results will be returned in this case.
R = getresult("monitor_name","T");	Returns the result T from the monitor. T is a dataset.

Examples

This example shows how to get the electric field dataset from a monitor. We then apply a number of operations to the dataset, such as finding the maximum |E|^2 value, viewing the dataset with the visualizer, and creating a plot of Ex at the first frequency point.

Note that E is a dataset, rather than a simple matrix based variable. Data within the dataset can be accessed with the '.' operator, as shown below.

# get Electric field dataset
E=getresult("monitor","E");
# output dataset value to prompt
?E;
# check size of position vectors and data matrices
?size(E.f);
?size(E.Ex);
# find maximum |E|^2 value 
?max(E.E2);
# view dataset with visualizer
visualize(E);
# select first frequency point of Ex data, then create plot
Ex = pinch(E.Ex,4,1); 
image(E.x*1e6,E.y*1e6,Ex,"x (um)","y (um)","Ex");
 E vs x, y, z, lambda/f
 result: 
 5 1 
 result: 
 343 255 1 5 
 result: 
 3.223651 

getdata - Script command

FDTD MODE DGTD CHARGE HEAT FEEM INTERCONNECT

Get raw data from a simulation object. In most cases, it is more convenient to get a complete dataset with  getresult, rather than getting individual data elements with getdata.

Remember to run the simulation before using getdata.

For FDTD and MODE:

Syntax	Description
?getdata;	Returns names of all objects with data.
?getdata("monitor")	Returns list of of data within the simulation object.
out = getdata( "monitor", "dataname");	Gets data from a monitor. For example, you can use Ex = getdata("monitor1","Ex"); to get the Ex field data from monitor1.
out = getdata( "monitor", "dataname", option);	The optional argument, option, can have a value of 1 or 2. If it is 2, the data is unfolded where possible according to the symmetry or anti-symmetric boundaries if it comes from a monitor that intersect such a boundary at x min, y min or z min. The default value of option is 2. For Propagator simulations in MODE, this options also allow users to choose whether to expand the data to the correct size for dimensions where the field component is zero. Option 1 will return a singleton value of 0 for the field component in that dimension, and option 2 will return a matrix (composed of zeros) that matches the size of the other field components.

For CHARGE, HEAT, DGTD, FEEM:

Syntax	Description
?getdata;	Returns names of all objects with data.
?getdata("monitor")	Returns list of of results within the simulation object.
?getdata( "monitor", "result");	Returns list of of data within the simulation object result.
out = getdata( "monitor", "result", "dataname");	Gets the simulation data.

For INTERCONNECT: The getdata command is available in INTERCONNECT for compatibility with other Lumerical products, but it's best to use the getresult script function to access INTERCONNECT simulation data.

Examples

This example shows how to use getdata to check which data is available.

?getdata;
?getdata("monitor");
> monitor
> source
> 
> x y z surface_normal dimension f Ex Ey Ez
> Hx Hy Hz power 

Next, we use getdata to create a image plot of Ex(x,y). We also show how getresult can be used to create the same figure.

# get raw data with getdata
x=getdata("monitor","x");
y=getdata("monitor","y");
z=getdata("monitor","z");
f=getdata("monitor","f");
Ex=getdata("monitor","Ex");
# select first frequency point of Ex data, then create plot
?size(Ex);
Ex = pinch(Ex,4,1); 
image(x*1e6,y*1e6,Ex,"x (um)","y (um)","Ex");
# use getresult to get all of the E field data in a single command
E=getresult("monitor","E");
# select first frequency point of Ex data, then create plot
?size(E.Ex);
Ex = pinch(E.Ex,4,1); # select first frequency point to plot
image(E.x*1e6,E.y*1e6,Ex,"x (um)","y (um)","Ex"); 

Get a list of data in the 'Device region' object, then get the 'n' carrier concentration data.

?getdata("Device region");
?getdata("Device region","active");
n=getdata("Device region","active","n");
?size(n);
> active drain source
> n p Ei Ec Ev Efn Efp log10(N) mun mup 
> result: 
>  2826 1 9 1 

 

getelectric - Script command

FDTD MODE

Returns the sum of the amplitude squares for all electric field components, i.e. it returns |Ex| 2 +|Ey| 2 +|Ez| 2 .

Syntax	Description
out = getelectric( "monitorname");	Returns |Ex| 2 +|Ey| 2 +|Ez| 2 from the monitor.
getelectric( "monitorname", option);	The optional argument, option, can have a value of 1 or 2. If it is 2, the data is unfolded where possible according to the symmetry or anti-symmetric boundaries if it comes from a monitor that intersect such a boundary at x min, y min or z min. The default value of option is 2.

Examples

This example creates an image plot of |E|^2 for a z-normal frequency monitor in the x-y plane.

E2=getelectric("output");
x=getdata("output","x");
y=getdata("output","y");
image(x,y,E2);

getmagnetic - Script command

FDTD MODE

Returns the sum of the amplitude squares for all magnetic field components, i.e. it returns |Hx| 2 +|Hy| 2 +|Hz| 2 .

Syntax	Description
out = getmagnetic( "monitorname");	Returns |Hx| 2 +|Hy| 2 +|Hz| 2 from the monitor.
getmagnetic( "monitorname", option);	The optional argument, option, can have a value of 1 or 2. If it is 2, the data is unfolded where possible according to the symmetry or anti-symmetric boundaries if it comes from a monitor that intersect such a boundary at x min, y min or z min. The default value of option is 2.

Examples

This example creates an image plot of |H|^2 for a z-normal frequency monitor in the x-y plane.

H2=getmagnetic("output");
x=getdata("output","x");
y=getdata("output","y");
image(x,y,H2);

 

runanalysis - Script command

FDTD MODE DGTD CHARGE HEAT FEEM INTERCONNECT

Runs the analysis script in analysis objects.

Note: Scripts that already have data are not re-run; to re-run a script, first clear data using clearanalysis.

Syntax	Description
runanalysis;	Runs the analysis scripts in all analysis objects in the simulation file. This function does not return any data.
runanalysis("group name");	Runs the analysis script in the analysis object named "group name". This function does not return any data.

clearanalysis - Script command

FDTD MODE DGTD CHARGE HEAT FEEM INTERCONNECT

Clears analysis object results. This data is also cleared by switching from Analysis Mode to Layout Mode.

Note: The analysis object results are calculated with the runanalysis command.

Syntax	Description
clearanalysis;	Clears analysis object results. This function does not return any data.
clearanalysis( "name1", "name2", ...);	Clears data from specific analysis objects.

 

havedata - Script command

FDTD MODE DGTD CHARGE HEAT FEEM

Used to see a simulation object (such as a monitor) has any data. This command is very similar to haveresult, but is intended to be used with the getdata command, rather than getresult.

Syntax	Description
havedata;	Returns 1 if any simulation objects have raw data, and 0 if none have any raw data.
havedata("name");	Returns 1 if "name" has raw data, and 0 if it does not have any raw data.
havedata("name","data");	Returns 1 if "name" has the raw data named "data", and 0 if it does not have that data.

Examples

The following example shows the output of ?getdata, when it is called after a simulation has been run. There is a monitor group in the simulation that has an analysis script file and at least one result parameter. Before the analysis script is run, the monitor group does not have data, after it is run the monitor group has data that is stored in the result parameter.

?getdata;
local sources:
 source2 
local monitors:
 monitor group 
?havedata("monitor group");
result: 
0 
runanalysis("monitor group");
?havedata("monitor group");
result: 
1  

haveresult - Script command

FDTD MODE DGTD CHARGE HEAT FEEM INTERCONNECT

Used to see a simulation object (such as a monitor) has any results.

Note: This command is very similar to havedata, but is intended to be used with the getresult command, rather than getdata.

Syntax	Description
haveresult;	Returns 1 if any simulation objects currently have any results.
haveresult("name");	Returns 1 if "name" has any results, and 0 if it does not.
haveresult("name","data");	Returns 1 if the "name" has a result named "data", and 0 if it does not.

Examples

The following example shows the output of ?getresult, when it is called after a simulation has been run. There are several monitors and a source with available results.

?getresult;
time
T
R
ModeSource
?haveresult;  # check if results are available
result: 
1 
?haveresult("T"); # check if 'T' has any results
result: 
1 
?haveresult("TT"); # check if 'TT' has any results 
result: 
0 
?haveresult("T","E"); # check if 'T' has a result named 'E'
result: 
1  

 

getvariable - Script command

INTERCONNECT

Returns the value of a workspace variable, if the value is not found it returns a ‘default’ value.

Syntax	Description
out= getvariable (property,default);	Returns the value of a workspace variable, if the value is not found it returns a ‘default’ value.

Examples

?getvariable("variable");

copydcard - Script command

FDTD MODE

Will create a global copy of any d-card currently in memory.

Syntax	Description
copydcard( "name");	Will create a global copy of any d-card currently in memory called "name". By default, the new name will be "::global_name". For example, copydcard("mode1"); sends mode1 to the deck, named global_mode1. This function does not return any data.
copydcard( "name", "newname");	Will create a global copy of any d-card currently in memory called "name". The new name will be "::newname".

Examples

Sending modes to the d-card and run overlap analysis, eg, in the FDE solver

copydcard("mode1","test_mode1");
copydcard("mode2","test_mode2");
?overlap("test_mode1","test_mode2");

Sending field profiles to the d-card and run overlap analysis, eg, in the FDTD solver

copydcard("::model::R","test_mode1"); # for the fields recorded by R, where R is the monitor name
copydcard("::model::T","test_mode2"); # for the fields recorded by T, where T is the monitor name
?overlap("test_mode1","test_mode2");

 

cleardcard - Script command

FDTD MODE

Clears global d-cards. Only global d-cards are cleared. Local d-cards are associated with the current simulation and can only be cleared by switching from Analysis Mode to Layout Mode.

Syntax	Description
cleardcard;	Clears all the global d-cards. This function does not return any data.
cleardcard( "name1", "name2", ...);	Clears any number of specified d-cards.

mcfit - Script command

INTERCONNECT

The script command runs the multi-coefficient fitting for a file containing multiple frequency dependent transmission values.

Syntax

Description

mcfit(filenamein,filenameout,npoles,tolerance,automatic) ;

Runs the multi-coefficient fitting for a file containing multiple frequency dependent transmission values (filenamein), where each transmission depends on an operating point, and generates a file containing the fitting data (filenameout). The number of poles and the fitting tolerance are defined by parameters npoles and tolerance respectively. The parameter ‘automatic’ define if the fitting will use the user defined npoles or estimate the number of poles automatically.

 

mczfit - Script command

INTERCONNECT

Fits a variable gain filter to a family of gain curve data, where each curve in the family corresponds to a value of carrier density, producing a file of gain filter coefficients to be used by the TWLM element.

Syntax

Description

out=mczfit(inputfilename, outputfilebase, centrefrequency, samplerate, maxnumcoef, tol, maxiter, rectangular, rolloff);

Fits a variable gain filter to a family of gain curve data, where each curve in the family corresponds to a value of carrier density, producing a file of gain filter coefficients to be used by the TWLM element. " inputfilename " is a string containing the name of the input data file (including the suffix).  The format of the input data is specified below. " outputfilename " is a string containing the name (excluding the suffix) of the file containing the gain filter coefficients. " centrefrequency " is the center frequency of the frequency band for which the gain fitting is to be performed. " samplerate " is the bandwidth of the frequency band for which the gain fitting is to be performed. " maxnumcoef " is the maximum number of filter coefficients to be used to fit to the data. " tol " is the tolerance " rectangular " is a bool value, it defines the data format. "true" represents 'real' and 'imaginary' format; "false" represents polar coordinate format with 'amplitude' and 'phase' " maxiter " is the maximum number of iterations used in fitting to the data. " rolloff " is the fraction of the bandwidth over which the input frequency data is rolled off to the average of the two values at the band edges.

Implementation detail

The format of the data file is as follows:

(1, Nc)
carrierdensity_1, carrierdenisty_2, …, carrierdensity_Nc
(Ns, Nc+1)
freq_1gain_1_1gain_1_2…gain_1_Nc
freq_2gain_2_1gain_2_2…gain_2_Nc
……………
freq_Nsgain_Ns_1gain_Ns_2…gain_Ns_Nc

where the parameters are defined in the table below:

Nc	The number of gain curvers
Ns	The number of frequency samples
carrierdensity_j	The carrier density corresponding to the j-th gain curve
freq_i	The i-th frequency sample
gain_i_j	The gain value for the i-th frequency sample in the j-th curve

Notes:

1. The frequencies must be ordered in ascending order, such that frequency_1 is  the lowest and frequency_Ns is the highest
2. The gain curves and carrier densities must be ordered in descending order of carrier density. That is, carrierdensity_1 is the largest carrier density and carrierdensity_Nc is the lowest carrier density, and gain_i_1 is  the gain  for the  largest carrier density and i-th frequency sample and gain_i_Nc is the gain for the lowest carriest density and i-th frequency sample.

The return values are listed in the table below:

fit_out	A struct with fields
frequency	A column vector of the frequency sample points
input	A matrix with the column vectors containing the input frequency response to be fit for each operating  point
operatingPoint	A row vector containing the input operating points corresponding to the input frequency responses  in the columns of the input matrix
operatingPointInterpolated	A row vector containing values of the linearly interpolated values of operating points between the  input values of operating points
output	A matrix with the column vectors containing the fit frequency response for each input operating  point
outputInterpolated	A matrix with the column vectors containing the fit frequency response for each linearly interpolated  operating point contained in row vector ‘operatingPointInterpolated’.

Note:

This script function also produces a gain filter coefficients to be used by the TWLM element. The name of the file will be outputfilename.mcfdb.

Example

Please refer to the application example page  Gain Fitting  for the detailed usage of this command.

 

simulationdiverged - Script command

FDTD

In layout mode, check whether the simulation reached the divergence checking auto shutoff threshold.

Syntax	Description
out=simulationdiverged;	Returns 1 if the simulation reached the auto shutoff max threshold, 0 otherwise.

tdecq - Script command

INTERCONNECT

Calculates the figure of merit of the PAM-4 transmitters knows as Transmitter and Dispersion Eye Closure Quaternary (TDECQ) as defined in IEEE Standard 802.3 2018. Depending on the input parameters it can also return other properties of the input signal, as well as convergence information.

Syntax

Description

out=tdecq(signal, reference, parameter);

Calculates the figure of merit of the PAM-4 transmitters knows as TDECQ as defined in IEEE Standard 802.3 2018. Depending on the input parameters it can also return other properties of the input signal, as well as convergence information. The specification of the input arguments are as follows: signal: the signal captured by the data acquisition device (e.g., storage oscilloscope) of the measured set-up prescribed in IEEE Standard 802.3 2018. The signal needs to be a 1D matrix. reference: the undistorted test Short Stress Pattern Random – Quaternary (SSPRQ) sequence (for PAM-4) driving the transmitter, scaled and biased to match the input signal. The reference needs to be a 1D matrix. parameters: a struct containing the required and optional fields in the table below.

Parameter	Default	Default value	Type	Unit	Description
samples_per_UI	required		scalar		The number of samples per unit interval (UI), also known as the number of samples per symbol.
symbol_rate	required		scalar	Hz	The symbol rate of the signal.
filter_bandwidth	required		scalar	Hz	The 3dB bandwidth of the Bessel-Thompson filter applied after optical to electrical conversion in the setup prescribed in the Standard. It is also referred to as the channel bandwidth.
num_bins	optional	64	scalar		The number of bins in the histograms specified in the standard.
Pavg	optional	-1	scalar	Watts	The average power of the input signal.
outer_OMA	optional	-1	scalar	Watts	The outer modulation amplitude, outer of the input signal, as specified in the standard.
tap_spacing	optional	samples_per_UI	scalar	Watts	The tap spacing of the feed forward equalizer (FFE) prescribed in  the standard, in units of samples.
sigma_s	optional	0	scalar	Watts	Standard deviation of the noise added by the optical to electrical conversion process  and oscilloscope combination.
ser_search_limit_iter	optional	40	scalar		The limit on the number of iterations of the damped binary search that  finds the amount of noise that needs to be added to exactly  yield the bit  error rate (BER) prescribed in the standard.
ser_search_rel_tol	optional	0.01	scalar		The relative tolerance at which the aforementioned damped binary search will  terminate.
ser_search_limit_update_ratio	optional	0 (no limit)	scalar		The maximum step that may be taken in the aforementioned damped binary search.
ser_opt_limit_iter	optional	1000	scalar		The limit on the number iterations that the FFE tap-weight optimizer may take in optimizing the symbol error (SER) for a given amount of added statistical noise.
ser_opt_xtol	optional	1e-6	scalar		The tolerance on the weights for the tap-weight optimizer.
ser_opt_ftol	optional	1e-6	scalar		The tolerance on the SER for the tap-weight optimizer.
mmse_only	optional	0	scalar		A non-zero value will cause the function to perform only a linear optimization of the tap weights by fitting the equalized signal to the reference signal.
report	optional	0	scalar		The report level. report = 0: only the value of TDECQ will be returned by the function. 0 < report < 1:a struct with the following fields will be returned by the function: TDECQ, outer_OMA, Pavg, eq_taps report > 1: a struct with the fields described below will be returned by the function

Report results struct format:

TDECQ	the calculated value of TDECQ in dB
outer_OMA	the measured value of OMAouter on the input signal as defined in the standard in Watts
Pavg	the average power of the input signal as defined in the standard in Watts
eq_taps	the optimized values of the FFE tap weights in a matrix
SER	the optimized symbol rate
sigmaG	the standard deviation of the amount of noise that can be added to yield the BER prescribed in the standard
search_iterations	the number of iterations executed in searching to for the standard deviation of the amount of noise that can be added to yield the BER prescribed in the standard
SER_window_offset	the offset of the windows applied to the eye diagram, in units of samples,  in forming the histograms used to calculate the SER. please refer to the standard for more detailed information

Example

This example calculates the TDECQ result for the PAM4 signal in the TDECQ example:

switchtodesign;

# define reference signal
lenSSPRQ=65535;
numSSPRQ=1;
nbins=400;
signalRate = 26.5625e9;
besselFilterBW = 13.28125e9;
symSSPRQ = zeros(lenSSPRQ,1);
strSSPRQb0 = getnamed("TDECQ_1", "strSSPRQb0");
strSSPRQb1 = getnamed("TDECQ_1", "strSSPRQb1"); 

for(i=1:lenSSPRQ){
   symSSPRQ(i) = str2num(substring(strSSPRQb0,i,1)) + 2*str2num(substring(strSSPRQb1,i,1));
}

# define TDECQ calculation parameters
sampleRate = getnamed("::Root Element", "sample rate");
bitRate = getnamed("::Root Element", "bitrate");
samplesPerBit = round(sampleRate/bitRate);
params = struct;
params.samples_per_UI = round(sampleRate/bitRate);
params.symbol_rate = signalRate;
params.filter_bandwidth = besselFilterBW;
params.num_bins = nbins;
params.sigma_s = 0.0;
params.ser_search_limit_iter = getnamed("TDECQ_1", "SER search max iter");
params.ser_search_relative_tolerance = 0.01;
params.ser_search_limit_update_ratio = 0;
params.ser_opt_limit_iter= getnamed("TDECQ_1", "SER optim max iter");
params.ser_opt_xtol = 1e-6;
params.ser_opt_ftol = 1e-6;
params.mmse_only = 0;
params.report =1;

# run and get signal
run;
runanalysis;
signal = getresult("TDECQ_1", "Signal 1");
signal = signal.power;
 
# calculate TDECQ
TDECQ_result = tdecq(signal,symSSPRQ,params);

 

outeroma - Script command

INTERCONNECT

Returns the quantity OMAouter

as specified in IEEE Standard 802.3 2018.

Syntax	Description
out=outeroma(signal, samplespersymbol, reference) ;	Returns the quantity OMAouter

as specified in IEEE Standard 802.3 2018. It is essentially the amplitude of the signal pattern.

The specification of the input arguments is as follows:

signal: a 1D matrix

samplespersymbol: the number of samples per unit interval (UI) or symbol

reference: the reference PAM-4 test symbol pattern

The function returns the OMAouter

.

Example

This example calculates the OMAouter

for the PAM4 signal in the  Optical PAM-4  example:

clear;
switchtodesign;

# reset simulation parameters to include more bits in the simulation
ignoreBit = 8;
timeWindow = 6.5536e-7;
sampleRate = 2e11;
Nsamples = 131072;
setnamed("EYE_REF", "ignore start periods", ignoreBit);
setnamed("EYE_REF", "ignore end periods", ignoreBit);
setnamed("VSA_1", "ignore start symbols", ignoreBit);
setnamed("VSA_1", "ignore end symbols", ignoreBit);
setnamed("::Root Element", "simulation input", "time window");
setnamed("::Root Element", "time window", timeWindow);
setnamed("::Root Element", "sample rate", sampleRate);
setnamed("PRBS Generator", "order", 32);
setnamed("PRBS Generator", "automatic seed", true);
setnamed("PRBS Generator_1", "order", 32);
setnamed("PRBS Generator_1", "automatic seed", true); 

run; 

# get signal results
signal = getresult("EYE_REF", "waveform/input");
signal = signal.getattribute("amplitude (a.u.)");
reference = getresult("VSA_1", "waveform/constellation I");
reference = reference.getattribute("amplitude (a.u.)");
signalThreshold = [0.000575, 0.000735, 0.00092];

samplesPerSymbol = getnamed("::Root Element", "samples per bit");
Nsequency = getnamed("::Root Element", "sequence length");
N = length(signal);
Nsignal = (Nsequency - ignoreBit*2)*samplesPerSymbol; 

# pad signal with 0 if signal is cut off by the analyzers
if (N < Nsequency*samplesPerSymbol) {
    signalReshape = matrix(1, Nsequency*samplesPerSymbol);
    signalReshape(1:N) = signal(1:N);                        
}

# define resference signal
for (ii = 1:length(reference)) {
    if (reference(ii) < signalThreshold(1)) { reference(ii) = 0; } 
    else {
        if (reference(ii) < signalThreshold(2)) { reference(ii) = 1; }
        else {
            if (reference(ii) < signalThreshold(3)) { reference(ii) = 2; }
            else { reference(ii) = 3; }
        }
    }           
}

signal = signalReshape(1+samplesPerSymbol*ignoreBit : end - samplesPerSymbol*ignoreBit);

?OMAouter = outeroma(signal, samplesPerSymbol, reference);