CircuitModel

CircuitModel(
    mesh_refinement: Annotated[float, exclusiveMinimum=0] | None = None,
    verbose: bool = True,
    port_map: dict[str, tuple[str, complex] | tuple[str, str, complex]]
    | None = None,
) -> None

Model based on circuit-level S-parameter calculation.

The component is expected to be composed of interconnected references. Scattering parameters are computed based on the S matrices from all references and their interconnections.

The S matrix of each reference is calculated based on the active model of the reference’s component. Each calculation is preceded by an update to the component’s technology, the component itself, and its active model by calling Reference.update. They are reset to their original state after the CircuitModel.start function is called. Keyword arguments in Reference.s_matrix_kwargs will be passed on to CircuitModel.start.

If a reference includes repetitions, it is flattened so that each instance is called separately.

Connections between incompatible ports (butt couplings) are handled automatically. For electrical ports, if either one has impedance information, the coupling matrix is approximated by reflection and transmission coefficients derived from both port impedances. For optical ports and electrical ports without impedance information, an EMEModel is used to calculate the butt coupling coefficients.

Args

• mesh_refinement: Minimal number of mesh elements per wavelength used for mode solving.
• verbose: Flag setting the verbosity of mode solver runs.
• port_map: Optional mapping from circuit ports to boundary terminals and reference impedances. When supplied, the whole component is assembled as one terminal hierarchy before conversion to an S matrix.

See Also

• Component.get_netlist
• PortSpec.impedance
• Circuit Model guide

Methods

Method	Description
autograd_smatrix	Compute an autograd-compatible S matrix for traced parameters.
estimate_cost	Estimate the cost for S matrix computation.
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.
transform	Apply a transformation to this model.
update	Update this model.

autograd_smatrix

autograd_smatrix(
    self,
    *,
    component,
    traced_params,
    frequencies,
    component_for_params,
    param_names,
    show_progress=True,
    model_kwargs=None,
)

Compute an autograd-compatible S matrix for traced parameters.

Important

This is an abstract method that must be implemented by derived classes that support autograd-based S-matrix computation.

Args

• component (Component): Nominal component associated with this autograd evaluation.
• traced_params (ndarray): Traced parameter vector used by autograd.
• frequencies (Sequence[float]): Frequency values at which to calculate the scattering parameters (in Hz).
• component_for_params (Callable[[ndarray], Component]): Callback that returns the component for a given traced parameter vector.
• param_names (Sequence[str]): Flattened traced parameter names aligned with traced_params.
• show_progress (bool): Progress display hint from Component.s_matrix.
• model_kwargs (dict[str, Any] | None): Model-specific keyword arguments forwarded from Component.s_matrix.

Returns

AutogradSMatrix: Autograd-compatible S matrix.

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.

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],
    updates: dict[
        str | tuple[str | re.Pattern | int | None, ...],
        dict[str, dict[str, Any]],
    ]
    | None = None,
    chain_technology_updates: bool = True,
    verbose: bool | None = None,
    cost_estimation: bool = False,
    **kwargs: object,
) -> object

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.
• updates: Dictionary of parameter updates to be applied to components, technologies, and models for references within the main component. See below for further information.
• chain_technology_updates: if set, a technology update will trigger an update for all components using that technology.
• verbose: If set, overrides the model’s verbose attribute and is passed to reference models.
• cost_estimation: If set, Tidy3D simulations are uploaded, but not executed. S matrix will not be computed.
• **kwargs: Keyword arguments passed to reference models.

Returns

Result object with attributes status and s_matrix.

The 'updates' dictionary contains keyword arguments for the Reference.update function for the references in the component dependency tree, such that, when the S parameter of a specific reference are computed, that reference can be updated without affecting others using the same component.

The enclosing component’s netlist is extracted before reference updates are applied. Updates must preserve each reference’s parent-visible ports, terminal connectivity, and port-model or terminal-model representation. Technology updates must also preserve connectivity rules used by the enclosing component. Updated internal geometry or hierarchy is supported when the parent-visible interface is unchanged; nested CircuitModel instances extract their own updated netlists. Selectors match pre-update component names and reference indices.

Each key in the dictionary is a reference query: a path string or a tuple. select_references previews the references a query selects, and a query that selects none emits a RuntimeWarning.

A path string lists component names separated by /, from the main component down:

• name: references to components with exactly that name. * matches any characters and ? a single one. A backslash makes the next character literal, as in \*, \[ or \/.

• name[i]: only the i-th reference to each matching component name.

• **: any number of levels, including none.

A tuple holds any number of the following:

• name: str | re.Pattern: references to components whose name matches the regular expression from its start, so "ARM" also selects "ARM_2". End it with $ to match the whole name.

• i: int, directly following name: only the i-th reference to each matching component name. A negative value selects all of them.

• None: any number of levels, including none.

References are numbered from 0 for each component name, in netlist order. Each repetition in a reference array counts as one reference.

Examples

>>> updates = {
...     # Component updates for the first "ARM" reference in the
...     # main component
...     "ARM[0]": {"component_updates": {"radius": 10}},
...     # Model updates for the second "BEND" reference under any
...     # "SUB" reference in the main component
...     "SUB/BEND[1]": {"model_updates": {"verbose": False}},
...     # Technology updates for references to components whose
...     # name starts with "COMP", at any depth
...     "**/COMP*": {"technology_updates": {"thickness": 0.3}},
...     # A tuple query: components named "MZM_" and digits, at any
...     # depth
...     (None, r"MZM_\d+$"): {"model_updates": {"verbose": False}},
... }
>>> s_matrix = component.s_matrix(
...     frequencies, model_kwargs={"updates": updates}
... )  # doctest: +SKIP

See Also

• Circuit Model guide
• Cascaded Rings Filter example

transform

transform(
    self, translation=(0, 0), rotation=0, scaling=1, x_reflection=False
)

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.

Properties

Property	Description
mesh_refinement
port_map	Mapping from circuit ports to terminal voltages and impedances.
verbose

mesh_refinement

No description available.

port_map

Mapping from circuit ports to terminal voltages and impedances.

verbose

No description available.

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.