moat-dev-heat-sim 0.0.1__py3-none-any.whl

moat/dev/heat/sim/__init__.py

@@ -0,0 +1,16 @@
+"""
+Plant simulator for the heat controller.
+
+A deterministic, seeded, sans-IO model of the heating plant (buffer,
+heat pump, circulation pump, heating circuit, hot water, pellet burner,
+weather), advanced by :meth:`~moat.dev.heat.sim.plant.Plant.step`. It has no MoaT-Link
+dependency.
+"""
+
+from __future__ import annotations
+
+from .config import PlantCfg
+from .heat_pump import Stage
+from .plant import SENSORS, Energy, Faults, Inputs, Plant
+
+__all__ = ["SENSORS", "Energy", "Faults", "Inputs", "Plant", "PlantCfg", "Stage"]

moat/dev/heat/sim/_main.py

@@ -0,0 +1,48 @@
+"""
+``moat dev heat sim``: run the plant simulator on MoaT-Link.
+"""
+
+from __future__ import annotations
+
+import anyio
+from pathlib import Path as FSPath
+
+import asyncclick as click
+
+from typing import Any
+
+__all__ = ["cli"]
+
+
+@click.command(short_help="Run the plant simulator on MoaT-Link.")
+@click.option(
+    "-s",
+    "--scenario",
+    type=click.Path(exists=True, dir_okay=False, path_type=FSPath),
+    help="Scenario file (plant setup and event schedule).",
+)
+@click.option("-t", "--dt", type=float, default=10, help="Simulated seconds per step.")
+@click.option("-x", "--scale", type=float, default=1, help="Simulated seconds per real second.")
+@click.option("-d", "--duration", type=float, help="Stop after this many simulated seconds.")
+@click.pass_obj
+async def cli(
+    obj: Any, scenario: FSPath | None, dt: float, scale: float, duration: float | None
+) -> None:
+    """
+    Run the plant simulator on MoaT-Link.
+
+    The simulator publishes its sensors at the real ``heat.s.*`` and
+    ``temp.*`` paths and reacts to the commands written there, so do not
+    run it next to a real plant. Use a separate MoaT-Link root (``link.root``
+    in the configuration) for dry runs.
+    """
+    from moat.link.client import Link  # noqa: PLC0415
+
+    from .link import SimLink  # noqa: PLC0415
+    from .scenario import Scenario  # noqa: PLC0415
+
+    sc = Scenario.load(scenario) if scenario is not None else Scenario()
+    async with Link(obj.cfg.link) as link:
+        sim = SimLink(link, sc, dt=dt, scale=scale)
+        with anyio.move_on_after(None if duration is None else duration / scale):
+            await sim.run()

moat/dev/heat/sim/_util.py

@@ -0,0 +1,61 @@
+"""Shared physics helpers for the plant simulator."""
+
+from __future__ import annotations
+
+import math
+
+__all__ = ["C_WATER", "clamp", "kgps", "tank"]
+
+C_WATER = 4.186
+"""Specific heat of water, kJ/(kg·K). One litre of water is taken as 1 kg."""
+
+
+def kgps(lpm: float) -> float:
+    """Convert a flow in l/min to kg/s."""
+    return lpm / 60
+
+
+def clamp(v: float, lo: float, hi: float) -> float:
+    """Restrict ``v`` to ``[lo, hi]``."""
+    return lo if v < lo else min(v, hi)
+
+
+def tank(
+    t0: float,
+    cap: float,
+    fc: float,
+    t_in: float,
+    ua: float,
+    t_amb: float,
+    p: float,
+    dt: float,
+) -> tuple[float, float, float]:
+    """
+    Advance a well-mixed volume of water by ``dt`` seconds, exactly.
+
+    The volume has heat capacity ``cap`` (kJ/K). Water enters at ``t_in``
+    with capacity rate ``fc`` (kW/K, i.e. mass flow times c) and leaves
+    at the tank's own temperature. ``ua`` (kW/K) couples it to ``t_amb``;
+    ``p`` (kW) is added directly.
+
+    Returns ``(t_new, t_avg, e_loss)``: the final temperature, the time
+    average of the temperature over the interval (i.e. the effective
+    temperature of the outflow, whose energy is ``fc * t_avg * dt``), and
+    the energy lost to the surroundings (kJ).
+
+    The ODE is linear, so this is energy-conserving for any ``dt``.
+    """
+    g = fc + ua
+    if g <= 0:
+        t1 = t0 + p * dt / cap
+        return t1, (t0 + t1) / 2, 0.0
+    t_eq = (fc * t_in + ua * t_amb + p) / g
+    x = dt * g / cap
+    if x < 1e-9:
+        t1 = t0 + (t_eq - t0) * x
+        t_avg = (t0 + t1) / 2
+    else:
+        e = math.exp(-x)
+        t1 = t_eq + (t0 - t_eq) * e
+        t_avg = t_eq + (t0 - t_eq) * (1 - e) / x
+    return t1, t_avg, ua * (t_avg - t_amb) * dt

