Solver and analysis

solve

Calculate the waveguide modes with the finite-difference (FDM) or the finite-element (FEM) solver. The fields, effective indices, losses and TE fractions are saved as described under FDM(), whichever solver runs.

Parameters:

solver_method (str) – ‘FDM’ or ‘FEM’ runs that solver, the same as calling FDM() or FEM(), and sets the profile’s solver setting to it. ‘default’ runs the solver the solver setting selects, without changing it. That setting is itself ‘default’ unless changed, which is the FDM in every session, default: ‘default’
profile (str or int) – profile name to save the solved profile under, default: ‘_default’
section (str) – name of an EME section to solve a slice from, instead of the profile’s own settings/shapes, default: None
propagation_distance (float) – [nm] where along section to take the cross-section, default: None
include_heat (bool) – whether to include the temperature change from the most recent heat() solve, default: True
include_static (bool) – whether to apply the electro-optic (Pockels) permittivity perturbation from the most recent electrostatic() solve, default: True
verbose (bool) – print progress, default: True
simulation_name (str) – simulation name, default: ‘emode’

Returns:

what FDM() or FEM() returns, for whichever solver ran.

Note

The FEM solver requires an EMode^3D license, so solve() needs one whenever it runs the FEM: with solver_method='FEM', or with ‘default’ when the profile’s solver setting is ‘FEM’. See FEM on the Multi-Physics page.

FDM

Calculate the waveguide modes using the finite difference method. Calling FDM() sets the profile’s solver setting to ‘FDM’, so EME() and sweep() then use the FDM too. It automatically runs EM_mesh as needed (generating x, y, permittivity, and permeability). After solving the mode, the effective index (effective_index), mode propagation loss (loss_dB_per_m), and field components (Fx, Fy, Ex, Ey, Ez, Hx, Hy, Hz, Sx, Sy, Sz) are available, where the fields are normalized to the equation below.

\[\frac{1}{2} \mathrm{Re} \iint \left( \vec E \times \vec H^* \right) \! \cdot \! \hat{z} \, \mathrm{d}x \, \mathrm{d}y = 1 \, \mathrm{W}\]

It also calculates the TE fraction of each mode (TE_fraction) with the following equation, and it saves the indices of the TE and TM modes (TE_indices and TM_indices).

\[\mathrm{{TE_fraction}} = \frac{\iint \left| \vec E_\mathrm{x} \right|^2 \, \mathrm{d}x \, \mathrm{d}y}{\iint \left| \vec E_\mathrm{x} \right|^2 + \left| \vec E_\mathrm{y} \right|^2 \, \mathrm{d}x \, \mathrm{d}y}\]

A multi-wavelength profile (a wavelength list in settings(), or a set from create_profile_set()) is solved at each of its wavelengths, and is saved as one solved profile per wavelength, so get() returns a dict keyed by wavelength and plot() and EME() use the modes at each wavelength. FEM() and solve() do the same. The direct return value describes only the longest wavelength.

Parameters:

profile (str or int) – profile name to automatically create a profile after running FDM(), default: ‘_default’
section (str) – name of an EME section to solve a slice from, instead of the profile’s own settings/shapes, default: None
propagation_distance (float) – [nm] optional propagation distance used to compute an additional propagation phase/loss, default: None
mode_filter (str) – choose to filter the mode list for propagation direction of ‘forward’, ‘backward’, or ‘none’. It acts in the anisotropic solver only, since the isotropic solver returns forward modes by construction. It is saved in the profile’s settings, so a later EME() or sweep() that solves this profile again uses it too. Default: ‘forward’
fLanczos (int) – size of the eigensolver’s Krylov subspace as a multiple of the number of modes requested, at least 1. Raise it if the solve does not converge. It is saved in the profile’s settings like mode_filter. Default: 5
solve_type (str) – either ‘isotropic’, ‘anisotropic’, or ‘auto’ to control whether anisotropic materials are solved with the full tensor or reduced to their isotropic diagonal, default: ‘auto’
include_heat (bool) – whether to include heat-related material properties when meshing, default: True
include_static (bool) – whether to apply the electro-optic (Pockels) permittivity perturbation from the most recent electrostatic() solve, default: True
scattering (bool) – whether to automatically calculate interfacial scattering loss for all shapes after solving. The include_scattering setting in settings does the same for every solve of the profile. Default: False
verbose (bool) – print progress, default: True
simulation_name (str) – simulation name, default: ‘emode’

Note

