Model (pmrf.Model)

class pmrf.Model(*, name: str | None = None, metadata: Any = None)

Bases: Module

Base class for RF models.

Derive from this class to define your own, custom model.

This class should not be instantiated directly. It is created internally in ParamRF when models are built compositionally, or can be inherited from. When inheriting, at least one primary matrix method, such as pmrf.Model.s(), pmrf.Model.a(), pmrf.Model.y(), pmrf.Model.z(), or pmrf.Model.primary_matrix(), must be overridden. To implement a model by returning another model, inherit from pmrf.models.AbstractBuilder. Legacy classes may still override pmrf.Model.build() directly, but that interface is deprecated.

The model is an Equinox Module (an immutable dataclass) and a JAX PyTree. Parameters are declared using standard dataclass field syntax and should be annotated with type pmrf.Param and field specifier pmrf.param(). For more details on parameter definitions, see pmrf.parameters.

This class is not marked abstract: it acts more like a mix-in than an ABC.

Usage

Define new models by sub-classing the model and adding custom parameters and/or sub-models
Construct models by passing parameters and/or submodels to the initializer (like a dataclass).
Use pmrf.update() and methods such as terminated() and flipped() to create modified versions of your model.

Methods & Properties Summary

Core Methods

Method	Description
`s()`	Scattering (S) parameter matrix at impedance z0.
`a()`	ABCD parameter matrix.
`z()`	Impedance (Z) parameter matrix.
`y()`	Admittance (Y) parameter matrix.
`mna()`	Modified Nodal Analysis (MNA) stamp matrices.
`primary_matrix()`	Return the primary matrix. Can be overridden for dynamic dispatch.
`primary_domain`	The domain of the primary matrix as a string (e.g. `"s"`, `"a"`).
`build()`	Deprecated here; use `pmrf.models.AbstractBuilder`.
`expand()`	Expands the model’s topology. Used for circuit model flattening.

Helper Methods

Method	Description
`number_of_ports`	Number of ports.
`nports`	Alias of `number_of_ports`.
`port_tuples`	All (m, n) port index pairs.

Model Transformation

Method	Description
`flipped()`	Return a version of the model with ports flipped.
`renumbered()`	Return a version of the model with ports renumbered.
`terminated()`	Return a new model terminated by another (e.g. load).

File & Conversion Utilities

Method	Description
`to_skrf()`	Convert the model at frequencies to an `skrf.Network`.
`export_touchstone()`	Export the model response to a Touchstone file.

Examples

A general PiCLC network model:

import jax.numpy as jnp
import pmrf as prf

class PiCLC(prf.Model):
    C1: prf.Param
    L:  prf.Param
    C2: prf.Param

    def a(self, freq: prf.Frequency) -> jnp.ndarray:
        w = freq.w
        Y1, Y2, Y3 = (1j * w * self.C1), (1j * w * self.C2), 1 / (1j * w * self.L)
        return jnp.array([
            [1 + Y2 / Y3,        1 / Y3],
            [Y1 + Y2 + Y1*Y2/Y3, 1 + Y1 / Y3],
        ]).transpose(2, 0, 1)

a(frequency: Frequency) → Array

ABCD parameter matrix.

If a different parameter type is primary, this converts it to A.

Parameters:: frequency (Frequency) – Frequency grid.
Returns:: ABCD matrix with shape (nf, 2, 2).
Return type:: jnp.ndarray

build() → Model

Build the model (deprecated on direct Model subclasses).

Inherit from pmrf.models.AbstractBuilder to define a supported model-returning build() hook. This method remains temporarily available here for compatibility with existing classes that override it directly.

Return type:: Model
Raises:: NotImplementedError – In the base class; override in derived classes to build a compositional representation.

cascaded(other, **kwargs) → Model

Cascade this model with another, returning a new model.

See pmrf.models.composite.interconnected.Cascade.

Return type:: Model

expand() → tuple[list[tuple[Model, int]], list[list[tuple[Model, int]]]] | None

Expands this model into its internal graph representation for circuit flattening.

Used by Circuit.flattened to unpack composite models into a single flat netlist for a global matrix solve.

pmrf.models.AbstractBuilder delegates this to its built model, as does a direct Model.build() override, so user classes rarely need it. It is mainly for built-in composites such as pmrf.models.Cascade and pmrf.models.Renumbered.

Returns:

If the model is a composite or routing container, it returns a tuple of: - port_mapping: A list of length nports mapping each external port index

of this model to an internal (Model, port_index) tuple.

internal_connections: A list of sub-nodes (connections) to add to the netlist. Each node is a list of (Model, port_index) tuples.

If the model is a fundamental leaf component, it returns None.

Return type:

tuple or None

Examples

A 2-port model holding an inductor and capacitor in series:

>>> def expand(self):
...     L, C = self.inductor, self.capacitor
...     port_mapping = [(L, 0), (C, 1)]
...     internal_connections = [[(L, 1), (C, 0)]]
...     return port_mapping, internal_connections