moat/dev/heat/sim/buffer.py

@@ -0,0 +1,112 @@
+"""Stratified buffer tank."""
+
+from __future__ import annotations
+
+from ._util import C_WATER
+
+from typing import TYPE_CHECKING
+
+if TYPE_CHECKING:
+    from .config import BufferCfg
+
+__all__ = ["Buffer"]
+
+
+class Buffer:
+    """
+    A stack of equal, well-mixed layers; index 0 is the top.
+
+    Flows are plug flows between an inlet and an outlet layer (upwind,
+    conservative). Buoyancy is restored after each step by mixing
+    inverted layers; conduction and losses act between layers and to
+    the room.
+    """
+
+    def __init__(self, cfg: BufferCfg) -> None:
+        self.cfg = cfg
+        self.n = n = cfg.layers
+        self.mass = cfg.volume / n
+        t_top, t_bot = cfg.t_init
+        self.t = [t_top + (t_bot - t_top) * i / max(n - 1, 1) for i in range(n)]
+
+    def layer(self, frac: float) -> int:
+        """Index of the layer at relative height ``frac`` (0 = top, 1 = bottom)."""
+        return min(self.n - 1, max(0, int(frac * self.n)))
+
+    def temp(self, frac: float) -> float:
+        """Temperature at relative height ``frac``."""
+        return self.t[self.layer(frac)]
+
+    @property
+    def energy(self) -> float:
+        """Stored energy relative to 0 °C, kJ."""
+        return self.mass * C_WATER * sum(self.t)
+
+    def flow(self, m: float, t_in: float, enter: int, leave: int) -> float:
+        """
+        Move ``m`` kg of water through the tank.
+
+        Water at ``t_in`` enters at layer ``enter``; the same mass leaves
+        at layer ``leave``, and the layers in between shift. Returns the
+        temperature of the water that left, which is that of layer
+        ``leave`` before the call.
+
+        ``m`` must not exceed one layer's mass.
+        """
+        t = self.t
+        t_out = t[leave]
+        if m <= 0:
+            return t_out
+        f = m / self.mass
+        if f > 1 + 1e-9:
+            raise ValueError(f"Flow {m} kg exceeds layer mass {self.mass}")
+        if enter < leave:  # downwards
+            for i in range(leave, enter, -1):
+                t[i] += f * (t[i - 1] - t[i])
+        elif enter > leave:  # upwards
+            for i in range(leave, enter):
+                t[i] += f * (t[i + 1] - t[i])
+        t[enter] += f * (t_in - t[enter])
+        return t_out
+
+    def relax(self, dt: float) -> float:
+        """Conduction between layers and losses to the room. Returns the loss, kJ."""
+        cfg = self.cfg
+        t = self.t
+        n = self.n
+        cap = self.mass * C_WATER
+        k = cfg.k_cond * dt / cap
+        if k:
+            flux = [k * (t[i] - t[i + 1]) for i in range(n - 1)]
+            for i, q in enumerate(flux):
+                t[i] -= q
+                t[i + 1] += q
+        ua = cfg.ua / n
+        loss = 0.0
+        for i in range(n):
+            q = ua * (t[i] - cfg.t_amb) * dt
+            t[i] -= q / cap
+            loss += q
+        return loss
+
+    def mix(self) -> None:
+        """Mix inverted layers (warmer water below colder) until the stack is stable."""
+        t = self.t
+        if all(t[i] >= t[i + 1] for i in range(self.n - 1)):
+            return
+        # pool adjacent violators: blocks of (sum, count), means non-increasing
+        blocks: list[list[float]] = []
+        for v in t:
+            blocks.append([v, 1])
+            while len(blocks) > 1 and (
+                blocks[-2][0] / blocks[-2][1] < blocks[-1][0] / blocks[-1][1]
+            ):
+                s, c = blocks.pop()
+                blocks[-1][0] += s
+                blocks[-1][1] += c
+        i = 0
+        for s, c in blocks:
+            v = s / c
+            for _ in range(int(c)):
+                t[i] = v
+                i += 1

