tidy3d.components.base.Tidy3dBaseModel

class Tidy3dBaseModel

Bases: BaseModel

Base pydantic model that all Tidy3d components inherit from. Defines configuration for handling data structures as well as methods for importing, exporting, and hashing tidy3d objects. For more details on pydantic base models, see: Pydantic Models

Attributes

attrs

Methods

__init__(**kwargs)	Init method, includes post-init validators.
add_type_field()	Automatically place "type" field with model name in the model field dictionary.
copy([deep])	Copy a Tidy3dBaseModel.
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_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.
insert_traced_fields(field_mapping)	Recursively insert a map of paths to autograd-traced fields into a copy of this obj.
strip_traced_fields([starting_path, ...])	Extract a dictionary mapping paths in the model to the data traced by autograd.
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_static()	Version of object with all autograd-traced fields removed.
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.
updated_copy([path, deep])	Make copy of a component instance with **kwargs indicating updated field values.

Inherited Common Usage

__hash__()

Hash method.

__init__(**kwargs)

Init method, includes post-init validators.

classmethod __init_subclass__()

Things that are done to each of the models.

class Config

Bases: object

Sets config for all Tidy3dBaseModel objects.

Configuration Options

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.

arbitrary_types_allowed = True

validate_all = True

extra = 'forbid'

validate_assignment = True

allow_population_by_field_name = True

json_encoders = {<class 'autograd.tracer.Box'>: <function Tidy3dBaseModel.Config.<lambda>>, <class 'complex'>: <function Tidy3dBaseModel.Config.<lambda>>, <class 'numpy.ndarray'>: <function ndarray_encoder>, <class 'xarray.core.dataarray.DataArray'>: <bound method DataArray._json_encoder of <class 'tidy3d.components.data.data_array.DataArray'>>}

frozen = True

allow_mutation = False

copy_on_model_validation = 'none'

attrs

copy(deep=True, **kwargs)

Copy a Tidy3dBaseModel. With deep=True as default.

updated_copy(path=None, deep=True, **kwargs)

Make copy of a component instance with **kwargs indicating updated field values.

Note

If path supplied, applies the updated copy with the update performed on the sub- component corresponding to the path. For indexing into a tuple or list, use the integer value.

Example

>>> sim = simulation.updated_copy(size=new_size, path=f"structures/{i}/geometry") 

help(methods=False)

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) 

classmethod from_file(fname, group_path=None, **parse_obj_kwargs)

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 dict_from_file(fname, group_path=None)

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

to_file(fname)

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

classmethod from_json(fname, **parse_obj_kwargs)

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 dict_from_json(fname)

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

to_json(fname)

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

classmethod from_yaml(fname, **parse_obj_kwargs)

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 dict_from_yaml(fname)

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

to_yaml(fname)

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

static get_tuple_group_name(index)

Get the group name of a tuple element.

static get_tuple_index(key_name)

Get the index into the tuple based on its group name.

classmethod tuple_to_dict(tuple_values)

How we generate a dictionary mapping new keys to tuple values for hdf5.

classmethod get_sub_model(group_path, model_dict)

Get the sub model for a given group path.

classmethod dict_from_hdf5(fname, group_path='', custom_decoders=None)

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 from_hdf5(fname, group_path='', custom_decoders=None, **parse_obj_kwargs)

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

to_hdf5(fname, custom_encoders=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') 

classmethod dict_from_hdf5_gz(fname, group_path='', custom_decoders=None)

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 from_hdf5_gz(fname, group_path='', custom_decoders=None, **parse_obj_kwargs)

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

to_hdf5_gz(fname, custom_encoders=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') 

__lt__(other)

define < for getting unique indices based on hash.

__gt__(other)

define > for getting unique indices based on hash.

__le__(other)

define <= for getting unique indices based on hash.

__ge__(other)

define >= for getting unique indices based on hash.

__eq__(other)

Define == for two Tidy3dBaseModels.

strip_traced_fields(starting_path=(), include_untraced_data_arrays=False)

Extract a dictionary mapping paths in the model to the data traced by autograd.

Parameters:

• starting_path (tuple[str, ...] = ()) – If provided, starts recursing in self.dict() from this path of field names

• include_untraced_data_arrays (bool = False) – Whether to include DataArray objects without tracers. We need to include these when returning data, but are unnecessary for structures.

Returns:

mapping of traced fields used by autograd

Return type:

dict

insert_traced_fields(field_mapping)

Recursively insert a map of paths to autograd-traced fields into a copy of this obj.

to_static()

Version of object with all autograd-traced fields removed.

classmethod add_type_field()

Automatically place “type” field with model name in the model field dictionary.

classmethod generate_docstring()

Generates a docstring for a Tidy3D mode and saves it to the __doc__ of the class.

get_submodels_by_hash()

Return a dictionary of this object’s sub-models indexed by their hash values.