hardwave 0.1.0__py3-none-any.whl

hardwave/__init__.py

@@ -0,0 +1,118 @@
+"""
+Hardwave Platform — hardware simulation and development platform.
+
+Importing this package sets up all core infrastructure. Import `hardwave.stdlib`
+to also register all standard-library types and components.
+
+Quick start:
+    import hardwave
+    import hardwave.stdlib
+
+    from hardwave.simulation import SimulationGraph, SimulationEngine, SimulationConfig
+    from hardwave.solvers import SimulationDomain
+    from hardwave.stdlib.components.passive import Resistor, VoltageSource, Ground
+
+    graph = SimulationGraph()
+    graph.add_component(vs := VoltageSource("vs", param_values={"voltage": 9.0}))
+    graph.add_component(r1 := Resistor("r1", param_values={"resistance": 1000.0}))
+    graph.add_component(r2 := Resistor("r2", param_values={"resistance": 2000.0}))
+    graph.connect("vs", "voltage_out", "r1", "voltage")
+    graph.connect("vs", "voltage_out", "r2", "voltage")
+    graph.validate()
+
+    engine = SimulationEngine(graph)
+    result = engine.run(inputs={})
+    print(result.get_output("r1", "current"))  # 0.009
+"""
+
+__version__ = "0.1.0"
+
+# Core infrastructure (no side effects — registries are empty until populated)
+from hardwave.diagnostics import (
+    Diagnostic,
+    DiagnosticLevel,
+    HardwaveError,
+    TypeRegistrationError,
+    TypeNotFoundError,
+    ComponentRegistrationError,
+    ComponentNotFoundError,
+    PortNotFoundError,
+    TypeMismatchError,
+    PortDirectionError,
+    DuplicateConnectionError,
+    GraphValidationError,
+    SolverError,
+    SimulationError,
+    SimulationResultError,
+    DeserializationError,
+)
+from hardwave.premium.exceptions import (
+    PremiumError,
+    PremiumNotConfiguredError,
+    PremiumAuthError,
+    PremiumSyncError,
+    PremiumSolveError,
+    PremiumGraphSaveError,
+)
+
+from hardwave.types import HardwaveType, TypeRegistry
+from hardwave.ports import Port, PortDirection, input_port, output_port
+from hardwave.components import (
+    Component,
+    ComponentMeta,
+    Parameter,
+    CompositeComponent,
+    BuildContext,
+    Connection,
+    ComponentRegistry,
+    component,
+)
+from hardwave.solvers import (
+    Solver,
+    SimulationDomain,
+    FormulaSolver,
+    LookupTableSolver,
+    ODESolver,
+    MLModelSolver,
+)
+from hardwave.simulation import (
+    SimulationGraph,
+    SimulationEngine,
+    SimulationConfig,
+    SimulationResult,
+)
+from hardwave.visualization import VisualizationSpec, VisualizationKind
+from hardwave.telemetry import TelemetryRecord, TelemetryStore, ModelTrainer
+from hardwave.serialization import Serializable, SCHEMA_VERSION
+
+__all__ = [
+    # Diagnostics
+    "Diagnostic", "DiagnosticLevel",
+    "HardwaveError", "TypeRegistrationError", "TypeNotFoundError",
+    "ComponentRegistrationError", "ComponentNotFoundError",
+    "PortNotFoundError", "TypeMismatchError", "PortDirectionError",
+    "DuplicateConnectionError", "GraphValidationError", "SolverError",
+    "SimulationError", "SimulationResultError", "DeserializationError",
+    # Premium
+    "PremiumError", "PremiumNotConfiguredError", "PremiumAuthError",
+    "PremiumSyncError", "PremiumSolveError", "PremiumGraphSaveError",
+    # Types
+    "HardwaveType", "TypeRegistry",
+    # Ports
+    "Port", "PortDirection", "input_port", "output_port",
+    # Components
+    "Component", "ComponentMeta", "Parameter",
+    "CompositeComponent", "BuildContext", "Connection",
+    "ComponentRegistry", "component",
+    # Solvers
+    "Solver", "SimulationDomain", "FormulaSolver",
+    "LookupTableSolver", "ODESolver", "MLModelSolver",
+    # Simulation
+    "SimulationGraph", "SimulationEngine", "SimulationConfig", "SimulationResult",
+    # Visualization
+    "VisualizationSpec", "VisualizationKind",
+    # Telemetry
+    "TelemetryRecord", "TelemetryStore", "ModelTrainer",
+    # Serialization
+    "Serializable", "SCHEMA_VERSION",
+]