moat/dev/heat/sim/circuits.py

@@ -0,0 +1,129 @@
+"""Heat consumers: heating circuit with house, and the fresh-water station."""
+
+from __future__ import annotations
+
+import math
+
+from ._util import C_WATER, kgps, tank
+
+from typing import TYPE_CHECKING
+
+if TYPE_CHECKING:
+    from .config import DhwCfg, HeatingCfg
+
+__all__ = ["Dhw", "Heating"]
+
+
+class Heating:
+    """
+    Heating circuit: mixing valve, radiators, and a one-node house.
+
+    The mixing valve limits the supply to the flow setpoint; the buffer
+    supplies only the hot share of the circuit flow, the rest is
+    recirculated return water.
+    """
+
+    def __init__(self, cfg: HeatingCfg) -> None:
+        self.cfg = cfg
+        self.t_room = cfg.t_room
+        self.t_supply = cfg.t_room  # sensor value, lagging
+        self.q = 0.0  # radiator output, kW
+
+    def step(
+        self,
+        dt: float,
+        *,
+        on: bool,
+        setpoint: float,
+        t_tap: float,
+        t_air: float,
+        speed: float = 1.0,
+    ) -> tuple[float, float]:
+        """
+        Advance by ``dt``.
+
+        @speed scales the circuit flow (0…1, default 1 = full flow); zero
+        or missing means the pump stands still, which is thermally the
+        same as switching the circuit off.
+
+        Returns ``(m_buffer, t_return)``: the mass drawn from the buffer at
+        ``t_tap`` (kg) and the temperature it is returned at. The energy
+        taken is ``m_buffer * c * (t_tap - t_return)``.
+        """
+        cfg = self.cfg
+        m = 0.0
+        t_ret = t_tap
+        t_s = self.t_room
+        self.q = 0.0
+        flow = cfg.flow * speed if on else 0.0
+        if flow > 0:
+            t_s = min(t_tap, setpoint)
+            fc = kgps(flow) * C_WATER
+            dt_rad = t_s - self.t_room
+            if dt_rad > 0 and fc > 0:
+                q = min(cfg.k_rad * dt_rad**cfg.n_rad, fc * dt_rad)
+                t_ret = t_s - q / fc
+                if t_tap - t_ret > 0.01:
+                    m = kgps(flow) * dt * (t_s - t_ret) / (t_tap - t_ret)
+                    self.q = m * C_WATER * (t_tap - t_ret) / dt
+
+        self.t_room, _, _ = tank(self.t_room, cfg.cap_house, 0, 0, cfg.ua_house, t_air, self.q, dt)
+        a = math.exp(-dt / cfg.sensor_tau)
+        self.t_supply = t_s + (self.t_supply - t_s) * a
+        return m, t_ret
+
+
+class Dhw:
+    """
+    Fresh-water station: domestic hot water is heated from the buffer top.
+
+    Draws are scheduled events. If the buffer top is too cold, the tap
+    temperature drops accordingly.
+    """
+
+    def __init__(self, cfg: DhwCfg) -> None:
+        self.cfg = cfg
+        self.events: list[tuple[float, float, float]] = []  # start, end, l/min
+        self.lpm = 0.0
+        self.t_tap = cfg.t_cold
+
+    def add(self, start: float, duration: float, lpm: float) -> None:
+        """Schedule a draw."""
+        self.events.append((start, start + duration, lpm))
+        self.events.sort()
+
+    def add_daily(self, day_start: float, day_offset: float) -> None:
+        """Schedule the configured daily draws for the day starting at ``day_start``."""
+        for hour, dur, lpm in self.cfg.daily:
+            self.add(day_start + hour * 3600 - day_offset, dur, lpm)
+
+    def demand(self, now: float) -> float:
+        """Current draw, l/min."""
+        while self.events and self.events[0][1] <= now:
+            self.events.pop(0)
+        return sum(lpm for s, e, lpm in self.events if s <= now < e)
+
+    def step(self, dt: float, now: float, t_top: float) -> tuple[float, float]:
+        """
+        Advance by ``dt``.
+
+        Returns ``(m_buffer, t_return)`` like :meth:`Heating.step`.
+        """
+        cfg = self.cfg
+        self.lpm = lpm = self.demand(now)
+        if not lpm:
+            self.t_tap = cfg.t_cold
+            return 0.0, t_top
+        t_ret = cfg.t_cold + cfg.approach
+        t_tap = max(cfg.t_cold, min(cfg.t_hot, t_top - cfg.min_delta))
+        if t_top <= t_ret:
+            self.t_tap = cfg.t_cold
+            return 0.0, t_top
+        q = kgps(lpm) * C_WATER * (t_tap - cfg.t_cold)
+        m = q * dt / (C_WATER * (t_top - t_ret))
+        m_max = kgps(cfg.primary_max) * dt
+        if m > m_max:
+            m = m_max
+            t_tap = cfg.t_cold + m * (t_top - t_ret) / (kgps(lpm) * dt)
+        self.t_tap = t_tap
+        return m, t_ret

