nwp500-python 9.5.1__tar.gz → 9.7.0__tar.gz

{nwp500_python-9.5.1 → nwp500_python-9.7.0}/CHANGELOG.rst

@@ -2,6 +2,65 @@
 Changelog
 =========
 
+Version 9.7.0 (2026-10-21)
+==========================
+
+Added
+-----
+- **Calibrate from Home Assistant's history** (#179), for a heater with
+  no recording of its statuses.
+  ``sim_home_assistant.read_heater_history`` reads the heater's own
+  entities a day at a time: the probes, what is heating, the in-use
+  flag, the stop threshold, the operation mode, the error code, the
+  power, the energy to setpoint and the heater's own air, each number
+  from the unit it was recorded in. An entity that changes on every
+  response (``heard``) says when the heater was observed.
+  ``sim_calibrate.calibrate_changes`` fits on what it read, and gives
+  the same ``Calibrated`` and ``report()`` as ``calibrate``.
+- ``sim_adapters.ChangeRows`` and ``sim_adapters.change_history``: the
+  calibration frame from each value's changes and the instants the
+  heater was heard from, for any store of that history.
+- ``History.states``: every row's state as written, numbers or not.
+  ``HomeAssistantClient.read_history`` fills it (``parse_states``).
+- ``sim_home_assistant.to_w`` and ``to_wh``.
+
+Version 9.6.0 (2026-10-21)
+==========================
+
+Added
+-----
+- **Calibration outside the CLI** (``nwp500.sim_calibrate``, #177).
+  ``calibrate``, ``Calibrated``, ``report``, ``Term`` and ``max_gap``
+  moved here from ``nwp500.cli.calibration`` so an application can
+  calibrate without ``click`` or ``rich``. ``calibrate`` takes
+  ``HeaterParams`` or a parameters document as ``params`` and raises
+  ``CalibrationInputError`` (a ``ValueError``). Its notes no longer name
+  the command's options; ``nwp-cli simulate calibrate`` adds them.
+- ``status_history.iter_read`` yields a recording's statuses one at a
+  time.
+- ``sim_adapters.add_inputs`` adds the air, its humidity, a meter's
+  draws, the circulation's runs and the unobserved gaps to a frame
+  ``sim_adapters.history`` built.
+
+Changed
+-------
+- **A long history calibrates in bounded memory** (#177).
+  ``sim_adapters.history`` reads its statuses one at a time and keeps
+  only the frame's values, and ``sim_calibrate.calibrate`` takes the
+  record's span and gaps from the frame, so a generator over day files
+  is read once. 60 days of statuses (about 540,000) now take about
+  150 MB instead of about 6 GB of parsed statuses. The drawing and
+  circulating columns are computed per span instead of per row and
+  span.
+
+Documentation
+-------------
+- The calibration how-to says the recorder writes every status the
+  heater sends and what that costs on disk, shows calibrating from
+  day files with ``sim_calibrate``, adds calibrating in an
+  application, and says what Home Assistant's 10-day retention means
+  for a longer record.
+
 Version 9.5.1 (2026-10-21)
 ==========================
 

{nwp500_python-9.5.1/src/nwp500_python.egg-info → nwp500_python-9.7.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: nwp500-python
-Version: 9.5.1
+Version: 9.7.0
 Summary: A library for controlling Navien NWP500 Water Heaters via NaviLink
 Home-page: https://github.com/eman/nwp500-python
 Author: Emmanuel Levijarvi

nwp500_python-9.7.0/docs/how-to/calibrate-simulator.rst

@@ -0,0 +1,337 @@
+======================================
+Calibrate the Simulator to Your Heater
+======================================
+
+The simulator's default parameters are one NWP500-65's, fitted at one
+installation. Record what your own heater reports for a few weeks and
+fit its standby loss, its compressor and its power to that record.
+
+.. contents::
+   :local:
+   :depth: 1
+
+
+Record the history
+==================
+
+``nwp-cli simulate record`` appends every status the heater sends to a
+file until you stop it (Ctrl+C): the answers to the status requests it
+makes every 30 seconds (``--every``), and the statuses the heater sends
+between them. One heater sent about 370 an hour, about half of them
+identical to the one before. A line is about 2.3 kB, so a day of
+recording is about 20 MB, or 0.2 MB gzipped. The command needs the
+``cli`` extra and no other:
+
+.. code-block:: bash
+
+   nwp-cli simulate record history.jsonl
+   nwp-cli simulate record history.jsonl --every 60
+
+Each line is one status, as JSON: the instant it arrived and the
+status payload as the heater sent it:
+
+.. code-block:: json
+
+   {"t": "2026-10-18T23:09:10.298+00:00", "status": {"dhwUse": 1, "...": 0}}
+
+Stopping and starting again appends to the same file, so the record
+can have gaps. The heater may have heated or delivered water during a
+gap, so ``calibrate`` takes any spacing between statuses of more than
+4 times the record's usual spacing (and at least 5 minutes) as
+unobserved. No quiet window and no recovery spans such a gap, and the
+report counts them. The identical statuses are what show the heater was
+observed between changes, so keep them.
+
+Write the file any other way you like (an MQTT callback, an export
+from a home-automation recorder) as long as each line has this shape:
+``nwp500.status_history.line(instant, raw_status)`` writes one.
+``status_history.read(lines)`` reads them back as
+``(instant, DeviceStatus)`` pairs, and ``status_history.iter_read(lines)``
+yields them one at a time, for a long recording.
+
+Record through quiet nights and full recoveries. The standby fit needs
+windows of 3 hours or more with no heating and no hot water in use. The
+compressor fit needs at least 5 recoveries that reached their target,
+and holds out the latest fifth once there are 10. The power fits need
+10 compressor cycles.
+
+
+Record the air beside the heater
+================================
+
+The standby loss is the heat the tank loses to the air it stands in,
+so the fit needs that air over the whole record. The heater does not
+read it while idle: its sensor sits at the heat pump's intake, and it
+reads the air the heater stands in only while the evaporator fan runs.
+Idle, it reads the cabinet, about 6 °F warm. So give one of these:
+
+- **A sensor beside the heater:** a CSV file of its readings, an ISO
+  8601 instant with its UTC offset and a temperature in your preferred
+  unit on each row (a header row is skipped):
+
+  .. code-block:: text
+
+     time,temperature
+     2026-10-18T00:00:00-07:00,61.2
+     2026-10-18T00:05:00-07:00,61.0
+
+- **A constant,** for a heater in conditioned space that holds one
+  temperature.
+
+- **Home Assistant:** ``--sources FILE``, the same sources file as
+  ``simulate run`` takes (:doc:`simulate-heater`). The command reads the
+  air beside the heater and its humidity over the record. It also reads
+  the meter's draws and the circulation's runs, which make the quiet
+  test exact: the heater's own "hot water in use" flag also fires on
+  circulation. The air is used only over the span its history covers,
+  and not while its sensor was ``unavailable``; the humidity takes the
+  50 % default outside that span, and the report says how much that
+  is. Home Assistant keeps 10 days of history by default, so of a
+  60-day record only the last 10 days have the air, and the standby
+  loss is fitted from those alone. For the whole record, raise the
+  recorder's ``purge_keep_days`` to cover it before you start
+  recording, or give the air another way (``--air``). Where the
+  meter's or the circulation's history doesn't cover the whole record,
+  the heater's own flag is used instead. ``--air``, ``--ambient`` and
+  ``--humidity`` override the sources.
+
+Without the air, the standby loss keeps the base's value and the report
+says so. When you give the air, the recoveries use it too; without it,
+they use the heater's own reading while the compressor runs.
+
+``--humidity`` takes the same kind of file, in %RH, for the
+evaporator; without it the command gives the fits 50 %.
+
+
+Calibrate
+=========
+
+``nwp-cli simulate calibrate`` needs the ``cli`` and ``sim`` extras. It
+reads the history and prints what each fit found. With ``-o`` it also
+writes the fitted parameters, as a ``HeaterParams`` document:
+
+.. code-block:: bash
+
+   nwp-cli simulate calibrate history.jsonl --air air.csv -o params.json
+   nwp-cli simulate calibrate history.jsonl --ambient 68 -o params.json
+   nwp-cli simulate calibrate history.jsonl --sources sources.toml -o params.json
+   nwp-cli simulate run --params params.json
+
+It refits the 65 gal defaults. For another tank size, start from that
+size's parameters with ``--params``:
+
+.. code-block:: python
+
+   import json
+   from nwp500 import sim
+   from nwp500.sim.params import params_to_document
+
+   with open("base.json", "w") as f:
+       json.dump(params_to_document(sim.default_params(3)), f)  # 80 gal
+
+The report has a row for each term. Each row gives the term's value,
+the evidence it was fitted from and its error, and whether it was
+fitted or kept the base's value, and why:
+
+.. list-table::
+   :header-rows: 1
+   :widths: 30 70
+
+   * - Term
+     - Fitted from
+   * - Standby loss and its exponent
+     - Quiet windows of 3 h or more, starting 45 minutes after any
+       heating or hot water in use. A window counts only if its fit
+       tracks the probes within 2 °F. The exponent is fitted only when
+       the windows span two 20 °F bands of tank-to-air difference; it
+       is held at 0 (a constant loss) otherwise.
+   * - Zone gap time constant
+     - How fast the upper and lower probes' gap closes over quiet
+       windows; it needs 20 windows that open with a gap of 2 °F or
+       more.
+   * - Compressor constant, evaporator approach
+     - Heat-pump recoveries that reached their target, against the loss
+       just fitted. The error is the mean absolute error of the
+       recovery durations, in minutes, also on the held-out recoveries.
+       A fit pinned on a bound is reported and not applied.
+   * - Input power scale, COP scale, start-up energy, COP lift
+     - The heater's own power readings over each compressor cycle,
+       against the compressor just fitted. The COP uses only cycles
+       with no hot water in use from 30 minutes before them to their
+       end.
+
+``Unfitted`` lists every term that kept the base's value. The answers
+those terms reach say so in their ``reasons`` (for example
+``standby_uncalibrated``). The ``book``, ``readiness`` and ``draw``
+terms are always listed, because they are fitted only from a hot-water
+meter's draws, which the command does not take (see below).
+
+
+From Python
+===========
+
+``nwp500.sim_calibrate.calibrate`` does what the command does, and
+``report`` gives the command's rows as ``Term`` values. It takes the
+statuses one at a time, so a recording kept as a file per day can be
+read in order without holding every status:
+
+.. code-block:: python
+
+   from pathlib import Path
+
+   from nwp500 import sim, sim_calibrate, status_history
+
+   def recorded(days):
+       for day in days:
+           with day.open(encoding="utf-8") as f:
+               yield from status_history.iter_read(f)
+
+   done = sim_calibrate.calibrate(
+       recorded(sorted(Path("history").glob("*.jsonl"))),
+       air=air_readings,            # [(instant, temperature), ...]
+       humidity=humidity_readings,  # [(instant, %RH), ...]
+       params=sim.default_params(),  # or your own HeaterParams
+   )
+   params = done.calibration.params
+   for term in sim_calibrate.report(done):
+       print(term.name, term.value, "fitted" if term.fitted else term.why)
+
+Give ``ambient`` instead of ``air`` for a constant, or neither: the
+standby loss then keeps the base's value. Without ``humidity`` the fits
+get 50 %. An input it cannot use raises ``CalibrationInputError``.
+
+On a desktop computer, 60 days of statuses (about 540,000) took about
+40 seconds to read and 10 to fit, in about 150 MB.
+
+Calibrate in an application
+---------------------------
+
+An application that records the heater itself, such as a Home
+Assistant integration, can calibrate the same way:
+
+1. Write each status it receives with ``status_history.line``, a file
+   per UTC day, and keep as many days as the fit should cover.
+2. Read the air beside the heater and its humidity over the same span
+   with ``sim_home_assistant.record_inputs(client, entities, start,
+   end)``, and pass the result as ``record=``. It also brings the
+   meter's draws and the circulation's runs. Any client with the same
+   ``read_history`` as ``HomeAssistantClient`` works. The recorder's
+   retention limits the air, as above.
+3. Call ``sim_calibrate.calibrate`` in a worker thread. It takes the
+   gaps from the statuses' own spacing: a span longer than 4 times
+   their usual spacing, and at least 5 minutes, is unobserved.
+4. Store ``params_to_document(done.calibration.params)``, and show the
+   ``report(done)`` rows and ``done.notes``.
+
+``sim.calibration.calibrate`` underneath takes the frame
+``sim_adapters.history`` builds; ``sim_adapters.add_inputs`` adds the
+air, the humidity, a meter's draws and the circulation's runs to it.
+From there you can also give the draws that price the heat each
+cycle's draws took. The fits for the readiness terms, the heat book,
+the draw response and the elements also run there: see "Improve
+accuracy" and "Fit the elements" in :doc:`simulate-heater`.
+
+
+Calibrate from Home Assistant's history
+=======================================
+
+A heater whose integration writes its values to Home Assistant can be
+calibrated from that history, with no recording of its statuses. Home
+Assistant keeps each entity's changes, and a value that holds writes
+none, so the history also needs an entity that changes every time the
+heater answers, such as the integration's last response time. Its
+changes are when the heater was heard from; a silence between them
+longer than 4 times their usual spacing (and at least 5 minutes) is
+unobserved, as a gap between statuses is.
+
+.. code-block:: python
+
+   from datetime import UTC, datetime, timedelta
+
+   from nwp500 import sim_calibrate
+   from nwp500 import sim_home_assistant as ha
+
+   entities = ha.HeaterEntities(
+       heard="sensor.water_heater_last_mqtt_response",
+       upper="sensor.water_heater_tank_upper_temperature",
+       lower="sensor.water_heater_tank_lower_temperature",
+       compressor="binary_sensor.water_heater_compressor_running",
+       upper_element="binary_sensor.water_heater_upper_element",
+       lower_element="binary_sensor.water_heater_lower_element",
+       heat_source="sensor.water_heater_current_heat_source",
+       dhw_in_use="binary_sensor.water_heater_dhw_in_use",
+       target="sensor.water_heater_hp_lower_off_temperature",
+       operation_mode="sensor.water_heater_current_operation_mode",
+       error_code="sensor.water_heater_error_code",
+       power="sensor.water_heater_current_power",
+       energy_to_setpoint="sensor.water_heater_energy_to_setpoint",
+       ambient="sensor.water_heater_ambient_temperature",
+   )
+   end = datetime.now(UTC)
+   start = end - timedelta(days=60)
+   async with ha.HomeAssistantClient(url, token) as client:
+       history = await ha.read_heater_history(client, entities, start, end)
+       record = await ha.record_inputs(client, ha.Entities(air=..., humidity=...),
+                                       start, end)
+   done = sim_calibrate.calibrate_changes(
+       history.rows, history.observed, record=record, notes=history.notes
+   )
+
+Use your own entity ids. Only ``heard`` and the two probes are needed;
+leave out what your installation does not record. ``read_heater_history``:
+
+- reads a day at a time, so the heartbeat's rows are never all held as
+  Home Assistant gives them;
+- takes each number from the unit it was recorded in (°F, °C or K; W or
+  kW; Wh or kWh), ``on`` and ``off`` from the binary sensors, and the
+  heat source, operation mode and error code by their enum names
+  (``HeatSource``, ``CurrentOperationMode``, ``ErrorCode``);
+- takes ``unavailable`` or ``unknown`` on any of the entities as an
+  outage of the heater, unobserved (an enum's own ``UNKNOWN`` is a
+  value);
+- takes the heat source as the compressor's state where no compressor
+  entity is given;
+- notes a value it could not read, and an entity whose history starts
+  after ``start``.
+
+Give ``anti_legionella`` where it is recorded. Without it an
+anti-legionella cycle is not kept out of the recoveries, and the notes
+say so.
+
+Home Assistant keeps 10 days of history by default, so ``start`` reaches
+back only that far unless the recorder's ``purge_keep_days`` is raised
+to cover the record you want to fit. The same is true of the air.
+
+Rows from another store of the same history (an export, say) go in as
+``sim_adapters.ChangeRows``, each value's changes as ``(instant,
+value)`` pairs, with the instants heard from:
+``sim_calibrate.calibrate_changes(rows, observed, ...)``.
+
+On a desktop computer, 60 days with a heartbeat every 10 seconds
+(about 550,000 rows) took about 13 seconds to read, not counting Home
+Assistant's own queries, and 11 to fit, in about 180 MB.
+
+
+Limitations
+===========
+
+- **The draws.** The heater reports no draw volume, and in recorded
+  statuses its inlet and flow readings read 0. The draw terms
+  (``book``, ``readiness``, ``draw``) need a hot-water meter and an
+  inlet probe.
+- **Circulation the heater does not run.** The quiet test is the
+  heater's own "hot water in use" flag, which also fires on
+  circulation. A loop's heat that does not trip the flag is invisible
+  to the heater and lands in the standby loss. From Python, pass the
+  circulation's runs (``record=`` or ``sa.history(...,
+  circulating=...)``) to keep them out of the quiet windows.
+
+
+See also
+========
+
+* :doc:`simulate-heater`: run the simulator with your parameters
+* :doc:`/reference/python_api/sim`: ``sim_calibrate``,
+  ``sim.calibration``, ``sim_adapters.history``,
+  ``sim_adapters.change_history``, ``status_history`` and
+  ``sim_home_assistant.read_heater_history``

