Skip to content

small_signal ¤

Reusable source-driven linear models and physical small-signal observables.

Classes:

Name Description
QuadratureDrive

Independent complex RF peak phasors driving the two field coordinates.

SmallSignalModel

Fixed-bias linearization callable as model(freqs=..., sources=...).

SmallSignalResponse

Physical peak response phasors, retaining both optical field coordinates.

Functions:

Name Description
build_small_signal_model

Build an immutable numerical snapshot with static source and node names.

validate_small_signal_groups

Reject real-only native Jacobians in a doubled complex system.

QuadratureDrive ¤

Bases: Module

Independent complex RF peak phasors driving the two field coordinates.

With the exp(+j omega t) convention, the source perturbation is Re(x exp(j omega t)) + j Re(y exp(j omega t)). A scalar source drive is shorthand for QuadratureDrive(x=amplitude, y=0), including optical sources.

SmallSignalModel ¤

Bases: Module

Fixed-bias linearization callable as model(freqs=..., sources=...).

response() is equivalent to calling the model. Parameters and DC bias are fixed at construction; source phasors and frequencies are runtime inputs. No matching loads or scattering normalization are introduced.

Methods:

Name Description
response

Call the model; identical to model(freqs=freqs, sources=sources).

response ¤

response(
    *, freqs: Array, sources: Mapping[str, complex | Array | QuadratureDrive]
) -> SmallSignalResponse

Call the model; identical to model(freqs=freqs, sources=sources).

Source code in circulax/small_signal.py
def response(
    self,
    *,
    freqs: jax.Array,
    sources: Mapping[str, complex | jax.Array | QuadratureDrive],
) -> SmallSignalResponse:
    """Call the model; identical to model(freqs=freqs, sources=sources)."""
    return self(freqs=freqs, sources=sources)

SmallSignalResponse ¤

Bases: Module

Physical peak response phasors, retaining both optical field coordinates.

The final axes of solution are (frequency, unknown). Complex-mode unknowns are stored as [x coordinates, y coordinates], each containing complex RF phasors. Additional leading axes may be introduced by external jax.vmap. y_dc uses the same block layout, but contains real DC coordinates.

Methods:

Name Description
power

Return complex optical power-modulation peak phasors in watts.

quadratures

Extract complex RF phasors of both physical field coordinates.

sidebands

Return actual envelope coefficients at +omega and -omega.

voltage

Extract a physical electrical voltage peak phasor in volts.

Attributes:

Name Type Description
port_map dict[str, int]

Return stable node and internal-state aliases.

port_map property ¤

port_map: dict[str, int]

Return stable node and internal-state aliases.

power ¤

power(port: str, *, field_unit: str) -> Array

Return complex optical power-modulation peak phasors in watts.

field_unit must be 'sqrt(W)', explicitly declaring the selected field power normalized, with P = |E|**2. This computes 2 * (x_dc * dx + y_dc * dy), preserving RF phase. It is not DC power, modulation magnitude, or electrical absorbed power. The selected node must itself represent the intended optical field, e.g. a traveling wave; a total field at a mismatched boundary is not an incident power wave.

Source code in circulax/small_signal.py
def power(self, port: str, *, field_unit: str) -> jax.Array:
    """Return complex optical power-modulation peak phasors in watts.

    field_unit must be 'sqrt(W)', explicitly declaring the selected field
    power normalized, with P = |E|**2. This computes
    2 * (x_dc * dx + y_dc * dy), preserving RF phase. It is not DC power,
    modulation magnitude, or electrical absorbed power. The selected node
    must itself represent the intended optical field, e.g. a traveling wave;
    a total field at a mismatched boundary is not an incident power wave.
    """
    if field_unit != "sqrt(W)":
        msg = "power() requires field_unit='sqrt(W)' for a power-normalized optical field"
        raise ValueError(msg)
    if not self.is_complex:
        msg = "power() currently supports optical fields in complex-mode circuits only"
        raise NotImplementedError(msg)
    index = self._index(port)
    dx, dy = self.quadratures(port)
    return 2 * (self.y_dc[..., index, None] * dx + self.y_dc[..., index + self.num_vars, None] * dy)

quadratures ¤

quadratures(positive: str, negative: str | None = None) -> tuple[Array, Array]

Extract complex RF phasors of both physical field coordinates.

Optionally take the field difference between two nodes. Real circuits have only the x coordinate and return zeros for the y coordinate.

Source code in circulax/small_signal.py
def quadratures(self, positive: str, negative: str | None = None) -> tuple[jax.Array, jax.Array]:
    """Extract complex RF phasors of both physical field coordinates.

    Optionally take the field difference between two nodes. Real circuits
    have only the x coordinate and return zeros for the y coordinate.
    """
    index = self._index(positive)
    x = self.solution[..., index]
    y = self.solution[..., index + self.num_vars] if self.is_complex else jnp.zeros_like(x)
    if negative is not None:
        index = self._index(negative)
        x = x - self.solution[..., index]
        if self.is_complex:
            y = y - self.solution[..., index + self.num_vars]
    return x, y

