Module component 

Component Trait and Supporting Types

This module defines Component, the central trait that drives the entire PedalKernel compilation pipeline. Every circuit element — from a simple resistor to a 12AX7 vacuum tube — implements Component to declare its electrical behavior, topology, and runtime characteristics.

Design Philosophy

Components declare; the compiler reacts. The pipeline never pattern-matches on component types. Instead, it queries trait methods to determine how each component participates in the circuit:

• What edges does it create? (Component::edges) — determines graph topology
• Is it passive or nonlinear? (Component::is_passive, Component::is_nonlinear) — determines stage solver
• What is its output impedance? (Component::output_impedance) — determines stage boundaries
• What non-ideal effects does it have? (Component::nonideal_fx) — determines post-processing
• How does signal flow through it? (Component::signal_terminals) — determines feedback loops

This inversion of control means adding a new component type requires implementing one trait — no changes to the graph builder, SPQR decomposer, stage builder, or any other pipeline stage.

How Components Drive the Pipeline

Stage Splitting via Output Impedance

OutputImpedance controls where the compiler can safely split a circuit into independent processing stages. This is based on Harold Black’s theorem: a negative-feedback amplifier’s output behaves as a voltage source (zero output impedance), meaning downstream loads cannot affect upstream behavior.

When a component returns OutputImpedance::VoltageSource, the compiler knows it can insert a stage boundary after that component’s output. Op-amps in negative feedback return VoltageSource; passive components return OutputImpedance::Finite.

Feedback Detection via Signal Terminals

SignalTerminals drives the feedback analysis pass. The compiler uses Tarjan’s strongly-connected-component algorithm to find feedback loops. Components with SignalTerminals::Amplifier define the forward path direction; passive components with SignalTerminals::Passive can carry signal in either direction and may form the feedback path.

Post-Processing via Non-Ideal Effects

NonIdealFx allows components to declare physical imperfections from their SPICE models and datasheets. An LM308 op-amp declares its 1 MHz GBW product and 0.3 V/us slew rate; the stage builder translates these into a first-order IIR lowpass and a slew-rate limiter applied after the ideal WDF/MNA solver.

Key Types

• Component — the trait itself (see its documentation for method groups)
• EdgeKind — electrical classification of a circuit edge (Linear, Reactive, Nonlinear, Vcvs, etc.)
• ComponentEdge — a single edge declared by a component
• GraphRole — how a component participates in circuit graph construction
• OutputImpedance — voltage-source vs. finite impedance classification
• SignalTerminals — signal flow directionality for feedback analysis
• NonIdealFx — non-ideal behaviors (GBW, slew rate, rail saturation)
• StampResult — result of stamping a component into an MNA matrix
• StampContext — pin-to-MNA-index resolution for multi-terminal stamping
• ControlParam — controllable parameter declaration (pots, LFO rate, etc.)
• ModulationSink — how a component receives LFO/envelope modulation
• SolverMethod — preferred nonlinear solver (Newton-Raphson, Wright Omega, Ebers-Moll, Gummel-Poon)

Structs

ComponentEdge

A single edge declared by a component.

ControlParam

A controllable parameter declared by a component.

KMethodSpec

Component-declared K-method table shape.

ModulationSink

Modulation sink: how a component receives LFO/envelope control signals.

NeighborReq

A single neighbour requirement declared by an active device terminal.

PinConfig

Pin configuration for validation and graph construction.

ResolveContext

Context provided to resolve_edges() so a component can decide its role based on how it’s wired in the circuit.

StampContext

Context for multi-terminal MNA stamping.

Enums

BiasResult

Result of applying DC bias to an active component.

Cardinality

How many neighbours of a given NeighborRole a terminal expects.

ControlParamKind

Classification of a component’s controllable parameter.

EdgeKind

Classification of a circuit edge by electrical behavior.

GraphRole

How a component participates in circuit graph construction.

KMethodAxis

Semantic axis in a K-method lookup table.

ModulationSinkKind

Classification of a modulation sink by target type.

NeighborRole

Device-agnostic classification of what a neighbouring passive (or active) element does for an active device’s terminal.

NonIdealFx

Non-ideal behavior declared by a component (from its datasheet/SPICE model).

OutputImpedance

Component-declared non-ideal behavior applied as post-processing.

PinDirection

Inferred direction for a component pin (used by layout).

PortSemantic

Electrical behavior classification for a component port (pin pair).

SignalTerminals

Signal flow classification for a component’s pins.

SolverMethod

Preferred nonlinear solver method for a component.

StampResult

Result of stamping a component into an MNA system.

Constants

K_AXIS_INCIDENT_1D

K_AXIS_INCIDENT_CONTROL_2D

K_AXIS_INCIDENT_CONTROL_CONTROL_3D

Traits

Component

The single source of truth for circuit component behavior.