hardwave/components/__init__.py

@@ -0,0 +1,15 @@
+from hardwave.components.base import Component, ComponentMeta, Parameter
+from hardwave.components.composite import CompositeComponent, BuildContext, Connection
+from hardwave.components.registry import ComponentRegistry
+from hardwave.components.decorators import component
+
+__all__ = [
+    "Component",
+    "ComponentMeta",
+    "Parameter",
+    "CompositeComponent",
+    "BuildContext",
+    "Connection",
+    "ComponentRegistry",
+    "component",
+]

hardwave/components/base.py

@@ -0,0 +1,253 @@
+"""
+Component base class, ComponentMeta, and Parameter.
+"""
+
+from __future__ import annotations
+
+from abc import ABC, abstractmethod
+from dataclasses import dataclass, field
+from typing import Any, ClassVar, Optional, Type, TYPE_CHECKING
+
+from hardwave.ports.port import Port
+from hardwave.diagnostics import PortNotFoundError
+
+if TYPE_CHECKING:
+    from hardwave.solvers.base import Solver
+    from hardwave.visualization.spec import VisualizationSpec
+
+
+# ---------------------------------------------------------------------------
+# ComponentMeta
+# ---------------------------------------------------------------------------
+
+@dataclass
+class ComponentMeta:
+    """
+    Static metadata for a component class.
+
+    This is attached to the component class itself (not instances) and is
+    used by the registry and UI.
+    """
+
+    name: str               # Unique identifier, e.g. "DCMotor"
+    display_name: str       # Human-readable, e.g. "DC Brushed Motor"
+    version: str            # Semantic version, e.g. "1.0.0"
+    description: str        # One-line summary
+    docs: str               # Full markdown documentation
+    category: str           # Hierarchy path, e.g. "Electrical/Motors"
+    tags: list[str] = field(default_factory=list)
+    author: str = ""
+    source_url: str = ""    # Link to datasheet, GitHub repo, etc.
+
+    def to_dict(self) -> dict:
+        return {
+            "name": self.name,
+            "display_name": self.display_name,
+            "version": self.version,
+            "description": self.description,
+            "docs": self.docs,
+            "category": self.category,
+            "tags": list(self.tags),
+            "author": self.author,
+            "source_url": self.source_url,
+        }
+
+
+# ---------------------------------------------------------------------------
+# Parameter
+# ---------------------------------------------------------------------------
+
+@dataclass
+class Parameter:
+    """
+    A static configuration value on a component.
+
+    Unlike ports, parameters do not carry signals between components.
+    They are set at instantiation time and remain constant during simulation.
+
+    Parameters can also be exposed as input ports to allow them to be driven
+    by other components (e.g., a variable resistor whose resistance is the
+    output of another component). Set `can_be_port=True` to enable this.
+    """
+
+    name: str
+    display_name: str
+    unit: str
+    python_type: Type
+    default: Any
+    description: str = ""
+    min_value: Optional[float] = None
+    max_value: Optional[float] = None
+    can_be_port: bool = False   # If True, component may expose this as an input port
+
+    def to_dict(self) -> dict:
+        return {
+            "name": self.name,
+            "display_name": self.display_name,
+            "unit": self.unit,
+            "python_type": self.python_type.__name__,
+            "default": self.default,
+            "description": self.description,
+            "min_value": self.min_value,
+            "max_value": self.max_value,
+            "can_be_port": self.can_be_port,
+        }
+
+
+# ---------------------------------------------------------------------------
+# Component base class
+# ---------------------------------------------------------------------------
+
+class Component(ABC):
+    """
+    Base class for all hardware components.
+
+    Subclasses must:
+      1. Define `meta: ClassVar[ComponentMeta]`
+      2. Define `ports: ClassVar[list[Port]]`
+      3. Implement `solve(inputs: dict) -> dict`
+    """
+
+    # --- Class-level declarations (must be set by subclass) ---
+    meta: ClassVar[ComponentMeta]
+    ports: ClassVar[list[Port]]
+    parameters: ClassVar[list[Parameter]] = []
+    visualizations: ClassVar[list["VisualizationSpec"]] = []
+
+    def __init__(
+        self,
+        instance_id: str,
+        param_values: Optional[dict] = None,
+    ) -> None:
+        """
+        Args:
+            instance_id:   Unique identifier for this instance within a project.
+                           e.g. "motor_1", "r3"
+            param_values:  Override values for class-level parameters.
+        """
+        self.instance_id = instance_id
+        self._param_values: dict = dict(param_values) if param_values else {}
+        self._solver: Optional["Solver"] = None   # Injected solver (optional override)
+        self._telemetry_log: list[dict] = []
+
+    # ------------------------------------------------------------------
+    # Port access
+    # ------------------------------------------------------------------
+
+    @classmethod
+    def get_port(cls, name: str) -> Port:
+        """Return the port with the given name. Raises PortNotFoundError if absent."""
+        for p in cls.ports:
+            if p.name == name:
+                return p
+        raise PortNotFoundError(
+            f"Port '{name}' not found on component '{cls.meta.name}'. "
+            f"Available ports: {[p.name for p in cls.ports]}"
+        )
+
+    @classmethod
+    def input_ports(cls) -> list[Port]:
+        """Return all INPUT ports."""
+        return [p for p in cls.ports if p.is_input]
+
+    @classmethod
+    def output_ports(cls) -> list[Port]:
+        """Return all OUTPUT ports."""
+        return [p for p in cls.ports if p.is_output]
+
+    # ------------------------------------------------------------------
+    # Parameter access
+    # ------------------------------------------------------------------
+
+    def get_param(self, name: str) -> Any:
+        """
+        Return the effective value for a parameter.
+        Instance-level override takes priority over class-level default.
+        """
+        if name in self._param_values:
+            return self._param_values[name]
+        for p in self.parameters:
+            if p.name == name:
+                return p.default
+        raise KeyError(
+            f"Parameter '{name}' not found on component '{self.meta.name}'"
+        )
+
+    def set_param(self, name: str, value: Any) -> None:
+        """Set an instance-level parameter override."""
+        param_names = [p.name for p in self.parameters]
+        if name not in param_names:
+            raise KeyError(
+                f"Parameter '{name}' not found on component '{self.meta.name}'. "
+                f"Available: {param_names}"
+            )
+        self._param_values[name] = value
+
+    # ------------------------------------------------------------------
+    # Solver
+    # ------------------------------------------------------------------
+
+    @abstractmethod
+    def solve(self, inputs: dict) -> dict:
+        """
+        Transform a dict of input values into a dict of output values.
+
+        Args:
+            inputs: Dict mapping input port names to their current values.
+                    Only ports that are connected or have defaults are included.
+
+        Returns:
+            Dict mapping output port names to computed values.
+            Must include all output port names defined in cls.ports.
+
+        Raises:
+            SolverError: If the computation cannot complete (e.g., division by zero,
+                         model inference failure, physics divergence).
+        """
+        ...
+
+    def set_solver(self, solver: "Solver") -> None:
+        """
+        Inject an alternative solver.
+        When set, the simulation engine calls solver.solve(inputs, component)
+        instead of self.solve(inputs).
+        This allows swapping in an ML-based solver without modifying the component.
+        """
+        self._solver = solver
+
+    def _execute_solve(self, inputs: dict) -> dict:
+        """
+        Called by the simulation engine to get outputs.
+        Routes to injected solver if present, otherwise calls self.solve().
+        """
+        if self._solver is not None:
+            return self._solver.solve(inputs, self)
+        return self.solve(inputs)
+
+    # ------------------------------------------------------------------
+    # Telemetry
+    # ------------------------------------------------------------------
+
+    def log_telemetry(self, inputs: dict, outputs: dict, timestamp: float) -> None:
+        """
+        Record an inputs/outputs pair with a timestamp.
+        Used to accumulate real-world data for model training.
+        """
+        self._telemetry_log.append(
+            {
+                "timestamp": timestamp,
+                "inputs": dict(inputs),
+                "outputs": dict(outputs),
+            }
+        )
+
+    def export_telemetry(self) -> list[dict]:
+        """Return accumulated telemetry records."""
+        return list(self._telemetry_log)
+
+    # ------------------------------------------------------------------
+    # Utility
+    # ------------------------------------------------------------------
+
+    def __repr__(self) -> str:
+        return f"{type(self).__name__}(instance_id={self.instance_id!r})"