sidebands ¤

sidebands(port: str) -> tuple[Array, Array]

Return actual envelope coefficients at +omega and -omega.

For E(t) = E_dc + upperexp(j omega t) + lowerexp(-j omega t), upper=(dx+jdy)/2 and lower=(conj(dx)+jconj(dy))/2. The labels refer to envelope frequency; optical upper/lower labeling additionally depends on the chosen optical carrier time convention.

Source code in circulax/small_signal.py
def sidebands(self, port: str) -> tuple[jax.Array, jax.Array]:
    """Return actual envelope coefficients at +omega and -omega.

    For E(t) = E_dc + upper*exp(j omega t) + lower*exp(-j omega t),
    upper=(dx+j*dy)/2 and lower=(conj(dx)+j*conj(dy))/2. The labels refer
    to envelope frequency; optical upper/lower labeling additionally
    depends on the chosen optical carrier time convention.
    """
    dx, dy = self.quadratures(port)
    return (dx + 1j * dy) / 2, (jnp.conj(dx) + 1j * jnp.conj(dy)) / 2

voltage ¤

voltage(positive: str, negative: str | None = None) -> Array

Extract a physical electrical voltage peak phasor in volts.

The caller declares these nodes electrical; no discipline is inferred. In a mixed complex circuit the electrical voltage is the x coordinate.

Source code in circulax/small_signal.py
def voltage(self, positive: str, negative: str | None = None) -> jax.Array:
    """Extract a physical electrical voltage peak phasor in volts.

    The caller declares these nodes electrical; no discipline is inferred.
    In a mixed complex circuit the electrical voltage is the x coordinate.
    """
    return self.quadratures(positive, negative)[0]

build_small_signal_model ¤

build_small_signal_model(
    circuit: Circuit,
    groups: dict[str, Any],
    y_dc: Array,
    *,
    dc_groups: dict[str, Any] | None = None
) -> SmallSignalModel

Build an immutable numerical snapshot with static source and node names.

Source code in circulax/small_signal.py
def build_small_signal_model(
    circuit: Circuit,
    groups: dict[str, Any],
    y_dc: jax.Array,
    *,
    dc_groups: dict[str, Any] | None = None,
) -> SmallSignalModel:
    """Build an immutable numerical snapshot with static source and node names."""
    is_complex = circuit.solver.is_complex
    validate_small_signal_groups(groups, is_complex=is_complex)
    if dc_groups is not None:
        validate_small_signal_groups(dc_groups, is_complex=is_complex)
    bias = jnp.asarray(y_dc)
    expected = circuit.sys_size * (2 if is_complex else 1)
    if bias.shape != (expected,) or jnp.iscomplexobj(bias):
        msg = f"Small-signal y_dc must be a real coordinate array of shape ({expected},)"
        raise ValueError(msg)
    conductance, capacitance = linearize_ac(
        groups, circuit.sys_size, bias, is_complex=is_complex, quadratures=is_complex, dc_groups=dc_groups
    )
    source_names = tuple(
        sorted(
            name
            for group in groups.values()
            if getattr(group, "ac_source_stamp", ())
            for name in (getattr(group, "index_map", None) or {})
        )
    )
    stamps = jnp.zeros((circuit.sys_size, len(source_names)), dtype=jnp.complex128)
    for group in groups.values():
        for local_row, coefficient in getattr(group, "ac_source_stamp", ()):
            for name, instance in group.index_map.items():
                stamps = stamps.at[group.eq_indices[instance, local_row], source_names.index(name)].add(coefficient)
    dynamic_groups = {
        name: group for name, group in groups.items() if getattr(group, "is_fdomain", False) or getattr(group, "has_delay", False)
    }
    return SmallSignalModel(
        conductance,
        capacitance,
        bias,
        stamps,
        dynamic_groups,
        tuple(sorted(circuit.port_map.items())),
        source_names,
        circuit.sys_size,
        is_complex,
    )

validate_small_signal_groups ¤

validate_small_signal_groups(groups: dict[str, Any], *, is_complex: bool) -> None

Reject real-only native Jacobians in a doubled complex system.

Source code in circulax/small_signal.py
def validate_small_signal_groups(groups: dict[str, Any], *, is_complex: bool) -> None:
    """Reject real-only native Jacobians in a doubled complex system."""
    if is_complex and any(hasattr(g, "model_id") or getattr(g, "combined_func", None) is not None for g in groups.values()):
        msg = "Complex-mode small-signal models with native/combined real-only Jacobians are not supported"
        raise NotImplementedError(msg)