AbstractBuilder

class pmrf.models.adapters.delegated.AbstractBuilder(*, name: str | None = None, metadata: Any = None)

Bases: Model, ABC

Abstract base for an RF model implemented by building another model.

Subclasses implement build() and may then be used anywhere a pmrf.Model is accepted. The returned model supplies the complete RF interface of the builder, including its port count and expanded topology.

build() is a pure, lazy realization hook rather than a one-time initializer. It may be called during RF evaluation, JAX tracing, port discovery, topology expansion, or explicit introspection. Implementations must not perform I/O or mutation, and ParamRF does not cache the returned model. Its type, PyTree topology, and port count must remain stable for a given set of static fields; topology must not depend on dynamic fitted parameter values.

expand()

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

This method is used by graph algorithms (like the solver in Circuit.flattened) to unpack composite models, wrappers, and nested hierarchies into a single flat netlist. This allows global matrix solves to be used, where desired.

pmrf.models.AbstractBuilder delegates this method to its built model. The legacy direct Model.build() override does the same. Most user classes therefore do not need to implement topology expansion manually; it is mainly intended for built-in composite models such as pmrf.models.Cascade or 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

Imagine a custom 2-port model that internally connects an Inductor and Capacitor in series. When asked to expand, it exposes the inner components and their wiring:

>>> def expand(self):
...     # 1. Grab internal components
...     L, C = self.inductor, self.capacitor
...
...     # 2. Map our external ports to the internal components
...     port_mapping = [
...         (L, 0),  # External port 0 maps to Inductor port 0
...         (C, 1)   # External port 1 maps to Capacitor port 1
...     ]
...
...     # 3. Define the internal connections (the netlist)
...     # Connect Inductor port 1 to Capacitor port 0
...     internal_connections = [
...         [(L, 1), (C, 0)]
...     ]
...
...     return port_mapping, internal_connections

mna(frequency: Frequency) → MNAStamp

(experimental) Modified Nodal Analysis (MNA) stamp.

Can be overridden in sub-classes.

If the model does not explicitly define an MNA stamp, this automatically delegates to the appropriate conversion utility (s2mna, z2mna, etc.). Explicitly defined Y-matrices are prioritized to maximize matrix sparsity, while other domains fall back to auxiliary variables to guarantee stability.

primary_matrix(frequency: Frequency, **kwargs)

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 proprerty directly overriden 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 overriden itself in order to 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 – Key-word arguments forwarded to the primary matrix function, such as z0.

Return type:

jnp.ndarray

Raises:

NotImplementedError – If no primary property is overridden.

property number_of_ports: int

Number of ports.

Return type:

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.