Variable Descriptions

Descriptions of the variables stored in a simulation file. Variables are read back with get, or – for grids, fields, shapes and whole profiles – with the typed accessors get_grid, get_fields, get_shape and get_profile. Some variables have an alias, a copy under an older name kept for compatibility. SHAPE stands for a shape name and NAME for a profile name.

How the simulation file is organized

A simulation file has two levels.

Top-level variables describe the file and the EME circuit: EMode_simulation_file, file_type, emode_version, materials, profiles, eme_scattering, propagation_resolution, and – once the corresponding functions have run – sweep_data, S_matrix (through get('S_matrix')), response and sources. inspect returns their names. Names beginning with an underscore are internal and may change between versions.

Profiles live under the top-level profiles dictionary, one entry per cross-section. '_default' is the working profile that settings, shape, mesh and FDM act on unless profile= is given. label_profile saves a copy of it under a name; FDM with profile= saves its result under a name; and create_profile_set groups profiles solved at different wavelengths into one multi-wavelength profile, in which case per-profile results come back as a dictionary keyed by wavelength. Every function that reads a profile takes profile=NAME: get, get_fields, get_grid, get_shape, get_profile, confinement, effective_area, group_index, orthogonality, report, scattering, mesh, FDM, delete_profile. reset acts on '_default' only and leaves named profiles alone.

Settings (window, resolution, boundary condition, PML, …) are part of the profile but are not returned by get(); read them from get_profile(NAME).settings.

Per-profile variables

Read with get(key, profile=NAME) (default NAME='_default'); a multi-wavelength profile (a profile set) returns a dict[float, ...] of the same, keyed by wavelength.

background_material

(float or str) The background material of the profile’s simulation window, setting the default material where no shapes are defined.

effective_index

(list) The real part of the effective index for each mode.

Alias: n_eff

Ex, Ey, Ez, Hx, Hy, Hz

(complex arrays) The electric (E [V/nm]) and magnetic (H [A/nm]) fields in the x-, y-, and z-directions. These calculated fields are interpolated to the center point of each mesh grid (defined by xc and yc). 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}\]

Deprecated: fetching these through get() (rather than get_fields) prints a deprecation warning.

Fx, Fy

(complex arrays) Raw fields that are solved. They either correspond to the electric or magnetic fields depending on field_to_solve. However, these raw fields are defined on the Yee mesh grid, not the center points of the mesh grid. An internal function extracts all other field components from Fx, Fy, permittivity, and permeability.

Gx, Gy

(complex arrays) The auxiliary longitudinal raw field components present for a bend or an anisotropic solve. Present only when the corresponding basis actually carries them.

confinement_window

(list) The confinement factor for each specified mode is saved under this variable only when the confinement region is specified with a list of vertices, instead of a specific shape.

effective_area

(list) The effective area of each waveguide mode in units of square microns (\(\mu \mathrm{m}^2\)), calculated by the following equation.

\[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}\]

extent, pml_extent

(list) [xmin, xmax, ymin, ymax] of the full simulation window, and of the window with the pml region excluded.

group_index

(list) The group refractive index calculated for each mode.

Alias: n_g

loss_dB_per_m

(float) [dB/m] The power loss coefficient (\(\alpha\)), which relates to the imaginary part of the effective index (\(\kappa\)) by the following equation with the wavelength (\(\lambda\)).

Alias: alpha

\[\kappa = \frac{\alpha \lambda}{(4 \pi) 10 \, \mathrm{log}_{10}(e)} \approx \frac{\alpha \lambda}{54.575}\]

maximum_overlap

(float) Largest overlap in the mode list, calculated from the orthogonality() function.

overlap

(list) The overlap integral in overlap uses the following formula to calculate the modal excitation of \(\vec E_2\) by \(\vec E_1\).

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_2^* \cdot \vec E_1 \, \mathrm{d}x \, \mathrm{d}y \right|^2}{\iint \left| \vec E_1 \right|^2 \, \mathrm{d}x \, \mathrm{d}y \, \iint \left| \vec E_2 \right|^2 \, \mathrm{d}x \, \mathrm{d}y}\]

Note: overlap currently stores this result on the '_default' profile regardless of profile_b. The value returned directly by the function call is correct.

permittivity, permeability

(list) The permittivity and permeability arrays are defined by mesh from the current shapes and settings. Each is a list of arrays defining the corresponding parameters in the x-, y-, and z-directions.

PML_indices

(list) Indices of modes that carry less than 75% of their power inside the simulation window – modes of the pml (absorbing) region rather than of the device. Present only when the profile was solved with a pml. See window_confinement, and remove_pml_modes_bool/pml_seed_bool under Settings.

scattering_sum, scattering_loss

