IdealTransformer

IdealTransformer(
    *,
    turns_ratio: Annotated[float, exclusiveMinimum=0],
    port_map: dict[
        str,
        tuple[str, Annotated[complex, units='Ω']]
        | tuple[str, str, Annotated[complex, units='Ω']],
    ]
    | None = None,
) -> None

Ideal transformer with turns ratio n:1.

Constraint equations: $V(p_1) - V(p_2) = n (V(s_1) - V(s_2))$, $I_p = -n I_s$. Uses a pure constraint stamp with one auxiliary branch current. No impedance entries on the diagonal; no singularities at any frequency including DC.

Circuit diagram (4-terminal, floating):

        n:1
p1 ---.° || °,--- s1
       ) || (
       ) || (
       ) || (
p2 ---'  ||  '--- s2

Args

• turns_ratio: Turns ratio $n$ between primary and secondary.
• port_map: Port mappings from terminals (see LumpedModel).

Terminals:

• p1: Primary positive terminal
• p2: Primary negative terminal
• s1: Secondary positive terminal
• s2: Secondary negative terminal

Note

Use differential port mapping to extract 2-port S-parameters:

>>> port_map = {
...     "primary": ("p1", "p2", 50.0),
...     "secondary": ("s1", "s2", 50.0),
... }

Example

>>> # 2:1 step-down transformer
>>> xfmr = pf.IdealTransformer(turns_ratio=2.0)

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 lumped model.
setup_time_stepper	Set up a time stepper for time-domain simulation.
start	Start the S-matrix computation for this lumped model.
start_mna	Start the MNA matrix computation for this lumped model.
transform	Apply a transformation to this model.
update	Update this lumped 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 lumped 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 LumpedModel.start_mna.

Returns

SMatrix: Computed S matrix.

setup_time_stepper

Set up a time stepper for time-domain simulation.

start

start(self, component, frequencies, **kwargs)

Start the S-matrix computation for this lumped model.

Calls start_mna to get the MNA matrix, then wraps the result in a runner that converts to S-parameters using the port_map.

Args

• component (Component): Component to perform the calculation.
• frequencies (Sequence[float]): Frequency values at which to calculate the scattering parameters (in Hz).
• **kwargs (object): Passed to start_mna.

Returns

LumpedModelRunner: Runner with status, mna_matrix, and s_matrix attributes.

start_mna

start_mna(
    self,
    component: photonforge.Component | None,
    frequencies: list[float],
    **kwargs: object,
) -> photonforge.MNAMatrix

Start the MNA matrix computation for this lumped model.

Important

This is an abstract method that must be implemented by derived classes.

Return an MNAMatrix containing the MNA stamp for this component, if the calculation can be performed synchronously.

Otherwise, it must return an object with attributes status and mna_matrix that will be pooled to check the calculation progress. The status attribute must return a dictionary with 'progress' (a number from 0 to 100 indicating the calculation progress) and 'message' (one of 'running', 'success', or 'error', indicating the current calculation status). The 'mna_matrix' attribute should return the computed MNAMatrix once the calculation is successful (or None otherwise).

Terminal naming convention: Terminal names starting with _ are reserved for auxiliary branch-current variables (e.g., _I for an inductor branch current, _I1 / _I2 for transmission line branch currents). User-defined terminal names for physical nodes should not start with _ to avoid collisions when elements are composed inside a larger MNA hierarchy.

Args

• component (Component): Component to perform the calculation.
• frequencies (Sequence[float]): Frequency values at which to calculate the matrix parameters (in Hz).
• **kwargs (object): Additional keyword arguments.

Returns

MNAMatrix | object: Either an MNA matrix directly, or a runner with status and mna_matrix attributes.

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 lumped model.

Args

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

Returns

LumpedModel: This lumped model.

Attributes

Attribute	Description
parametric_function	str: Function used to update a parametric component.
parametric_kwargs	dict[str, object]: Keyword arguments used to update a parametric component.
port_map	dict[str, tuple[str, complex] | tuple[str, str, complex]] | None: Mapping from port names to (signal_terminal, impedance) or (signal_terminal, reference_terminal, impedance) tuples.
properties	Properties: Object properties.
random_variables	list[RandomVariable]: Random variables associated to this model’s parameters.
time_stepper	TimeStepper | None: Time stepper associated with this model.

parametric_function

str: Function used to update a parametric component.

parametric_kwargs

dict[str, object]: Keyword arguments used to update a parametric component.

port_map

dict[str, tuple[str, complex] | tuple[str, str, complex]] | None: Mapping from port names to (signal_terminal, impedance) or (signal_terminal, reference_terminal, impedance) tuples.

properties

Properties: Object properties.

random_variables

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

time_stepper

TimeStepper | None: Time stepper associated with this model.