tidy3d.FieldData#

class tidy3d.FieldData(*, type: Literal['FieldData'] = 'FieldData', Ex: tidy3d.components.data.data_array.ScalarFieldDataArray = None, Ey: tidy3d.components.data.data_array.ScalarFieldDataArray = None, Ez: tidy3d.components.data.data_array.ScalarFieldDataArray = None, Hx: tidy3d.components.data.data_array.ScalarFieldDataArray = None, Hy: tidy3d.components.data.data_array.ScalarFieldDataArray = None, Hz: tidy3d.components.data.data_array.ScalarFieldDataArray = None, monitor: tidy3d.components.monitor.FieldMonitor, symmetry: Tuple[typing.Literal[0, - 1, 1], typing.Literal[0, - 1, 1], typing.Literal[0, - 1, 1]] = (0, 0, 0), symmetry_center: Tuple[float, float, float] = None, grid_expanded: tidy3d.components.grid.grid.Grid = None, grid_primal_correction: Union[float, tidy3d.components.data.data_array.FreqDataArray, tidy3d.components.data.data_array.TimeDataArray, tidy3d.components.data.data_array.FreqModeDataArray] = 1.0, grid_dual_correction: Union[float, tidy3d.components.data.data_array.FreqDataArray, tidy3d.components.data.data_array.TimeDataArray, tidy3d.components.data.data_array.FreqModeDataArray] = 1.0)#

Bases: tidy3d.components.data.dataset.FieldDataset, tidy3d.components.data.monitor_data.ElectromagneticFieldData

Data associated with a FieldMonitor: scalar components of E and H fields.

Parameters

Ex (Optional[ScalarFieldDataArray] = None) – Spatial distribution of the x-component of the electric field.
Ey (Optional[ScalarFieldDataArray] = None) – Spatial distribution of the y-component of the electric field.
Ez (Optional[ScalarFieldDataArray] = None) – Spatial distribution of the z-component of the electric field.
Hx (Optional[ScalarFieldDataArray] = None) – Spatial distribution of the x-component of the magnetic field.
Hy (Optional[ScalarFieldDataArray] = None) – Spatial distribution of the y-component of the magnetic field.
Hz (Optional[ScalarFieldDataArray] = None) – Spatial distribution of the z-component of the magnetic field.
monitor (FieldMonitor) – Frequency-domain field monitor associated with the data.
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 and flux.
grid_primal_correction (Union[float, FreqDataArray, TimeDataArray, FreqModeDataArray] = 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] = 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.

Example

>>> from tidy3d import ScalarFieldDataArray
>>> x = [-1,1,3]
>>> y = [-2,0,2,4]
>>> z = [-3,-1,1,3,5]
>>> f = [2e14, 3e14]
>>> coords = dict(x=x[:-1], y=y[:-1], z=z[:-1], f=f)
>>> grid = Grid(boundaries=Coords(x=x, y=y, z=z))
>>> scalar_field = ScalarFieldDataArray((1+1j) * np.random.random((2,3,4,2)), coords=coords)
>>> monitor = FieldMonitor(
...     size=(2,4,6), freqs=[2e14, 3e14], name='field', fields=['Ex', 'Hz'], colocate=True
... )
>>> data = FieldData(monitor=monitor, Ex=scalar_field, Hz=scalar_field, grid_expanded=grid)

__init__(**kwargs)#: Init method, includes post-init validators.

Methods