export_touchstone(filename: str, frequency: Frequency | Any, sigma: float = 0.0, **skrf_kwargs)

Export the model response to a Touchstone file via scikit-rf.

Parameters:

filename (str)
frequency (Frequency | skrf.Frequency)
sigma (float, default=0.0) – Additive complex noise std for S-parameters.
**skrf_kwargs – Forwarded to skrf.Network.write_touchstone().

Returns:

Return value of Network.write_touchstone.

Return type:

Any

flipped(**kwargs) → Model

Return a version of the model with ports flipped.

See pmrf.models.composite.transformed.Flipped.

Return type:: Model

mna(frequency: Frequency) → MNAStamp

(experimental) Modified Nodal Analysis (MNA) stamp.

Can be overridden in sub-classes.

Otherwise converts from another domain (y2mna, z2mna, etc.). Y is preferred because it gives the sparsest stamp; other domains add auxiliary variables.

primary_matrix(freq: Frequency, **kwargs) → Array

The primary matrix (e.g. s, a etc.) as a function of frequency.

The primary matrix represents the matrix returned by pmrf.Model.primary_domain, which is either overridden by sub-classes, or is the first property directly overridden out of pmrf.Model.s(), pmrf.Model.a(), pmrf.Model.y(), pmrf.Model.z() (in that order), unless :meth:pmrf.Model.build is overridden, in which case the primary matrix of the built model is returned.

This method can also be overridden itself in order to dynamically implement one of the matrices as opposed to overriding it explicitly.

If this method is called and self.primary_domain is ‘s’, then ‘z0’ should be passed in kwargs.

Parameters:

freq (Frequency) – Frequency grid.
kwargs – Keyword arguments forwarded to the primary matrix function, such as z0.

Return type:

jnp.ndarray

Raises:

NotImplementedError – If no primary property is overridden.

renumbered(from_ports: tuple[int], to_ports: tuple[int] = None, **kwargs) → Model

Return a version of the model with ports renumbered.

See pmrf.models.composite.transformed.Renumbered.

Parameters:

from_ports (tuple[int]) – The original port indices that map to to_ports.
to_ports (tuple[int]) – The new port indices.

Return type:

Model

Scattering parameter matrix at port impedance z0.

If a different parameter type (a, z, y, mna) is primary, this converts it to S.

To convert between port impedances, use pmrf.rf.renormalize_s().

Derived classes that implement S-parameters should use the power wave definition. Convert other definitions (such as traveling waves) with pmrf.rf.s2s().

Parameters:: frequency (Frequency) – Frequency grid.
Returns:: S-parameter matrix with shape (nf, n, n).
Return type:: jnp.ndarray

terminated(other: Model = 'short', **kwargs) → Model

Terminate this model in another, returning a new model.

See pmrf.models.composite.transformed.Terminated.

Parameters:: other (Model | str, optional) – The model to terminate this one in. Can be literals ‘short’, ‘open’ or any model with half the ports of this one. Defaults to a ‘short’.
Return type:: Model

Convert the model at frequencies to an skrf.Network.

The active primary property (self.primary_domain) is used.

Parameters:

frequency (pmrf.frequency.Frequency | skrf.Frequency) – Frequency grid.
z0 (ArrayLike, optional) – The reference impedance, scalar or per-port. Defaults to the model’s native reference impedance, such as a pmrf.models.Circuit’s Port impedances, or to 50 Ω for a model without one. The same value is used for the S-parameters and for Network.z0.
sigma (float, default=0.0) – If nonzero, add complex Gaussian noise with stdev sigma to s.
**kwargs – Forwarded to skrf.Network constructor. port_names defaults to a pmrf.models.Circuit’s Port names, if any Port is named.

Return type:

skrf.Network

y(frequency: Frequency) → Array

Admittance (Y) parameter matrix.

If a different parameter type is primary, this converts it to Y.

Parameters:: frequency (Frequency) – Frequency grid.
Returns:: Y matrix with shape (nf, n, n).
Return type:: jnp.ndarray

z(frequency: Frequency) → Array

Impedance (Z) parameter matrix.

If a different parameter type is primary, this converts it to Z.

Parameters:: frequency (Frequency) – Frequency grid.
Returns:: Z matrix with shape (nf, n, n).
Return type:: jnp.ndarray

nports: Alias of number_of_ports.

number_of_ports

Number of ports.

Return type:: int

property port_tuples: list[tuple[int, int]]

All (m, n) port index pairs.

Return type:: list[tuple[int, int]]

property primary_domain: str

The primary domain (e.g. "s", "a") as a string.

The primary property is the first overridden among PRIMARY_DOMAINS, unless build is overridden, in which case the primary property of the built model is returned.

Return type:: str
Raises:: NotImplementedError – If no primary property is overridden.

supports_native_z0: ClassVar[bool] = False: Whether the model has a native reference impedance, so that s() accepts z0=None (ADR-0006). A model that sets it defaults to z0=None.