Building Graphs

A SimulationGraph is a directed acyclic graph of component instances connected by typed ports. Hardwave validates wiring at construction time so type errors surface before any simulation runs.

Adding components

from hardwave.simulation import SimulationGraph
from hardwave.stdlib.components.passive import VoltageSource, Resistor, VoltageRegulator

graph = SimulationGraph()

graph.add_component(VoltageSource("psu",  param_values={"voltage": 12.0}))
graph.add_component(VoltageRegulator("ldo", param_values={"output_voltage": 5.0}))
graph.add_component(Resistor("load", param_values={"resistance": 100.0}))

Each instance has a unique instance_id string used in connections and result queries.

Connecting ports

graph.connect("psu",  "voltage_out",  "ldo",  "v_in")
graph.connect("ldo",  "v_out",        "load", "voltage")

Each connect() call creates a directed edge from an output port to an input port.

Fan-out and fan-in

Fan-out: connect one output to many inputs (always allowed).
Fan-in: connect many outputs to one input only when the target port is declared with aggregating_input_port().

# Fan-out: same voltage to two resistors
graph.connect("vs", "voltage_out", "r1", "voltage")
graph.connect("vs", "voltage_out", "r2", "voltage")

# Fan-in: two current sources into a summing node
graph.connect("src_a", "current_out", "node", "current_in")
graph.connect("src_b", "current_out", "node", "current_in")

Connection rules

Hardwave enforces these rules at wiring time:

Error	Cause
`PortNotFoundError`	Port name does not exist on that component
`PortDirectionError`	Connecting output→output or input→input
`TypeMismatchError`	Source and target types are incompatible
`DuplicateConnectionError`	Second wire to a regular `input_port()`
`MaxConnectionsExceededError`	More connections than `max_connections`

Aggregating Input Ports

Declare multi-connection ports and custom aggregation

Validation

Always validate before running:

diagnostics = graph.validate(
    external_inputs={
        "ldo": {"load_current": 0.05},
    }
)
for d in diagnostics:
    print(d)  # warnings only; errors raise GraphValidationError

validate() checks that every required input port is either:

Connected to an upstream output
Has a default value
Will be satisfied by an external input passed to run()

It also runs cycle detection (Kahn’s algorithm). Cycles raise GraphValidationError before simulation starts. Aggregating ports with min_connections raise INSUFFICIENT_CONNECTIONS when too few wires are present.

If you add extra components to a graph, every required port on every component must be satisfied at validation time, even if nothing is wired to that component’s outputs.

External inputs

Some ports are driven from outside the graph (ambient temperature, user commands, test fixtures):

result = engine.run(
    inputs={
        "ldo": {"load_current": 0.05},   # 50 mA load
    },
)

Pass the same external inputs to validate() so validation matches the run configuration.

Editing graphs

graph.disconnect("load", "voltage")   # remove all connections feeding load.voltage
graph.disconnect("node", "current_in", "src_a", "current_out")  # remove one source
graph.connections_to("node", "current_in")  # inspect incoming wires
graph.remove_component("load")        # remove instance and all its connections

During engine.run(), Hardwave calls graph.topological_order() to determine a safe evaluation sequence. For each component it collects input values from upstream outputs (aggregating multi-connection ports when declared), external inputs, or port defaults, calls the solver, and stores outputs for downstream components.

Getting Started

Guides

Simulation

Reference

Adding components

Connecting ports

Fan-out and fan-in

Connection rules

Aggregating Input Ports

Validation

External inputs

Editing graphs

Next steps

Steady-State Simulation

Saving Graphs

​Adding components

​Connecting ports

​Fan-out and fan-in

​Connection rules

Aggregating Input Ports

​Validation

​External inputs

​Editing graphs

​Next steps

Steady-State Simulation

Saving Graphs

Adding components

Connecting ports

Fan-out and fan-in

Connection rules

Validation

External inputs

Editing graphs

Next steps