LumpedModel¶

class photonforge.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.

Parameters:

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

Implementation Requirements

Lumped models must:

Derive from this class
Implement start_mna() returning an MNAMatrix
Call super().__init__ with all parameters as keyword arguments
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 nodal terminals map to ports:

Ground-Referenced Ports: Use (signal, impedance) (this is the only ground-referenced form):
```
>>> port_map = {"P1": ("node1", 50.0)}
```
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
...         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

`autograd_smatrix`(*, component, ...[, ...])	Compute an autograd-compatible S matrix for traced parameters.
`estimate_cost`(args, *kwargs)	Estimate the cost for S matrix computation.
`s_matrix`(component, frequencies[, ...])	Compute the S matrix for a component using this lumped model.
`setup_time_stepper`	Not supported for lumped models.
`start`(component, frequencies, **kwargs)	Start the S-matrix computation for this lumped model.
`start_mna`(component, frequencies, **kwargs)	Start the MNA matrix computation for this lumped model.
`transform`([translation, rotation, scaling, ...])	Apply a transformation to this model.
`update`(args, *kwargs)	Update this lumped model.

Attributes

`parametric_function`	Function used to update a parametric component.
`parametric_kwargs`	Keyword arguments used to update a parametric component.
`port_map`	Mapping from port names to (signal_terminal, impedance) or (signal_terminal, reference_terminal, impedance) tuples.
`properties`	Object properties.
`random_variables`	Random variables associated to this model's parameters.
`time_stepper`	Lumped models do not use time steppers.

parametric_function¶

Function used to update a parametric component.

Type:: str

parametric_kwargs¶

Keyword arguments used to update a parametric component.

Type:: dict[str, object]

port_map¶

Mapping from port names to (signal_terminal, impedance) or (signal_terminal, reference_terminal, impedance) tuples.

Type:: dict[str, tuple[str, complex] | tuple[str, str, complex]] | None

properties¶

Object properties.

Type:: Properties

random_variables¶

Random variables associated to this model’s parameters.

Type:: list[RandomVariable]

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

Compute the S matrix for a component using this lumped model.

Parameters:

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:

Computed S matrix.

Return type:

SMatrix

setup_time_stepper()¶: Not supported for lumped models.

start(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.

Parameters:

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:

Runner with status, mna_matrix, and s_matrix attributes.

Return type:

LumpedModelRunner

start_mna(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 future LumpedCircuitModel.

Parameters:

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:

Either an MNA matrix directly, or a runner with status and mna_matrix attributes.

Return type:

MNAMatrix | object

time_stepper¶

Lumped models do not use time steppers.

Type:: None

update(*args, **kwargs)¶

Update this lumped model.

Parameters:

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

Returns:

This lumped model.

Return type:

LumpedModel