`__init__`(**kwargs)	Init method, includes post-init validators.
`add_type_field`()	Automatically place "type" field with model name in the model field dictionary.
`apply_phase`(phase)	Create a copy where all elements are phase-shifted by a value (in radians).
`at_coords`(coords)	Colocate data to some supplied coordinates.
`colocate`([x, y, z])	Colocate all of the data at a set of x, y, z coordinates.
`construct`([_fields_set])	Creates a new model setting __dict__ and __fields_set__ from trusted or pre-validated data.
`copy`(**kwargs)	Copy a Tidy3dBaseModel.
`dict`(*[, include, exclude, by_alias, ...])	Generate a dictionary representation of the model, optionally specifying which fields to include or exclude.
`dict_from_file`(fname[, group_path])	Loads a dictionary containing the model from a .yaml, .json, .hdf5, or .hdf5.gz file.
`dict_from_hdf5`(fname[, group_path, ...])	Loads a dictionary containing the model contents from a .hdf5 file.
`dict_from_hdf5_gz`(fname[, group_path, ...])	Loads a dictionary containing the model contents from a .hdf5.gz file.
`dict_from_json`(fname)	Load dictionary of the model from a .json file.
`dict_from_yaml`(fname)	Load dictionary of the model from a .yaml file.
`dot`(field_data[, conjugate])	Dot product (modal overlap) with another `FieldData` object.
`from_file`(fname[, group_path])	Loads a `Tidy3dBaseModel` from .yaml, .json, .hdf5, or .hdf5.gz file.
`from_hdf5`(fname[, group_path, custom_decoders])	Loads `Tidy3dBaseModel` instance to .hdf5 file.
`from_hdf5_gz`(fname[, group_path, ...])	Loads `Tidy3dBaseModel` instance to .hdf5.gz file.
`from_json`(fname, **parse_obj_kwargs)	Load a `Tidy3dBaseModel` from .json file.
`from_orm`(obj)
`from_yaml`(fname, **parse_obj_kwargs)	Loads `Tidy3dBaseModel` from .yaml file.
`generate_docstring`()	Generates a docstring for a Tidy3D mode and saves it to the __doc__ of the class.
`get_sub_model`(group_path, model_dict)	Get the sub model for a given group path.
`get_submodels_by_hash`()	Return a dictionary of this object's sub-models indexed by their hash values.
`get_tuple_group_name`(index)	Get the group name of a tuple element.
`get_tuple_index`(key_name)	Get the index into the tuple based on its group name.
`help`([methods])	Prints message describing the fields and methods of a `Tidy3dBaseModel`.
`json`(*[, include, exclude, by_alias, ...])	Generate a JSON representation of the model, include and exclude arguments as per dict().
`normalize`(source_spectrum_fn)	Return copy of self after normalization is applied using source spectrum function.
`outer_dot`(field_data[, conjugate])	Dot product (modal overlap) with another `FieldData` object.
`package_colocate_results`(centered_fields)	How to package the dictionary of fields computed via self.colocate().
`package_flux_results`(flux_values)	How to package flux
`parse_file`(path, *[, content_type, ...])
`parse_obj`(obj)
`parse_raw`(b, *[, content_type, encoding, ...])
`schema`([by_alias, ref_template])
`schema_json`(*[, by_alias, ref_template])
`to_file`(fname)	Exports `Tidy3dBaseModel` instance to .yaml, .json, or .hdf5 file
`to_hdf5`(fname[, custom_encoders])	Exports `Tidy3dBaseModel` instance to .hdf5 file.
`to_hdf5_gz`(fname[, custom_encoders])	Exports `Tidy3dBaseModel` instance to .hdf5.gz file.
`to_json`(fname)	Exports `Tidy3dBaseModel` instance to .json file
`to_source`(source_time, center[, size])	Create a `CustomFieldSource` from the fields stored in the `FieldData`.
`to_yaml`(fname)	Exports `Tidy3dBaseModel` instance to .yaml file.
`tuple_to_dict`(tuple_values)	How we generate a dictionary mapping new keys to tuple values for hdf5.
`update_forward_refs`(**localns)	Try to update ForwardRefs on fields based on this Model, globalns and localns.
`updated_copy`(**kwargs)	Make copy of a component instance with `**kwargs` indicating updated field values.
`validate`(value)
`warn_missing_grid_expanded`(val)	If `colocate` not provided, set to true, but warn that behavior has changed.

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.
`field_components`	Maps the field components to thier associated data.
`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.
`grid_locations`	Maps field components to the string key of their grid locations on the yee lattice.
`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.
`symmetry_eigenvalues`	Maps field components to their (positive) symmetry eigenvalues.
`symmetry_expanded`	Return the `AbstractFieldData` with fields expanded based on symmetry.
`symmetry_expanded_copy`	Create a copy of the `AbstractFieldData` with fields expanded based on symmetry.
`time_reversed_copy`	Make a copy of the data with time-reversed fields.
`monitor`

class Config#

Bases: object

Sets config for all Tidy3dBaseModel objects.

allow_population_by_field_namebool = True: Allow properties to stand in for fields(?).
arbitrary_types_allowedbool = True: Allow types like numpy arrays.
extrastr = ‘forbid’: Forbid extra kwargs not specified in model.
json_encodersDict[type, Callable]: Defines how to encode type in json file.
validate_allbool = True: Validate default values just to be safe.
validate_assignmentbool: Re-validate after re-assignment of field in model.

__eq__(other)#: Define == for two Tidy3DBaseModels.

__ge__(other)#: define >= for getting unique indices based on hash.

__gt__(other)#: define > for getting unique indices based on hash.

__hash__() → int#: Hash method.

classmethod __init_subclass__() → None#: Things that are done to each of the models.

__iter__() → TupleGenerator#: so dict(model) works

__le__(other)#: define <= for getting unique indices based on hash.

