moat-dev-heat-sim 0.0.1__tar.gz

moat_dev_heat_sim-0.0.1/LICENSE.txt

@@ -0,0 +1,14 @@
+The code in this repository, and all MoaT submodules it refers to,
+is part of the MoaT project.
+
+Unless a submodule's LICENSE.txt states otherwise, all included files are
+licensed under the LGPL V3, as published by the FSF at
+https://www.gnu.org/licenses/lgpl-3.0.html .
+
+In addition to the LGPL's terms, the author(s) respectfully ask all users of
+this code to contribute any bug fixes or enhancements. Also, please link back to
+https://M-o-a-T.org.
+
+Thank you.
+
+Copyright © 2021 ff.: the MoaT contributor(s), as per the git changelog(s).

moat_dev_heat_sim-0.0.1/Makefile

@@ -0,0 +1,14 @@
+#!/usr/bin/make -f
+
+PACKAGE = moat-dev-heat-sim
+MAKEINCL ?= $(shell python3 -mmoat src path)/make/py
+
+ifneq ($(wildcard $(MAKEINCL)),)
+include $(MAKEINCL)
+# availabe via http://github.com/smurfix/sourcemgr
+
+else
+%:
+	@echo "Please fix 'python3 -mmoat src path'."
+	@exit 1
+endif

moat_dev_heat_sim-0.0.1/PKG-INFO

@@ -0,0 +1,64 @@
+Metadata-Version: 2.4
+Name: moat-dev-heat-sim
+Version: 0.0.1
+Summary: Plant simulator and closed-loop test harness for the MoaT heating controller
+Author-email: Matthias Urlichs <matthias@urlichs.de>
+Project-URL: homepage, https://m-o-a-t.org
+Project-URL: repository, https://github.com/M-o-a-T/moat
+Keywords: MoaT
+Classifier: Development Status :: 4 - Beta
+Classifier: Framework :: AnyIO
+Classifier: Framework :: Trio
+Classifier: Framework :: AsyncIO
+Classifier: Programming Language :: Python :: 3
+Classifier: Intended Audience :: Developers
+Requires-Python: >=3.13
+Description-Content-Type: text/markdown
+License-File: LICENSE.txt
+Requires-Dist: anyio~=4.2
+Requires-Dist: asyncclick~=8.3
+Requires-Dist: moat-util~=0.64.8
+Requires-Dist: moat-lib-path~=0.4.1
+Requires-Dist: moat-link~=0.11.4
+Requires-Dist: moat-dev-heat~=1.0.0
+Dynamic: license-file
+
+# Heating simulator
+
+% start synopsis
+% start main
+
+A simulated heating plant for the heat controller (`moat-dev-heat`),
+for tests and dry runs: no part of it is needed to run the heating.
+
+% end synopsis
+
+The plant model (`moat.dev.heat.sim.Plant`) is deterministic (seeded)
+and sans-IO, advanced by `step(dt)`:
+
+- a stratified buffer (N layers, mixing, losses) with sensor taps for
+  `tb_water`, `tb_heat`, `tb_mid`, `tb_low`, and the hot-water section;
+- the heat pump: output = load × Pmax(t_air) with a COP curve,
+  `t_out = t_in + P / (c · flow)`, start delay, minimum load, power
+  draw, compressor speed, de-ice cycles, over-temperature trip, error
+  codes;
+- the circulation pump: flow(PWM) with dead zone and lag;
+- the heating circuit: radiator demand from the outside temperature,
+  valve modes, return temperature; the switchover valve;
+- hot-water draw events;
+- the pellet burner: KWB state-code sequence, ignition time and
+  warm-up, ignition failure, load → power, top temperature;
+- the weather: outside temperature profile and forecast;
+- fault injection: stuck or stale sensors, a dead flow pump.
+
+`moat dev heat sim` publishes the simulator on a MoaT-Link tree (a
+real or a test one) at the paths the pollers use, with a configurable
+time scale, for end-to-end tests and operator dry runs. Scenario files
+set up the plant and schedule events.
+
+The closed-loop runner (`moat.dev.heat.sim.loop.ClosedLoop`) wires the
+plant and the units' cores in-process, in simulated time; traces of its
+runs are compared with stored references (`moat.dev.heat.sim.trace`).
+The heat controller's tests use both.
+
+% end main

