simweave 0.4.0__py3-none-any.whl

simweave/continuous/solver.py

@@ -0,0 +1,237 @@
+"""First-order state-space ODE solver and plug-in system protocol.
+
+Two use modes:
+
+1. Standalone: call :func:`simulate` with a system, time span, and ``dt``.
+   Returns a :class:`SimulationResult` with full time/state arrays.
+2. Hybrid: wrap a system in :class:`ContinuousProcess` and register with a
+   :class:`~simweave.core.environment.SimEnvironment`. The environment clock
+   then drives the integration. Useful when discrete events and continuous
+   dynamics share a timeline (e.g. a vehicle queued at a junction whose
+   suspension is still integrating over bumps).
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+from typing import Callable, Iterable, Optional, Protocol, runtime_checkable
+
+import numpy as np
+
+from simweave.core.entity import Entity
+
+
+ArrayLike = np.ndarray
+InputFunc = Callable[[float], np.ndarray | float | int | None]
+
+
+@dataclass(slots=True)
+class SimulationResult:
+    time: np.ndarray
+    state: np.ndarray
+    state_labels: tuple[str, ...]
+    system_name: str
+    method: str
+
+    def final_state(self) -> np.ndarray:
+        return self.state[-1].copy()
+
+
+@runtime_checkable
+class SupportsDynamics(Protocol):
+    """Protocol for plug-in dynamic systems."""
+
+    def initial_state(self) -> np.ndarray: ...
+
+    def derivatives(
+        self,
+        t: float,
+        state: np.ndarray,
+        inputs: np.ndarray | float | int | None = None,
+    ) -> np.ndarray: ...
+
+
+class DynamicSystem:
+    """Base class for first-order state-space dynamic systems."""
+
+    def initial_state(self) -> np.ndarray:
+        raise NotImplementedError
+
+    def derivatives(
+        self,
+        t: float,
+        state: np.ndarray,
+        inputs: np.ndarray | float | int | None = None,
+    ) -> np.ndarray:
+        raise NotImplementedError
+
+    def inputs(self, t: float) -> np.ndarray | float | int | None:
+        return None
+
+    def state_labels(self) -> tuple[str, ...]:
+        x0 = self.initial_state()
+        return tuple(f"x{i}" for i in range(x0.size))
+
+    def validate_state(self, state: np.ndarray) -> None:
+        if state.ndim != 1:
+            raise ValueError("State must be a 1D array.")
+
+    @property
+    def name(self) -> str:
+        return self.__class__.__name__
+
+
+def _as_state_vector(state: Iterable[float] | np.ndarray) -> np.ndarray:
+    arr = np.asarray(state, dtype=float)
+    if arr.ndim != 1:
+        raise ValueError("State must be coercible to a 1D float array.")
+    return arr
+
+
+def _resolve_inputs(
+    system: SupportsDynamics,
+    external_inputs: Optional[InputFunc],
+    t: float,
+) -> np.ndarray | float | int | None:
+    if external_inputs is not None:
+        return external_inputs(t)
+    if hasattr(system, "inputs"):
+        return system.inputs(t)  # type: ignore[attr-defined]
+    return None
+
+
+def _step_euler(system, t, x, dt, external_inputs):
+    u = _resolve_inputs(system, external_inputs, t)
+    dx = np.asarray(system.derivatives(t, x, u), dtype=float)
+    return x + dt * dx
+
+
+def _step_rk4(system, t, x, dt, external_inputs):
+    u1 = _resolve_inputs(system, external_inputs, t)
+    k1 = np.asarray(system.derivatives(t, x, u1), dtype=float)
+    u2 = _resolve_inputs(system, external_inputs, t + 0.5 * dt)
+    k2 = np.asarray(
+        system.derivatives(t + 0.5 * dt, x + 0.5 * dt * k1, u2), dtype=float
+    )
+    k3 = np.asarray(
+        system.derivatives(t + 0.5 * dt, x + 0.5 * dt * k2, u2), dtype=float
+    )
+    u4 = _resolve_inputs(system, external_inputs, t + dt)
+    k4 = np.asarray(system.derivatives(t + dt, x + dt * k3, u4), dtype=float)
+    return x + (dt / 6.0) * (k1 + 2.0 * k2 + 2.0 * k3 + k4)
+
+
+_STEPPERS = {"euler": _step_euler, "rk4": _step_rk4}
+
+
+def simulate(
+    system: SupportsDynamics,
+    t_span: tuple[float, float],
+    dt: float,
+    x0: Iterable[float] | np.ndarray | None = None,
+    method: str = "rk4",
+    inputs: Optional[InputFunc] = None,
+) -> SimulationResult:
+    """Integrate a system over ``t_span`` with fixed step ``dt``."""
+    t0, tf = t_span
+    if dt <= 0:
+        raise ValueError("dt must be positive.")
+    if tf <= t0:
+        raise ValueError("t_span must satisfy tf > t0.")
+    if method not in _STEPPERS:
+        raise ValueError(f"Unknown method '{method}'. Use one of {tuple(_STEPPERS)}")
+
+    x_init = _as_state_vector(system.initial_state() if x0 is None else x0)
+    if hasattr(system, "validate_state"):
+        system.validate_state(x_init)  # type: ignore[attr-defined]
+
+    n_steps = int(np.floor((tf - t0) / dt)) + 1
+    time = t0 + np.arange(n_steps + 1, dtype=float) * dt
+    time = time[time <= tf + 1e-12]
+
+    state = np.zeros((time.size, x_init.size), dtype=float)
+    state[0] = x_init
+
+    stepper = _STEPPERS[method]
+    for i in range(1, time.size):
+        state[i] = stepper(system, time[i - 1], state[i - 1], dt, inputs)
+
+    labels = (
+        tuple(system.state_labels())
+        if hasattr(system, "state_labels")
+        else tuple(f"x{i}" for i in range(x_init.size))
+    )
+    return SimulationResult(
+        time=time,
+        state=state,
+        state_labels=labels,
+        system_name=getattr(system, "name", system.__class__.__name__),
+        method=method,
+    )
+
+
+# ---------------------------------------------------------------------------
+# Hybrid wrapper: turn a DynamicSystem into a SimEnvironment process.
+# ---------------------------------------------------------------------------
+
+
+class ContinuousProcess(Entity):
+    """Drive a DynamicSystem from a SimEnvironment's tick loop.
+
+    Each tick, integrates ``n_substeps`` sub-intervals of length ``dt / n_substeps``.
+    The previous state is appended to ``history_state`` with the corresponding
+    time in ``history_time``.
+    """
+
+    def __init__(
+        self,
+        system: SupportsDynamics,
+        method: str = "rk4",
+        n_substeps: int = 1,
+        inputs: InputFunc | None = None,
+        name: str | None = None,
+    ) -> None:
+        super().__init__(
+            name=name or getattr(system, "name", system.__class__.__name__)
+        )
+        if method not in _STEPPERS:
+            raise ValueError(f"Unknown method '{method}'")
+        if n_substeps < 1:
+            raise ValueError("n_substeps must be >= 1")
+        self.system = system
+        self.method = method
+        self.n_substeps = n_substeps
+        self.inputs = inputs
+        self.state = _as_state_vector(system.initial_state())
+        self._stepper = _STEPPERS[method]
+        self.history_time: list[float] = []
+        self.history_state: list[np.ndarray] = []
+
+    def on_register(self, env) -> None:
+        super().on_register(env)
+        self.history_time.append(env.clock.t)
+        self.history_state.append(self.state.copy())
+
+    def tick(self, dt: float, env) -> None:
+        super().tick(dt, env)
+        sub_dt = dt / self.n_substeps
+        t = env.clock.t
+        for _ in range(self.n_substeps):
+            self.state = self._stepper(self.system, t, self.state, sub_dt, self.inputs)
+            t += sub_dt
+        self.history_time.append(env.clock.t + dt)
+        self.history_state.append(self.state.copy())
+
+    def has_work(self, env) -> bool:
+        return True  # continuous dynamics always "have work"
+
+    def result(self) -> SimulationResult:
+        return SimulationResult(
+            time=np.asarray(self.history_time),
+            state=np.asarray(self.history_state),
+            state_labels=tuple(self.system.state_labels())
+            if hasattr(self.system, "state_labels")
+            else tuple(f"x{i}" for i in range(self.state.size)),
+            system_name=getattr(self.system, "name", self.system.__class__.__name__),
+            method=self.method,
+        )

simweave/continuous/systems/__init__.py

@@ -0,0 +1,14 @@
+from simweave.continuous.systems.mass_spring_damper import MassSpringDamper
+from simweave.continuous.systems.pendulum import SimplePendulum
+from simweave.continuous.systems.quarter_car import QuarterCarModel
+from simweave.continuous.systems.rlc import SeriesRLC
+from simweave.continuous.systems.thermal import ThermalRC, TwoMassThermal
+
+__all__ = [
+    "MassSpringDamper",
+    "SimplePendulum",
+    "QuarterCarModel",
+    "SeriesRLC",
+    "ThermalRC",
+    "TwoMassThermal",
+]

simweave/continuous/systems/mass_spring_damper.py

@@ -0,0 +1,43 @@
+from __future__ import annotations
+
+import numpy as np
+
+from simweave.continuous.solver import DynamicSystem
+
+
+class MassSpringDamper(DynamicSystem):
+    """Single degree-of-freedom mass-spring-damper.
+
+    State x = [displacement, velocity]
+    Equation: m x'' + c x' + k x = F(t)
+    """
+
+    def __init__(
+        self,
+        mass: float,
+        damping: float,
+        stiffness: float,
+        x0: tuple[float, float] = (0.0, 0.0),
+    ):
+        if mass <= 0:
+            raise ValueError("mass must be positive")
+        self.mass = float(mass)
+        self.damping = float(damping)
+        self.stiffness = float(stiffness)
+        self._x0 = np.asarray(x0, dtype=float)
+
+    def initial_state(self) -> np.ndarray:
+        return self._x0.copy()
+
+    def state_labels(self) -> tuple[str, str]:
+        return ("x", "x_dot")
+
+    def derivatives(
+        self, t: float, state: np.ndarray, inputs: float | int | None = None
+    ) -> np.ndarray:
+        displacement, velocity = state
+        force = 0.0 if inputs is None else float(inputs)
+        acceleration = (
+            force - self.damping * velocity - self.stiffness * displacement
+        ) / self.mass
+        return np.array([velocity, acceleration], dtype=float)

simweave/continuous/systems/pendulum.py

@@ -0,0 +1,49 @@
+from __future__ import annotations
+
+import numpy as np
+
+from simweave.continuous.solver import DynamicSystem
+
+
+class SimplePendulum(DynamicSystem):
+    """Simple pendulum with optional viscous damping and external torque.
+
+    State x = [theta, theta_dot]
+    Equation:
+        theta'' + (c / (m l^2)) theta' + (g/l) sin(theta) = tau / (m l^2)
+    """
+
+    def __init__(
+        self,
+        length: float,
+        mass: float = 1.0,
+        gravity: float = 9.81,
+        damping: float = 0.0,
+        x0: tuple[float, float] = (0.0, 0.0),
+    ):
+        if length <= 0 or mass <= 0:
+            raise ValueError("length and mass must be positive")
+        self.length = float(length)
+        self.mass = float(mass)
+        self.gravity = float(gravity)
+        self.damping = float(damping)
+        self._x0 = np.asarray(x0, dtype=float)
+        self._inertia = self.mass * self.length**2
+
+    def initial_state(self) -> np.ndarray:
+        return self._x0.copy()
+
+    def state_labels(self) -> tuple[str, str]:
+        return ("theta", "theta_dot")
+
+    def derivatives(
+        self, t: float, state: np.ndarray, inputs: float | int | None = None
+    ) -> np.ndarray:
+        theta, theta_dot = state
+        torque = 0.0 if inputs is None else float(inputs)
+        theta_ddot = (
+            torque
+            - self.damping * theta_dot
+            - self.mass * self.gravity * self.length * np.sin(theta)
+        ) / self._inertia
+        return np.array([theta_dot, theta_ddot], dtype=float)

simweave/continuous/systems/quarter_car.py

@@ -0,0 +1,59 @@
+from __future__ import annotations
+
+import numpy as np
+
+from simweave.continuous.solver import DynamicSystem
+
+
+class QuarterCarModel(DynamicSystem):
+    """Two degree-of-freedom quarter-car suspension model.
+
+    State vector x = [z_s, z_s_dot, z_u, z_u_dot]
+    where:
+        z_s: sprung mass displacement
+        z_u: unsprung mass displacement
+    """
+
+    def __init__(
+        self,
+        sprung_mass: float,
+        unsprung_mass: float,
+        suspension_stiffness: float,
+        damping: float,
+        tyre_stiffness: float,
+        x0: tuple[float, float, float, float] = (0.0, 0.0, 0.0, 0.0),
+    ):
+        if sprung_mass <= 0 or unsprung_mass <= 0:
+            raise ValueError("Masses must be positive")
+        self.m_s = float(sprung_mass)
+        self.m_u = float(unsprung_mass)
+        self.k_s = float(suspension_stiffness)
+        self.c_s = float(damping)
+        self.k_t = float(tyre_stiffness)
+        self._x0 = np.asarray(x0, dtype=float)
+
+    def initial_state(self) -> np.ndarray:
+        return self._x0.copy()
+
+    def state_labels(self) -> tuple[str, str, str, str]:
+        return ("z_s", "z_s_dot", "z_u", "z_u_dot")
+
+    def derivatives(
+        self, t: float, state: np.ndarray, inputs: float | int | None = None
+    ) -> np.ndarray:
+        z_s, z_s_dot, z_u, z_u_dot = state
+        z_r = 0.0 if inputs is None else float(inputs)
+
+        suspension_deflection = z_s - z_u
+        suspension_velocity = z_s_dot - z_u_dot
+
+        z_s_ddot = (
+            -self.k_s * suspension_deflection - self.c_s * suspension_velocity
+        ) / self.m_s
+        z_u_ddot = (
+            self.k_s * suspension_deflection
+            + self.c_s * suspension_velocity
+            - self.k_t * (z_u - z_r)
+        ) / self.m_u
+
+        return np.array([z_s_dot, z_s_ddot, z_u_dot, z_u_ddot], dtype=float)

simweave/continuous/systems/rlc.py

@@ -0,0 +1,44 @@
+from __future__ import annotations
+
+import numpy as np
+
+from simweave.continuous.solver import DynamicSystem
+
+
+class SeriesRLC(DynamicSystem):
+    """Series RLC circuit in charge-current form.
+
+    State x = [q, i]
+    Equation:
+        L q'' + R q' + (1/C) q = V(t)
+    """
+
+    def __init__(
+        self,
+        resistance: float,
+        inductance: float,
+        capacitance: float,
+        x0: tuple[float, float] = (0.0, 0.0),
+    ):
+        if inductance <= 0 or capacitance <= 0:
+            raise ValueError("inductance and capacitance must be positive")
+        self.resistance = float(resistance)
+        self.inductance = float(inductance)
+        self.capacitance = float(capacitance)
+        self._x0 = np.asarray(x0, dtype=float)
+
+    def initial_state(self) -> np.ndarray:
+        return self._x0.copy()
+
+    def state_labels(self) -> tuple[str, str]:
+        return ("charge", "current")
+
+    def derivatives(
+        self, t: float, state: np.ndarray, inputs: float | int | None = None
+    ) -> np.ndarray:
+        charge, current = state
+        voltage = 0.0 if inputs is None else float(inputs)
+        current_dot = (
+            voltage - self.resistance * current - charge / self.capacitance
+        ) / self.inductance
+        return np.array([current, current_dot], dtype=float)

simweave/continuous/systems/thermal.py

@@ -0,0 +1,127 @@
+"""Lumped-capacitance thermal models.
+
+Two models live here:
+
+* :class:`ThermalRC` -- a single-body thermal RC circuit. State is a
+  single temperature `T` that exchanges heat with an ambient `T_inf`
+  through a thermal resistance `R_th`, and stores energy in a thermal
+  capacitance `C_th`. Equation:
+
+      C_th * dT/dt = (T_inf - T) / R_th + Q_in(t)
+
+  Useful for batteries, electronics packages, and any first-order
+  thermal behaviour.
+
+* :class:`TwoMassThermal` -- two coupled lumps (e.g. a CPU core and a
+  heat sink) with internal conductance `k_12` between them and external
+  resistance from the second mass to ambient.
+"""
+
+from __future__ import annotations
+
+import numpy as np
+
+from simweave.continuous.solver import DynamicSystem
+
+
+class ThermalRC(DynamicSystem):
+    """First-order lumped-capacitance thermal model.
+
+    Parameters
+    ----------
+    thermal_resistance:
+        R_th in K/W. Larger => slower equilibration with ambient.
+    thermal_capacitance:
+        C_th in J/K. Larger => more thermal inertia.
+    ambient_temperature:
+        T_inf in Kelvin (or any consistent unit). Default 293.15 K (20 C).
+    initial_temperature:
+        Starting body temperature, same unit as ``ambient_temperature``.
+    """
+
+    def __init__(
+        self,
+        thermal_resistance: float,
+        thermal_capacitance: float,
+        ambient_temperature: float = 293.15,
+        initial_temperature: float = 293.15,
+    ) -> None:
+        if thermal_resistance <= 0 or thermal_capacitance <= 0:
+            raise ValueError(
+                "thermal_resistance and thermal_capacitance must be positive."
+            )
+        self.R_th = float(thermal_resistance)
+        self.C_th = float(thermal_capacitance)
+        self.T_inf = float(ambient_temperature)
+        self._x0 = np.array([float(initial_temperature)], dtype=float)
+
+    def initial_state(self) -> np.ndarray:
+        return self._x0.copy()
+
+    def state_labels(self) -> tuple[str, ...]:
+        return ("temperature",)
+
+    def derivatives(
+        self, t: float, state: np.ndarray, inputs: float | int | None = None
+    ) -> np.ndarray:
+        T = state[0]
+        heat_in = 0.0 if inputs is None else float(inputs)
+        dTdt = ((self.T_inf - T) / self.R_th + heat_in) / self.C_th
+        return np.array([dTdt], dtype=float)
+
+    @property
+    def time_constant(self) -> float:
+        """First-order time constant tau = R_th * C_th (seconds)."""
+        return self.R_th * self.C_th
+
+
+class TwoMassThermal(DynamicSystem):
+    """Two-lump thermal model: core <-> sink <-> ambient.
+
+    State: [T_core, T_sink], both in the same unit as ambient.
+    Q_in(t) is applied to the core. Sink dissipates to ambient via
+    ``R_sink_to_ambient``; core couples to sink via conductance
+    ``k_core_to_sink`` (W/K).
+    """
+
+    def __init__(
+        self,
+        C_core: float,
+        C_sink: float,
+        k_core_to_sink: float,
+        R_sink_to_ambient: float,
+        ambient_temperature: float = 293.15,
+        initial_core: float = 293.15,
+        initial_sink: float = 293.15,
+    ) -> None:
+        for name, val in (
+            ("C_core", C_core),
+            ("C_sink", C_sink),
+            ("k_core_to_sink", k_core_to_sink),
+            ("R_sink_to_ambient", R_sink_to_ambient),
+        ):
+            if val <= 0:
+                raise ValueError(f"{name} must be positive.")
+        self.C_core = float(C_core)
+        self.C_sink = float(C_sink)
+        self.k_cs = float(k_core_to_sink)
+        self.R_sa = float(R_sink_to_ambient)
+        self.T_inf = float(ambient_temperature)
+        self._x0 = np.array([initial_core, initial_sink], dtype=float)
+
+    def initial_state(self) -> np.ndarray:
+        return self._x0.copy()
+
+    def state_labels(self) -> tuple[str, ...]:
+        return ("core_temperature", "sink_temperature")
+
+    def derivatives(
+        self, t: float, state: np.ndarray, inputs: float | int | None = None
+    ) -> np.ndarray:
+        T_c, T_s = state
+        Q_in = 0.0 if inputs is None else float(inputs)
+        q_cs = self.k_cs * (T_c - T_s)  # core -> sink
+        q_sa = (T_s - self.T_inf) / self.R_sa  # sink -> ambient
+        dTc = (Q_in - q_cs) / self.C_core
+        dTs = (q_cs - q_sa) / self.C_sink
+        return np.array([dTc, dTs], dtype=float)

simweave/core/__init__.py

@@ -0,0 +1,18 @@
+"""Core runtime: clock, scheduler, entity, environment, logging."""
+
+from simweave.core.clock import Clock
+from simweave.core.scheduler import EventQueue, ScheduledEvent
+from simweave.core.entity import Entity
+from simweave.core.environment import SimEnvironment, Process
+from simweave.core.logging import configure, get_logger
+
+__all__ = [
+    "Clock",
+    "EventQueue",
+    "ScheduledEvent",
+    "Entity",
+    "SimEnvironment",
+    "Process",
+    "configure",
+    "get_logger",
+]

simweave/core/clock.py

@@ -0,0 +1,64 @@
+"""Simulation clock.
+
+simweave uses a fixed-step *atomic* clock as its time authority. Every process
+registered with the :class:`~simweave.core.environment.SimEnvironment` is
+invoked once per tick with the clock's current ``dt``.
+
+Atomic time is a design choice that makes Monte Carlo aggregation trivial:
+every replicate shares the same time grid, so summaries collapse to array
+reductions rather than ragged joins. Where sparse events would otherwise waste
+cycles, the environment can cooperate with the optional ``EventQueue`` to
+fast-forward idle gaps (see :mod:`simweave.core.scheduler`).
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+
+
+@dataclass
+class Clock:
+    """Fixed-step simulation clock.
+
+    Parameters
+    ----------
+    start:
+        Initial simulation time.
+    dt:
+        Fixed timestep. Units are whatever the rest of the model uses
+        (typically seconds, but can be hours, days, or dimensionless ticks).
+    end:
+        Optional end time. If provided, :meth:`is_finished` returns ``True``
+        once ``t >= end``.
+    """
+
+    start: float = 0.0
+    dt: float = 1.0
+    end: float | None = None
+    t: float = 0.0
+
+    def __post_init__(self) -> None:
+        if self.dt <= 0:
+            raise ValueError("Clock.dt must be positive.")
+        if self.end is not None and self.end <= self.start:
+            raise ValueError("Clock.end must be strictly greater than start.")
+        self.t = self.start
+
+    def advance(self, dt: float | None = None) -> None:
+        """Advance the clock by ``dt`` (defaults to ``self.dt``)."""
+        step = self.dt if dt is None else dt
+        if step < 0:
+            raise ValueError("Cannot advance clock by a negative interval.")
+        self.t += step
+
+    def jump_to(self, t: float) -> None:
+        """Jump the clock forward to absolute time ``t`` (no backward jumps)."""
+        if t < self.t:
+            raise ValueError("Cannot rewind the clock.")
+        self.t = t
+
+    def reset(self) -> None:
+        self.t = self.start
+
+    def is_finished(self) -> bool:
+        return self.end is not None and self.t >= self.end