Core Concepts

Hardwave treats hardware as a directed acyclic graph of typed components. Understanding a few core concepts is enough to build anything from a resistor network to a robot drivetrain.

Everything is a component

A component has:

Ports: typed slots that data flows through (inputs or outputs)
Parameters: static configuration values that do not change during a simulation run
A solver: the function that turns inputs into outputs

Components connect into a graph. The simulation engine walks the graph in topological order, calls each component’s solver with its current inputs, and propagates results downstream. You never call solve() directly during simulation. The engine does that for you. You can call solve() directly for unit testing.

Types

Types define the semantic meaning of signals. DCVoltage and Current are both floats at runtime, but Hardwave treats them as incompatible. You cannot accidentally wire a voltage output into a current input.

Built-in types

Import the standard library to register 30 hardware signal types:

import hardwave.stdlib

from hardwave.types import TypeRegistry
reg = TypeRegistry.instance()

reg.get("DCVoltage")       # V
reg.get("Current")         # A
reg.get("Resistance")      # Ω
reg.get("Torque")          # N·m
reg.get("Temperature")     # °C
reg.get("PWMSignal")       # dict {frequency_hz, duty_cycle}

for t in reg.list_types():
    print(f"{t.name:25s} {t.unit}")

Custom types

from hardwave.types import HardwaveType, TypeRegistry

Luminosity = HardwaveType(
    name="Luminosity",
    unit="lux",
    description="Illuminance",
    min_value=0.0,
)
TypeRegistry.instance().register(Luminosity)

For composite or bus types (CAN frames, I2C payloads), subclass HardwaveType and override validate().

Ports

Ports are declared with helper functions:

from hardwave.ports import input_port, output_port, aggregating_input_port, PortAggregation

ports = [
    input_port("voltage", "DCVoltage", "Applied voltage (V)"),
    output_port("current", "Current", "Current through the element (A)"),
]

Each port has a name, a type name (looked up in TypeRegistry), and a description. Input ports can be marked optional with a default value.

Single vs aggregating inputs

Helper	Connections	Use case
`input_port()`	One source only	Most signal paths
`aggregating_input_port()`	Many sources	Sum currents, average sensors, custom combine logic

Fan-out (one output → many inputs) works on any port. Fan-in (many outputs → one input) requires aggregating_input_port() on the target.

aggregating_input_port("current_in", "Current", aggregation=PortAggregation.SUM)

See Aggregating Input Ports for built-in modes, custom callables, and connection limits.

Components and the registry

Component classes are registered in the global ComponentRegistry singleton. The @component decorator attaches metadata and registers the class automatically:

from hardwave import component, input_port, output_port, Component, Parameter

@component(
    name="Thermistor",
    display_name="NTC Thermistor",
    version="1.0.0",
    description="NTC thermistor: resistance decreases with temperature",
    category="Sensors",
)
class Thermistor(Component):
    ports = [
        input_port("temperature", "Temperature", "Ambient temperature (°C)"),
        output_port("resistance", "Resistance", "Thermistor resistance (Ω)"),
    ]
    parameters = [
        Parameter("r_nominal", "Nominal Resistance", "Ω", float, 10_000.0),
    ]

    def solve(self, inputs: dict) -> dict:
        # ... physics here
        return {"resistance": R}

See Defining Components for the full authoring guide.

Solvers

Every component has a solver that computes outputs from inputs. The default solver is the component’s own solve() method, but you can inject a more sophisticated one at any time:

Solver	Use case
`FormulaSolver`	Wrap any callable (Ohm’s law, piecewise models)
`LookupTableSolver`	Interpolate measured or datasheet data
`ODESolver`	Physics-based transient models (RC, motors, thermal)
`MLModelSolver`	Local joblib-backed solver (advanced)
Hosted ML model	Cloud-trained solver via `hardwave.premium`

See Solvers for examples of each.

Simulation domains

Hardwave supports two simulation domains:

Domain	Behaviour
Steady-state	Solve the graph once; return a single value per output port
Transient	Step through time; return time series for every output port

Declare the domain in SimulationConfig. Components with internal state (motors, capacitors, batteries) participate automatically when using ODESolver.

Component health and faults

Components can report runtime health during simulation:

`ComponentHealth`	Value	Meaning
`OK`	0	Operating normally
`WARNING`	1	Out of spec; simulation continues
`FAULT`	2	Component failed; outputs degraded

Fault-aware stdlib components (DCMotor, LiPoCell) expose health and fault_code output ports and emit structured Diagnostic objects into SimulationResult. Override post_solve_diagnostics() and apply_fault_outputs() on custom components to add your own limits.

Component Faults and Health

Full guide to fault codes, FaultMode, and authoring fault rules

Design principles

Everything is a component. A resistor, an Arduino, a robot arm: the abstraction never breaks.
Components are defined in code. Python classes are the source of truth.
Solvers are pluggable. Swap a formula for a lookup table or ML model without touching wiring.
Strict typing at the boundary. Type errors are caught at graph construction time.
Composability is first-class. A composite component is indistinguishable from a primitive at its interface.
Data drives fidelity. Components start as formulas and grow into empirically-calibrated ML models.

Getting Started

Guides

Simulation

Reference

Everything is a component

Types

Built-in types

Custom types

Ports

Single vs aggregating inputs

Components and the registry

Solvers

Simulation domains

Component health and faults

Component Faults and Health

Design principles

​Everything is a component

​Types

​Built-in types

​Custom types

​Ports

​Single vs aggregating inputs

​Components and the registry

​Solvers

​Simulation domains

​Component health and faults

Component Faults and Health

​Design principles

Everything is a component

Types

Built-in types

Custom types

Ports

Single vs aggregating inputs

Components and the registry

Solvers

Simulation domains

Component health and faults

Design principles