tidy3d.components.data.monitor_data.ElectromagneticFieldData

tidy3d.components.data.monitor_data.ElectromagneticFieldData#

class ElectromagneticFieldData[source]#

Bases: AbstractFieldData, ElectromagneticFieldDataset, ABC

Collection of electromagnetic fields.

Parameters:

  • Ex (Optional[Union[ScalarFieldDataArray, ScalarFieldTimeDataArray, ScalarModeFieldDataArray, ScalarModeFieldCylindricalDataArray, EMEScalarModeFieldDataArray, EMEScalarFieldDataArray]] = None) – Spatial distribution of the x-component of the electric field.

  • Ey (Optional[Union[ScalarFieldDataArray, ScalarFieldTimeDataArray, ScalarModeFieldDataArray, ScalarModeFieldCylindricalDataArray, EMEScalarModeFieldDataArray, EMEScalarFieldDataArray]] = None) – Spatial distribution of the y-component of the electric field.

  • Ez (Optional[Union[ScalarFieldDataArray, ScalarFieldTimeDataArray, ScalarModeFieldDataArray, ScalarModeFieldCylindricalDataArray, EMEScalarModeFieldDataArray, EMEScalarFieldDataArray]] = None) – Spatial distribution of the z-component of the electric field.

  • Hx (Optional[Union[ScalarFieldDataArray, ScalarFieldTimeDataArray, ScalarModeFieldDataArray, ScalarModeFieldCylindricalDataArray, EMEScalarModeFieldDataArray, EMEScalarFieldDataArray]] = None) – Spatial distribution of the x-component of the magnetic field.

  • Hy (Optional[Union[ScalarFieldDataArray, ScalarFieldTimeDataArray, ScalarModeFieldDataArray, ScalarModeFieldCylindricalDataArray, EMEScalarModeFieldDataArray, EMEScalarFieldDataArray]] = None) – Spatial distribution of the y-component of the magnetic field.

  • Hz (Optional[Union[ScalarFieldDataArray, ScalarFieldTimeDataArray, ScalarModeFieldDataArray, ScalarModeFieldCylindricalDataArray, EMEScalarModeFieldDataArray, EMEScalarFieldDataArray]] = None) – Spatial distribution of the z-component of the magnetic field.

  • monitor (Union[FieldMonitor, FieldTimeMonitor, AuxFieldTimeMonitor, PermittivityMonitor, ModeMonitor, MediumMonitor])

  • symmetry (tuple[Literal[0, -1, 1], Literal[0, -1, 1], Literal[0, -1, 1]] = (0, 0, 0)) – Symmetry eigenvalues of the original simulation in x, y, and z.

  • symmetry_center (Optional[tuple[float, float, float]] = None) – Center of the symmetry planes of the original simulation in x, y, and z. Required only if any of the symmetry field are non-zero.

  • grid_expanded (Optional[Grid] = None) – Grid discretization of the associated monitor in the simulation which created the data. Required if symmetries are present, as well as in order to use some functionalities like getting Poynting vector and flux.

  • grid_primal_correction (Union[float, FreqDataArray, TimeDataArray, FreqModeDataArray, EMEFreqModeDataArray] = 1.0) – Correction factor that needs to be applied for data corresponding to a 2D monitor to take into account the finite grid in the normal direction in the simulation in which the data was computed. The factor is applied to fields defined on the primal grid locations along the normal direction.

  • grid_dual_correction (Union[float, FreqDataArray, TimeDataArray, FreqModeDataArray, EMEFreqModeDataArray] = 1.0) – Correction factor that needs to be applied for data corresponding to a 2D monitor to take into account the finite grid in the normal direction in the simulation in which the data was computed. The factor is applied to fields defined on the dual grid locations along the normal direction.

Attributes

colocation_boundaries

Coordinates to be used for colocation of the data to grid boundaries.

colocation_centers

Coordinates to be used for colocation of the data to grid centers.

complex_flux

Complex flux for data corresponding to a 2D monitor.

complex_poynting

Time-averaged Poynting vector for frequency-domain data associated to a 2D monitor, projected to the direction normal to the monitor plane.

fill_fraction_box

Convenience accessor using the Box defined on sort_spec.

flux

Flux for data corresponding to a 2D monitor.

grid_corrected_copy

Return a copy of self with grid correction factors applied (if necessary) and symmetry expanded.