(list) Total per-mode scattering loss [dB/m] summed over shape edges: scattering_sum is a list of per-shape contributions, scattering_loss their sum. Populated after scattering() runs.

shapes

(list) The list of Shape objects making up the profile, background included; prefer get_shape to read a single shape’s attributes and metadata.

Sx, Sy, Sz

(arrays) [W/nm] The Poynting vector in the x-, y-, and z-directions.

TE_fraction

(list) Fractions representing how much the mode is like a TE mode, calculated with the following equation.

\[\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}\]

TE_indices, TM_indices

(list) Indices for the corresponding TE or TM modes in the modes list.

wavelength

(float) [nm] Free-space wavelength.

window_confinement

(list) Fraction of each mode’s power inside the simulation window (inset by one grid cell on every side), only present when the profile has a pml. A mode below 75% is a mode of the absorbing region rather than of the device – what remove_pml_modes_bool discards and PML_indices designates.

xc, yc

(complex arrays) Cell-center coordinates of the mesh grid, in the x- and y-directions. These can be complex when pml layers are introduced.

Deprecated: x, y – read through get_grid instead.

Simulation-level variables

Read with get(key) (no profile=); listed by inspect.

emode_version: (str) The version of EMode that wrote the simulation file.
EMode_simulation_file: (str) The file name the simulation was created with; also serves as a marker that this is a valid EMode simulation file.
file_type: (str) The simulation file’s extension, '.eph'.
serialized: (bool) Internal bookkeeping for the file’s on-disk (de)serialization state.
eme_scattering: (bool) Legacy key, retained so old simulation files still load. It has no effect: EME scattering is controlled by EME_settings(apply_scattering=...).
materials: (list) Names of every material in the database, built-in and user-added. A user-added material’s own properties are returned by get(NAME); see user_material_NAME below.
priority_indices: (list) A list of indices corresponding to the priorities of the shapes in the current profile.
profiles: (dict) The named profiles saved in this file (see “How the simulation file is organized” above); does not include '_default'.
propagation_resolution: (float) [nm] Sampling resolution used along the propagation direction for EME field reconstruction.
response: (CircuitResponse) The power-dependent nonlinear response from the most recent EME solve with a declared excitation; returned by get('response'). It also carries trajectories, the forward amplitudes recorded along each \(\chi^{(2)}\) slice, read with power_vs_z(wavelength) or amplitude_vs_z(wavelength).
S_matrix: (SMatrix) The scattering matrix from a solved EME chain; returned by get('S_matrix') (EMode^3D only).
sources: (list) The declared excitation sources for the EME chain; returned by get('sources').
sweep_data: (dict) Results from the most recent sweep() call.
user_material_NAME: (str) The name of a user defined material.

Settings

Part of the profile, not returned by get(); read from get_profile(NAME).settings.

bend_radius

(float) [nm] Bend radius of the waveguide; 0 indicates that no bend is applied.

Alias: radius

boundary_condition

(str) Boundary condition for the simulation window; 0 indicates a metal boundary (driving all fields to zero at the boundary) and A or S indicate anti-symmetric or symmetric Ex; the first character indicates south boundary condition and the second character indicates the west boundary condition. This setting is not itself retrievable via get()/inspect(); use BC below to read back the resolved boundary condition.

BC

(str) A copy of the boundary_condition before running FDM(). After running FDM(), this variable represents the actual boundary condition string as a combination of ‘0’, ‘A’, or ‘S’. For example, setting the boundary_condition to ‘TE’ and running FDM() will result in BC changing to either ‘SS’, ‘0S’, ‘S0’, or ‘00’, depending on the index profile cross-section symmetry.

expansion_resolution

(list) List of the desired mesh step size in the x- and y-directions in the expanded regions around the perimeter of the simulation window.

expansion_size

(list) List of the size of the expanded regions in the x- and y-directions.

field_to_solve

(str) Desired transverse field component to solve; either ‘Et’ or ‘Ht’.

max_effective_index

(float) Upper limit for the effective index; the eigensolver’s shift, unless pml_seed_bool derives one automatically.

mesh_complete_bool

Removed; use get_profile(NAME).status.meshed.

num_modes

(int) Total number of modes to solve.

num_pml_layers

(int or list) Either an integer or a list of integers indicating the number of perfectly matched layers for all or each boundary: [North, South, East, West].

pml_thickness

(float or list) Either a float or a list of floats indicating the perfectly matched layer thickness in nm for all or each boundary: [North, South, East, West]. 0 means the boundary uses num_pml_layers instead. Unlike a layer count, this holds the absorber’s physical size fixed as the resolution changes.

pml_alpha_max

(float) The complex-frequency-shifted (CFS) term of the pml profile, where 0 disables it.

pml_kappa_max

(float) The maximum real coordinate stretch of the pml profile, reached at the outer pml face.

