Component Faults and Health

Hardwave components can emit runtime diagnostics when operating limits are exceeded (motor thermal runaway, battery over-discharge, over-current, and more). Unlike wiring ERRORs (which block simulation at validation time), runtime faults describe what happens during a simulation when physics pushes a component out of spec.

Diagnostic levels

Level	Meaning	Example	Simulation behaviour
`INFO`	Informational note	Operating in a non-linear region	Continue
`WARNING`	Out of spec, degraded	Battery SOC below 10%	Continue, flag in results
`ERROR`	Invalid wiring or config	Missing required port	Block at `validate()`
`FAULT`	Catastrophic component failure	Motor windings burned out	Degrade outputs; optionally stop sim

ERROR is reserved for graph validation. FAULT is for mid-simulation catastrophic failures.

Built-in fault-aware components

DCMotor

Outputs health and fault_code in addition to angular_velocity, current, and winding_temp.

Code	Level	Condition
`1`	WARNING	`MOTOR_THERMAL_HIGH`: winding temp approaching rated limit
`2`	WARNING	`MOTOR_OVER_CURRENT`: current above `max_continuous_current`
`100`	FAULT	`MOTOR_THERMAL_RUNAWAY`: winding temp exceeds `max_winding_temp`; motor stops

Key parameters: max_winding_temp (default 130 °C), max_continuous_current (default 5 A), warning_temp_fraction (default 0.9).

LiPoCell

Code	Level	Condition
`1`	WARNING	`CELL_LOW_SOC`: SOC below `min_soc_warning`
`2`	WARNING	`CELL_HIGH_TEMP`: temperature approaching `max_temperature`
`100`	FAULT	`CELL_OVERDISCHARGE`: SOC = 0 or voltage at empty; discharge cut off
`101`	FAULT	`CELL_THERMAL_DAMAGE`: temperature exceeds `max_temperature`; internal resistance permanently increased 5×

Reading diagnostics from results

from hardwave.simulation import SimulationEngine, SimulationConfig, FaultMode
from hardwave.solvers import SimulationDomain
from hardwave.stdlib.components.motors import DCMotor

graph = SimulationGraph()
graph.add_component(DCMotor("motor", param_values={
    "max_winding_temp": 30.0,
    "winding_resistance": 0.1,
    "thermal_resistance": 100.0,
}))

result = SimulationEngine(graph).run(
    inputs={"motor": {"voltage": 24.0, "load_torque": 0.0}},
)

# Filter by severity
for d in result.get_warnings():
    print(d)

for d in result.get_faults():
    print(f"[{d.code}] {d.message} at t={d.timestamp}")

# Per-component filter
motor_diags = result.get_diagnostics_by_component("motor")

# Health output ports (wireable into control logic)
health = result.get_output("motor", "health")      # 0=OK, 1=warning, 2=fault
fault_code = result.get_output("motor", "fault_code")

Diagnostics are included in result.to_dict() with step_index, timestamp, value, and threshold when applicable.

Fault modes

SimulationConfig.fault_mode controls how the engine responds to FAULT-level diagnostics:

from hardwave.simulation import SimulationConfig, FaultMode

# Default: keep simulating; faulted components return degraded outputs
config = SimulationConfig(fault_mode=FaultMode.CONTINUE)

# Abort on first fault (raises SimulationError)
config = SimulationConfig(fault_mode=FaultMode.STOP)

Wiring health into control logic

Connect a component’s health output to an MCU GPIO input to test firmware shutdown behaviour:

graph.connect("motor", "health", "mcu", "gpio_in_overtemp")

health is a ControlSignal: 0.0 = OK, 1.0 = warning, 2.0 = fault.

Adding faults to custom components

Override two hooks on Component:

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

class MyMotor(Component):
    FAULT_OVER_TEMP = 100

    def post_solve_diagnostics(self, inputs, outputs, *, t=None, step_index=None):
        diagnostics = []
        temp = outputs.get("winding_temp", 0.0)
        limit = self.get_param("max_temp")

        if temp >= limit:
            self.set_fault_code(self.FAULT_OVER_TEMP)
            diagnostics.append(make_diagnostic(
                DiagnosticLevel.FAULT,
                "MOTOR_THERMAL_RUNAWAY",
                f"Temperature {temp:.1f}°C exceeded {limit:.1f}°C",
                self.instance_id,
                port_name="winding_temp",
                step_index=step_index,
                timestamp=t,
                value=temp,
                threshold=limit,
            ))
        return diagnostics

    def apply_fault_outputs(self, outputs):
        degraded = dict(outputs)
        degraded["angular_velocity"] = 0.0
        degraded["current"] = 0.0
        return degraded

Add health and fault_code output ports to expose state on the graph:

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

The engine calls post_solve_diagnostics() after every solve step and populates health / fault_code automatically when those ports exist.

Error Handling Reference

Full exception hierarchy and validation diagnostic codes

Getting Started

Guides

Simulation

Reference

Component Faults and Health

Diagnostic levels

Built-in fault-aware components

DCMotor

LiPoCell

Reading diagnostics from results

Fault modes

Wiring health into control logic

Adding faults to custom components

Error Handling Reference

​Diagnostic levels

​Built-in fault-aware components

​DCMotor

​LiPoCell

​Reading diagnostics from results

​Fault modes

​Wiring health into control logic

​Adding faults to custom components

Error Handling Reference

Diagnostic levels

Built-in fault-aware components

DCMotor

LiPoCell

Reading diagnostics from results

Fault modes

Wiring health into control logic

Adding faults to custom components