intensity

Return the sum of the squared absolute electric field components.

mode_area

Effective mode area corresponding to a 2D monitor.

poynting

Time-averaged Poynting vector for frequency-domain data associated to a 2D monitor, projected to the direction normal to the monitor plane.

time_reversed_copy

Make a copy of the data with time-reversed fields.

grid_primal_correction

grid_dual_correction

monitor

symmetry

symmetry_center

grid_expanded

Ex

Ey

Ez

Hx

Hy

Hz

Methods

dot(field_data[, conjugate, bidirectional])

Dot product (modal overlap) with another FieldData object.

fill_fraction(bounding_box)

Return the field-energy fill fraction within bounding_box.

outer_dot(field_data[, conjugate, ...])

Outer dot product (pairwise modal overlap matrix) with another FieldData object.

package_flux_results(flux_values)

How to package flux based on the coordinates present in the data.

to_zbf(fname[, units, ...])

For a 2D monitor, export the fields to a Zemax Beam File (.zbf).

translated_copy(vector)

Create a copy of the ElectromagneticFieldData with fields translated by the provided vector.
grid_primal_correction#
grid_dual_correction#
property colocation_boundaries#

Coordinates to be used for colocation of the data to grid boundaries.

property colocation_centers#

Coordinates to be used for colocation of the data to grid centers.

property grid_corrected_copy#

Return a copy of self with grid correction factors applied (if necessary) and symmetry expanded.

property intensity#

Return the sum of the squared absolute electric field components.

property complex_poynting#

Time-averaged Poynting vector for frequency-domain data associated to a 2D monitor, projected to the direction normal to the monitor plane.

property poynting#

Time-averaged Poynting vector for frequency-domain data associated to a 2D monitor, projected to the direction normal to the monitor plane.

package_flux_results(flux_values)[source]#

How to package flux based on the coordinates present in the data.

property complex_flux#

Complex flux for data corresponding to a 2D monitor.

property flux#

Flux for data corresponding to a 2D monitor.

property mode_area#

Effective mode area corresponding to a 2D monitor.

fill_fraction(bounding_box)[source]#

Return the field-energy fill fraction within bounding_box. The fill fraction is defined as the ratio between the integrated field intensity inside the bounding box and the total integrated intensity over the monitor plane.

Parameters:

bounding_box (Box) – The bounding box used to compute the fill fraction.

Returns:

Fill fraction values for each frequency and mode index.

Return type:

FreqModeDataArray

property fill_fraction_box#

Convenience accessor using the Box defined on sort_spec.

The component of the box along the propagation axis does not influence the fill fraction, but the box must intersect the monitor plane.

dot(field_data, conjugate=True, bidirectional=True)[source]#

Dot product (modal overlap) with another FieldData object. Both datasets have to be frequency-domain data associated with a 2D monitor.

When either monitor uses colocate=True (default) or use_colocated_integration=True, the tangential fields from field_data are interpolated onto this object’s grid, so the two datasets may have different spatial discretizations. Otherwise, both datasets must share the same tangential grid.

Along the normal direction, the monitor position may differ and is ignored. Non-spatial coordinates (f, mode_index) are aligned by intersection; broadcasting is also supported when the other dataset has size 1 along a coordinate dimension.

The dot product is defined as:

If bidirectional=False, the dot product is instead:

Parameters:

  • field_data (FieldData | ModeData | ModeSolverData) – A data instance to compute the dot product with.

  • conjugate (bool, optional) – If True (default), the dot product is defined as above. If False, the definition is similar, but without the complex conjugation of the fields.

  • bidirectional (bool = True) – If True (default), computes the symmetric bidirectional overlap: 1/4 * integral(E1* x H2 + H1* x E2) dS. If False, computes just: 1/2 * integral(E1* x H2) dS.

Returns:

Data array with the complex-valued modal overlaps.

Return type:

FreqDataArray | FreqModeDataArray

Note

The dot product with and without conjugation is equivalent (up to a phase) for modes in lossless waveguides but differs for modes in lossy materials. In that case, the conjugated dot product can be interpreted as the fraction of the power carried by the second mode, but modes are not orthogonal with respect to that product and the sum of carried power fractions may be different from the total flux. In the non-conjugated definition, modes are orthogonal, but the interpretation of the dot product as power carried by a given mode is no longer valid.