The direct return value of this function (as called through emodeconnection) is a dict with keys field (a Field object), n_eff_tilde, TE_fraction, TE_indices, and TM_indices. The individual field components and derived quantities described above (effective_index, loss_dB_per_m, Ex/Ey/etc.) become available afterward from the saved profile via get()/get_fields(), not as top-level keys of this return value.

sweep

This function sweeps a calculation as a function of any available setting, shape parameter, or section parameter (EMode^3D only). Run a parameter sweep of key over defined values by solving solve_type for each value and saving a list of parameters defined by ‘result’ that correspond to the values. After running a sweep, the data will be available from a parameter called sweep_data, which includes all of the specified parameters of this funcion and the data specified by the result parameter. The result parameter can include any parameter that is listed in the inspect() output (after running the desired simulation). Additionally, the result parameter can include ‘scattering_loss’ (a sum of all scattering losses for each mode) or ‘mode_order’ (a list of mode indices used for tracking the order of the modes).

Parameters:

key (str) – any settings, shape, or section parameter that will have its value changed in the sweep, directly specify the key for settings parameters, specify ‘shape, SHAPE_NAME, SHAPE_KEY’ to specify shape the SHAPE_KEY of SHAPE_NAME, specify ‘section, SECTION_NAME, SECTION_KEY’ to specify the SECTION_KEY of SECTION_NAME. The accepted section keys are ‘length’, ‘num_modes’, ‘minimum_z_step’, ‘overlap_variation’, ‘z_slices’, ‘offset’, ‘etch_depth’, ‘sidewall_angle’, ‘window_width’, ‘window_height’, and ‘facet_angle’ (the tilt [degrees] of an angled facet on that section, see make_angled_facet_port()); any other section key raises an error naming it.
values (list or array) – the values that define the key during the sweep
solve_type (str) – either ‘mesh’, ‘FDM’, or ‘EME’ to specify which solver to run at each sweep step, where ‘FDM’ means a mode solve with the solver the solver setting selects (the FDM or the FEM), default: automatically chosen based on the key and result selection
result (str or list) – the parameters to save from each iteration of the sweep. This can be any value in the eph file. Internally, this calls get, so if you can read the value with get you can collect it with sweep. Additionally, ‘scattering_loss’ and ‘mode_order’ are accepted. default: ‘effective_index’
seed (bool) – whether to seed each solve step with the previous step’s mode list, default: True
adaptive (bool) – only for a wavelength sweep. values keeps its meaning – the wavelengths you want results at – and adaptive changes only where the solver runs: modes are matched between neighbouring solves through a phase-corrected overlap, and a bisection in wavelength places further solves until the mode list stops moving by more than tolerance, or the gap reaches minimum_step. The requested wavelengths are then filled in by interpolating the solved mode lists, which is much cheaper than solving every point when the modes vary smoothly. sweep_data additionally carries solved_wavelengths (where the solver actually ran) and unconverged (any stretch the sampler gave up on, reported rather than raised). Default: False
tolerance (float) – with adaptive, the largest mode-list change tolerated between adjacent solves, default: 1e-3
minimum_step (float) – [nm] with adaptive, the smallest wavelength gap the sampler will bisect into, default: the spacing of values
simulation_name (str) – simulation name, default: ‘emode’

confinement

Calculate confinement factor of specified shape. By default, only the area of the shape that is used to define the refractive index profile is included in the confinement factor. For instance, if another shape with a higher priority overlaps the specified shape, the overlapped area is not included. The confinement factors are also returned by this function; for a multi-wavelength profile, the return value is a dict keyed by wavelength.

Parameters:

profile (str) – profile name, default: ‘_default’
shape_list – name (from shape) or list of names of shapes to include in confinement or ‘all’ for all shapes, default: ‘all’
mode_list (str or list) – desired modes to calculate confinement, ‘all’, ‘TE’, ‘TM’, or a list of the desired mode indices, default: ‘all’
vertices (list (Nx2)) – list of vertices that define a closed polygon, specifying this parameter will override the shape_list input, default: None
ignore_priority (bool) – toggle ignoring overlapped shapes with higher priority, default: False
simulation_name (str) – simulation name, default: ‘emode’

effective_area

Calculate the effective areas for all modes. After running this function, an array called effective_area will become available and report will display the effective areas. The effective_area is also returned by this function and is in units of \(\mu\text{m}^2\); for a multi-wavelength profile, the return value is a dict keyed by wavelength.