hardwave/components/composite.py

@@ -0,0 +1,237 @@
+"""
+CompositeComponent, BuildContext, and Connection.
+"""
+
+from __future__ import annotations
+
+from abc import abstractmethod
+from dataclasses import dataclass
+from typing import Optional
+
+from hardwave.components.base import Component
+from hardwave.diagnostics import (
+    PortNotFoundError,
+    SolverError,
+    HardwaveError,
+)
+
+
+# ---------------------------------------------------------------------------
+# Connection
+# ---------------------------------------------------------------------------
+
+@dataclass
+class Connection:
+    """
+    A directed edge in the component graph.
+    Connects an output port of one component instance to an input port of another.
+
+    source_id:   instance_id of the source component
+    source_port: name of the output port on the source
+    target_id:   instance_id of the target component
+    target_port: name of the input port on the target
+    """
+    source_id: str
+    source_port: str
+    target_id: str
+    target_port: str
+
+    def to_dict(self) -> dict:
+        return {
+            "source_id": self.source_id,
+            "source_port": self.source_port,
+            "target_id": self.target_id,
+            "target_port": self.target_port,
+        }
+
+
+# ---------------------------------------------------------------------------
+# BuildContext
+# ---------------------------------------------------------------------------
+
+class BuildContext:
+    """
+    Context object passed to CompositeComponent.build().
+    Provides the API for constructing the internal sub-graph.
+    """
+
+    def __init__(self) -> None:
+        self._components: dict[str, Component] = {}
+        self._connections: list[Connection] = []
+        # Maps external input port name → list of (internal_component_id, internal_port)
+        # (fan-out: one external input can feed multiple internal ports)
+        self._input_map: dict[str, list[tuple[str, str]]] = {}
+        # Maps external output port name → (internal_component_id, internal_port)
+        self._output_map: dict[str, tuple[str, str]] = {}
+
+    def add(self, component: Component) -> Component:
+        """Register a sub-component instance. Returns the instance for chaining."""
+        self._components[component.instance_id] = component
+        return component
+
+    def connect(self, connection: Connection) -> None:
+        """Add a directed edge between two sub-component ports."""
+        self._connections.append(connection)
+
+    def map_input(
+        self,
+        external_port: str,
+        internal_component_id: str,
+        internal_port: str,
+    ) -> None:
+        """
+        Route an input value arriving at the composite's external port
+        to a sub-component's input port.
+        Multiple calls with the same external_port create fan-out: the same
+        external value is fed to all mapped internal ports.
+        """
+        if external_port not in self._input_map:
+            self._input_map[external_port] = []
+        self._input_map[external_port].append((internal_component_id, internal_port))
+
+    def map_output(
+        self,
+        external_port: str,
+        internal_component_id: str,
+        internal_port: str,
+    ) -> None:
+        """
+        Route a sub-component's output port value to the composite's
+        external output port.
+        """
+        self._output_map[external_port] = (internal_component_id, internal_port)
+
+
+# ---------------------------------------------------------------------------
+# CompositeComponent
+# ---------------------------------------------------------------------------
+
+class CompositeComponent(Component):
+    """
+    A component built from a sub-graph of connected sub-components.
+
+    Subclasses define the internal topology by overriding `build()`.
+    The `solve()` method is provided by CompositeComponent and runs the
+    internal graph, propagating values from the composite's own input
+    ports through the sub-graph and collecting the final outputs.
+
+    Subclasses must:
+      1. Define `meta`, `ports` (the EXTERNAL interface), and `parameters`
+         as for any Component.
+      2. Implement `build(ctx: BuildContext) -> None` which:
+         a. Adds sub-component instances via ctx.add(component_instance)
+         b. Connects them via ctx.connect(Connection(...))
+         c. Maps the composite's external ports to internal ports via
+            ctx.map_input(...) and ctx.map_output(...)
+    """
+
+    def __init__(
+        self,
+        instance_id: str,
+        param_values: Optional[dict] = None,
+    ) -> None:
+        super().__init__(instance_id, param_values)
+        self._build_context: Optional[BuildContext] = None
+
+    def _get_context(self) -> BuildContext:
+        """Lazily build and cache the internal sub-graph."""
+        if self._build_context is None:
+            ctx = BuildContext()
+            self.build(ctx)
+            self._build_context = ctx
+        return self._build_context
+
+    @abstractmethod
+    def build(self, ctx: BuildContext) -> None:
+        """Define the internal sub-graph."""
+        ...
+
+    def solve(self, inputs: dict) -> dict:
+        """Run the internal sub-graph. Do not override."""
+        ctx = self._get_context()
+
+        # values[component_id][port_name] = value
+        values: dict[str, dict] = {cid: {} for cid in ctx._components}
+
+        # Feed external inputs into the sub-graph via input mappings (fan-out supported)
+        for ext_port, targets in ctx._input_map.items():
+            if ext_port in inputs:
+                for (int_comp_id, int_port) in targets:
+                    values[int_comp_id][int_port] = inputs[ext_port]
+
+        # Topological sort of the internal sub-graph
+        order = self._topological_order(ctx)
+
+        # Run each sub-component in order
+        for comp in order:
+            cid = comp.instance_id
+            comp_inputs: dict = {}
+
+            # Gather from established values (from upstream outputs or injected inputs)
+            for port in comp.input_ports():
+                if port.name in values[cid]:
+                    comp_inputs[port.name] = values[cid][port.name]
+                elif not port.required and port.default_value is not None:
+                    comp_inputs[port.name] = port.default_value
+
+            # Execute
+            try:
+                comp_outputs = comp._execute_solve(comp_inputs)
+            except Exception as exc:
+                raise SolverError(
+                    f"CompositeComponent '{self.instance_id}': sub-component "
+                    f"'{cid}' failed: {exc}"
+                ) from exc
+
+            # Store outputs
+            for k, v in comp_outputs.items():
+                values[cid][k] = v
+
+            # Propagate to downstream components via connections
+            for conn in ctx._connections:
+                if conn.source_id == cid and conn.source_port in comp_outputs:
+                    values[conn.target_id][conn.target_port] = comp_outputs[conn.source_port]
+
+        # Collect external outputs via output mappings
+        result: dict = {}
+        for ext_port, (int_comp_id, int_port) in ctx._output_map.items():
+            if int_comp_id in values and int_port in values[int_comp_id]:
+                result[ext_port] = values[int_comp_id][int_port]
+            else:
+                raise SolverError(
+                    f"CompositeComponent '{self.instance_id}': output mapping "
+                    f"'{ext_port}' → '{int_comp_id}.{int_port}' produced no value"
+                )
+        return result
+
+    # ------------------------------------------------------------------
+    # Internal topological sort
+    # ------------------------------------------------------------------
+
+    def _topological_order(self, ctx: BuildContext) -> list[Component]:
+        """Kahn's algorithm on the internal sub-graph."""
+        in_degree: dict[str, int] = {cid: 0 for cid in ctx._components}
+        adjacency: dict[str, list[str]] = {cid: [] for cid in ctx._components}
+
+        for conn in ctx._connections:
+            if conn.source_id in adjacency and conn.target_id in in_degree:
+                adjacency[conn.source_id].append(conn.target_id)
+                in_degree[conn.target_id] += 1
+
+        queue = [cid for cid, deg in in_degree.items() if deg == 0]
+        order: list[str] = []
+
+        while queue:
+            cid = queue.pop(0)
+            order.append(cid)
+            for neighbour in adjacency[cid]:
+                in_degree[neighbour] -= 1
+                if in_degree[neighbour] == 0:
+                    queue.append(neighbour)
+
+        if len(order) != len(ctx._components):
+            raise SolverError(
+                f"CompositeComponent '{self.instance_id}' contains a cycle "
+                "in its internal sub-graph"
+            )
+        return [ctx._components[cid] for cid in order]

