Tidy3DModel

Tidy3DModel(
    run_time: tidy3d.components.run_time_spec.RunTimeSpec
    | float
    | None = None,
    medium: Annotated[
        tidy3d.components.medium.Medium
        | tidy3d.components.medium.AnisotropicMedium
        | tidy3d.components.medium.PECMedium
        | tidy3d.components.medium.PMCMedium
        | tidy3d.components.medium.PoleResidue
        | tidy3d.components.medium.Sellmeier
        | tidy3d.components.medium.Lorentz
        | tidy3d.components.medium.Debye
        | tidy3d.components.medium.Drude
        | tidy3d.components.medium.FullyAnisotropicMedium
        | tidy3d.components.medium.CustomMedium
        | tidy3d.components.medium.CustomPoleResidue
        | tidy3d.components.medium.CustomSellmeier
        | tidy3d.components.medium.CustomLorentz
        | tidy3d.components.medium.CustomDebye
        | tidy3d.components.medium.CustomDrude
        | tidy3d.components.medium.CustomAnisotropicMedium
        | tidy3d.components.medium.PerturbationMedium
        | tidy3d.components.medium.PerturbationPoleResidue
        | tidy3d.components.medium.LossyMetalMedium,
        _,
    ]
    | None = None,
    symmetry: Annotated[collections.abc.Sequence[int], _] = (0, 0, 0),
    boundary_spec: tidy3d.components.boundary.BoundarySpec | None = None,
    monitors: collections.abc.Sequence[
        typing.Annotated[
            tidy3d.components.monitor.FieldMonitor
            | tidy3d.components.monitor.FieldTimeMonitor
            | tidy3d.components.monitor.AuxFieldTimeMonitor
            | tidy3d.components.monitor.MediumMonitor
            | tidy3d.components.monitor.PermittivityMonitor
            | tidy3d.components.monitor.FluxMonitor
            | tidy3d.components.monitor.FluxTimeMonitor
            | tidy3d.components.monitor.ModeMonitor
            | tidy3d.components.monitor.ModeSolverMonitor
            | tidy3d.components.monitor.ModeTimeMonitor
            | tidy3d.components.monitor.FieldProjectionAngleMonitor
            | tidy3d.components.monitor.FieldProjectionCartesianMonitor
            | tidy3d.components.monitor.FieldProjectionKSpaceMonitor
            | tidy3d.components.monitor.DiffractionMonitor
            | tidy3d.components.monitor.DirectivityMonitor
            | tidy3d.components.microwave.monitor.MicrowaveModeMonitor
            | tidy3d.components.microwave.monitor.MicrowaveModeSolverMonitor
            | tidy3d.components.monitor.GaussianOverlapMonitor
            | tidy3d.components.monitor.AstigmaticGaussianOverlapMonitor
            | tidy3d.components.monitor.ThinLensOverlapMonitor
            | tidy3d.components.monitor.DipoleEmissionMonitor
            | tidy3d.components.monitor.PointCloudFieldMonitor
            | tidy3d.components.monitor.PointCloudPermittivityMonitor
            | tidy3d.components.monitor.SurfaceFieldMonitor
            | tidy3d.components.monitor.SurfaceFieldTimeMonitor,
            _,
        ]
    ] = (),
    structures: collections.abc.Sequence[
        tidy3d.components.structure.Structure
    ] = (),
    grid_spec: Annotated[float, exclusiveMinimum=0]
    | tidy3d.components.grid.grid_spec.GridSpec
    | None = None,
    shutoff: Annotated[float, exclusiveMinimum=0] | None = None,
    subpixel: tidy3d.components.subpixel_spec.SubpixelSpec
    | bool
    | None = None,
    courant: Annotated[float, maximum=1, minimum=0] | None = None,
    port_symmetries: collections.abc.Sequence[
        Annotated[collections.abc.Sequence[str, str, dict[str, str]], _]
    ]
    | collections.abc.Sequence[
        Annotated[collections.abc.Sequence[str | int], _]
    ]
    | collections.abc.Sequence[
        Annotated[
            collections.abc.Sequence[
                collections.abc.Sequence[str, str],
                collections.abc.Sequence[str, str],
                complex
                | collections.abc.Sequence[
                    collections.abc.Sequence[complex]
                ],
            ],
            _,
        ]
    ] = (),
    bounds: Annotated[
        collections.abc.Sequence[collections.abc.Sequence[float | None]], _
    ] = ((None, None, None), (None, None, None)),
    source_gap: Annotated[float, minimum=0] | None = None,
    simulation_updates: dict[str, object] | None = None,
    autograd_config: photonforge._autograd.tidy3d.config.Tidy3DAutogradConfig
    | None = None,
    verbose: bool = True,
) -> None