{nwp500_python-9.5.1 → nwp500_python-9.7.0}/docs/reference/python_api/sim.rst

@@ -297,6 +297,11 @@ Recorded history
 .. automodule:: nwp500.status_history
    :members:
 
+.. automodule:: nwp500.sim_calibrate
+   :members: calibrate, calibrate_changes, Calibrated, report, Term, max_gap,
+      CalibrationInputError, DEFAULT_HUMIDITY_PCT, GAP_SAMPLES, MIN_GAP,
+      DEFAULT_BASE_NOTE, NO_AIR_NOTE
+
 
 Home Assistant sources
 ======================
@@ -304,6 +309,8 @@ Home Assistant sources
 .. automodule:: nwp500.sim_home_assistant
    :members: HomeAssistantEnvironment, HomeAssistantClient, record_inputs,
       RecordInputs, Sources, Entities, sources_from, State, parse_state,
-      parse_history, parse_outages, History, history_for, parse_forecast,
+      parse_history, parse_outages, parse_states, History, history_for,
+      parse_forecast, read_heater_history, HeaterEntities, HeaterHistory,
+      HISTORY_WINDOW, to_w, to_wh,
       pump_runs, draw_spans, busy, covers_start, reports_after, percent,
       fresh, to_f, to_gpm, to_gal, to_rpm, HomeAssistantError