outer_dot(field_data, conjugate=True, bidirectional=True, truncate_to_monitor_bounds=False)[source]#

Outer dot product (pairwise modal overlap matrix) with another FieldData object.

When either monitor uses colocate=True (default) or use_colocated_integration=True, the tangential fields from field_data are interpolated onto this object’s grid, so the two datasets may have different spatial discretizations. Otherwise, both datasets must share the same tangential grid.

The calculation is performed for all common frequencies between the two datasets.

The dot product is defined as:

If bidirectional=False, the dot product is instead:

Parameters:

  • field_data (FieldData | ModeData | ModeSolverData) – A data instance to compute the dot product with.

  • conjugate (bool = True) – If True (default), the dot product is defined as above. If False, the definition is similar, but without the complex conjugation of the fields.

  • bidirectional (bool = True) – If True (default), computes the symmetric bidirectional overlap: 1/4 * integral(E1* x H2 + H1* x E2) dS. If False, computes just: 1/2 * integral(E1* x H2) dS.

  • truncate_to_monitor_bounds (bool = False) – Only used in the non-colocated integration path (when colocate=False). If True, clamp integration area to monitor bounds, consistent with complex_flux. If False (default), use grid-enclosing bounds.

Returns:

Data array with the complex-valued modal overlaps.

  • If neither dataset has mode_index: returns FreqDataArray.

  • If only self has mode_index: returns MixedModeDataArray with mode_index_0 coordinate.

  • If only field_data has mode_index: returns MixedModeDataArray with mode_index_1 coordinate.

  • If both datasets have mode_index: returns MixedModeDataArray with mode_index_0 and mode_index_1 coordinates.

Return type:

FreqDataArray | MixedModeDataArray

See also

:member:`dot`

property time_reversed_copy#

Make a copy of the data with time-reversed fields.

translated_copy(vector)[source]#

Create a copy of the ElectromagneticFieldData with fields translated by the provided vector. Can be used together with dot or outer_dot to compute overlaps between field data at different locations.

Parameters:

vector (tuple[float, float, float]) – Translation vector to apply to the field data.

Returns:

A data object with the translated fields.

Return type:

ElectromagneticFieldData

to_zbf(fname, units='mm', background_refractive_index=1, n_x=None, n_y=None, freq=None, mode_index=None, r_x=0, r_y=0, z_x=0, z_y=0, rec_efficiency=0, sys_efficiency=0)[source]#

For a 2D monitor, export the fields to a Zemax Beam File (.zbf).

The mode area is used to approximate the beam waist, which is only valid if the beam profile approximates a Gaussian beam.

Parameters:

  • fname (PathLike) – Full path to the .zbf file to be written.

  • units (UnitsZBF = "mm") – Spatial units used for the .zbf file. Options are "mm", "cm", "in", or "m". Defaults to "mm".

  • background_refractive_index (float = 1) – Refractive index of the medium surrounding the monitor. Defaults to 1.

  • n_x (Optional[int] = None) – Number of field samples along x. Must be a power of 2, between 2^5 and 2^13 inclusive per Zemax’s requirements. Defaults to None, in which case a value is chosen for the user depending on the coordinates in the field data.

  • n_y (Optional[int] = None) – Number of field samples along y. Must be a power of 2, between 2^5 and 2^13 inclusive per Zemax’s requirements. Defaults to None, in which case a value is chosen for the user depending on the coordinates in the field data.

  • freq (Optional[float] = None) – Field frequency selection. If None, the average of the recorded frequencies is used.

  • mode_index (Optional[int] = None) – For ModeData, choose which mode to save.

  • r_x (float = 0) – Pilot beam Rayleigh distance in x, um. Defaults to 0.

  • r_y (float = 0) – Pilot beam Rayleigh distance in y, um. Defaults to 0.

  • z_x (float = 0) – Pilot beam z position with respect to the waist in x, um. Defaults to 0.

  • z_y (float = 0) – Pilot beam z position with respect to the waist in y, um. Defaults to 0.

  • rec_efficiency (float = 0) – Receiver efficiency, zero if fiber coupling is not computed. Defaults to 0.

  • sys_efficiency (float = 0) – System efficiency, zero if fiber coupling is not computed. Defaults to 0.

Returns:

The two E field components being exported to .zbf.

Return type:

tuple[ScalarFieldDataArray,:class:~tidy3d.ScalarFieldDataArray]