pml_NSEW_bool

(list) List of booleans indicating if a perfectly matched layer (pml) boundary condition is applied to each boundary: [North, South, East, West].

pml_order

(float) The polynomial grading exponent of the pml stretch profile.

pml_reflection

(float) The target round-trip reflection that the pml is designed for, which sets the maximum pml conductivity.

pml_seed_bool

(bool) Seed the pml eigensolve with the fundamental mode of the same structure solved without a pml, so the guided fundamental lands at mode 0 without a hand-tuned max_effective_index.

remove_pml_modes_bool

(bool) Indicates whether or not to automatically remove artificial modes found in the pml layers.

shape_list, shape_materials

Removed; use get_profile(NAME).shapes (or the per-profile shapes variable above).

tolerance

(float) Numerical tolerance for convergence of the effective indices.

window_height

(float) [nm] Total height (y-direction) of the simulation window.

window_width

(float) [nm] Total width (x-direction) of the simulation window.

x_resolution, y_resolution

(float) [nm] Mesh grid step in the x- and y-directions.

Shape attributes

Read with get_shape (or get('shape_SHAPE')), which returns a Shape object with these attributes, plus a metadata dict populated once scattering()/confinement() have run for that shape.

SHAPE[‘correlation_length’]

(list) A list of two values describing the correlation length of the roughness on the vertical and horizontal edges of the shape.

Alias: Lc_nm

SHAPE[‘fill_material’]

(float or str) Either a value or a material name to define the refractive index in the etched region of a ‘planar’ shape.

SHAPE[‘geometry’]

(dict) A dictionary of the parameters of the shapes geometry

SHAPE[‘geometry’][‘etch_depth’]

(float) The etch depth associated with a ‘planar’ shape that also has a defined SHAPE['geometry']['mask']. The shape will have a thickness outside the mask definition equal to the difference between the SHAPE['geometry']['height'] and SHAPE['geometry']['etch_depth'] (or zero if this is negative).

SHAPE[‘geometry’][‘height’]

(float) Maximum size of the shape in the y-direction.

SHAPE[‘geometry’][‘mask’]

(list) The masks for this shape

SHAPE[‘geometry’][‘mask_offset’]

(list) The mask offsets for this shape

SHAPE[‘geometry’][‘position’]

(list) The x- and y-positions of the center point of the shape, constrained by the SHAPE['geometry']['width'] and SHAPE['geometry']['height'].

SHAPE[‘geometry’][‘shape_type’]

(str) The shape type is either ‘planar’, ‘conformal’, ‘polygon’, or ‘ellipse’.

SHAPE[‘geometry’][‘sidewall_angle’]

(float) [degrees] Angle of the side wall for a ‘planar’ shape relative to a vertical at 0 degrees.

SHAPE[‘geometry’][‘tone’]

(str) The tone of the mask (‘p’ or ‘n’)

SHAPE[‘geometry’][‘vertices’]

(list) Pairs of [x,y] vertices that define the perimeter of a shape.

SHAPE[‘geometry’][‘width’]

(float) Maximum size of the shape in the x-direction.

SHAPE[‘loss_dB_per_m’]

(float) [dB/m] Absorption coefficient for power loss in the region defined by the shape.

SHAPE[‘mask’]

(float or list) Width of the a mask for etching a ‘planar’ shape. Also accepts a list to define both the width and the x-offset of the mask.

SHAPE[‘name’]

(str) User-defined name of the shape. This name will be used to reference this shape in subsequent functions.

SHAPE[‘priority’]

(float) A value that defines the order in which the shape is drawn relative to other shapes. A higher value give a higher priority, putting the shape in front of other shapes with lower priority.

SHAPE[‘roughness_rms’]

(list) A list of two values describing the rms roughness on the vertical and horizontal edges of the shape.

Alias: st_dev_nm

SHAPE[‘metadata’]

(dict) A dictionary of metadata associated with the shape

SHAPE[‘metadata’][‘confinement’]

(list) Confinement factor for each mode in the corresponding shape.

SHAPE[‘metadata’][‘edges’]

(list) Definitions of edges for the corresponding shape where the scattering loss is calculated. These edges can be correlated to the loss values from SHAPE['metadata']['scattering_all_edges'].

SHAPE[‘metadata’][‘scattering_all_edges’]

(list) Calculated scattering loss for each edge of the shape, defined by SHAPE['metadata']['edges'].

SHAPE[‘metadata’][‘scattering_horizontal_edges’]

(list) Calculated scattering loss for each horizontal edge of the shape.

SHAPE[‘metadata’][‘scattering_sum’]

(list) Total calculated scattering loss for all edges of the shape.

SHAPE[‘metadata’][‘scattering_vertical_edges’]

(list) Calculated scattering loss for each vertical edge of the shape.