tidy3d.SpaceModulation#

class tidy3d.SpaceModulation(*, type: Literal['SpaceModulation'] = 'SpaceModulation', amplitude: Union[float, tidy3d.components.data.data_array.SpatialDataArray] = 1, phase: Union[float, tidy3d.components.data.data_array.SpatialDataArray] = 0, interp_method: Literal['nearest', 'linear'] = 'nearest')#

Bases: tidy3d.components.time_modulation.AbstractSpaceModulation

The modulation profile with a user-supplied spatial distribution of amplitude and phase.

Parameters
• amplitude (Union[float, SpatialDataArray] = 1) – Amplitude of modulation that can vary spatially. It takes the unit of whatever is being modulated.

• phase (Union[float, SpatialDataArray] = 0) – [units = rad]. Phase of modulation that can vary spatially.

• interp_method (Literal['nearest', 'linear'] = nearest) – Method of interpolation to use to obtain values at spatial locations on the Yee grids.

Note

$amp\_space(r) = amplitude(r) \cdot e^{i \cdot phase(r)}$

The full space-time modulation is,

$amp(r, t) = \Re[amp\_time(t) \cdot amp\_space(r)]$

Example

>>> Nx, Ny, Nz = 10, 9, 8
>>> X = np.linspace(-1, 1, Nx)
>>> Y = np.linspace(-1, 1, Ny)
>>> Z = np.linspace(-1, 1, Nz)
>>> coords = dict(x=X, y=Y, z=Z)
>>> amp = SpatialDataArray(np.random.random((Nx, Ny, Nz)), coords=coords)
>>> phase = SpatialDataArray(np.random.random((Nx, Ny, Nz)), coords=coords)
>>> space = SpaceModulation(amplitude=amp, phase=phase)

__init__(**kwargs)#

Init method, includes post-init validators.

Methods

 __init__(**kwargs) Init method, includes post-init validators. 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. 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. Return a dictionary of this object's sub-models indexed by their hash values. 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(). 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_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

 max_modulation Estimated maximum modulation amplitude. amplitude phase interp_method
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.

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

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

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

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

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

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

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

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.

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

property max_modulation: float#

Estimated maximum modulation amplitude.

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_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) #

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