moat/dev/heat/sim/config.py

@@ -0,0 +1,265 @@
+"""
+Configuration of the plant simulator.
+
+Units throughout: °C, l/min (flows), kW (power), kJ (energy), kW/K
+(conductances), kJ/K (heat capacities), seconds.
+
+The defaults describe a plausible SolvisMax buffer with a SolvisLea air
+heat pump and a KWB pellet burner; they are not measured values.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, field, fields, is_dataclass
+
+from typing import Any, Self
+
+__all__ = [
+    "BufferCfg",
+    "DhwCfg",
+    "HeatPumpCfg",
+    "HeatingCfg",
+    "PelletCfg",
+    "PelletCodes",
+    "PlantCfg",
+    "PumpCfg",
+    "SensorCfg",
+    "SwitchCfg",
+    "WeatherCfg",
+]
+
+
+class _Cfg:
+    """Mixin: build a (nested) config dataclass from a dict."""
+
+    @classmethod
+    def from_dict(cls, data: dict[str, Any] | None = None) -> Self:
+        """Build an instance, recursing into nested config classes."""
+        if not data:
+            return cls()
+        assert is_dataclass(cls)
+        kw = {}
+        ftypes = {f.name: f for f in fields(cls)}
+        for k, v in data.items():
+            if k not in ftypes:
+                raise KeyError(f"{cls.__name__}: unknown key {k!r}")
+            dflt = getattr(cls(), k)
+            if is_dataclass(dflt) and isinstance(v, dict):
+                kw[k] = type(dflt).from_dict(v)
+            else:
+                kw[k] = v
+        return cls(**kw)
+
+
+@dataclass
+class BufferCfg(_Cfg):
+    """Stratified buffer tank. Heights are fractions from the top (0) to the bottom (1)."""
+
+    volume: float = 900
+    layers: int = 12
+    ua: float = 0.003  # total loss to the room
+    k_cond: float = 0.004  # conduction between adjacent layers
+    t_amb: float = 15
+    t_init: tuple[float, float] = (55, 25)  # top, bottom; linear in between
+
+    tap_water: float = 0.03  # tb_water
+    tap_heat: float = 0.35  # tb_heat
+    tap_mid: float = 0.55  # tb_mid
+    tap_low: float = 0.95  # tb_low (return)
+
+    hp_in_water: float = 0.0  # heat pump supply while the switchover valve is set
+    hp_in_heat: float = 0.35  # heat pump supply otherwise
+    hp_out: float = 1.0  # heat pump return
+    pellet_in: float = 0.0
+    pellet_out: float = 1.0
+    heat_out: float = 0.35  # heating circuit supply
+    heat_in: float = 1.0  # heating circuit return
+    dhw_out: float = 0.0  # fresh-water station primary supply
+    dhw_in: float = 1.0
+
+
+@dataclass
+class HeatPumpCfg(_Cfg):
+    """Air/water heat pump."""
+
+    p_nom: float = 12  # thermal output at full speed, t_air = t_ref
+    t_ref: float = 7
+    p_slope: float = 0.025  # relative Pmax change per K of air temperature
+    eta: float = 0.45  # fraction of Carnot COP
+    cop_min: float = 1.5
+    cop_max: float = 8
+    lift_hot: float = 3  # condenser above t_out
+    lift_cold: float = 5  # evaporator below t_air
+
+    mode_off: int = 0  # cmd.mode value meaning "off"
+    min_load: float = 0.04  # commanded load below this means "off"
+    min_mod: float = 0.35  # minimum compressor speed while running
+    start_speed: float = 0.6  # speed during the start program
+    warmup: float = 300
+    ramp: float = 0.01  # speed change per second
+    start_delay: float = 60  # after mode on, before the compressor starts
+
+    aux: float = 0.15  # electrical draw of fan/controls while running
+    standby: float = 0.01
+
+    # The pipes between buffer and heat pump are long and insulated; each is
+    # a chain of mixed segments, which gives them some transport latency.
+    # Capacities include the pipe itself.
+    cap_pipe: float = 30  # supply pipe, buffer → heat pump; t_in at its end
+    ua_pipe: float = 0.006
+    n_pipe: int = 10
+    cap_ret: float = 30  # return pipe, heat pump → buffer
+    ua_ret: float = 0.006
+    n_ret: int = 10
+    outdoor: float = 0.5  # fraction of each pipe that is outside; the rest is at t_room
+    t_room: float = 15
+    cap_hx: float = 17  # condenser (t_out sensor)
+    ua_hx: float = 0.002
+    k_bleed: float = 0.03  # conduction between the t_in and t_out ends inside the unit
+
+    trip_out: float = 65  # t_out over-temperature trip
+    trip_in: float = 58  # t_in over-temperature trip
+    trip_reset: float = 5  # must cool this far below the trip point to reset
+    trip_code_out: int = 1101
+    trip_code_in: int = 1102
+    trip_path: str = "trip"  # error subpath for trips
+
+    ice_t_max: float = 6  # no icing above this air temperature
+    ice_t_span: float = 4  # full icing rate this far below ice_t_max
+    ice_rh_min: float = 0.6  # no icing below this relative humidity
+    ice_time: float = 2700  # s at full speed and worst conditions until de-icing
+    deice_time: float = 240
+    deice_power: float = 4  # heat taken from the water while de-icing
+    deice_el: float = 1.0
+
+
+@dataclass
+class PumpCfg(_Cfg):
+    """Heat-pump circulation pump, PWM controlled."""
+
+    flow_max: float = 30
+    dead: float = 0.05  # PWM dead zone (the frost task pulses at 1/16, "more than 5%")
+    exp: float = 0.8  # flow = flow_max * ((pwm-dead)/(1-dead)) ** exp
+    flow_min: float = 2  # minimum flow once the pump runs
+    residual: float = 0.6  # flow with the pump off and the loop valve open
+    tau: float = 3  # first-order lag
+
+
+@dataclass
+class HeatingCfg(_Cfg):
+    """Heating circuit with a mixing valve, radiators, and the house."""
+
+    flow: float = 15
+    k_rad: float = 0.08  # radiator output = k_rad * (t_supply - t_room) ** n_rad
+    n_rad: float = 1.3
+    ua_house: float = 0.25
+    cap_house: float = 20000
+    t_room: float = 20.5
+    sensor_tau: float = 120  # lag of the supply temperature sensor
+    off_codes: tuple[int, ...] = (5,)  # setting.heat.mode values meaning "off"
+
+
+@dataclass
+class DhwCfg(_Cfg):
+    """Fresh-water station (domestic hot water)."""
+
+    t_hot: float = 45
+    t_cold: float = 10
+    approach: float = 5  # primary return is this much above t_cold
+    min_delta: float = 2  # buffer top must exceed the tap temperature by this
+    primary_max: float = 30
+    daily: tuple[tuple[float, float, float], ...] = ()  # (hour, duration s, l/min)
+
+
+@dataclass
+class PelletCodes(_Cfg):
+    """KWB state codes as interpreted by the legacy controller."""
+
+    off: int = 0
+    prepare: int = 11
+    ignite: int = 2
+    run: int = 4
+    standby: int = 30
+    burnout: int = 31
+    afterrun: int = 32
+    fault: int = 44
+
+
+@dataclass
+class PelletCfg(_Cfg):
+    """Pellet burner (KWB) with its own boiler water and charging pump."""
+
+    p_nom: float = 15
+    min_mod: float = 0.3
+    ramp: float = 0.05  # kW per second
+    cap: float = 400
+    ua: float = 0.02
+    t_amb: float = 15
+    t_init: float = 20
+    flow: float = 20  # charging pump; must carry p_nom at the boiler goal
+    pump_on: float = 65  # default charging-pump start temperature
+    pump_hyst: float = 3
+    pump_min_delta: float = 2  # boiler must be this much warmer than the return
+
+    t_prepare: float = 120
+    t_ignite: float = 480
+    ignite_retries: int = 1
+    t_burnout: float = 600
+    t_afterrun: float = 300
+    hyst_off: float = 5  # burn out when this far above the goal temperature
+    hyst_on: float = 10  # restart from standby when this far below
+
+    codes: PelletCodes = field(default_factory=PelletCodes)
+
+
+@dataclass
+class WeatherCfg(_Cfg):
+    """Outside air. Daily sine plus seeded AR(1) noise, or a breakpoint profile."""
+
+    mean: float = 2
+    amp: float = 4
+    t_min_hour: float = 5
+    rh_mean: float = 0.8
+    rh_amp: float = 0.1  # humidity peaks when it's coldest
+    sigma: float = 0.5
+    tau: float = 3600
+    # (seconds, temperature) breakpoints; replaces the sine when set
+    profile: tuple[tuple[float, float], ...] | None = None
+    forecast_horizon: float = 6 * 3600
+    forecast_step: float = 900
+
+
+@dataclass
+class SwitchCfg(_Cfg):
+    """Automatic switchover valve (Solvis side): heat pump charges the water section."""
+
+    hyst_on: float = 2  # on when tb_water < water_setpoint - hyst_on
+    hyst_off: float = 2  # off when tb_water >= water_setpoint + hyst_off
+
+
+@dataclass
+class SensorCfg(_Cfg):
+    """Sensor imperfections."""
+
+    noise: float = 0.05  # σ of temperature noise
+    tau_pipe: float = 60  # lag of the t_in / t_out thermometers (in wells)
+    res_temp: float = 0.1
+    res_flow: float = 0.1
+    res_power: float = 0.01
+
+
+@dataclass
+class PlantCfg(_Cfg):
+    """The whole plant."""
+
+    buffer: BufferCfg = field(default_factory=BufferCfg)
+    heat_pump: HeatPumpCfg = field(default_factory=HeatPumpCfg)
+    pump: PumpCfg = field(default_factory=PumpCfg)
+    heating: HeatingCfg = field(default_factory=HeatingCfg)
+    dhw: DhwCfg = field(default_factory=DhwCfg)
+    pellet: PelletCfg = field(default_factory=PelletCfg)
+    weather: WeatherCfg = field(default_factory=WeatherCfg)
+    switch: SwitchCfg = field(default_factory=SwitchCfg)
+    sensor: SensorCfg = field(default_factory=SensorCfg)
+    max_dt: float = 10  # internal step limit
+    day_offset: float = 0  # seconds from local midnight at t=0