tidy3d.CustomMedium
tidy3d.CustomMedium#
- class tidy3d.CustomMedium#
Bases:
tidy3d.components.medium.AbstractMedium
Medium
with user-supplied permittivity distribution.- Parameters
name (Optional[str] = None) – Optional unique name for medium.
frequency_range (Optional[Tuple[float, float]] = None) – [units = (Hz, Hz)]. Optional range of validity for the medium.
eps_dataset (PermittivityDataset) – User-supplied dataset containing complex-valued permittivity as a function of space. Permittivity distribution over the Yee-grid will be interpolated based on
interp_method
.interp_method (Literal['nearest', 'linear'] = nearest) – Interpolation method to obtain permittivity values that are not supplied at the Yee grids; For grids outside the range of the supplied data, extrapolation will be applied. When the extrapolated value is smaller (greater) than the minimal (maximal) of the supplied data, the extrapolated value will take the minimal (maximal) of the supplied data.
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) >>> freqs = [2e14] >>> data = np.ones((Nx, Ny, Nz, 1)) >>> eps_diagonal_data = ScalarFieldDataArray(data, coords=dict(x=X, y=Y, z=Z, f=freqs)) >>> eps_components = {f"eps_{d}{d}": eps_diagonal_data for d in "xyz"} >>> eps_dataset = PermittivityDataset(**eps_components) >>> dielectric = CustomMedium(eps_dataset=eps_dataset, name='my_medium') >>> eps = dielectric.eps_model(200e12)
Show JSON schema
{ "title": "CustomMedium", "description": ":class:`.Medium` with user-supplied permittivity distribution.\n\nParameters\n----------\nname : Optional[str] = None\n Optional unique name for medium.\nfrequency_range : Optional[Tuple[float, float]] = None\n [units = (Hz, Hz)]. Optional range of validity for the medium.\neps_dataset : PermittivityDataset\n User-supplied dataset containing complex-valued permittivity as a function of space. Permittivity distribution over the Yee-grid will be interpolated based on ``interp_method``.\ninterp_method : Literal['nearest', 'linear'] = nearest\n Interpolation method to obtain permittivity values that are not supplied at the Yee grids; For grids outside the range of the supplied data, extrapolation will be applied. When the extrapolated value is smaller (greater) than the minimal (maximal) of the supplied data, the extrapolated value will take the minimal (maximal) of the supplied data.\n\nExample\n-------\n>>> Nx, Ny, Nz = 10, 9, 8\n>>> X = np.linspace(-1, 1, Nx)\n>>> Y = np.linspace(-1, 1, Ny)\n>>> Z = np.linspace(-1, 1, Nz)\n>>> freqs = [2e14]\n>>> data = np.ones((Nx, Ny, Nz, 1))\n>>> eps_diagonal_data = ScalarFieldDataArray(data, coords=dict(x=X, y=Y, z=Z, f=freqs))\n>>> eps_components = {f\"eps_{d}{d}\": eps_diagonal_data for d in \"xyz\"}\n>>> eps_dataset = PermittivityDataset(**eps_components)\n>>> dielectric = CustomMedium(eps_dataset=eps_dataset, name='my_medium')\n>>> eps = dielectric.eps_model(200e12)", "type": "object", "properties": { "name": { "title": "Name", "description": "Optional unique name for medium.", "type": "string" }, "frequency_range": { "title": "Frequency Range", "description": "Optional range of validity for the medium.", "units": [ "Hz", "Hz" ], "type": "array", "minItems": 2, "maxItems": 2, "items": [ { "type": "number" }, { "type": "number" } ] }, "type": { "title": "Type", "default": "CustomMedium", "enum": [ "CustomMedium" ], "type": "string" }, "eps_dataset": { "title": "Permittivity Dataset", "description": "User-supplied dataset containing complex-valued permittivity as a function of space. Permittivity distribution over the Yee-grid will be interpolated based on ``interp_method``.", "allOf": [ { "$ref": "#/definitions/PermittivityDataset" } ] }, "interp_method": { "title": "Interpolation method", "description": "Interpolation method to obtain permittivity values that are not supplied at the Yee grids; For grids outside the range of the supplied data, extrapolation will be applied. When the extrapolated value is smaller (greater) than the minimal (maximal) of the supplied data, the extrapolated value will take the minimal (maximal) of the supplied data.", "default": "nearest", "enum": [ "nearest", "linear" ], "type": "string" } }, "required": [ "eps_dataset" ], "additionalProperties": false, "definitions": { "PermittivityDataset": { "title": "PermittivityDataset", "description": "Dataset storing the diagonal components of the permittivity tensor.\n\nParameters\n----------\neps_xx : ScalarFieldDataArray\n Spatial distribution of the xx-component of the relative permittivity.\neps_yy : ScalarFieldDataArray\n Spatial distribution of the yy-component of the relative permittivity.\neps_zz : ScalarFieldDataArray\n Spatial distribution of the zz-component of the relative permittivity.\n\nExample\n-------\n>>> x = [-1,1]\n>>> y = [-2,0,2]\n>>> z = [-3,-1,1,3]\n>>> f = [2e14, 3e14]\n>>> coords = dict(x=x, y=y, z=z, f=f)\n>>> sclr_fld = ScalarFieldDataArray((1+1j) * np.random.random((2,3,4,2)), coords=coords)\n>>> data = PermittivityDataset(eps_xx=sclr_fld, eps_yy=sclr_fld, eps_zz=sclr_fld)", "type": "object", "properties": { "type": { "title": "Type", "default": "PermittivityDataset", "enum": [ "PermittivityDataset" ], "type": "string" }, "eps_xx": { "title": "DataArray", "description": "Spatial distribution of the xx-component of the relative permittivity.", "type": "xr.DataArray", "properties": { "_dims": { "title": "_dims", "type": "Tuple[str, ...]" } }, "required": [ "_dims" ] }, "eps_yy": { "title": "DataArray", "description": "Spatial distribution of the yy-component of the relative permittivity.", "type": "xr.DataArray", "properties": { "_dims": { "title": "_dims", "type": "Tuple[str, ...]" } }, "required": [ "_dims" ] }, "eps_zz": { "title": "DataArray", "description": "Spatial distribution of the zz-component of the relative permittivity.", "type": "xr.DataArray", "properties": { "_dims": { "title": "_dims", "type": "Tuple[str, ...]" } }, "required": [ "_dims" ] } }, "required": [ "eps_xx", "eps_yy", "eps_zz" ], "additionalProperties": false } } }
- attribute eps_dataset: tidy3d.components.data.dataset.PermittivityDataset [Required]#
User-supplied dataset containing complex-valued permittivity as a function of space. Permittivity distribution over the Yee-grid will be interpolated based on
interp_method
.- Validated by
_eps_inf_greater_no_less_than_one_sigma_positive
_single_frequency
- attribute frequency_range: Tuple[float, float] = None#
Optional range of validity for the medium.
- attribute interp_method: Literal['nearest', 'linear'] = 'nearest'#
Interpolation method to obtain permittivity values that are not supplied at the Yee grids; For grids outside the range of the supplied data, extrapolation will be applied. When the extrapolated value is smaller (greater) than the minimal (maximal) of the supplied data, the extrapolated value will take the minimal (maximal) of the supplied data.
- attribute name: str = None#
Optional unique name for medium.
- Validated by
field_has_unique_names
- classmethod add_type_field() None #
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) 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, or .hdf5 file.
- Parameters
fname (str) – Full path to the .yaml or .json 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 = '') 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.
- Returns
Dictionary containing the model.
- Return type
dict
Example
>>> sim_dict = Simulation.dict_from_hdf5(fname='folder/sim.hdf5')
- 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')
- static eps_complex_to_eps_sigma(eps_complex: complex, freq: float) Tuple[float, float] #
Convert complex permittivity at frequency
freq
to permittivity and conductivity values.- Parameters
eps_complex (complex) – Complex-valued relative permittivity.
freq (float) – Frequency to evaluate permittivity at (Hz).
- Returns
Real part of relative permittivity & electric conductivity.
- Return type
Tuple[float, float]
- static eps_complex_to_nk(eps_c: complex) Tuple[float, float] #
Convert complex permittivity to n, k values.
- Parameters
eps_c (complex) – Complex-valued relative permittivity.
- Returns
Real and imaginary parts of refractive index (n & k).
- Return type
Tuple[float, float]
- eps_dataset_freq(frequency: float) tidy3d.components.data.dataset.PermittivityDataset #
Permittivity dataset at
frequency
. The dispersion comes from DC conductivity that results in nonzero Im[eps].- Parameters
frequency (float) – Frequency to evaluate permittivity at (Hz).
- Returns
The permittivity evaluated at
frequency
.- Return type
- eps_diagonal(frequency: float) Tuple[complex, complex, complex] #
Main diagonal of the complex-valued permittivity tensor at
frequency
. Spatially, we take max{||eps||}, so that autoMesh generation works appropriately.
- eps_diagonal_on_grid(frequency: float, coords: tidy3d.components.grid.grid.Coords) Tuple[tidy3d.components.types.ArrayLike_dtype=<class 'complex'>_ndim=4, tidy3d.components.types.ArrayLike_dtype=<class 'complex'>_ndim=4, tidy3d.components.types.ArrayLike_dtype=<class 'complex'>_ndim=4] #
Spatial profile of main diagonal of the complex-valued permittivity at
frequency
interpolated at the supplied coordinates.- Parameters
frequency (float) – Frequency to evaluate permittivity at (Hz).
coords (
Coords
) – The grid point coordinates over which interpolation is performed.
- Returns
The complex-valued permittivity tensor at
frequency
interpolated at the supplied coordinate.- Return type
Tuple[np.ndarray, np.ndarray, np.ndarray]
- eps_model(frequency: float) complex #
Spatial and poloarizaiton average of complex-valued permittivity as a function of frequency.
- static eps_sigma_to_eps_complex(eps_real: float, sigma: float, freq: float) complex #
convert permittivity and conductivity to complex permittivity at freq
- Parameters
eps_real (float) – Real-valued relative permittivity.
sigma (float) – Conductivity.
freq (float) – Frequency to evaluate permittivity at (Hz). If not supplied, returns real part of permittivity (limit as frequency -> infinity.)
- Returns
Complex-valued relative permittivity.
- Return type
complex
- classmethod from_eps_raw(eps: tidy3d.components.data.data_array.ScalarFieldDataArray, interp_method: Literal['nearest', 'linear'] = 'nearest') tidy3d.components.medium.CustomMedium #
Construct a
CustomMedium
from datasets containing raw permittivity values.- Parameters
eps (
ScalarFieldDataArray
) – Dataset containing complex-valued permittivity as a function of space.interp_method (
InterpMethod
, optional) – Interpolation method to obtain permittivity values that are not supplied at the Yee grids.
- Returns
Medium containing the spatially varying permittivity data.
- Return type
- classmethod from_file(fname: str, group_path: Optional[str] = None, **parse_obj_kwargs) tidy3d.components.base.Tidy3dBaseModel #
Loads a
Tidy3dBaseModel
from .yaml, .json, or .hdf5 file.- Parameters
fname (str) – Full path to the .yaml or .json 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 = '', **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.
**parse_obj_kwargs – Keyword arguments passed to pydantic’s
parse_obj
method.
Example
>>> simulation.to_hdf5(fname='folder/sim.hdf5')
- 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_nk(n: tidy3d.components.data.data_array.ScalarFieldDataArray, k: Optional[tidy3d.components.data.data_array.ScalarFieldDataArray] = None, interp_method: Literal['nearest', 'linear'] = 'nearest') tidy3d.components.medium.CustomMedium #
Construct a
CustomMedium
from datasets containing n and k values.- Parameters
n (
ScalarFieldDataArray
) – Real part of refractive index.k (
ScalarFieldDataArray
= None) – Imaginary part of refrative index.interp_method (
InterpMethod
, optional) – Interpolation method to obtain permittivity values that are not supplied at the Yee grids.
- Returns
Medium containing the spatially varying permittivity data.
- Return type
- classmethod from_orm(obj: Any) Model #
- 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.
- 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.
- grids(bounds: Tuple[Tuple[float, float, float], Tuple[float, float, float]]) Dict[str, tidy3d.components.grid.grid.Grid] #
Make a
Grid
corresponding to the data in eacheps_ii
component. The min and max coordinates along each dimension are bounded bybounds
.
- 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) unicode #
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().
- nk_model(frequency: float) Tuple[float, float] #
Real and imaginary parts of the refactive index as a function of frequency.
- Parameters
frequency (float) – Frequency to evaluate permittivity at (Hz).
- Returns
Real part (n) and imaginary part (k) of refractive index of medium.
- Return type
Tuple[float, float]
- static nk_to_eps_complex(n: float, k: float = 0.0) complex #
Convert n, k to complex permittivity.
- Parameters
n (float) – Real part of refractive index.
k (float = 0.0) – Imaginary part of refrative index.
- Returns
Complex-valued relative permittivty.
- Return type
complex
- static nk_to_eps_sigma(n: float, k: float, freq: float) Tuple[float, float] #
Convert
n
,k
at frequencyfreq
to permittivity and conductivity values.- Parameters
n (float) – Real part of refractive index.
k (float = 0.0) – Imaginary part of refrative index.
frequency (float) – Frequency to evaluate permittivity at (Hz).
- Returns
Real part of relative permittivity & electric conductivity.
- Return type
Tuple[float, float]
- classmethod parse_file(path: Union[str, pathlib.Path], *, content_type: unicode = None, encoding: unicode = 'utf8', proto: pydantic.parse.Protocol = None, allow_pickle: bool = False) Model #
- classmethod parse_obj(obj: Any) Model #
- classmethod parse_raw(b: Union[str, bytes], *, content_type: unicode = None, encoding: unicode = 'utf8', proto: pydantic.parse.Protocol = None, allow_pickle: bool = False) Model #
- plot(freqs: float, ax: matplotlib.axes._axes.Axes = None) matplotlib.axes._axes.Axes #
Plot n, k of a
Medium
as a function of frequency.- Parameters
freqs (float) – Frequencies (Hz) to evaluate the medium properties at.
ax (matplotlib.axes._subplots.Axes = None) – Matplotlib axes to plot on, if not specified, one is created.
- Returns
The supplied or created matplotlib axes.
- Return type
matplotlib.axes._subplots.Axes
- classmethod schema(by_alias: bool = True, ref_template: unicode = '#/definitions/{model}') DictStrAny #
- classmethod schema_json(*, by_alias: bool = True, ref_template: unicode = '#/definitions/{model}', **dumps_kwargs: Any) unicode #
- sigma_model(freq: float) complex #
Complex-valued conductivity as a function of frequency.
- Parameters
freq (float) – Frequency to evaluate conductivity at (Hz).
- Returns
Complex conductivity at this frequency.
- Return type
complex
- 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) None #
Exports
Tidy3dBaseModel
instance to .hdf5 file.- Parameters
fname (str) – Full path to the .hdf5 file to save the
Tidy3dBaseModel
to.
Example
>>> simulation.to_hdf5(fname='folder/sim.hdf5')
- 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) tidy3d.components.base.Tidy3dBaseModel #
Make copy of a component instance with
**kwargs
indicating updated field values.
- classmethod validate(value: Any) Model #
- property n_cfl#
This property computes the index of refraction related to CFL condition, so that the FDTD with this medium is stable when the time step size that doesn’t take material factor into account is multiplied by
n_cfl`
.For dispersiveless custom medium, it equals
min[sqrt(eps_inf)]
, wheremin
is performed over all components and spatial points.