hardwave/components/decorators.py

@@ -0,0 +1,56 @@
+"""
+@component decorator: attaches ComponentMeta and auto-registers the class.
+"""
+
+from __future__ import annotations
+
+from typing import Callable, Optional, Type
+
+from hardwave.components.base import Component, ComponentMeta
+from hardwave.components.registry import ComponentRegistry
+
+
+def component(
+    name: str,
+    display_name: str,
+    version: str,
+    description: str,
+    docs: str,
+    category: str,
+    tags: Optional[list[str]] = None,
+    author: str = "",
+    source_url: str = "",
+) -> Callable[[Type[Component]], Type[Component]]:
+    """
+    Class decorator that attaches ComponentMeta and registers the class
+    with the global ComponentRegistry.
+
+    Usage:
+        @component(
+            name="Resistor",
+            display_name="Resistor",
+            version="1.0.0",
+            description="Ideal resistor",
+            docs="Implements Ohm's Law: V = IR.",
+            category="Electrical/Passive",
+        )
+        class Resistor(Component):
+            ...
+    """
+
+    def decorator(cls: Type[Component]) -> Type[Component]:
+        cls.meta = ComponentMeta(
+            name=name,
+            display_name=display_name,
+            version=version,
+            description=description,
+            docs=docs,
+            category=category,
+            tags=tags or [],
+            author=author,
+            source_url=source_url,
+        )
+        ComponentRegistry.instance().register(cls)
+        return cls
+
+    return decorator