\[A_\mathrm{eff} = \frac{\left( \iint \left| \vec E \right|^2 \, \mathrm{d}x \, \mathrm{d}y \right)^2}{\iint \left| \vec E \right|^4 \, \mathrm{d}x \, \mathrm{d}y} \, \mu\text{m}^2\]

Parameters:

profile (str) – profile name, default: ‘_default’
simulation_name (str) – simulation name, default: ‘emode’

orthogonality

Calculate the highest value of mode overlap between modes in the mode list. After running this function, a variable called maximum_overlap will become available in metadata of the named (or default) profile, and the maximum_overlap is returned by this function; for a multi-wavelength profile, the return value is a dict keyed by wavelength. Ideally, this value is less than \(10^{-3}\), indicating an accurate mode list.

Parameters:

profile (str or int) – profile name, default: ‘_default’
simulation_name (str) – simulation name, default: ‘emode’

group_index

Calculate the group index for all modes. First, group_index runs FDM (if not already run), then it runs FDM a second time with 0.01 % longer wavelength to calculate the group index. After running this function, an array called group_index will become available and report will display the group index. The group_index array is also returned by this function; for a multi-wavelength profile, the return value is a dict keyed by wavelength.

Parameters:

profile (str) – profile name, default: ‘_default’
simulation_name (str) – simulation name, default: ‘emode’

report

Display a simulation report table with information about each mode: mode number; effective index; TE fraction; loss (dB/m); a PML column when the profile was solved with a pml, marking the modes that carry less than 75% of their power inside the window (see PML_indices and window_confinement in Variable Descriptions); per-shape confinement factors and scattering loss (if calculated); effective areas (if calculated).

The line above the table gives the wavelength and the mode solver that produced the modes, for example Wavelength: 1550.0 nm Solver: FEM. A saved CSV records both below the table.

Returns the table as a dictionary keyed by profile name, each table holding one list per column. A multi-wavelength profile returns one table per wavelength, keyed by wavelength; an unsolved profile returns an empty table.

Parameters:

profile (str) – profile name, default: ‘_default’
save (bool) – whether to save the table to a file or not, default: False
file_name (str) – name of the file to save, default: ‘mode_report’
file_type (str) – file type to save, ‘txt’, ‘latex’, or ‘csv’, default: ‘txt’
simulation_name (str) – simulation name, default: ‘emode’

label_profile

Saves a copy of the default profile (settings, shapes, mesh and any solved modes) under name in the profiles dictionary of the simulation file, meshing it first if needed. A multi-wavelength profile is saved whole, with each member meshed and keeping its own name. Named profiles are read with profile=NAME in get, get_fields, get_grid, get_shape and get_profile, are the inputs to overlap, mode_order and the EME section functions, and are not affected by reset.

Parameters:

name (str) – save the current simulation state to this name, default: ‘0’
simulation_name (str) – simulation name, default: ‘emode’

overlap

Calculate overlap integral between two modes. The result is returned by this function and saved on the profile named by profile_b, where get('overlap', profile=profile_b) reads the latest result and get('overlaps', profile=profile_b) a record of every overlap computed against it (see Variable Descriptions).

Coldren, Larry A., Scott W. Corzine, and Milan L. Mashanovitch, ‘’Diode lasers and photonic integrated circuits,’’ John Wiley & Sons, 2012.

\[\mathrm{overlap} = \frac{4 n_\mathrm{eff,1} n_\mathrm{eff,2}}{(n_\mathrm{eff,1} + n_\mathrm{eff,2})^2} \frac{\left| \iint \vec E_1 \times \vec H_2 \, \mathrm{d}x \, \mathrm{d}y \right|^2}{\iint \left| \vec E_1 \times \vec H_1 \right| \, \mathrm{d}x \, \mathrm{d}y \, \iint \left| \vec E_2 \times \vec H_2 \right| \, \mathrm{d}x \, \mathrm{d}y}\]

Parameters:

profile_a (str or int) – label of first profile, default: ‘_default’
mode_a (int) – mode number from the first profile, default: 0
simulation_name_a (str) – simulation name for the first mode set, default: ‘emode’
profile_b (str or int) – label of second profile, default: ‘_default’
mode_b (int) – mode number from the second profile, default: 0
simulation_name_b (str) – simulation name for the second mode set, default: ‘emode’

mode_order

Calculate mode ordering between two mode lists. The result is returned as a list.

Parameters:

profile_a (str or int) – label of first profile, default: ‘’
profile_b (str or int) – label of second profile, default: ‘’
raw_fields (bool) – use the raw (un-normalized) field data for the ordering comparison instead of the interpolated fields, default: False
simulation_name (str) – simulation name, default: ‘emode’

scattering

Calculates the scattering loss from a specified shape and mode using the Volume Current Method [1]. Results are saved in the variables SHAPE.metadata['scattering_vertical_edges'] (total loss from all vertical interfaces), SHAPE.metadata['scattering_horizontal_edges'] (total loss from all horizontal interfaces), SHAPE.metadata['scattering_sum'] (total scattering loss), SHAPE.metadata['edges'] (list of edge points for calculating scattering loss), and SHAPE.metadata['scattering_all_edges'] (scattering loss from corresponding edges). The fields are interpolated to the exact edge position along the interface. The scattering results are also returned by this function as a dictionary keyed by shape name; for a multi-wavelength profile, the return value is a dict keyed by wavelength.

[1] T. Barwicz and H. A. Haus, “Three-dimensional analysis of scattering losses due to sidewall roughness in microphotonic waveguides,” J. Lightwave Technol. 23, 2719 (2005).

Parameters:

profile (str) – profile name, default: ‘_default’
shape (str) – name of the shape for calculating the interfacial scattering, can also be a list of shapes or None (which calculates scattering for all shapes), default: None
shapes (str) – alias for shape
mode_list – mode number, list of mode numbers, or ‘all’, default: ‘all’
simulation_name (str) – simulation name for the second mode set, default: ‘emode’

plot

Interactive plot for the fields (if available), refractive index, and shapes, or saving a plot. Colorbars are in V/nm for the electric fields, A/nm for the magnetic fields, and W/nm for the Poynting vectors.

For EME plots in the ‘z-x’ or ‘z-y’ planes, the data dropdown also offers an ‘Outline’ view that displays a geometry-only outline of the declared sections. Once sections are declared with straight_section(), pwd_section(), taper_section(), or gds_section(), calling plot() before running EME() shows only the ‘Outline’ view, which is useful to check the section layout before solving. After EME() has run, ‘Outline’ is available alongside the field components.

Parameters:

component (str) – field component or index, ‘Ex/y/z’; ‘Hx/y/z’; ‘Sx/y/z’; ‘Index’; ‘Shapes’, default: ‘Ex’
plot_function (str) – plotting function, ‘real’; ‘imag’; ‘abs’; ‘abs^2’; ‘log’, default: ‘real’
mode (int) – mode number, default: 0
aspect_ratio (str or float) – the height:width aspect ratio, ‘norm’ uses the normal aspect ratio of 0.707, ‘real’ uses the real aspect ratio defined by the simulation window, or a float specifies the aspect ratio, default: ‘norm’
index_outline (bool) – setting index outline, default: True
text_display (bool) – setting text display, default: True
mesh_display (bool) – setting mesh display: the finite-difference grid for an FDM solve, or the triangle mesh for an FEM solve (in the cross-section view), default: False
window_display (bool) – setting window display, default: False
legend (bool) – setting inclusion of a legend on the index and shape plots, default: True
port (int or str) – (EME) the input port that the field is excited from, either a port index or a port name (see Port), default: 0
plane (str) – (EME) plot cross-section plane setting. For 2D simulations, this defaults to ‘x-y’. For 3D simulations, it accepts ‘x-y’, ‘z-x’, or ‘z-y’, default: ‘z-x’
slice_position (float or None) – (EME) location of the third dimension for a cross-section display. For example, if plane is ‘z-x’, then the slice_position refers to the y-position of the cross-section. If None, it reduces the third dimension with the reduction selected in the plot window: ‘sum’ (default), which totals the field across the fixed transverse axis, or ‘mean’, which averages it, default: None
forward_only (bool) – (EME) render only the forward-propagating component of the field instead of the total (forward + backward)
wavelength (float) – (EME) which wavelength’s field to render on a multi-wavelength circuit, such as the pump or the second harmonic of a \(\chi^{(2)}\) section. Default: None, the circuit’s first wavelength
driven (bool) – a plot of a \(\chi^{(2)}\) section uses the declared excitation rather than a unit mode, because conversion depends on power. Each slice is drawn from the forward amplitudes recorded along it, so the generated wavelength builds along the guide instead of stepping at slice boundaries. Without a declared excitation the field shown is the small-signal response and the solver says so field; this only changes the display decomposition of the already-solved field, it does not re-solve, default: False
resolution (float or str) – (EME) sample spacing in nm along the propagation axis for the ‘z-x’/’z-y’ longitudinal panels, smaller is finer; ‘auto’ picks a spacing of roughly one sample per horizontal display pixel, default: ‘auto’
excitation (str) – (EME) render the field launched by a free-space field declared with free_space_field, instead of unit amplitude in mode at port. It also selects which port the field is viewed at. This is the only API surface for viewing one; in the plot window the same choice appears in the Mode menu as '<name> (free space)'. Default: None
normalization (str) – the field family the colour scale is normalized to, either ‘vector’ (the full transverse vector at the excitation plane) or ‘component’ (the plotted component alone), default: ‘vector’
profile (str or None) – render a stored profile by name instead of the EME section. Once a simulation has declared sections, the plot always follows the section, so this is the only way to view a profile saved by an earlier FDM(profile=...) call. An unknown name raises an error listing the available profiles, default: None
file_name (str) – if specified, forces the function to save a file with the given parameters and will not display the interactive plot, file is saved under a directory called EM_figures, default: None
file_type (str) – file type for saving a plot, ‘pdf’ or ‘png’, default: ‘’ (no extension is added to file_name unless a file type is given)
simulation_name (str) – simulation name, default: ‘emode’