moat_dev_heat_sim-0.0.1/README.md

@@ -0,0 +1,39 @@
+# Heating simulator
+
+% start synopsis
+% start main
+
+A simulated heating plant for the heat controller (`moat-dev-heat`),
+for tests and dry runs: no part of it is needed to run the heating.
+
+% end synopsis
+
+The plant model (`moat.dev.heat.sim.Plant`) is deterministic (seeded)
+and sans-IO, advanced by `step(dt)`:
+
+- a stratified buffer (N layers, mixing, losses) with sensor taps for
+  `tb_water`, `tb_heat`, `tb_mid`, `tb_low`, and the hot-water section;
+- the heat pump: output = load × Pmax(t_air) with a COP curve,
+  `t_out = t_in + P / (c · flow)`, start delay, minimum load, power
+  draw, compressor speed, de-ice cycles, over-temperature trip, error
+  codes;
+- the circulation pump: flow(PWM) with dead zone and lag;
+- the heating circuit: radiator demand from the outside temperature,
+  valve modes, return temperature; the switchover valve;
+- hot-water draw events;
+- the pellet burner: KWB state-code sequence, ignition time and
+  warm-up, ignition failure, load → power, top temperature;
+- the weather: outside temperature profile and forecast;
+- fault injection: stuck or stale sensors, a dead flow pump.
+
+`moat dev heat sim` publishes the simulator on a MoaT-Link tree (a
+real or a test one) at the paths the pollers use, with a configurable
+time scale, for end-to-end tests and operator dry runs. Scenario files
+set up the plant and schedule events.
+
+The closed-loop runner (`moat.dev.heat.sim.loop.ClosedLoop`) wires the
+plant and the units' cores in-process, in simulated time; traces of its
+runs are compared with stored references (`moat.dev.heat.sim.trace`).
+The heat controller's tests use both.
+
+% end main

moat_dev_heat_sim-0.0.1/pyproject.toml

@@ -0,0 +1,39 @@
+[build-system]
+build-backend = "setuptools.build_meta"
+requires = ["wheel","setuptools"]
+
+[project]
+classifiers = [
+	"Development Status :: 4 - Beta",
+	"Framework :: AnyIO",
+	"Framework :: Trio",
+	"Framework :: AsyncIO",
+	"Programming Language :: Python :: 3",
+	"Intended Audience :: Developers",
+]
+dependencies = [
+	"anyio ~= 4.2",
+	"asyncclick ~= 8.3",
+	"moat-util ~= 0.64.8",
+	"moat-lib-path ~= 0.4.1",
+	"moat-link ~= 0.11.4",
+	"moat-dev-heat ~= 1.0.0",
+]
+keywords = ["MoaT"]
+requires-python = ">=3.13"
+name = "moat-dev-heat-sim"
+authors = [{email = "matthias@urlichs.de",name = "Matthias Urlichs"}]
+description = "Plant simulator and closed-loop test harness for the MoaT heating controller"
+readme = "README.md"
+version = "0.0.1"
+
+[project.urls]
+homepage = "https://m-o-a-t.org"
+repository = "https://github.com/M-o-a-T/moat"
+
+[tool.setuptools]
+[tool.setuptools.packages.find]
+where = ["src"]
+
+[tool.setuptools.package-data]
+"*" = ["*.yaml"]

moat_dev_heat_sim-0.0.1/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

moat_dev_heat_sim-0.0.1/src/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-0.0.1/src/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-0.0.1/src/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-0.0.1/src/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-0.0.1/src/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