tidy3d.plugins.smatrix.ComponentModeler#

class tidy3d.plugins.smatrix.ComponentModeler(*, simulation: tidy3d.components.simulation.Simulation, ports: typing.Tuple[tidy3d.plugins.smatrix.smatrix.Port, ...] = (), freqs: typing.Union[typing.Tuple[float, ...], tidy3d.components.types.ArrayLike[dtype=float, ndim=1]], folder_name: str = 'default', element_mappings: typing.Tuple[typing.Tuple[typing.Tuple[typing.Tuple[str, pydantic.v1.types.NonNegativeInt], typing.Tuple[str, pydantic.v1.types.NonNegativeInt]], typing.Tuple[typing.Tuple[str, pydantic.v1.types.NonNegativeInt], typing.Tuple[str, pydantic.v1.types.NonNegativeInt]], typing.Union[tidy3d.components.types.tidycomplex, tidy3d.components.types.ComplexNumber]], ...] = (), run_only: typing.Optional[typing.Tuple[typing.Tuple[str, pydantic.v1.types.NonNegativeInt], ...]] = None, verbose: bool = False, callback_url: str = None, path_dir: str = '.', type: typing.Literal['ComponentModeler'] = 'ComponentModeler')#

Bases: tidy3d.components.base.Tidy3dBaseModel

Tool for modeling devices and computing scattering matrix elements.

Parameters

simulation (Simulation) – Simulation describing the device without any sources present.
ports (Tuple[Port, ...] = ()) – Collection of ports describing the scattering matrix elements. For each input mode, one simulation will be run with a modal source.
freqs (Union[Tuple[float, ...], ArrayLike[dtype=float, ndim=1]]) – [units = Hz]. Array or list of frequencies at which to evaluate the scattering matrix.
folder_name (str = default) – Name of the folder for the tasks on web.
element_mappings (Tuple[Tuple[Tuple[Tuple[str, pydantic.v1.types.NonNegativeInt], Tuple[str, pydantic.v1.types.NonNegativeInt]], Tuple[Tuple[str, pydantic.v1.types.NonNegativeInt], Tuple[str, pydantic.v1.types.NonNegativeInt]], Union[tidy3d.components.types.tidycomplex, tidy3d.components.types.ComplexNumber]], ...] = ()) – Mapping between elements of the scattering matrix, as specified by pairs of (port name, mode index) matrix indices, where the first element of the pair is the output and the second element of the pair is the input.Each item of element_mappings is a tuple of (element1, element2, c), where the scattering matrix Smatrix[element2] is set equal to c * Smatrix[element1].If all elements of a given column of the scattering matrix are defined by element_mappings, the simulation corresponding to this column is skipped automatically.
run_only (Optional[Tuple[Tuple[str, pydantic.v1.types.NonNegativeInt], ...]] = None) – If given, a tuple of matrix indices, specified by (Port, int), to run only, excluding the other rows from the scattering matrix. If this option is used, the data corresponding to other inputs will be missing in the resulting matrix.
verbose (bool = False) – Whether the ComponentModeler should print status and progressbars.
callback_url (Optional[str] = None) – Http PUT url to receive simulation finish event. The body content is a json file with fields {'id', 'status', 'name', 'workUnit', 'solverVersion'}.
path_dir (str = .) – Base directory where data and batch will be downloaded.

