LumpedModel

LumpedModel(*, port_map=None, **kwargs)

Abstract lumped model class for computing MNA (Modified Nodal Analysis) stamps.

Lumped models represent electrical subcircuits using frequency-dependent MNA matrices. When port_map is set, a LumpedModel acts as a Model and provides S-parameters derived from the MNA matrix.

Args

• port_map (dict[str, tuple[str, complex] | tuple[str, str, complex]] | None): Port mappings from terminals. See description below.
• **kwargs (object): Additional keyword arguments.

Implementation Requirements

Lumped models must:

1. Derive from this class
2. Implement start_mna returning an MNAMatrix
3. Call super().__init__ with all parameters as keyword arguments
4. Be registered with register_model_class

The start_mna method can return either:

• MNAMatrix: MNA stamp matrix (synchronous computation).
• A runner object with status dict and mna_matrix attribute.

Port Mapping

The port_map defines how MNA terminals map to ports:

1. Ground-Referenced Ports: Use (signal, impedance) (this is the only ground-referenced form):

   >>> port_map = {"P1": ("node1", 50.0)}

2. Differential Ports: Specify both signal and reference terminals:

   >>> port_map = {"P1": ("sig", "ref", 50.0)}

   Note: in the 3-tuple form, reference_terminal is always explicit. For example, ("sig", "", 50.0) uses the literal terminal name "", not ground. In this form, both signal_terminal and reference_terminal must match terminals present in the model’s returned MNAMatrix.

Example

>>> import numpy as np
>>>
>>> class RCFilter(pf.LumpedModel):
...     def __init__(self, *, resistance, capacitance, **kwargs):
...         super().__init__(resistance=resistance, capacitance=capacitance, **kwargs)
...         self.R = resistance
...         self.C = capacitance
...
...     def start_mna(self, component, frequencies, **kwargs):
...         omega = 2 * np.pi * np.array(frequencies)
...         G = 1 / self.R
...         # exp(-i w t) convention: a capacitor's admittance is -j w C.
...         Y_C = -1j * omega * self.C
...
...         elements = {
...             ("in", "in"): np.full(len(frequencies), G, dtype=complex),
...             ("in", "out"): np.full(len(frequencies), -G, dtype=complex),
...             ("out", "in"): np.full(len(frequencies), -G, dtype=complex),
...             ("out", "out"): G + Y_C,
...         }
...         return pf.MNAMatrix(frequencies, elements)
...
>>> pf.register_model_class(RCFilter)
>>> model = RCFilter(
...     resistance=50.0,
...     capacitance=1e-12,
...     port_map={"in": ("in", 50.0), "out": ("out", 50.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, frequencies, **kwargs)

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.