__lt__(other)#: define < for getting unique indices based on hash.

__pretty__(fmt: Callable[[Any], Any], **kwargs: Any) → Generator[Any, None, None]#: Used by devtools (https://python-devtools.helpmanual.io/) to provide a human readable representations of objects

__repr_name__() → str#: Name of the instance’s class, used in __repr__.

__rich_repr__() → RichReprResult#: Get fields for Rich library

classmethod __try_update_forward_refs__(**localns: Any) → None#: Same as update_forward_refs but will not raise exception when forward references are not defined.

classmethod add_type_field() → None#: Automatically place “type” field with model name in the model field dictionary.

apply_phase(phase: float) → tidy3d.components.data.dataset.AbstractFieldDataset#: Create a copy where all elements are phase-shifted by a value (in radians).

at_coords(coords: tidy3d.components.grid.grid.Coords) → xarray.core.dataset.Dataset#

Colocate data to some supplied coordinates. This is a convenience method that wraps colocate, and skips dimensions for which the data has a single data point only (colocate will error in that case.) If the coords are out of bounds for the data otherwise, an error will still be produced.

Parameters: coords (Coords) – Coordinates in x, y and z to colocate to.
Returns: Dataset containing all of the fields in the data interpolated to boundary locations on the Yee grid.
Return type: xarray.Dataset

colocate(x=None, y=None, z=None) → xarray.core.dataset.Dataset#

Colocate all of the data at a set of x, y, z coordinates.

Parameters

x (Optional[array-like] = None) – x coordinates of locations. If not supplied, does not try to colocate on this dimension.
y (Optional[array-like] = None) – y coordinates of locations. If not supplied, does not try to colocate on this dimension.
z (Optional[array-like] = None) – z coordinates of locations. If not supplied, does not try to colocate on this dimension.

Returns

Dataset containing all fields at the same spatial locations. For more details refer to xarray’s Documentaton.

Return type

xr.Dataset

Note

For many operations (such as flux calculations and plotting), it is important that the fields are colocated at the same spatial locations. Be sure to apply this method to your field data in those cases.

property colocation_boundaries: tidy3d.components.grid.grid.Coords#: Coordinates to be used for colocation of the data to grid boundaries.

property colocation_centers: tidy3d.components.grid.grid.Coords#: Coordinates to be used for colocation of the data to grid centers.

classmethod construct(_fields_set: Optional[SetStr] = None, **values: Any) → Model#: Creates a new model setting __dict__ and __fields_set__ from trusted or pre-validated data. Default values are respected, but no other validation is performed. Behaves as if Config.extra = ‘allow’ was set since it adds all passed values

copy(**kwargs) → tidy3d.components.base.Tidy3dBaseModel#: Copy a Tidy3dBaseModel. With deep=True as default.

dict(*, include: Optional[Union[AbstractSetIntStr, MappingIntStrAny]] = None, exclude: Optional[Union[AbstractSetIntStr, MappingIntStrAny]] = None, by_alias: bool = False, skip_defaults: Optional[bool] = None, exclude_unset: bool = False, exclude_defaults: bool = False, exclude_none: bool = False) → DictStrAny#: Generate a dictionary representation of the model, optionally specifying which fields to include or exclude.

classmethod dict_from_file(fname: str, group_path: Optional[str] = None) → dict#

Loads a dictionary containing the model from a .yaml, .json, .hdf5, or .hdf5.gz file.

Parameters

fname (str) – Full path to the file to load the Tidy3dBaseModel from.
group_path (str, optional) – Path to a group inside the file to use as the base level.

Returns

A dictionary containing the model.

Return type

dict

Example

>>> simulation = Simulation.from_file(fname='folder/sim.json') 

classmethod dict_from_hdf5(fname: str, group_path: str = '', custom_decoders: Optional[List[Callable]] = None) → dict#

Loads a dictionary containing the model contents from a .hdf5 file.

Parameters

fname (str) – Full path to the .hdf5 file to load the Tidy3dBaseModel from.
group_path (str, optional) – Path to a group inside the file to selectively load a sub-element of the model only.
custom_decoders (List[Callable]) – List of functions accepting (fname: str, group_path: str, model_dict: dict, key: str, value: Any) that store the value in the model dict after a custom decoding.

Returns

Dictionary containing the model.

Return type

dict

Example

>>> sim_dict = Simulation.dict_from_hdf5(fname='folder/sim.hdf5') 

classmethod dict_from_hdf5_gz(fname: str, group_path: str = '', custom_decoders: Optional[List[Callable]] = None) → dict#

Loads a dictionary containing the model contents from a .hdf5.gz file.

Parameters

