base_component ¤

def component(
    ports: tuple[str, ...] = (),
    states: tuple[str, ...] = (),
    amplitude_param: str = "",
    port_aliases: "dict[str, str | tuple[str, ...]] | None" = None,
    holomorphic: bool = False,
) -> Any:
    """Decorator for defining a time-independent circuit component.

    Compiles the decorated physics function into a :class:`CircuitComponent`
    subclass. The function must begin with ``signals`` followed by parameters
    with defaults, which become JAX-traceable Equinox fields on the resulting
    class. Ports and internal states share the ``signals`` namespace.

    Args:
        ports: Ordered tuple of port names. Must match the connection keys
            used in the netlist.
        states: Ordered tuple of internal state variable names. State
            variables are appended to the solver's state vector after the
            node voltages.
        amplitude_param: Name of the parameter that represents the source
            amplitude (e.g. ``"I"`` for a current source). When non-empty,
            DC homotopy solvers will scale this parameter during stepping.
            Leave empty (default) for passive components.
        port_aliases: Optional mapping from a canonical port name to one or
            more alternate names a netlist may use instead, e.g.
            ``{"p1": "P", "p2": "N"}``. Lets integrators (e.g. Mosaic/kfnetlist)
            reuse this component's physics under their own port-naming
            convention without redefining it.
        holomorphic: If ``True``, the component's physics function is
            holomorphic (complex-differentiable), enabling the faster N×N
            Wirtinger AC solve.  Defaults to ``False`` (safe: the full 2N×2N
            real-block system is always correct).  Set to ``True`` for
            components whose physics uses only holomorphic operations — if
            *every* component in a circuit is holomorphic, the AC sweep
            uses the faster N×N path automatically.

    Returns:
        A decorator that accepts a physics function and returns a
        :class:`CircuitComponent` subclass.

    Example::

        @component(ports=("p1", "p2"))
        def Resistor(signals: Signals, R: float = 1.0):
            i = (signals.p1 - signals.p2) / R
            return {"p1": i, "p2": -i}, {}

    """
    return lambda fn: _build_component(
        fn, ports, states, uses_time=False, amplitude_param=amplitude_param, port_aliases=port_aliases, holomorphic=holomorphic
    )

def source(
    ports: tuple[str, ...] = (),
    states: tuple[str, ...] = (),
    amplitude_param: str = "",
    port_aliases: "dict[str, str | tuple[str, ...]] | None" = None,
    holomorphic: bool = False,
) -> Any:
    """Decorator for defining a time-dependent circuit component.

    Identical to :func:`component` except the decorated physics function
    must accept ``t`` as its second argument (after ``signals``),
    and may use it to implement time-varying behaviour such as sinusoidal
    sources or delayed step functions.

    Args:
        ports: Ordered tuple of port names.
        states: Ordered tuple of internal state variable names.
        amplitude_param: Name of the parameter that represents the source
            amplitude (e.g. ``"V"`` for a voltage source). When non-empty,
            DC homotopy solvers will scale this parameter during stepping.
            Leave empty (default) for time-dependent components that are not
            primary excitation sources.
        port_aliases: Optional mapping from a canonical port name to one or
            more alternate names a netlist may use instead. See
            :func:`component`.
        holomorphic: If ``True``, the component's physics is holomorphic.
            Defaults to ``False`` (safe).  See :func:`component`.

    Returns:
        A decorator that accepts a physics function and returns a
        :class:`CircuitComponent` subclass.

    Example::

        @source(ports=("p1", "p2"), states=("i_src",))
        def VoltageSource(signals: Signals, t: float, V: float = 1.0):
            constraint = (signals.p1 - signals.p2) - V
            return {"p1": signals.i_src, "p2": -signals.i_src, "i_src": constraint}, {}

    """
    return lambda fn: _build_component(
        fn, ports, states, uses_time=True, amplitude_param=amplitude_param, port_aliases=port_aliases, holomorphic=holomorphic
    )