S matrix model based on Tidy3D FDTD calculation.

Args

• run_time: Maximal simulation run-time (in seconds) or an instance of tidy3d.RuntImeSpec.
• medium: Background medium. If None, the technology default is used.
• symmetry: Component symmetries.
• boundary_spec: Simulation boundary specifications (absorber by default).
• monitors: Extra field monitors added to the simulation.
• structures: Additional structures included in the simulations.
• grid_spec: Simulation grid specification. A single float can be used to specify the min_steps_per_wvl for an auto grid.
• shutoff: Field decay factor for simulation termination.
• subpixel: Flag controlling subpixel averaging in the simulation grid or an instance of tidy3d.SubpixelSpec.
• courant: Courant stability factor.
• port_symmetries: Port symmetries to reduce the number of simulation runs. See note below.
• bounds: Bound overrides for the final simulation in the form ((xmin, ymin, zmin), (xmax, ymax, zmax)). Values set to None are ignored.
• source_gap: Separation between source and monitor representing a component port. Defaults to 2 grid cells for optical simulations and 1% of the maximum wavelength for electrical ones. The defaults are used when this is unset or set to 0.
• simulation_updates: Dictionary of updates applied to all simulations generated by this model. See example below.
• autograd_config: Optional Tidy3D autograd configuration. When unset, defaults are used, including gradient_method="auto" to prefer geometry Jacobians and fall back to permittivity sensitivities. Normal routing is per (parameter, structure) entry, while geometry finite-difference issues fall back per parameter row.
• verbose: 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, courant, and source_gap 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. Usually, that means each item is a permutation of the sorted list of component ports.

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

Example

Keys in simulation_updates specify a path to the value that will be updated using a '/' as separator, analogously to the path argument in the updated_copy method from tidy3d objects. For indexing into a tuple or list, an integer value is used. The first part of the path can be an input in the form port@mode to specify that the update should be applied to a that simulation only.

>>> simulation_updates = {
...     "P0@0/grid_spec/grid_x/max_scale": 1.3,
...     "boundary_spec/z/plus": td.PML(),
...     "center/2": 0.0,
... }
>>> model = pf.Tidy3DModel(simulation_updates=simulation_updates)

See Also

• Tidy3D Model guide
• Y splitter example

Methods

Method	Description
autograd_smatrix	Compute autograd-compatible S-matrix for Tidy3D autograd gradients.
batch_data	Return the Tidy3D BatchData for a given component.
estimate_cost	Estimate the cost for S matrix computation.
get_simulations	Return all simulations required by this component.
s_matrix	Compute the S matrix for a component using this model.
setup_time_stepper	Obtain a time stepper for a component using this model.
start	Start computing the S matrix response from a component.
test_port_symmetries	Test this models port symmetries with a component.
transform	Apply a transformation to this model.
update	Update this model.

autograd_smatrix

autograd_smatrix(
    self,
    *,
    component: photonforge.Component,
    traced_params: numpy.ndarray,
    frequencies: collections.abc.Sequence[float],
    component_for_params: collections.abc.Callable[
        [numpy.ndarray], photonforge.Component
    ],
    param_names: collections.abc.Sequence[str],
    show_progress: bool = True,
    model_kwargs: dict[str, Any] | None = None,
) -> photonforge._autograd.smatrix.AutogradSMatrix

Compute autograd-compatible S-matrix for Tidy3D autograd gradients.

batch_data

batch_data(
    self,
    component: photonforge.Component,
    frequencies: collections.abc.Sequence[float],
    *,
    inputs: collections.abc.Sequence[str] = (),
    verbose: bool | None = None,
    show_progress: bool = True,
    **kwargs: object,
) -> object

Return the Tidy3D BatchData for a given component.

Uses the same arguments as Tidy3DModel.start.

estimate_cost

estimate_cost(self, *args, **kwargs)

Estimate the cost for S matrix computation.

All arguments are passed to the model’s start method with the addition of the keyword argument cost_estimation=True.

Returns

float: Cost estimation.

get_simulations

get_simulations(
    self,
    component: photonforge.Component,
    frequencies: collections.abc.Sequence[float],
    sources: collections.abc.Sequence[str] = (),
) -> (
    dict[str, tidy3d.components.simulation.Simulation]
    | tidy3d.components.simulation.Simulation
)

Return all simulations required by this component.

Args

• component: Instance of Component for calculation.
• frequencies: Sequence of frequencies for the simulation.
• sources: 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.

s_matrix

s_matrix(self, component, frequencies, show_progress=True, model_kwargs={})

Compute the S matrix for a component using this model.

Args