fname (str) – Full path to the .hdf5.gz file to load the Tidy3dBaseModel from.
group_path (str, optional) – Path to a group inside the file to selectively load a sub-element of the model only.
custom_decoders (List[Callable]) – List of functions accepting (fname: str, group_path: str, model_dict: dict, key: str, value: Any) that store the value in the model dict after a custom decoding.

Returns

Dictionary containing the model.

Return type

dict

Example

>>> sim_dict = Simulation.dict_from_hdf5(fname='folder/sim.hdf5.gz') 

classmethod dict_from_json(fname: str) → dict#

Load dictionary of the model from a .json file.

Parameters: fname (str) – Full path to the .json file to load the Tidy3dBaseModel from.
Returns: A dictionary containing the model.
Return type: dict

Example

>>> sim_dict = Simulation.dict_from_json(fname='folder/sim.json') 

classmethod dict_from_yaml(fname: str) → dict#

Load dictionary of the model from a .yaml file.

Parameters: fname (str) – Full path to the .yaml file to load the Tidy3dBaseModel from.
Returns: A dictionary containing the model.
Return type: dict

Example

>>> sim_dict = Simulation.dict_from_yaml(fname='folder/sim.yaml') 

dot(field_data: Union[tidy3d.components.data.monitor_data.FieldData, tidy3d.components.data.monitor_data.ModeSolverData], conjugate: bool = True) → tidy3d.components.data.data_array.ModeAmpsDataArray#

Dot product (modal overlap) with another FieldData object. Both datasets have to be frequency-domain data associated with a 2D monitor. Along the tangential directions, the datasets have to have the same discretization. Along the normal direction, the monitor position may differ and is ignored. Other coordinates (frequency, mode_index) have to be either identical or broadcastable. Broadcasting is also supported in the case in which the other field_data has a dimension of size 1 whose coordinate is not in the list of coordinates in the self dataset along the corresponding dimension. In that case, the coordinates of the self dataset are used in the output.

Parameters

field_data (ElectromagneticFieldData) – A data instance to compute the dot product with.
conjugate (bool, optional) – If True (default), the dot product is defined as 1 / 4 times the integral of E_self* x H_other - H_self* x E_other, where x is the cross product and * is complex conjugation. If False, the complex conjugation is skipped.

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 of the first mode carried by the second, 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 power carried by a given mode is no longer valid.

property field_components: Dict[str, tidy3d.components.data.data_array.DataArray]#: Maps the field components to thier associated data.

property flux: tidy3d.components.data.data_array.FluxDataArray#: Flux for data corresponding to a 2D monitor.

classmethod from_file(fname: str, group_path: Optional[str] = None, **parse_obj_kwargs) → tidy3d.components.base.Tidy3dBaseModel#

Loads a Tidy3dBaseModel from .yaml, .json, .hdf5, or .hdf5.gz file.

Parameters

fname (str) – Full path to the file to load the Tidy3dBaseModel from.
group_path (str, optional) – Path to a group inside the file to use as the base level. Only for hdf5 files. Starting / is optional.
**parse_obj_kwargs – Keyword arguments passed to either pydantic’s parse_obj function when loading model.

Returns

An instance of the component class calling load.

Return type

Tidy3dBaseModel

Example

>>> simulation = Simulation.from_file(fname='folder/sim.json') 

classmethod from_hdf5(fname: str, group_path: str = '', custom_decoders: Optional[List[Callable]] = None, **parse_obj_kwargs) → tidy3d.components.base.Tidy3dBaseModel#

Loads Tidy3dBaseModel instance to .hdf5 file.

Parameters

fname (str) – Full path to the .hdf5 file to load the Tidy3dBaseModel from.
group_path (str, optional) – Path to a group inside the file to selectively load a sub-element of the model only. Starting / is optional.
custom_decoders (List[Callable]) – List of functions accepting (fname: str, group_path: str, model_dict: dict, key: str, value: Any) that store the value in the model dict after a custom decoding.
**parse_obj_kwargs – Keyword arguments passed to pydantic’s parse_obj method.

Example

>>> simulation = Simulation.from_hdf5(fname='folder/sim.hdf5') 

classmethod from_hdf5_gz(fname: str, group_path: str = '', custom_decoders: Optional[List[Callable]] = None, **parse_obj_kwargs) → tidy3d.components.base.Tidy3dBaseModel#

Loads Tidy3dBaseModel instance to .hdf5.gz file.

Parameters

