Tidy3DModel

class photonforge.Tidy3DModel(run_time=None, medium=None, symmetry=(0, 0, 0), boundary_spec=None, monitors=(), structures=(), grid_spec=None, shutoff=None, subpixel=None, courant=None, port_symmetries=(), bounds=((None, None, None), (None, None, None)), verbose=True)

S matrix model based on Tidy3D FDTD calculation.

Parameters:

• run_time (RunTimeSpec | float | None) – Maximal simulation run-time (in seconds).

• medium (Medium | AnisotropicMedium | PECMedium | PoleResidue | Sellmeier | Lorentz | Debye | Drude | FullyAnisotropicMedium | CustomMedium | CustomPoleResidue | CustomSellmeier | CustomLorentz | CustomDebye | CustomDrude | CustomAnisotropicMedium | PerturbationMedium | PerturbationPoleResidue | LossyMetalMedium | None) – Background medium. If None, the technology default is used.

• symmetry (Sequence[int]) – Component symmetries.

• boundary_spec (BoundarySpec | None) – Simulation boundary specifications (absorber by default).

• monitors (Sequence[FieldMonitor | FieldTimeMonitor | PermittivityMonitor | FluxMonitor | FluxTimeMonitor | ModeMonitor | ModeSolverMonitor | FieldProjectionAngleMonitor | FieldProjectionCartesianMonitor | FieldProjectionKSpaceMonitor | DiffractionMonitor | DirectivityMonitor]) – Extra field monitors added to the simulation.

• structures (Sequence[Structure]) – Additional structures included in the simulations.

• grid_spec (float | GridSpec) – Simulation grid specification. A single float can be used to specify the min_steps_per_wvl for an auto grid.

• shutoff (float) – Field decay factor for simulation termination.

• subpixel (bool) – Flag controlling subpixel averaging in the simulation grid.

• courant (float) – Courant stability factor.

• port_symmetries (Sequence[Sequence[str, str, dict[str, str]]] | Sequence[Sequence[str] | Sequence[int]] | Sequence[Sequence[Sequence[str, str], Sequence[str, str], float | ndarray]]) – Port symmetries to reduce the number of simulation runs. See note below.

• bounds (Sequence[Sequence[float | None]]) – Bound overrides for the final simulation in the form ((xmin, ymin, zmin), (xmax, ymax, zmax)). Values set to None are ignored.

• verbose (bool) – Control solver verbosity.

If not set, the default grid specification for the component simulations is defined based on the wavelengths used in the s_matrix call. Defaults for run_time, boundary_spec, shutoff, subpixel, and courant can be defined in a "tidy3d" dictionary in config.default_kwargs. Note that the values used are the ones available at the time of the s_matrix or start call, not when model is initialized.

The start method accepts an inputs argument as a sequence or set of port names to limit the computation to those inputs. Instead of port names, {port}@{mode} specifications are also accepted.

Note

Each item in the port_symmetries sequence is a tuple of port names indicating the port replacements that do not affect the S matrix computation.

For example, in a Y junction with input “P0” and outputs “P1” and “P2” operating in the fundamental TE mode, we can exchange ports “P1” and “P2” and the S matrix remains the same, because S₁₀ = S₂₀ and S₁₁ = S₂₂. This symmetry is represented as the sequence ("P0", "P2", "P1"), which exchange “P1” anf “P2” with respect to the sorted port list “P0”, “P1”, “P2”. We could also use indices instead of port names to the same effect: (0, 2, 1).

It is also possible to represent S matrix symmetries for individual elements and with correction factors. This form requires a reference element, a mapped element, and a multiplication factor: ((src, dst1), (src2, dst2), c), which translates into S[src2@i, dst2@j] = c[i,j] * S[src1@i, dst1@j] for all mode indices i and j supported by the source and destination ports, respectively. Note that the multiplicative factor is an array so that each mode can be phase-compensated according to its field symmetry (if c is an scalar, all modes use the same value).

See also

• Tidy3D Model guide

• Y splitter example

Methods