• component (Component): Component to perform the calculation.
• frequencies (Sequence[float]): Frequency values at which to calculate the scattering parameters (in Hz).
• show_progress (bool): If True, show computation progress.
• model_kwargs (dict[str, object]): Keyword arguments passed to Model.start. Accepted arguments depend on the model type.

Returns

SMatrix: Computed S matrix.

Example

Compute only the responses from mode 0 of P0 with Tidy3D to reduce the number and cost of simulations:

>>> model = pf.Tidy3DModel()
>>> s_matrix = model.s_matrix(  # doctest: +SKIP
...     component,
...     frequencies,
...     model_kwargs={"inputs": ("P0@0",)},
... )

A port name such as ("P0",) selects all modes of that port. All outputs for the selected inputs are returned; responses from unselected inputs are not computed. Use Model.estimate_cost with the same inputs passed directly to estimate the reduced run.

setup_time_stepper

setup_time_stepper(
    self,
    component,
    time_step,
    carrier_frequency=0,
    show_progress=True,
    time_stepper_kwargs={},
)

Obtain a time stepper for a component using this model.

Args

• component (Component): Component for the time stepper.
• time_step (float): The interval between time steps (in seconds).
• carrier_frequency (float): The carrier frequency used to construct the time stepper. The carrier should be omitted from the input signals, as it is handled automatically by the time stepper.
• show_progress (bool): If True, show computation progress.
• time_stepper_kwargs (dict[str, object]): Keyword arguments passed to TimeStepper.setup. Each time stepper type can accept a different set of arguments. Check the documentation for the each time stepper’s setup_state method for more information.

Returns

TimeStepper: Initialized time stepper.

start

start(
    self,
    component: photonforge.Component,
    frequencies: collections.abc.Sequence[float],
    *,
    inputs: collections.abc.Sequence[str] = (),
    verbose: bool | None = None,
    cost_estimation: bool = False,
    **kwargs: object,
) -> photonforge.models.tidy3d._Tidy3DModelRunner

Start computing the S matrix response from a component.

Args

• component: Component from which to compute the S matrix.
• frequencies: Sequence of frequencies at which to perform the computation.
• inputs: Limit calculation to specific inputs, reducing the number and cost of simulations. A port name selects all its modes; a {port}@{mode} specification selects one mode. All outputs for the selected inputs are returned, while responses from unselected inputs are not computed.
• verbose: If set, overrides the model’s verbose attribute.
• cost_estimation: If set, simulations are uploaded, but not executed. S matrix will not be computed.
• **kwargs: Unused.

Returns

Result object with attributes status and s_matrix.

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

test_port_symmetries(
    self,
    component: photonforge.Component,
    frequencies: collections.abc.Sequence[float],
    plot_error: bool = True,
    atol: float = 0.02,
    **kwargs: object,
) -> bool

Test this models port symmetries with a component.

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

Args

• component: Component to test.
• frequencies: Frequencies to use during the test.
• plot_error: Create a plot for elements with symmetry errors.
• atol: 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.

transform

transform(
    self,
    translation: collections.abc.Sequence[float] | complex = (0, 0),
    rotation: float = 0,
    scaling: float = 1,
    x_reflection: bool = False,
) -> 'Tidy3DModel'

Apply a transformation to this model.

The base implementation is a no-op and returns self. Derived classes can override this method to transform model-specific geometry settings.

Args

• translation (Sequence[float] | complex): Translation vector.
• rotation (float): Rotation angle in degrees.
• scaling (float): Magnification factor.
• x_reflection (bool): Mirror across the horizontal axis.

Returns

Model: This object with transformations applied.

update

update(self, *args, **kwargs)

Update this model.

All contents of the model are updated with the contents from the updated version. object contents or modifications introduced after the model creation (outside of the original parametric function) are not propagated.

The model’s time stepper does not participate in the update, unless the __init__ method of the derived model class replaces it via set_time_stepper.

Args

• *args (object): Positional arguments to the parametric model.
• **kwargs (object): Keyword arguments to the parametric model.

Returns

Model: This model.

Note

The original keyword arguments used to generate the model are stored and updated with the passed kwargs. This updated version is used in the function call and will be stored for future updates. Positional arguments are not stored.

Attributes

Attribute	Description
parametric_function	str: Function used to update the model.
parametric_kwargs	dict[str, object]: Keyword arguments used to update the model.
properties	Properties: Object properties.
random_variables	list[RandomVariable]: Random variables associated to the model’s parameters.
time_stepper	TimeStepper | None: Time stepper associated with this model.

parametric_function

str: Function used to update the model.

parametric_kwargs

dict[str, object]: Keyword arguments used to update the model.

properties

Properties: Object properties.

random_variables

list[RandomVariable]: Random variables associated to the model’s parameters.

time_stepper

TimeStepper | None: Time stepper associated with this model.