material_explorer

Interactive material explorer to plot the refractive indices of all available materials. The default wavelength range in the plot corresponds to the recommended range from the material reference listed below the plot. If wavelengths are specified outside this range, the model will be plotted with a dashed line instead of a solid line. User defined materials are also available.

Parameters:

file_name (str) – if specified, forces the function to save a file with the given parameters and will not display the interactive plot, file is saved under a directory called EM_figures, default: None
file_type (str) – file type for saving a plot, ‘pdf’ or ‘png’, default: ‘’ (no extension is added to file_name unless a file type is given)
simulation_name (str) – simulation name, default: ‘emode’

refractive_index

Returns the refractive index from a material name (retrieved from the internal reference list), a MaterialSpec object, or from a custom refractive index value. Optionally, the material’s reference (or citation) may be returned.

Parameters:

material (str) – material name; for AlGaAs, the fraction of Al relative to Ga is included in the material name separated by a comma, for example: “AlGaAs, 0.2” for a Al_{0.2}Ga_{0.8}As.
wavelength (float) – [nm] wavelength, default: 1550
reference (bool) – additionally return the citation for the material, default: False

Returns:

[n_x, n_y, n_z] or ([n_x, n_y, n_z], reference)

permeability

Returns the relative permeability from a material name (retrieved from the internal reference list) or from a custom permeability value. Optionally, the material’s reference (or citation) may be returned.

Parameters:

material (str) – material name
wavelength (float) – [nm] wavelength, default: 1550
reference (bool) – additionally return the citation for the material, default: False

Returns:

[permeability_x, permeability_y, permeability_z] or ([permeability_x, permeability_y, permeability_z], reference)

permittivity

Returns the relative permittivity from a material name (retrieved from the internal reference list) or from a custom value. For isotropic materials this is a 3-element array; for fully anisotropic materials it is a 3×3 tensor. Optionally, the material’s reference (or citation) may be returned.

Parameters:

material (str, float, or list) – material name, or a float/list for a custom value
wavelength (float) – [nm] wavelength, default: 1550
reference (bool) – additionally return the citation for the material, default: False

Returns:

[eps_x, eps_y, eps_z], a 3×3 array, or the corresponding tuple with reference

d_matrix

Returns the second-order nonlinear d-matrix of a material. Optionally, the material’s reference (or citation) may be returned.

Parameters:

material (str) – material name
wavelength (float) – [nm] wavelength, default: 1550
reference (bool) – additionally return the citation for the material, default: False

Returns:

d-matrix with shape (3, 6), or (d-matrix, reference)

mesh

Generalized mesh tool for arbitrary shapes on a rectangular grid. This is called internally by FDM if it has not already been called by the user. Generates vertices for each shape, the actual refractive index for each shape, arrays to define the center points (x, y) of the mesh grid, and the relative permittivity and permeability matrices (permittivity and permeability).

Parameters:

profile (str) – profile name, default: ‘_default’
run_mesh (bool) – whether to actually run the meshing step now, or just mark the profile as prepared for meshing without running it, default: True
verbose (bool) – control the display of the progress bar, default: True
simulation_name (str) – simulation name, default: ‘emode’