batch_data_for(component)	Return the Tidy3D BatchData for a given component.
batch_file_for(component)	Return the file used to store the Tidy3D BatchData for a component.
data_path_for(component)	Return the path for the cached data for a component.
estimate_cost(component, frequencies, *[, ...])	Estimate the cost of the S matrix computation.
from_bytes(byte_repr)	De-serialize this model.
get_simulations(component, frequencies[, ...])	Return all simulations required by this component.
s_matrix(component, frequencies[, ...])	Compute the S matrix for a component using this model.
start(component, frequencies, *[, inputs, ...])	Start computing the S matrix response from a component.
test_port_symmetries(component, frequencies)	Test this models port symmetries with a component.
update(*args, **kwargs)	Update this model.

Attributes

as_bytes	Serialize this model.
parametric_function	Function used to update a parametric component.
parametric_kwargs	Keyword arguments used to update a parametric component.
random_variables	List of monte_carlo.RandomVariable associated to this component's parameters.

property as_bytes: bytes

Serialize this model.

batch_data_for(component)

Return the Tidy3D BatchData for a given component.

Parameters:

component (Component)

Return type:

Any | None

batch_file_for(component)

Return the file used to store the Tidy3D BatchData for a component.

Parameters:

component (Component)

Return type:

Path

data_path_for(component)

Return the path for the cached data for a component.

Parameters:

component (Component)

Return type:

Path

estimate_cost(component, frequencies, *, inputs=(), verbose=None)

Estimate the cost of the S matrix computation.

The estimation ignores any cached data.

Parameters:

• component (Component) – Component from which to compute the S matrix.

• frequencies (Sequence[float]) – Sequence of frequencies at which to perform the computation.

• inputs (Sequence[str]) – Limit calculation to specific inputs. Each item must be a port name or a {port}@{mode} specification.

• verbose (bool | None) – If set, overrides the model’s verbose attribute.

Returns:

Estimated computation cost.

Return type:

float

Important

When using geometry symmetry, the mode numbering in inputs is relative to the solver run with the symmetry applied, not the mode number presented in the final S matrix.

classmethod from_bytes(byte_repr)

De-serialize this model.

Parameters:

byte_repr (bytes)

Return type:

Tidy3DModel

get_simulations(component, frequencies, sources=())

Return all simulations required by this component.

Parameters:

• component (Component) – Instance of Component for calculation.

• frequencies (Sequence[float]) – Sequence of frequencies for the simulation.

• sources (Sequence[str]) – Port names to be used as sources ({port}@{mode} specifications are also accepted). If empty, use all required sources based on this model’s port symmetries.

Returns:

Dictionary of tidy3d.Simulation indexed by source name or a single simulation if the component has no ports.

Return type:

dict[str, Simulation] | Simulation

start(component, frequencies, *, inputs=(), verbose=None, **kwargs)

Start computing the S matrix response from a component.

Parameters:

• component (Component) – Component from which to compute the S matrix.

• frequencies (Sequence[float]) – Sequence of frequencies at which to perform the computation.

• inputs (Sequence[str]) – Limit calculation to specific inputs. Each item must be a port name or a {port}@{mode} specification.

• verbose (bool | None) – If set, overrides the model’s verbose attribute.

• **kwargs – Unused.

Returns:

Result object with attributes status and s_matrix.

Return type:

_Tidy3DModelRunner

Important

When using geometry symmetry, the mode numbering in inputs is relative to the solver run with the symmetry applied, not the mode number presented in the final S matrix.

test_port_symmetries(component, frequencies, plot_error=True, atol=0.02, **kwargs)

Test this models port symmetries with a component.

Effectively executes all simulations required without symmetries and compares with the symmetry setting.

Parameters:

• component (Component) – Component to test.

• frequencies (Sequence[float]) – Frequencies to use during the test.

• plot_error (bool) – Create a plot for elements with symmetry errors.

• atol (float) – Absolute tolerance when comparing results.

• **kwargs – Arguments to replace in the model during the test.

Returns:

Boolean indicating whether the symmetries for all Tidy3D models in the component are correct.

Return type:

bool