fname (str) – Full path to the .hdf5.gz file to load the Tidy3dBaseModel from.
group_path (str, optional) – Path to a group inside the file to selectively load a sub-element of the model only. Starting / is optional.
custom_decoders (List[Callable]) – List of functions accepting (fname: str, group_path: str, model_dict: dict, key: str, value: Any) that store the value in the model dict after a custom decoding.
**parse_obj_kwargs – Keyword arguments passed to pydantic’s parse_obj method.

Example

>>> simulation = Simulation.from_hdf5_gz(fname='folder/sim.hdf5.gz') 

classmethod from_json(fname: str, **parse_obj_kwargs) → tidy3d.components.base.Tidy3dBaseModel#

Load a Tidy3dBaseModel from .json file.

Parameters

fname (str) – Full path to the .json file to load the Tidy3dBaseModel from.

Returns

Tidy3dBaseModel – An instance of the component class calling load.
**parse_obj_kwargs – Keyword arguments passed to pydantic’s parse_obj method.

Example

>>> simulation = Simulation.from_json(fname='folder/sim.json') 

classmethod from_yaml(fname: str, **parse_obj_kwargs) → tidy3d.components.base.Tidy3dBaseModel#

Loads Tidy3dBaseModel from .yaml file.

Parameters

fname (str) – Full path to the .yaml file to load the Tidy3dBaseModel from.
**parse_obj_kwargs – Keyword arguments passed to pydantic’s parse_obj method.

Returns

An instance of the component class calling from_yaml.

Return type

Tidy3dBaseModel

Example

>>> simulation = Simulation.from_yaml(fname='folder/sim.yaml') 

classmethod generate_docstring() → str#: Generates a docstring for a Tidy3D mode and saves it to the __doc__ of the class.

classmethod get_sub_model(group_path: str, model_dict: dict | list) → dict#: Get the sub model for a given group path.

get_submodels_by_hash() → Dict[int, List[Union[str, Tuple[str, int]]]]#: Return a dictionary of this object’s sub-models indexed by their hash values.

static get_tuple_group_name(index: int) → str#: Get the group name of a tuple element.

static get_tuple_index(key_name: str) → int#: Get the index into the tuple based on its group name.

property grid_corrected_copy: tidy3d.components.data.monitor_data.ElectromagneticFieldData#: Return a copy of self with grid correction factors applied (if necessary) and symmetry expanded.

property grid_locations: Dict[str, str]#: Maps field components to the string key of their grid locations on the yee lattice.

help(methods: bool = False) → None#

Prints message describing the fields and methods of a Tidy3dBaseModel.

Parameters: methods (bool = False) – Whether to also print out information about object’s methods.

Example

>>> simulation.help(methods=True) 

property intensity: tidy3d.components.data.data_array.ScalarFieldDataArray#: Return the sum of the squared absolute electric field components.

json(*, include: Optional[Union[AbstractSetIntStr, MappingIntStrAny]] = None, exclude: Optional[Union[AbstractSetIntStr, MappingIntStrAny]] = None, by_alias: bool = False, skip_defaults: Optional[bool] = None, exclude_unset: bool = False, exclude_defaults: bool = False, exclude_none: bool = False, encoder: Optional[Callable[[Any], Any]] = None, models_as_dict: bool = True, **dumps_kwargs: Any) → str#

Generate a JSON representation of the model, include and exclude arguments as per dict().

encoder is an optional function to supply as default to json.dumps(), other arguments as per json.dumps().

property mode_area: tidy3d.components.data.data_array.FreqModeDataArray#

Effective mode area corresponding to a 2D monitor.

Effective mode area is calculated as: (∫|E|²dA)² / (∫|E|⁴dA)

normalize(source_spectrum_fn: Callable[[float], complex]) → tidy3d.components.data.dataset.FieldDataset#: Return copy of self after normalization is applied using source spectrum function.

outer_dot(field_data: Union[tidy3d.components.data.monitor_data.FieldData, tidy3d.components.data.monitor_data.ModeSolverData], conjugate: bool = True) → tidy3d.components.data.data_array.MixedModeDataArray#

Dot product (modal overlap) with another FieldData object.

The tangential fields from field_data are interpolated to this object’s grid, so the data arrays don’t need to have the same discretization. The calculation is performed for all common frequencies between data arrays. In the output, mode_index_0 and mode_index_1 are the mode indices from this object and field_data, respectively, if they are instances of ModeSolverData.

Parameters

field_data (ElectromagneticFieldData) – A data instance to compute the dot product with.
conjugate (bool = True) – If True (default), the dot product is defined as 1 / 4 times the integral of E_self* x H_other - H_self* x E_other, where x is the cross product and * is complex conjugation. If False, the complex conjugation is skipped.

Returns

Data array with the complex-valued modal overlaps between the two mode data.

Return type

xarray.DataArray