pyghe 0.1.0__tar.gz

pyghe-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Philippe Pasquier
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

pyghe-0.1.0/PKG-INFO

@@ -0,0 +1,154 @@
+Metadata-Version: 2.4
+Name: pyghe
+Version: 0.1.0
+Summary: Python interface to the simulation kernel of GHE Analysis: ground heat exchangers, g-functions, borehole resistance, sizing
+Author: Philippe Pasquier
+License-Expression: MIT
+Project-URL: Homepage, https://www.gheanalysis.com
+Project-URL: Documentation, https://pyghe.readthedocs.io
+Project-URL: Repository, https://github.com/ppasquier/pyghe
+Project-URL: Issues, https://github.com/ppasquier/pyghe/issues
+Project-URL: Changelog, https://pyghe.readthedocs.io/en/latest/changelog.html
+Keywords: geothermal,ground heat exchanger,borehole,g-function,heat pump,simulation,thermal plume,groundwater flow
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Science/Research
+Classifier: Programming Language :: Python :: 3
+Classifier: Topic :: Scientific/Engineering
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: numpy>=1.24
+Provides-Extra: pandas
+Requires-Dist: pandas>=2; extra == "pandas"
+Provides-Extra: notebooks
+Requires-Dist: matplotlib>=3.8; extra == "notebooks"
+Requires-Dist: pandas>=2; extra == "notebooks"
+Requires-Dist: jupyterlab>=4; extra == "notebooks"
+Provides-Extra: docs
+Requires-Dist: sphinx>=7; extra == "docs"
+Requires-Dist: myst-nb>=1.1; extra == "docs"
+Requires-Dist: numpydoc>=1.7; extra == "docs"
+Requires-Dist: sphinx-rtd-theme>=2; extra == "docs"
+Provides-Extra: test
+Requires-Dist: pytest>=7; extra == "test"
+Requires-Dist: pandas>=2; extra == "test"
+Requires-Dist: matplotlib>=3.8; extra == "test"
+Requires-Dist: nbformat>=5; extra == "test"
+Requires-Dist: nbclient>=0.9; extra == "test"
+Requires-Dist: ipykernel>=6; extra == "test"
+Dynamic: license-file
+
+# pyghe
+
+[GHE Analysis](https://www.gheanalysis.com/pages/ghe-analysis) is a desktop application for the
+design and simulation of ground heat exchangers. pyghe runs its kernel from Python: borehole
+resistance, g-functions, hourly entering fluid temperatures and the length a borehole field needs.
+It is the same code as the application, so a script and the interface give the same answer.
+
+```python skip
+import pyghe as ga
+
+p = ga.Project.load("my_project.ghe")        # a .ghe file, or a Project built in Python
+p.ground_heat_exchanger.active_length = 180
+result = p.simulate()
+print(result.eft.min())                       # entering fluid temperature, °C
+```
+
+## Installing
+
+```console
+pip install pyghe
+```
+
+You need Python 3.10 or later, numpy, and a Large or Academic licence of Analysis Suite.
+[Installation](docs/install.md) explains how pyghe finds the executable and how to check that
+everything is in place.
+
+## Quick start
+
+Two heat pumps on four boreholes and a building that heats in winter and cools in summer. The
+script prints the coldest fluid temperature the heat pumps see over 25 years:
+
+```python
+import numpy as np
+import pyghe as ga
+
+p = ga.Project()
+p.simulation_duration = 25
+p.building_loads = ga.HourlyBuildingLoadsCombined(
+    combined_demand=30 * np.cos(2 * np.pi * np.arange(8760) / 8760))      # kW, heating +
+p.gshp_system.system_type = "Water-water (zone)"
+p.gshp_system.number_of_heat_pumps = 2
+p.gshp_system.flow_rate_of_pump_a = ga.ByMode(heating=120, cooling=120)  # L/min
+p.heat_pump_performance.temperature_limit = ga.ByMode(heating=0.0, cooling=30.0)  # °C
+p.heat_pump_performance.performance_data = ga.PerformanceConstant(
+    cooling_cap=20, cooling_cop=4.5, heating_cap=15, heating_cop=3.5)
+p.heat_carrier_fluid = ga.HeatCarrierFluid("Propylene glycol", antifreeze_mass_concentration=25)
+p.borehole_resistance = ga.SingleULoop(
+    borehole_diameter=0.152, grout_thermal_conductivity=1.25, shank_spacing=0.1,
+    pipe_inner_diameter=0.033, pipe_outer_diameter=0.044, pipe_thermal_conductivity=0.39)
+g = p.ground_heat_exchanger
+g.ground_thermal_conductivity, g.ground_volumetric_capacity = 2.5, 2.2
+g.mean_surface_temperature, g.geothermal_heat_flux = 10.0, 60
+g.active_length, g.burial_depth = 150, 2
+g.coordinates = ga.Coordinates.rectangle(nx=2, ny=2, spacing=6.0)
+
+print(p.simulate().eft.min())                     # °C
+```
+
+The nodes are filled in the order of the project tree: loads, heat pumps, fluid, borehole, ground.
+A project saved from a script opens in the application, which recomputes it and shows what a
+script leaves aside. [Getting started](docs/getting-started.md) builds a larger example step by
+step.
+
+## Documentation
+
+The documentation starts at [docs/index.md](docs/index.md). To build it as HTML:
+
+```console
+pip install -e .[docs]
+python -m sphinx -b html docs docs/_build/html
+```
+
+## Citing
+
+pyghe is GHE Analysis driven from Python, so please cite the application.
+
+> Pasquier, P. (2025). *GHE Analysis – Interactive simulation of ground heat exchangers*. P³
+> Geothermal inc. <https://doi.org/10.5281/zenodo.15660526>
+
+[Citing](docs/citing.md) and [Methods](docs/methods.md) list the papers behind each method.
+
+## Contact
+
+Bug reports and suggestions are welcome as [issues on GitHub](https://github.com/ppasquier/pyghe/issues), or through
+[www.gheanalysis.com](https://www.gheanalysis.com).
+
+## Working on the package
+
+```console
+git clone https://github.com/ppasquier/pyghe
+cd pyghe
+python -m venv .venv
+.venv/Scripts/python -m pip install -e .[test,docs]
+set PYGHE_CLI=C:\...\AnalysisSuite-cli.exe
+.venv/Scripts/python -m pytest -q
+```
+
+The executable is the one of the [download page](https://www.gheanalysis.com/pages/download), unpacked as
+[Installation](docs/install.md) describes. Without `PYGHE_CLI` or the executable where pyghe looks for
+it, the tests that run it are skipped. They need a Large or Academic licence
+activated on the computer.
+
+I test the documentation like the code: `tests/test_docs.py` runs every code block of this page
+and of `docs/` against the executable, so an example that stops working fails the build. A block
+fenced `python skip` is shown without being run. `tests/test_notebooks.py` checks the committed
+outputs of the notebooks; setting `PYGHE_TEST_NOTEBOOKS=1` also runs them afresh, which takes
+about a minute.
+
+[CONTRIBUTING.md](CONTRIBUTING.md) says how to propose a change.
+
+## Licence
+
+pyghe is released under the MIT licence ([LICENSE](LICENSE)). It needs `AnalysisSuite-cli`, which is
+distributed with GHE Analysis under its own licence terms.

pyghe-0.1.0/README.md

@@ -0,0 +1,114 @@
+# pyghe
+
+[GHE Analysis](https://www.gheanalysis.com/pages/ghe-analysis) is a desktop application for the
+design and simulation of ground heat exchangers. pyghe runs its kernel from Python: borehole
+resistance, g-functions, hourly entering fluid temperatures and the length a borehole field needs.
+It is the same code as the application, so a script and the interface give the same answer.
+
+```python skip
+import pyghe as ga
+
+p = ga.Project.load("my_project.ghe")        # a .ghe file, or a Project built in Python
+p.ground_heat_exchanger.active_length = 180
+result = p.simulate()
+print(result.eft.min())                       # entering fluid temperature, °C
+```
+
+## Installing
+
+```console
+pip install pyghe
+```
+
+You need Python 3.10 or later, numpy, and a Large or Academic licence of Analysis Suite.
+[Installation](docs/install.md) explains how pyghe finds the executable and how to check that
+everything is in place.
+
+## Quick start
+
+Two heat pumps on four boreholes and a building that heats in winter and cools in summer. The
+script prints the coldest fluid temperature the heat pumps see over 25 years:
+
+```python
+import numpy as np
+import pyghe as ga
+
+p = ga.Project()
+p.simulation_duration = 25
+p.building_loads = ga.HourlyBuildingLoadsCombined(
+    combined_demand=30 * np.cos(2 * np.pi * np.arange(8760) / 8760))      # kW, heating +
+p.gshp_system.system_type = "Water-water (zone)"
+p.gshp_system.number_of_heat_pumps = 2
+p.gshp_system.flow_rate_of_pump_a = ga.ByMode(heating=120, cooling=120)  # L/min
+p.heat_pump_performance.temperature_limit = ga.ByMode(heating=0.0, cooling=30.0)  # °C
+p.heat_pump_performance.performance_data = ga.PerformanceConstant(
+    cooling_cap=20, cooling_cop=4.5, heating_cap=15, heating_cop=3.5)
+p.heat_carrier_fluid = ga.HeatCarrierFluid("Propylene glycol", antifreeze_mass_concentration=25)
+p.borehole_resistance = ga.SingleULoop(
+    borehole_diameter=0.152, grout_thermal_conductivity=1.25, shank_spacing=0.1,
+    pipe_inner_diameter=0.033, pipe_outer_diameter=0.044, pipe_thermal_conductivity=0.39)
+g = p.ground_heat_exchanger
+g.ground_thermal_conductivity, g.ground_volumetric_capacity = 2.5, 2.2
+g.mean_surface_temperature, g.geothermal_heat_flux = 10.0, 60
+g.active_length, g.burial_depth = 150, 2
+g.coordinates = ga.Coordinates.rectangle(nx=2, ny=2, spacing=6.0)
+
+print(p.simulate().eft.min())                     # °C
+```
+
+The nodes are filled in the order of the project tree: loads, heat pumps, fluid, borehole, ground.
+A project saved from a script opens in the application, which recomputes it and shows what a
+script leaves aside. [Getting started](docs/getting-started.md) builds a larger example step by
+step.
+
+## Documentation
+
+The documentation starts at [docs/index.md](docs/index.md). To build it as HTML:
+
+```console
+pip install -e .[docs]
+python -m sphinx -b html docs docs/_build/html
+```
+
+## Citing
+
+pyghe is GHE Analysis driven from Python, so please cite the application.
+
+> Pasquier, P. (2025). *GHE Analysis – Interactive simulation of ground heat exchangers*. P³
+> Geothermal inc. <https://doi.org/10.5281/zenodo.15660526>
+
+[Citing](docs/citing.md) and [Methods](docs/methods.md) list the papers behind each method.
+
+## Contact
+
+Bug reports and suggestions are welcome as [issues on GitHub](https://github.com/ppasquier/pyghe/issues), or through
+[www.gheanalysis.com](https://www.gheanalysis.com).
+
+## Working on the package
+
+```console
+git clone https://github.com/ppasquier/pyghe
+cd pyghe
+python -m venv .venv
+.venv/Scripts/python -m pip install -e .[test,docs]
+set PYGHE_CLI=C:\...\AnalysisSuite-cli.exe
+.venv/Scripts/python -m pytest -q
+```
+
+The executable is the one of the [download page](https://www.gheanalysis.com/pages/download), unpacked as
+[Installation](docs/install.md) describes. Without `PYGHE_CLI` or the executable where pyghe looks for
+it, the tests that run it are skipped. They need a Large or Academic licence
+activated on the computer.
+
+I test the documentation like the code: `tests/test_docs.py` runs every code block of this page
+and of `docs/` against the executable, so an example that stops working fails the build. A block
+fenced `python skip` is shown without being run. `tests/test_notebooks.py` checks the committed
+outputs of the notebooks; setting `PYGHE_TEST_NOTEBOOKS=1` also runs them afresh, which takes
+about a minute.
+
+[CONTRIBUTING.md](CONTRIBUTING.md) says how to propose a change.
+
+## Licence
+
+pyghe is released under the MIT licence ([LICENSE](LICENSE)). It needs `AnalysisSuite-cli`, which is
+distributed with GHE Analysis under its own licence terms.

pyghe-0.1.0/pyproject.toml

@@ -0,0 +1,40 @@
+[build-system]
+requires = ["setuptools>=77"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "pyghe"
+version = "0.1.0"
+description = "Python interface to the simulation kernel of GHE Analysis: ground heat exchangers, g-functions, borehole resistance, sizing"
+readme = "README.md"
+requires-python = ">=3.10"
+dependencies = ["numpy>=1.24"]
+authors = [{ name = "Philippe Pasquier" }]
+license = "MIT"
+license-files = ["LICENSE"]
+keywords = ["geothermal", "ground heat exchanger", "borehole", "g-function", "heat pump", "simulation", "thermal plume", "groundwater flow"]
+classifiers = [
+    "Development Status :: 3 - Alpha",
+    "Intended Audience :: Science/Research",
+    "Programming Language :: Python :: 3",
+    "Topic :: Scientific/Engineering",
+]
+
+[project.urls]
+Homepage = "https://www.gheanalysis.com"
+Documentation = "https://pyghe.readthedocs.io"
+Repository = "https://github.com/ppasquier/pyghe"
+Issues = "https://github.com/ppasquier/pyghe/issues"
+Changelog = "https://pyghe.readthedocs.io/en/latest/changelog.html"
+
+[project.optional-dependencies]
+pandas = ["pandas>=2"]
+notebooks = ["matplotlib>=3.8", "pandas>=2", "jupyterlab>=4"]
+docs = ["sphinx>=7", "myst-nb>=1.1", "numpydoc>=1.7", "sphinx-rtd-theme>=2"]
+test = ["pytest>=7", "pandas>=2", "matplotlib>=3.8", "nbformat>=5", "nbclient>=0.9", "ipykernel>=6"]
+
+[tool.setuptools.packages.find]
+where = ["src"]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]

pyghe-0.1.0/setup.cfg

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

pyghe-0.1.0/src/pyghe/__init__.py

@@ -0,0 +1,46 @@
+"""Python interface to the GHE module of Analysis Suite.
+
+    import pyghe as ga
+    p = ga.Project()
+    p.ground_heat_exchanger.ground_thermal_conductivity = 2.5
+    ...
+    result = p.simulate()
+
+Names and units follow the interface of GHE Analysis (SI): each attribute of a Project is a
+node of the Analysis Tree. Every number is computed by the application's kernel through
+AnalysisSuite-cli.
+"""
+
+from ._base import ByMode
+from ._case import DEFAULT_SERIES, SERIES
+from ._cli import close_servers, configure, find_cli
+from .batch import run_many, sweep
+from .borehole_resistance import Coaxial, DoubleULoopA, DoubleULoopD, SingleULoop, StandingColumn
+from .building_loads import (HourlyBuildingLoadsCombined, HourlyBuildingLoadsSeparate, HourlyGroundLoadsCombined,
+                             MonthlyBuildingLoadsSeparate)
+from .errors import (CliError, CliNotFoundError, ConvergenceWarning, PygheError, InvalidInputError,
+                     KernelError, KernelWarning, LicenseError, NotConvergedError, OutsideInterfaceWarning,
+                     SeriesNotRequested)
+from .ground_heat_exchanger import Coordinates, GroundHeatExchanger
+from .gshp_system import SYSTEM_TYPES, GSHPSystem
+from .heat_carrier_fluid import FLUIDS, HeatCarrierFluid
+from .heat_pump_performance import HeatPumpPerformance, ManufacturerData, PerformanceConstant, PerformanceTemperature
+from .project import PLUME_READINGS, Project, ProjectDescription, SizingTool, fluid_properties
+from .results import (BoreholeResistanceResult, FluidProperties, GFunctionResult, Result, SimulationResult,
+                      SizingResult, ThermalPlume2DResult, ThermalPlume3DResult, load_result)
+
+__version__ = "0.1.0"
+
+__all__ = [
+    "BoreholeResistanceResult", "ByMode", "CliError", "CliNotFoundError", "Coaxial",
+    "ConvergenceWarning", "Coordinates", "DEFAULT_SERIES", "DoubleULoopA", "DoubleULoopD",
+    "FLUIDS", "FluidProperties", "GFunctionResult", "GSHPSystem", "PygheError",
+    "GroundHeatExchanger", "HeatCarrierFluid", "HeatPumpPerformance",
+    "HourlyBuildingLoadsCombined", "HourlyBuildingLoadsSeparate", "HourlyGroundLoadsCombined",
+    "InvalidInputError", "KernelError", "KernelWarning", "LicenseError", "ManufacturerData",
+    "MonthlyBuildingLoadsSeparate", "NotConvergedError", "OutsideInterfaceWarning", "PLUME_READINGS",
+    "PerformanceConstant", "PerformanceTemperature", "Project", "ProjectDescription", "Result", "SERIES", "SYSTEM_TYPES",
+    "SeriesNotRequested", "SimulationResult", "SingleULoop", "SizingResult", "SizingTool",
+    "StandingColumn", "ThermalPlume2DResult", "ThermalPlume3DResult", "close_servers", "configure",
+    "find_cli", "fluid_properties", "load_result", "run_many", "sweep",
+]

pyghe-0.1.0/src/pyghe/_base.py

@@ -0,0 +1,278 @@
+"""Common machinery of the project's nodes: slots, validation on assignment, units, repr."""
+
+import dataclasses
+import math
+
+import numpy as np
+
+from .errors import InvalidInputError
+
+HOURS_PER_YEAR = 8760
+
+
+def param(unit="", check=None, default=None, factory=None, symbol=""):
+    """A node field: its unit and symbol as the interface shows them (both printed by repr)
+    and the check run on every assignment. None always means 'not set' and is never checked."""
+    meta = {"unit": unit, "check": check, "symbol": symbol}
+    if factory is not None:
+        return dataclasses.field(default_factory=factory, metadata=meta)
+    return dataclasses.field(default=default, metadata=meta)
+
+
+def private():
+    """A field the user does not set: not a constructor argument, not compared, not printed."""
+    return dataclasses.field(default=None, init=False, metadata={"private": True})
+
+
+def _public(obj):
+    return [f for f in dataclasses.fields(obj) if not f.metadata.get("private")]
+
+
+_checks_cache = {}
+
+
+def _checks_of(cls):
+    checks = _checks_cache.get(cls)
+    if checks is None:
+        checks = {f.name: f.metadata.get("check") for f in dataclasses.fields(cls)}
+        _checks_cache[cls] = checks
+    return checks
+
+
+class Node:
+    """Base of every node. Subclasses are dataclasses with slots, so that assigning a
+    misspelt attribute raises AttributeError instead of creating a new field."""
+
+    __slots__ = ()
+
+    def __setattr__(self, name, value):
+        check = _checks_of(type(self)).get(name)
+        if check is not None and value is not None:
+            value = check(value, f"{type(self).__name__}.{name}")
+        object.__setattr__(self, name, value)
+
+    def __eq__(self, other):
+        if type(other) is not type(self):
+            return NotImplemented
+        for f in _public(self):
+            a, b = getattr(self, f.name), getattr(other, f.name)
+            if isinstance(a, np.ndarray) or isinstance(b, np.ndarray):
+                if a is None or b is None or not np.array_equal(a, b, equal_nan=True):
+                    return False
+            elif a != b:
+                return False
+        return True
+
+    __hash__ = None
+
+    def __repr__(self):
+        return "\n".join(self._describe())
+
+    def _describe(self, indent=""):
+        lines = [f"{indent}{type(self).__name__}"]
+        for f in _public(self):
+            value = getattr(self, f.name)
+            symbol = f.metadata.get("symbol", "")
+            name = f"{f.name} ({symbol})" if symbol else f.name
+            if isinstance(value, Node):
+                sub = value._describe(indent + "    ")
+                lines.append(f"{indent}  {name}: {sub[0].strip()}")
+                lines.extend(sub[1:])
+            elif isinstance(value, ByMode):
+                lines.append(f"{indent}  {name} = {value!r}")
+            else:
+                lines.append(f"{indent}  {name} = {_show(value, f.metadata.get('unit', ''))}")
+        return lines
+
+
+def _show(value, unit):
+    if value is None:
+        return "(not set)"
+    if isinstance(value, np.ndarray):
+        if value.size == 0:
+            text = "[] (0 values)"
+        else:
+            text = f"[{value.min():.6g} … {value.max():.6g}] ({value.size} values)"
+    else:
+        text = repr(value)
+    return f"{text} {unit}".rstrip()
+
+
+# Checks. Each returns the value to store, converted, or raises InvalidInputError naming the
+# attribute. Those taking settings are classes, not closures: a ByMode keeps its check, and
+# pickle (multiprocessing, joblib) refuses local functions.
+
+def real(value, where):
+    if isinstance(value, bool):
+        raise InvalidInputError(f"{where} must be a number, got {value!r}")
+    try:
+        x = float(value)
+    except (TypeError, ValueError):
+        raise InvalidInputError(f"{where} must be a number, got {value!r}") from None
+    if not math.isfinite(x):
+        raise InvalidInputError(f"{where} must be finite, got {x}")
+    return x
+
+
+def positive(value, where):
+    x = real(value, where)
+    if x <= 0:
+        raise InvalidInputError(f"{where} must be > 0, got {x}")
+    return x
+
+
+def non_negative(value, where):
+    x = real(value, where)
+    if x < 0:
+        raise InvalidInputError(f"{where} must be >= 0, got {x}")
+    return x
+
+
+class between:
+    def __init__(self, low, high, low_open=False, high_open=False):
+        self.low, self.high, self.low_open, self.high_open = low, high, low_open, high_open
+
+    def __call__(self, value, where):
+        x = real(value, where)
+        low, high = self.low, self.high
+        if (x < low or (self.low_open and x == low)) or (x > high or (self.high_open and x == high)):
+            lo = "(" if self.low_open else "["
+            hi = ")" if self.high_open else "]"
+            raise InvalidInputError(f"{where} must lie in {lo}{low}, {high}{hi}, got {x}")
+        return x
+
+
+class integer:
+    def __init__(self, minimum=None, choices=None):
+        self.minimum, self.choices = minimum, choices
+
+    def __call__(self, value, where):
+        if isinstance(value, bool) or not float(real(value, where)).is_integer():
+            raise InvalidInputError(f"{where} must be an integer, got {value!r}")
+        n = int(value)
+        if self.minimum is not None and n < self.minimum:
+            raise InvalidInputError(f"{where} must be >= {self.minimum}, got {n}")
+        if self.choices is not None and n not in self.choices:
+            raise InvalidInputError(f"{where} must be one of {', '.join(map(str, self.choices))}, got {n}")
+        return n
+
+
+class one_of:
+    def __init__(self, *choices):
+        self.choices = choices
+
+    def __call__(self, value, where):
+        if value not in self.choices:
+            raise InvalidInputError(f"{where} must be one of {', '.join(map(repr, self.choices))}, got {value!r}")
+        return value
+
+
+class instance_of:
+    def __init__(self, *classes):
+        self.classes = classes
+
+    def __call__(self, value, where):
+        if not isinstance(value, self.classes):
+            names = " or ".join(c.__name__ for c in self.classes)
+            raise InvalidInputError(f"{where} must be a {names}, got {type(value).__name__}")
+        return value
+
+
+class series:
+    """A read-only float64 array. Reassign the attribute to change it: an array edited in place
+    would bypass the checks."""
+
+    def __init__(self, length=None, minimum_length=1, allow_nan=False):
+        self.length, self.minimum_length, self.allow_nan = length, minimum_length, allow_nan
+
+    def __call__(self, value, where):
+        try:
+            a = np.array(value, dtype=np.float64, copy=True)
+        except (TypeError, ValueError):
+            raise InvalidInputError(f"{where} must be an array of numbers") from None
+        if a.ndim != 1:
+            raise InvalidInputError(f"{where} must be one-dimensional, got shape {a.shape}")
+        if self.length is not None and a.size != self.length:
+            raise InvalidInputError(f"{where} must hold {self.length} values, got {a.size}")
+        if a.size < self.minimum_length:
+            raise InvalidInputError(f"{where} must hold at least {self.minimum_length} value(s)")
+        bad = ~np.isfinite(a) if not self.allow_nan else np.isinf(a)
+        if bad.any():
+            raise InvalidInputError(f"{where}[{int(np.argmax(bad))}] is not finite")
+        a.setflags(write=False)
+        return a
+
+
+def node(dc=None, kw_only=True):
+    """Decorator: a slotted keyword-only dataclass deriving from Node."""
+    def wrap(cls):
+        return dataclasses.dataclass(slots=True, kw_only=kw_only, repr=False, eq=False)(cls)
+    return wrap(dc) if dc is not None else wrap
+
+
+class ByMode:
+    """A pair of values, one for heating and one for cooling. Assigned to a node, it takes the
+    unit and the check of that attribute, which then apply to each of its two values."""
+
+    __slots__ = ("heating", "cooling", "_check", "_unit", "_where")
+
+    def __init__(self, heating=None, cooling=None):
+        object.__setattr__(self, "_check", None)
+        object.__setattr__(self, "_unit", "")
+        object.__setattr__(self, "_where", "ByMode")
+        self.heating = heating
+        self.cooling = cooling
+
+    def __setattr__(self, name, value):
+        if name in ("heating", "cooling") and value is not None and self._check is not None:
+            value = self._check(value, f"{self._where}.{name}")
+        object.__setattr__(self, name, value)
+
+    def __eq__(self, other):
+        return (isinstance(other, ByMode) and self.heating == other.heating
+                and self.cooling == other.cooling)
+
+    def __deepcopy__(self, memo):
+        twin = ByMode()
+        for name in self.__slots__:
+            object.__setattr__(twin, name, getattr(self, name))
+        return twin
+
+    def __reduce__(self):
+        return _restore_by_mode, tuple(getattr(self, name) for name in self.__slots__)
+
+    def __repr__(self):
+        return (f"ByMode(heating={_show(self.heating, self._unit)}, "
+                f"cooling={_show(self.cooling, self._unit)})")
+
+
+def _restore_by_mode(*values):
+    pair = ByMode()
+    for name, value in zip(ByMode.__slots__, values):
+        object.__setattr__(pair, name, value)
+    return pair
+
+
+class by_mode:
+    """Check of an attribute holding a ByMode. Accepts a ByMode, a (heating, cooling) pair or
+    a dict with those keys; returns a new ByMode bound to check and unit."""
+
+    def __init__(self, check, unit=""):
+        self.check, self.unit = check, unit
+
+    def __call__(self, value, where):
+        if isinstance(value, ByMode):
+            h, c = value.heating, value.cooling
+        elif isinstance(value, dict) and set(value) <= {"heating", "cooling"}:
+            h, c = value.get("heating"), value.get("cooling")
+        elif isinstance(value, (tuple, list)) and len(value) == 2:
+            h, c = value
+        else:
+            raise InvalidInputError(f"{where} must be a ByMode(heating=..., cooling=...)")
+        pair = ByMode()
+        object.__setattr__(pair, "_check", self.check)
+        object.__setattr__(pair, "_unit", self.unit)
+        object.__setattr__(pair, "_where", where)
+        pair.heating = h
+        pair.cooling = c
+        return pair