__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.
`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.
`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_path_dir`(path_dir)	Check whether the supplied 'path_dir' matches the internal field value.
`get_port_by_name`(port_name)	Get the port from the name.
`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().
`load`([path_dir])	Load a scattering matrix from saved BatchData object.
`parse_file`(path, *[, content_type, ...])
`parse_obj`(obj)
`parse_raw`(b, *[, content_type, encoding, ...])
`plot_sim`([x, y, z, ax])	Plot a `Simulation` with all sources added for each port, for troubleshooting.
`plot_sim_eps`([x, y, z, ax])	Plot permittivity of the `Simulation` with all sources added for each port.
`run`([path_dir])	Solves for the scattering matrix of the system.
`schema`([by_alias, ref_template])
`schema_json`(*[, by_alias, ref_template])
`shift_port`(port)	Generate a new port shifted by the shift amount in normal direction.
`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_monitor`(port)	Creates a mode monitor from a given port.
`to_source`(port, mode_index)	Creates a list of mode sources from a given port.
`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)

Attributes

`batch`	Batch associated with this component modeler.
`batch_path`	Path to the batch saved to file.
`matrix_indices_monitor`	Tuple of all the possible matrix indices (port, mode_index) in the Component Modeler.
`matrix_indices_run_sim`	Tuple of all the source matrix indices (port, mode_index) in the Component Modeler.
`matrix_indices_source`	Tuple of all the source matrix indices (port, mode_index) in the Component Modeler.
`max_mode_index`	maximum mode indices for the smatrix dataset for the in and out ports, respectively.
`port_names`	List of port names for inputs and outputs, respectively.
`sim_dict`	Generate all the `Simulation` objects for the S matrix calculation.
`simulation`
`ports`
`freqs`
`folder_name`
`element_mappings`
`run_only`
`verbose`
`callback_url`
`path_dir`

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.

property batch: tidy3d.web.api.container.Batch#: Batch associated with this component modeler.

property batch_path: str#: Path to the batch saved to file.

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') 

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.

get_path_dir(path_dir: str) → None#: Check whether the supplied ‘path_dir’ matches the internal field value.

get_port_by_name(port_name: str) → tidy3d.plugins.smatrix.smatrix.Port#: Get the port from the name.

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.

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) 

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().

load(path_dir: str = '.') → tidy3d.plugins.smatrix.smatrix.SMatrixDataArray#: Load a scattering matrix from saved BatchData object.

property matrix_indices_monitor: Tuple[Tuple[str, pydantic.v1.types.NonNegativeInt], ...]#: Tuple of all the possible matrix indices (port, mode_index) in the Component Modeler.

property matrix_indices_run_sim: Tuple[Tuple[str, pydantic.v1.types.NonNegativeInt], ...]#: Tuple of all the source matrix indices (port, mode_index) in the Component Modeler.

property matrix_indices_source: Tuple[Tuple[str, pydantic.v1.types.NonNegativeInt], ...]#: Tuple of all the source matrix indices (port, mode_index) in the Component Modeler.

property max_mode_index: Tuple[int, int]#: maximum mode indices for the smatrix dataset for the in and out ports, respectively.

plot_sim(x: float = None, y: float = None, z: float = None, ax: matplotlib.axes._axes.Axes = None, **kwargs) → matplotlib.axes._axes.Axes#: Plot a Simulation with all sources added for each port, for troubleshooting.

plot_sim_eps(x: float = None, y: float = None, z: float = None, ax: matplotlib.axes._axes.Axes = None, **kwargs) → matplotlib.axes._axes.Axes#: Plot permittivity of the Simulation with all sources added for each port.

property port_names: Tuple[List[str], List[str]]#: List of port names for inputs and outputs, respectively.

run(path_dir: str = '.') → tidy3d.plugins.smatrix.smatrix.SMatrixDataArray#: Solves for the scattering matrix of the system.

shift_port(port: tidy3d.plugins.smatrix.smatrix.Port) → tidy3d.plugins.smatrix.smatrix.Port#: Generate a new port shifted by the shift amount in normal direction.

property sim_dict: Dict[str, tidy3d.components.simulation.Simulation]#: Generate all the Simulation objects for the S matrix calculation.

to_file(fname: str) → None#

Exports Tidy3dBaseModel instance to .yaml, .json, or .hdf5 file

Parameters: fname (str) – Full path to the .yaml or .json file to save the Tidy3dBaseModel to.

Example

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

to_hdf5(fname: str, custom_encoders: Optional[List[Callable]] = None) → None#

Exports Tidy3dBaseModel instance to .hdf5 file.

Parameters

fname (str) – Full path to the .hdf5 file to save the Tidy3dBaseModel to.
custom_encoders (List[Callable]) – List of functions accepting (fname: str, group_path: str, value: Any) that take the value supplied and write it to the hdf5 fname at group_path.

Example

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

to_hdf5_gz(fname: str, custom_encoders: Optional[List[Callable]] = None) → None#

Exports Tidy3dBaseModel instance to .hdf5.gz file.

Parameters

fname (str) – Full path to the .hdf5.gz file to save the Tidy3dBaseModel to.
custom_encoders (List[Callable]) – List of functions accepting (fname: str, group_path: str, value: Any) that take the value supplied and write it to the hdf5 fname at group_path.

Example

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

to_json(fname: str) → None#

Exports Tidy3dBaseModel instance to .json file

Parameters: fname (str) – Full path to the .json file to save the Tidy3dBaseModel to.

Example

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

to_monitor(port: tidy3d.plugins.smatrix.smatrix.Port) → tidy3d.components.monitor.ModeMonitor#: Creates a mode monitor from a given port.

to_source(port: tidy3d.plugins.smatrix.smatrix.Port, mode_index: int) → List[tidy3d.components.source.ModeSource]#: Creates a list of mode sources from a given port.

to_yaml(fname: str) → None#

Exports Tidy3dBaseModel instance to .yaml file.

Parameters: fname (str) – Full path to the .yaml file to save the Tidy3dBaseModel to.

Example

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

classmethod tuple_to_dict(tuple_values: tuple) → dict#: How we generate a dictionary mapping new keys to tuple values for hdf5.

classmethod update_forward_refs(**localns: Any) → None#: Try to update ForwardRefs on fields based on this Model, globalns and localns.

updated_copy(**kwargs) → tidy3d.components.base.Tidy3dBaseModel#: Make copy of a component instance with **kwargs indicating updated field values.