{nwp500_python-9.5.1 → nwp500_python-9.7.0}/setup.cfg

@@ -112,6 +112,16 @@ forbidden_modules =
 	awsiot
 	logging
 
+[importlinter:contract:calibrate-no-cli]
+name = An application calibrates without the CLI's dependencies
+type = forbidden
+source_modules = 
+	nwp500.sim_calibrate
+forbidden_modules = 
+	nwp500.cli
+	click
+	rich
+
 [importlinter:contract:ble-optional]
 name = Only nwp500.ble imports bleak, and only nwp-cli's ble backend imports nwp500.ble
 type = forbidden
@@ -138,6 +148,7 @@ source_modules =
 	nwp500.reservations
 	nwp500.sim
 	nwp500.sim_adapters
+	nwp500.sim_calibrate
 	nwp500.sim_home_assistant
 	nwp500.sim_live
 	nwp500.status_history

nwp500_python-9.7.0/src/nwp500/cli/calibration.py

@@ -0,0 +1,190 @@
+"""``nwp-cli simulate calibrate``: fit the heater's parameters to its
+recorded history.
+
+The history is the statuses the heater reported
+(``nwp500.status_history``, as ``nwp-cli simulate record`` writes them).
+The fits and the report's terms are ``nwp500.sim_calibrate``'s; this
+module reads the command's files and prints the report.
+
+This module needs the ``sim`` extra.
+"""
+
+import csv
+import json
+import logging
+import math
+import sys
+from collections.abc import Sequence
+from dataclasses import replace
+from datetime import datetime
+from pathlib import Path
+from typing import Any, TextIO
+
+from rich.console import Console
+from rich.table import Table
+
+from nwp500 import sim_calibrate as sc
+from nwp500 import status_history
+from nwp500.sim.params import params_to_document
+from nwp500.sim_calibrate import Calibrated, Term, report
+
+from .simulate import InputError, read_params
+
+__author__ = "Emmanuel Levijarvi"
+__copyright__ = "Emmanuel Levijarvi"
+__license__ = "MIT"
+
+_logger = logging.getLogger(__name__)
+
+#: A reading: an instant and a value.
+Reading = tuple[datetime, float]
+
+
+def read_history(path: str | Path) -> list[status_history.TimedStatus]:
+    """The statuses recorded at ``path``."""
+    try:
+        with Path(path).open(encoding="utf-8") as f:
+            readings = status_history.read(f)
+    except (OSError, ValueError) as e:
+        raise InputError(f"cannot read the history {path}: {e}") from None
+    if not readings:
+        raise InputError(f"the history {path} holds no statuses")
+    return readings
+
+
+def read_readings(path: str | Path, what: str) -> list[Reading]:
+    """A CSV file's readings: an ISO 8601 instant with its offset, then
+    a value, on each row. A first row that is not one is a header."""
+    try:
+        with Path(path).open(encoding="utf-8", newline="") as f:
+            rows = [r for r in csv.reader(f) if r and any(c.strip() for c in r)]
+    except OSError as e:
+        raise InputError(f"cannot read the {what} {path}: {e}") from None
+    out: list[Reading] = []
+    for number, row in enumerate(rows, start=1):
+        try:
+            at = datetime.fromisoformat(row[0].strip())
+            value = float(row[1])
+        except IndexError, ValueError:
+            if number == 1:
+                continue
+            raise InputError(
+                f"row {number} of the {what} {path} is not an instant "
+                "and a value"
+            ) from None
+        if at.tzinfo is None:
+            raise InputError(
+                f"row {number} of the {what} {path}: give the instant's "
+                "UTC offset"
+            )
+        if math.isfinite(value):
+            out.append((at, value))
+    if not out:
+        raise InputError(f"the {what} {path} holds no readings")
+    return out
+
+
+async def read_record(
+    sources: Any, readings: Sequence[status_history.TimedStatus]
+) -> Any:
+    """What ``sources`` recorded over ``readings``' span
+    (``sim_home_assistant.record_inputs``)."""
+    from nwp500 import sim_home_assistant as ha
+
+    first = min(t for t, _ in readings)
+    last = max(t for t, _ in readings)
+    async with ha.HomeAssistantClient(sources.url, sources.token) as client:
+        return await ha.record_inputs(client, sources.entities, first, last)
+
+
+#: The library's notes, naming the command's options.
+_OPTION_NOTES = {
+    sc.DEFAULT_BASE_NOTE: "refitting the 65 gal defaults (give --params "
+    "for another tank size)",
+    sc.NO_AIR_NOTE: "no air given (--air, --ambient or --sources): the "
+    "standby loss is not fitted",
+}
+
+
+def calibrate(
+    readings: Sequence[status_history.TimedStatus],
+    *,
+    air: Sequence[Reading] | None = None,
+    ambient: float | None = None,
+    humidity: Sequence[Reading] | None = None,
+    params: Any = None,
+    record: Any = None,
+) -> Calibrated:
+    """``sim_calibrate.calibrate`` with ``params`` a parameters
+    document, its errors as ``InputError`` and its notes naming the
+    command's options."""
+    base = None if params is None else read_params(params, "--params")
+    try:
+        done = sc.calibrate(
+            readings,
+            air=air,
+            ambient=ambient,
+            humidity=humidity,
+            params=base,
+            record=record,
+        )
+    except sc.CalibrationInputError as e:
+        raise InputError(str(e)) from None
+    return replace(
+        done, notes=tuple(_OPTION_NOTES.get(n, n) for n in done.notes)
+    )
+
+
+def _kept(t: Term) -> str:
+    if t.fitted:
+        return f"fitted: {t.note}" if t.note else "fitted"
+    return f"base: {t.why}" if t.why else "base"
+
+
+def print_report(done: Calibrated, console: Console) -> None:
+    """The report as tables on ``console``."""
+    c = done.calibration
+    console.print(
+        f"{done.n_statuses} statuses; quiet test: {c.standby.quiet_by}; "
+        f"{len(c.recoveries)} recoveries found"
+    )
+    if done.n_gaps:
+        minutes = done.max_gap.total_seconds() / 60
+        console.print(
+            f"{done.n_gaps} gap{'' if done.n_gaps == 1 else 's'} of over "
+            f"{minutes:g} min between statuses: no fit spans them"
+        )
+    console.print(
+        {
+            "readings": "Air: the readings given",
+            "constant": "Air: the constant given",
+            "source": "Air: the sources' record beside the heater",
+            None: "Air: none given; recoveries use the heater's own reading",
+        }[done.air]
+    )
+    table = Table(title="Calibration")
+    for column in ("Term", "Value", "From", "Error", "Kept"):
+        table.add_column(column)
+    for t in report(done):
+        table.add_row(
+            t.name,
+            t.value,
+            t.samples,
+            t.error,
+            _kept(t),
+        )
+    console.print(table)
+    unfitted = ", ".join(c.params.unfitted) or "none"
+    console.print(f"Unfitted: {unfitted}")
+
+
+def run(
+    done: Calibrated, output: str | Path | None, out: TextIO | None = None
+) -> None:
+    """Print the report and write the parameters to ``output``."""
+    for note in done.notes:
+        _logger.warning(note)
+    print_report(done, Console(file=out or sys.stdout))
+    if output is not None:
+        text = json.dumps(params_to_document(done.calibration.params), indent=2)
+        Path(output).write_text(text + "\n", encoding="utf-8")