File management

Simulation data are stored in an EMode Photonix file with the extension ‘.eph’. This file is created when a simulation is initialized, and existing simulation files can be opened by EMode for further analysis.

init

Create a simulation instance with an associated ‘.eph’ file to run the simulation and store data. This function is automatically called when the emodeconnection class is initialized.

Parameters:

save_path (str) – path to save the simulation file relative to the current working directory, default: ‘.’
simulation_name (str) – simulation name, default: ‘emode’

open

Open an existing simulation ‘.eph’ file. This can be used to retrieve previous simulation data or to run a simulation based on a template.

Parameters:

save_path (str) – path to open the simulation file relative to the current working directory, default: ‘.’
simulation_name (str) – simulation name, default: ‘emode’
new_simulation_name (bool or str) – new simulation name so the old file is not over-written, default: False (the original simulation_name is reused)
force (bool) – if a file with the target name is already open elsewhere, open it anyway instead of auto-renaming to an available filename, default: False

get

Extract data from an existing simulation to your Python environment.

Parameters:

key (str) – name of the variable or parameter to extract. This can also be a list of fields of any combination of [Ex, Ey, Ez, Hx, Hy, Hz, Sx, Sy, Sz]. See Variable Descriptions for a complete list and description of all available variables. Use 'S_matrix' (EMode^3D only) to retrieve the scattering matrix from a solved EME chain as an SMatrix object.
profile (str) – label of the profile to extract the data defined by key from, default: ‘_default’
simulation_name (str) – simulation name, default: ‘emode’

get_fields

Extract field data from an existing simulation to your Python environment.

Parameters:

key (str or list[str]) – name of the field to extract a list of fields of any combination of [Ex, Ey, Ez, Hx, Hy, Hz, Sx, Sy, Sz].
include_expand (bool) – whether to include the expanded region, default: True
include_pml (bool) – whether to include the PML region, default: True
unfold (bool) – whether to include the full window (unfolded) or strictly the solved window (potentially smaller due to applied symmetries), default: True
profile (str) – label of the profile to extract the data defined by key from, default: ‘_default’
simulation_name (str) – simulation name, default: ‘emode’

Returns:

a Field object for a single-wavelength profile, or a FieldSet (a Field for each wavelength, indexable/iterable like a dict[float, Field]) for a multi-wavelength profile.

Return type:

Field | FieldSet

get_grid

Extract grid data from an existing simulation to your Python environment.

Parameters:

include_expand (bool) – whether to include the expanded region, default: True
include_pml (bool) – whether to include the PML region, default: True
unfold (bool) – whether to include the full window (unfolded) or strictly the solved window (potentially smaller due to applied symmetries), default: True
profile (str) – label of the profile to extract the grid from, default: ‘_default’
simulation_name (str) – simulation name, default: ‘emode’

Returns:

a Grid object for a single-wavelength profile, or a GridSet (a Grid for each wavelength, indexable/iterable like a dict[float, Grid]) for a multi-wavelength profile.

Return type:

Grid | GridSet

get_shape

Extract shape data from an existing simulation. Returns the shape object with a metadata dictionary attached (scattering and confinement results for that shape).

Parameters:

key (str) – name of the shape to extract
profile (str) – label of the profile to extract the shape from, default: ‘_default’
simulation_name (str) – simulation name, default: ‘emode’

get_profile

Extract a full profile object from an existing simulation. Returns a Profile object containing the settings, shapes, grid, and field data associated with the named profile.

Parameters:

profile (str) – label of the profile to extract, default: ‘_default’
simulation_name (str) – simulation name, default: ‘emode’

create_profile_set

Group several single-wavelength profiles into one named multi-wavelength profile set, keyed internally by wavelength. All named profiles must share identical shapes, and each must be at a distinct wavelength. The original individual profiles are deleted once grouped.

Parameters:

profiles (str or list[str]) – names of the profiles to group
profile_set_name (str) – name of the resulting profile set, default: ‘_default’
simulation_name (str) – simulation name, default: ‘emode’

delete_profile

Delete a named profile (or reset the _default profile’s settings) from the simulation file.

Parameters:

profile (str) – name of the profile to delete
simulation_name (str) – simulation name, default: ‘emode’

clear_field_data

Deletes the following data from every profile to reduce the ‘.eph’ file size: Fx, Fy, Ex, Ey, Ez, Hx, Hy, Hz, Sx, Sy, Sz, x, y, permittivity, permeability.

Parameters:

profile (str) – currently ignored; field data is cleared from all profiles regardless of this argument, default: ‘_default’
simulation_name (str) – simulation name, default: ‘emode’

save

Saves a simulation file and keeps the simulation file in the ‘open’ state.

Parameters:

save_all_fields (bool) – whether all field data should be saved (so the E, H, and S fields can be accessed without an EMode license) or just the raw field data (Fx and Fy), default: False
file_type (str) – file type to save the simulation file as, either ‘eph’ or ‘mat’, default: ‘eph’
close (bool) – whether to close the simulation file after saving, default: False
new_save_path (str) – if set, saves the simulation file in this new path, default: None
simulation_name (str) – simulation name, default: ‘emode’

close

Saves or deletes a simulation file. This function is called through the “close” method of emodeconnection, and these optional parameters can be passed directly to the “close” method.

Parameters:

save (bool) – saves simulation file if True and deletes the simulation file if False, default: True
save_all_fields (bool) – whether all field data should be saved (so the E, H, and S fields can be accessed without an EMode license) or just the raw field data (Fx and Fy), default: False
file_type (str) – file type to save the simulation file as, either ‘eph’ or ‘mat’, default: ‘eph’
simulation_name (str) – simulation name, default: ‘emode’