base_component ¤

def component(
    ports: tuple[str, ...] = (),
    states: tuple[str, ...] = (),
    amplitude_param: str = "",
) -> 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, s)`` followed by any
    number of parameters with defaults, which become JAX-traceable Equinox
    fields on the resulting class.

    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.

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

    Example::

        @component(ports=("p1", "p2"))
        def Resistor(signals: Signals, s: States, 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)

def source(
    ports: tuple[str, ...] = (),
    states: tuple[str, ...] = (),
    amplitude_param: str = "",
) -> Any:
    """Decorator for defining a time-dependent circuit component.

    Identical to :func:`component` except the decorated physics function
    must accept ``t`` as its third argument (after ``signals`` and ``s``),
    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.

    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, s: States, t: float, V: float = 1.0):
            constraint = (signals.p1 - signals.p2) - V
            return {"p1": s.i_src, "p2": -s.i_src, "i_src": constraint}, {}

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