Defining Components

Components are Python classes with typed ports, configurable parameters, and a solve() method. Hardwave provides a decorator for quick authoring and a manual registration path for full control.

Using the @component decorator

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",
    docs="Uses the Steinhart-Hart equation approximation.",
    category="Sensors",
    tags=["sensor", "temperature", "thermistor"],
)
class Thermistor(Component):
    ports = [
        input_port("temperature", "Temperature", "Ambient temperature (°C)"),
        output_port("resistance", "Resistance", "Thermistor resistance at given temperature"),
    ]

    parameters = [
        Parameter("r_nominal",  "Nominal Resistance", "Ω",   float, 10_000.0),
        Parameter("t_nominal",  "Nominal Temperature", "°C", float, 25.0),
        Parameter("beta",       "Beta Coefficient",    "K",  float, 3950.0),
    ]

    def solve(self, inputs: dict) -> dict:
        import math
        T_c = inputs["temperature"]
        T_k = T_c + 273.15
        T0 = self.get_param("t_nominal") + 273.15
        R0 = self.get_param("r_nominal")
        B  = self.get_param("beta")
        R  = R0 * math.exp(B * (1 / T_k - 1 / T0))
        return {"resistance": R}

The decorator automatically attaches ComponentMeta and registers the class with ComponentRegistry.

Manual definition

from hardwave.components import Component, ComponentMeta, ComponentRegistry, Parameter
from hardwave.ports import input_port, output_port

class MyGasSensor(Component):
    meta = ComponentMeta(
        name="MyGasSensor",
        display_name="Custom Gas Sensor",
        version="1.0.0",
        description="Reads CO2 concentration",
        category="Sensors/Gas",
    )
    ports = [
        input_port("analog_in", "AnalogSignal", "Sensor output voltage (0-5V)"),
        output_port("co2_ppm", "AnalogSignal",  "CO2 concentration in PPM"),
    ]
    parameters = [
        Parameter("sensitivity", "Sensitivity", "V/PPM", float, 0.002),
    ]

    def solve(self, inputs: dict) -> dict:
        V = inputs["analog_in"]
        ppm = V / self.get_param("sensitivity")
        return {"co2_ppm": ppm}

ComponentRegistry.instance().register(MyGasSensor)

Parameters

Parameter defines static configuration on a component instance:

Parameter(
    name="t_min",
    display_name="Lower Temperature Threshold",
    unit="°C",
    python_type=float,
    default=20.0,
    description="Temperature at or below which the vent stays shut",
)

Access parameters at solve time with self.get_param("t_min"). Override defaults when adding instances to a graph:

graph.add_component(ThermostatController("ctrl", param_values={"t_min": 22.0, "t_max": 38.0}))

Optional ports

Mark input ports as optional with a default:

input_port("load_torque", "Torque", "Load on the servo shaft",
           required=False, default=0.0)

Aggregating input ports

When several upstream components should drive the same input, use aggregating_input_port(). The engine gathers all connected values and produces one value for solve().

from hardwave.ports import aggregating_input_port, PortAggregation

def net_current(values, component, port):
    return sum(values)

ports = [
    # Built-in sum
    aggregating_input_port(
        "current_in", "Current",
        aggregation=PortAggregation.SUM,
        description="Total current from all branches",
    ),
    # Custom callable: fully replaces built-in aggregation
    aggregating_input_port("current_in", "Current", aggregate=net_current),
]

Built-in modes include SUM, MEAN, MIN, MAX, PRODUCT, FIRST, and LAST. Optional min_connections and max_connections enforce wiring limits at validation or connect time.

Aggregating Input Ports

Full guide with graph wiring, disconnect APIs, and serialization notes

Testing in isolation

Call solve() directly before wiring a component into a graph:

controller = ThermostatController("ctrl")
result = controller.solve({"temperature": 27.5})
print(result)  # {'vent_state': 0.5, 'pwm_out': {...}}

Injecting a custom solver

Replace the default solve() logic without changing ports or wiring:

from hardwave.solvers import FormulaSolver

def my_formula(inputs, component):
    V = inputs["voltage"]
    R = component.get_param("resistance")
    return {"current": V / R, "power": V**2 / R}

r = Resistor("r1", param_values={"resistance": 470.0})
r.set_solver(FormulaSolver(my_formula))

See Solvers for ODE, lookup table, and ML solver options.

Runtime fault diagnostics

Components can emit WARNING and FAULT diagnostics when operating limits are exceeded during simulation. Implement two optional hooks:

from hardwave.components.health import make_diagnostic
from hardwave.diagnostics import DiagnosticLevel

def post_solve_diagnostics(self, inputs, outputs, *, t=None, step_index=None):
  # Return a list of Diagnostic objects; call self.set_fault_code() for FAULTs
  return []

def apply_fault_outputs(self, outputs):
  # Return modified outputs when self.is_faulted is True
  return outputs

Expose health and fault_code output ports so other components (e.g. an MCU) can react to faults:

output_port("health", "ControlSignal", "0=OK, 1=warning, 2=fault"),
output_port("fault_code", "ControlSignal", "Machine-readable fault code"),

Component Faults and Health

Built-in fault rules, FaultMode, and result inspection

Getting Started

Guides

Simulation

Reference

Defining Components

Using the @component decorator

Manual definition

Parameters

Optional ports

Aggregating input ports

Aggregating Input Ports

Testing in isolation

Injecting a custom solver

Runtime fault diagnostics

Component Faults and Health

​Using the @component decorator

​Manual definition

​Parameters

​Optional ports

​Aggregating input ports

Aggregating Input Ports

​Testing in isolation

​Injecting a custom solver

​Runtime fault diagnostics

Component Faults and Health

Using the @component decorator

Manual definition

Parameters

Optional ports

Aggregating input ports

Testing in isolation

Injecting a custom solver

Runtime fault diagnostics