nwp500-python 9.9.0__tar.gz → 9.10.0__tar.gz

{nwp500_python-9.9.0 → nwp500_python-9.10.0}/CHANGELOG.rst

@@ -2,6 +2,107 @@
 Changelog
 =========
 
+Version 9.10.0 (2026-10-22)
+===========================
+
+Added
+-----
+- **The heat book from a heater's values' changes** (#191).
+  ``sim_adapters.book_from_changes`` books the tank's heat from
+  ``ChangeRows`` and the instants the heater was heard from (a
+  ``HeaterHistory``'s ``rows`` and ``observed``, as
+  ``calibrate_changes`` takes them), with the same steps, anchor search
+  and silent-meter refusal as ``book_from_history``. Like the rows, its
+  flows are gal/min and its temperatures °F, whatever the preferred
+  units. A span the heater
+  wasn't heard from (a silence longer than ``max_gap`` of the heard
+  instants, or an outage) breaks the book: it is read only from after
+  the last one, and is None while the heater isn't heard at ``at``.
+  ``book_steps_from_changes`` gives the steps, and ``silences`` the
+  unheard spans.
+- ``sim_adapters.cold_supply_f``: the mains' plateau with the probe in
+  °F, reading no unit preference. The live source's inlet reads through it,
+  so a preference changed while it runs changes nothing.
+- ``sim_adapters.cold_supply(..., window=)``: how far back a long draw
+  counts (72 hours by default).
+- **The heat book's terms and the circulation loop's loss, fitted
+  together** (#196). ``sim_calibrate.fit_book`` fits the book's
+  compressor heat rate and slope with the air, its standby UA and a
+  circulation loop's loss per gallon from a heater's values' changes,
+  the household's draws, and the pump's runs with the loop's flow, each
+  given apart from the other. The loss is fitted with the book's terms
+  on the pairs of quiet full tanks with a run between. It needs 10
+  pairs (10 with a run for the loss), and keeps the base unless the
+  refit books the held-out latest fifth no worse, and unless a term
+  reaches its bound (``BookTermsFit``). ``sim.calibration.fit_terms_l1``
+  fits the terms exactly on ``RecordedBook.pair_terms``, within
+  ``BOOK_TERM_BOUNDS``. ``sim_adapters.run_readings`` gives the book a
+  loop's flow readings within its runs, each run's first held from its
+  start, as the fit takes them, and ``sim_adapters.run_flow`` gives runs
+  at a flow.
+- **A scenario document over the live scenario** (#201).
+  ``sim_live.overlay`` lays a scenario document over the heater's
+  composed scenario, as ``nwp-cli simulate --live`` does, and the CLI
+  now calls it: objects merge key by key (``sim.codec.merge``) and any
+  other value replaces. The start, horizon and zone take defaults, and
+  the parameters come from the caller, then the document, then the
+  heater, then the defaults (``Built``).
+- **The simulator's answers as documents** (#205).
+  ``sim.codec.to_document`` writes ``Readiness``, ``Recovery``,
+  ``RecoveryResult``, ``Forecast``, ``ActiveCycle``,
+  ``ElementModeResult``, ``Deliverable``, ``Trace`` and
+  ``HeaterProfile`` as JSON documents with ``schema_version`` and a
+  ``kind`` (``DOCUMENT_KINDS``), as ``result_to_document`` does for a
+  walk's result.
+- **The live parts from values read** (#207).
+  ``sim_live.heater_reading(status, feature)`` and
+  ``live_schedules(status, reservations, tou)``: what
+  ``LiveHeaterSource`` and ``LiveScheduleSource`` read, from a status,
+  a feature info, the reservations and the TOU periods read any other
+  way. Both sources now build their answers through them.
+
+Fixed
+-----
+- The live source's inlet looked back 72 hours of wall time, an hour
+  more or less than 72 hours across a clock change. It now looks back
+  72 elapsed hours.
+- ``book_from_history`` counted a missing meter reading (None or NaN)
+  as the meter reporting, so a gap filled with them passed the
+  ``METER_MAX_GAP`` check and was booked as no flow. Missing readings
+  now count as silence.
+
+Changed
+-------
+- ``parse_state`` and the simulate how-to say that over Home
+  Assistant's REST API an entity's ``last_reported`` comes from a copy
+  that a report of the same value doesn't renew, so a sensor holding
+  one value for over an hour can read as stale.
+- ``sim.calibration.RecordedBook`` prices a draw against each step's
+  inlet, as the heat book does (``book.step_heat_btu``), where it priced
+  it against the book's reference. Without an inlet the steps take
+  ``inlet_default_f``, the reference by default, and nothing changes.
+- ``max_gap``, ``GAP_SAMPLES`` and ``MIN_GAP`` are defined in
+  ``sim_adapters`` and documented there. ``sim_calibrate`` still exports
+  them.
+- **The household's draws come from a demand entity** (#203). The
+  simulator no longer works out when hot water was drawn from a water
+  meter. ``sim_home_assistant.Entities.demand`` (``demand`` in a
+  sources file) is a binary sensor on while the household draws hot
+  water, with the circulation's water not among its draws; the live
+  inlet's long draws and ``record_inputs``' ``drawing`` come from it
+  (``demand_spans``). ``sim.cold_supply.plateau_t_cold``,
+  ``sim_adapters.cold_supply`` and ``cold_supply_f`` take the draws as
+  (start, end) spans (``draws=``) in place of the meter's flow and draw
+  instants; ``ColdSupplyParams`` loses ``tick_s``, ``tick_gap_s`` and
+  ``draw_gpm``.
+
+Removed
+-------
+- ``Entities.meter_volume`` and ``meter_flow`` (and their sources-file
+  keys), ``sim.meter``, ``sim_home_assistant.draw_spans``,
+  ``volume_spans`` and ``reports_after``: the simulator's own reading
+  of draws from a water meter.
+
 Version 9.9.0 (2026-10-22)
 ==========================
 

{nwp500_python-9.9.0/src/nwp500_python.egg-info → nwp500_python-9.10.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: nwp500-python
-Version: 9.9.0
+Version: 9.10.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.9.0 → nwp500_python-9.10.0}/docs/how-to/calibrate-simulator.rst

@@ -81,7 +81,8 @@ Idle, it reads the cabinet, about 6 °F warm. So give one of these:
 - **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
+  the household's draws (the ``demand`` entity) 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
@@ -91,7 +92,7 @@ Idle, it reads the cabinet, about 6 °F warm. So give one of these:
   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,
+  draws' 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.
 
@@ -221,7 +222,7 @@ Assistant integration, can calibrate the same way:
 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
+   household'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
@@ -274,7 +275,7 @@ without ``keep_better``.
 
 ``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.
+air, the humidity, the household'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
@@ -367,6 +368,101 @@ On a desktop computer, 60 days with a heartbeat every 10 seconds
 Assistant's own queries, and 11 to fit, in about 180 MB.
 
 
+Fit the heat book
+=================
+
+The heat book (``book_from_changes``) counts the heat the tank holds
+from the compressor's heat rate and its slope with the air, the standby
+UA, and, with a circulation pump, the loop's loss per gallon
+(``CirculationParams.loss_btu_per_gal``). ``fit_book`` fits them
+together from the heater's history, the household's draws, and the
+pump's runs with the loop's flow. The draws and the loop's flow are
+yours to give, apart from each other: the fit takes every gallon of the
+draws as hot water drawn, and each run at the loop's flow.
+
+.. code-block:: python
+
+   from dataclasses import replace
+
+   from nwp500 import sim_adapters as sa
+
+   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)
+   params = sim_calibrate.calibrate_changes(
+       history.rows, history.observed, record=record, notes=history.notes
+   ).calibration.params
+   fit = sim_calibrate.fit_book(
+       history.rows, history.observed, params,
+       flow=draws, runs=runs, circulation_flow=loop_flow,
+       air=record.air or (),
+   )
+   params = replace(params, book=fit.book)
+
+``draws`` and ``loop_flow`` are (instant, gal/min) readings and ``runs``
+the pump's (start, end) spans; ``record_inputs``' air is °F, as the fit
+takes it. ``fit.loss_btu_per_gal`` is the loop's loss for your
+``CirculationParams`` (None without one).
+
+The fit reads the pairs of quiet full tanks up to
+``book.max_anchor_age_h`` apart, and fits each term for the least mean
+absolute error between the book and the probes at the second of each
+pair:
+
+- **The book's terms:** the compressor's heat rate and slope, and the
+  standby UA, on every pair. A term the pairs can't tell apart from
+  the others (the slope, with the air never off one temperature) stays
+  at ``params.book``. The rest of the book (its draw line, the anchors'
+  age, the valve's line) is ``params``'.
+- **The loop's loss per gallon:** on 10 pairs with a run between,
+  with the book's terms. With fewer, the loss is
+  ``params.circulation``'s, and without one, the pairs with a run are
+  left out. A pair with a run that has no flow reading is left out.
+
+The fit needs 10 pairs. It holds out the latest fifth and replaces the
+base only when it books them no worse. A term on its bound
+(``sim.calibration.BOOK_TERM_BOUNDS``) is no fit: the book misses
+something between those anchors that the term is standing in for. The
+loop's loss on its bound, or one the pairs can't tell from the book's
+terms (runs that follow the recoveries), leaves the loss at the base's;
+any other term on its bound keeps the base. ``fit.kept`` says which it
+kept and ``fit.why`` why. A span the heater wasn't heard from, a probe
+read nothing, or the draws were silent over an hour, breaks the book.
+
+A pair with a run needs a quiet full tank on each side of it, so they
+come slowly. With a pump running about once a day, one installation had
+5 in 14 days and 19 in 42: fit on four weeks or more, and raise Home
+Assistant's ``purge_keep_days`` to keep them.
+
+Book with the same inputs. Runs are priced with the loop's loss, in a
+``CirculationParams`` of your installation's with ``meter_share`` 0,
+since the draws hold none of the loop's water; without a loss, they
+can't be booked. ``sa.run_readings`` gives the book each run's flow as
+the fit takes it: its own readings, the first from its start, and none
+read outside the runs.
+
+.. code-block:: python
+
+   from nwp500.sim.params import CirculationParams
+
+   book = None
+   loss = fit.loss_btu_per_gal
+   if loss is not None or not runs:
+       loop = None
+       if loss is not None:
+           loop = CirculationParams(
+               displaced_gal=..., flow_gpm=..., loss_btu_per_gal=loss,
+               meter_share=0.0,
+           )
+       book = sa.book_from_changes(
+           history.rows, history.observed, replace(params, circulation=loop),
+           at=end, flow=draws, circulation=runs,
+           circulation_flow=sa.run_readings(runs, loop_flow),
+           air=record.air or (),
+       )
+
+
 Limitations
 ===========
 

{nwp500_python-9.9.0 → nwp500_python-9.10.0}/docs/how-to/simulate-heater.rst

@@ -138,8 +138,7 @@ pass it with ``--sources`` (or set ``NWP500_SOURCES``):
    air = "sensor.beside_the_heater_temperature"
    humidity = "sensor.beside_the_heater_humidity"
    inlet = "sensor.cold_supply_temperature"
-   meter_volume = "sensor.water_volume"     # volume since the last report
-   meter_flow = "sensor.water_flow_rate"
+   demand = "binary_sensor.hot_water_demand"  # on while hot water is drawn
    circulation_speed = "sensor.circulation_pump_speed"
    weather = "weather.forecast_home"
 
@@ -167,9 +166,17 @@ give:
 - **the humidity:** a reading at most an hour old;
 - **the inlet:** the plateau of the long draws (11 minutes or more,
   circulation off) in the last 72 hours, from the inlet probe and the
-  meter. Name the meter's flow rate as well as its volume. A
+  ``demand`` entity: a binary sensor that is on while the household
+  draws hot water, with the circulation's water not among its draws. A
   circulation pump with no speed reading leaves no estimate.
 
+A reading's age is from when Home Assistant last heard the sensor
+report (``last_reported``). Over the REST API, Home Assistant serves
+that from a copy of the state it keeps until the state changes, and a
+report of the same value doesn't renew the copy. So a sensor that has
+held one value for over an hour can read as over an hour old, and its part
+keeps its default, even while it still reports.
+
 Units come from each entity's ``unit_of_measurement``: the pump's speed
 in rpm or Hz. A part that can't be read, or is stale, keeps its
 default, and a warning on stderr says why. ``--ambient``, ``--inlet``
@@ -217,6 +224,35 @@ source when TOU is on and its periods cannot be read. A missing
 feature info leaves ``composed.params`` None (the tank size is
 unknown). Change a part with ``composed.scenario.model_copy(update=...)``.
 
+With the status, the feature info, the reservations and the TOU
+periods already read some other way, build the same parts from them:
+``sim_live.heater_reading(status, feature)`` is what
+``LiveHeaterSource`` reads, and ``sim_live.live_schedules(status,
+reservations, tou)`` what ``LiveScheduleSource`` reads. Pass either to
+``compose`` as ``sim_live.Given(...)``. ``tou`` is the ``TOUInfo`` the
+TOU read gives, or the ``TOUPeriod`` list itself; the TOU switch is the
+status's. ``live_schedules`` raises ``LiveReadError`` when the status
+has TOU on and ``tou`` is None.
+
+To lay a scenario document over the heater as it is now, as
+``nwp-cli simulate --scenario ... --live`` does, use ``overlay``:
+
+.. code-block:: python
+
+   built = sim_live.overlay(composed, doc, now=datetime.now(UTC))
+   result = sim.simulate(built.scenario, built.params)
+
+Objects merge key by key, and any other value, a list included,
+replaces the one under it, so ``{"schema_version": 1, "scenario":
+{"settings": {"setpoint_f": 125}}}`` changes the setpoint and keeps
+the rest of the heater's settings. ``composed`` or ``doc`` may be None.
+Where neither gives one, the start is ``now``, the horizon 24 hours,
+and the zone ``tz=``. The parameters are ``params=``, then the
+document's, then the heater's, then the 65 gal defaults (with a note in
+``built.notes``). ``replace=`` takes parts that stand in whole for the
+scenario's, and ``over=`` parts laid on after them. A document that
+doesn't make a scenario raises ``ValueError``.
+
 To have the models themselves, read them directly. Each MQTT read is a
 request answered on a subscription:
 
@@ -824,6 +860,30 @@ heater's statuses, book the tank's heat from the record and pass it as
    )
    readiness = sim.time_to_ready(scenario, params, book=book)
 
+With the heater's values recorded as changes instead (Home Assistant's
+entity history, which ``read_heater_history`` reads), book from those,
+with the instants the heater was heard from:
+
+.. code-block:: python
+
+   from nwp500 import sim_home_assistant as ha
+
+   history = await ha.read_heater_history(client, entities, start, now)
+   book = sa.book_from_changes(
+       history.rows,
+       history.observed,
+       params,
+       at=now,
+       flow=draws_gpm,        # gal/min, whatever the preferred units
+   )
+
+Like the history's rows, its ``flow`` and ``circulation_flow`` are
+gal/min and its ``inlet`` and ``air`` °F, whatever the preferred units.
+A span the heater wasn't heard from (an outage, or a silence much
+longer than its usual reporting) breaks the book: it is walked only
+from an anchor after the last one, and is None while the heater isn't
+heard now.
+
 Without a meter, start one only when you know the tank is full and
 quiet (``sa.full_tank_book``).
 
@@ -835,12 +895,18 @@ the air around the pipe:
 
    from nwp500.sim.cold_supply import on_the_mains
 
-   cold = sa.cold_supply(inlet_probe, at=now, flow=meter_flow,
+   cold = sa.cold_supply(inlet_probe, at=now, draws=draws,
                          circulation=runs)
    book, measured = on_the_mains(book, cold)
    readiness = sim.time_to_ready(scenario, params, book=book,
                                  inlet_measured=measured)
 
+``draws`` are the (start, end) spans the household drew hot water,
+without the circulation's water. ``sa.cold_supply`` takes the probe in
+the preferred unit. ``sa.cold_supply_f`` takes it in °F and reads no
+unit preference, for a caller whose preference may change while it
+runs.
+
 The mains is the median plateau of the long draws (11 minutes or more,
 with circulation off) over the last 72 hours, read from minute 9 of each
 draw, once the probe has passed the stagnant pipe. There is none
@@ -1162,7 +1228,21 @@ the ones you want to look at again, or attach one to a bug report:
        scenario, params = codec.scenario_from_document(f.read())
 
 ``codec.result_to_document(result)`` writes a result the same
-way.
+way. The other answers (``time_to_ready``, ``next_recovery``,
+``recovery``, ``forecast``, ``active_cycle``, ``element_mode``,
+``readiness``, ``standby`` and ``heater_profile``) are documents through
+``codec.to_document``:
+
+.. code-block:: python
+
+   doc = codec.to_document(sim.time_to_ready(scenario, params))
+   doc["kind"]             # "readiness"
+   doc["deliverable_gal"]  # the answer's fields, at the top level
+
+Each document has ``schema_version`` and ``kind``, the answer's type
+in snake case (``codec.DOCUMENT_KINDS``). Instants are ISO 8601 strings,
+nested answers are objects, and a number that isn't finite is null, so
+the document is strict JSON.
 
 
 See also

{nwp500_python-9.9.0 → nwp500_python-9.10.0}/docs/reference/python_api/sim.rst

@@ -154,6 +154,7 @@ Hot water and the heat book
       clean_draws, CleanDraw, crossing,
       demonstrated, frontier, capacity, held_out, fit_evidence,
       EvidenceFit, cold_lower_cap, RecordedBook, fit_book_terms, BookFit,
+      fit_terms_l1, BOOK_TERMS, BOOK_TERM_BOUNDS,
       book_error_bands, book_error_btu, empty_point,
       zone_empty_point, withheld_btu, book_walk, long_draws,
       front_frame, fit_front, FrontFit, settle_tails, fit_front_settle,
@@ -184,9 +185,6 @@ Hot water and the heat book
 .. automodule:: nwp500.sim.cold_supply
    :members: plateau_t_cold, ColdSupply, ColdSupplyParams, on_the_mains
 
-.. automodule:: nwp500.sim.meter
-   :members: flow_gpm
-
 .. automodule:: nwp500.sim.record
    :members: Record, RecordedWrite, Recorded, RecordedStarts, corroborator
 
@@ -291,7 +289,9 @@ Live sources
    :members: compose, Composed, Source, Given, HeaterReading,
       LiveHeaterSource, LiveScheduleSource, LiveReadError, read_status,
       read_feature, read_reservations, HeaterSource, ScheduleSource,
-      EnvironmentSource, LoadSource, DEFAULT_TIMEOUT
+      EnvironmentSource, LoadSource, DEFAULT_TIMEOUT, overlay, Built,
+      DEFAULT_HORIZON, DEFAULT_PARAMS_NOTE, zone_name, heater_reading,
+      live_schedules
 
 
 Recorded history
@@ -301,9 +301,10 @@ Recorded history
    :members:
 
 .. automodule:: nwp500.sim_calibrate
-   :members: calibrate, calibrate_changes, Calibrated, report, Term, max_gap,
+   :members: calibrate, calibrate_changes, Calibrated, report, Term,
+      fit_book, BookTermsFit, MIN_BOOK_PAIRS, MIN_RUN_PAIRS,
       score, Judged, HeldOut, GROUPS, air_unread_note,
-      CalibrationInputError, DEFAULT_HUMIDITY_PCT, GAP_SAMPLES, MIN_GAP,
+      CalibrationInputError, DEFAULT_HUMIDITY_PCT,
       DEFAULT_BASE_NOTE, NO_AIR_NOTE
 
 
@@ -312,9 +313,9 @@ Home Assistant sources
 
 .. automodule:: nwp500.sim_home_assistant
    :members: HomeAssistantEnvironment, HomeAssistantClient, record_inputs,
-      RecordInputs, Sources, Entities, sources_from, State, parse_state,
+      RecordInputs, INLET_LOOKBACK, Sources, Entities, sources_from, State, parse_state,
       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,
+      pump_runs, demand_spans, busy, covers_start, percent,
       fresh, to_f, to_gpm, to_gal, to_rpm, HomeAssistantError

{nwp500_python-9.9.0 → nwp500_python-9.10.0}/docs/reference/simulator-inputs.rst

@@ -519,6 +519,13 @@ tank over the cold water of a recent draw. Start one only from what you know:
      - You record the heater's statuses and meter the hot water: the
        book is walked from the last time the record shows the tank
        full and quiet after a recovery (below).
+   * - ``sim_adapters.book_from_changes(rows, observed, params, at=...,
+       flow=...)``
+     - The same, from the heater's values' changes (``ChangeRows``) and
+       the instants it was heard from, as Home Assistant records them,
+       with the flows in gal/min and the temperatures in °F.
+       Only an anchor after the last span the heater wasn't heard from
+       counts.
    * - A ``Booked`` from your own record
      - You keep a book of the tank's heat some other way.
 
@@ -540,7 +547,17 @@ median of the probe's readings over the last 3 hours
 (``book.inlet_window_s``), the default without one. The meter must
 report at rest too: a silence over an hour in the window is refused,
 since it would read as a quiet full tank. A missing reading (None or
-NaN) is skipped, and the value before it holds.
+NaN) is skipped, and the value before it holds; it doesn't count as the
+meter reporting.
+
+``book_from_changes`` grids the changes the same way, each value held
+until its next change; without a compressor flag, the heat source says
+when the compressor runs. A value that holds writes no change, so only
+``observed`` says the heater was heard. A silence between those
+instants longer than ``max_gap`` of them (4 times their usual spacing,
+and at least 5 minutes), or one of ``rows.outages``, is a span nobody
+saw. The book is read only from after the last such span, and is None
+when the heater isn't heard at ``at``.
 
 To build the steps yourself, pass them to ``book.book_steps``.
 ``BookStep.circulation_in_meter_gpm`` is

{nwp500_python-9.9.0 → nwp500_python-9.10.0}/src/nwp500/cli/__main__.py

@@ -1276,8 +1276,8 @@ async def simulate_record(
     "--sources",
     type=click.Path(exists=True, dir_okay=False),
     envvar="NWP500_SOURCES",
-    help="A TOML file naming where the air, its humidity, the meter and "
-    "the circulation are recorded (Home Assistant)",
+    help="A TOML file naming where the air, its humidity, the hot water "
+    "demand and the circulation are recorded (Home Assistant)",
 )
 @click.pass_context
 def simulate_calibrate(

{nwp500_python-9.9.0 → nwp500_python-9.10.0}/src/nwp500/cli/simulate.py

@@ -32,6 +32,9 @@ from nwp500.sim.codec import (
     result_to_document,
     scenario_to_document,
 )
+from nwp500.sim.codec import (
+    merge as merge,
+)
 from nwp500.sim.engine import SimulationError
 from nwp500.sim.params import params_from_document
 
@@ -47,7 +50,7 @@ __license__ = "MIT"
 _logger = logging.getLogger(__name__)
 
 #: How far a run looks ahead when nothing else says.
-DEFAULT_HOURS = 24.0
+DEFAULT_HOURS = sim_live.DEFAULT_HORIZON / timedelta(hours=1)
 
 
 class InputError(ValueError):
@@ -69,23 +72,9 @@ def read_document(path: str | Path, what: str) -> dict[str, Any]:
 def zone_name(name: str) -> str:
     """``name``, when it is an IANA zone this machine knows."""
     try:
-        ZoneInfo(name)
-    except ZoneInfoNotFoundError, ValueError:
-        raise InputError(f"unknown time zone {name!r}") from None
-    return name
-
-
-def merge(base: Mapping[str, Any], over: Mapping[str, Any]) -> dict[str, Any]:
-    """``base`` with ``over`` laid on it: objects merge key by key; any
-    other value, a list included, replaces the one under it."""
-    out = dict(base)
-    for key, value in over.items():
-        under = out.get(key)
-        if isinstance(value, Mapping) and isinstance(under, Mapping):
-            out[key] = merge(under, value)  # pyright: ignore[reportUnknownArgumentType]
-        else:
-            out[key] = value
-    return out
+        return sim_live.zone_name(name)
+    except ValueError as e:
+        raise InputError(str(e)) from None
 
 
 def local_zone() -> str | None:
@@ -110,6 +99,16 @@ def local_zone() -> str | None:
     return None
 
 
+#: A scenario ready to walk, with its parameters.
+Built = sim_live.Built
+
+#: The library's notes, naming the command's options.
+_OPTION_NOTES = {
+    sim_live.DEFAULT_PARAMS_NOTE: "the tank size is unknown: using the 65 "
+    "gal defaults (give --params)",
+}
+
+
 @dataclass(frozen=True)
 class Inputs:
     """What the command was given. Files are read already; ``ambient``
@@ -169,78 +168,48 @@ class Inputs:
         )
 
 
-@dataclass(frozen=True)
-class Built:
-    """A scenario ready to walk, with its parameters."""
-
-    scenario: sim.Scenario
-    params: sim.HeaterParams
-    #: What the driver assumed, for the user to see.
-    notes: tuple[str, ...] = ()
-
-
 def build(
     inputs: Inputs, live: sim_live.Composed | None, now: datetime
 ) -> Built:
     """The scenario: the device's parts (``live``), the scenario
-    document's laid over them, then the flags'. ``now`` is the start
-    when nothing gives one."""
-    data: dict[str, Any] = {}
-    if live is not None:
-        data = scenario_to_document(live.scenario)["scenario"]
-    if inputs.scenario is not None:
-        data = merge(data, inputs.scenario["scenario"])
+    document's laid over them (``sim_live.overlay``), then the flags'.
+    ``now`` is the start when nothing gives one."""
+    replace: dict[str, Any] = {}
     if inputs.start is not None:
-        data["start"] = inputs.start
-    data.setdefault("start", now)
+        replace["start"] = inputs.start
     if inputs.hours is not None:
-        data["horizon"] = timedelta(hours=inputs.hours)
-    data.setdefault("horizon", timedelta(hours=DEFAULT_HOURS))
+        replace["horizon"] = timedelta(hours=inputs.hours)
     if inputs.tz is not None:
-        data["tz"] = inputs.tz
-    elif "tz" not in data:
-        data["tz"] = inputs.zone()
-    elif isinstance(data["tz"], str):
-        # The model's own check raises a KeyError for an unknown zone.
-        zone_name(data["tz"])
+        replace["tz"] = inputs.tz
     if inputs.environment is not None:
-        data["environment"] = dict(inputs.environment)
-    if inputs.ambient is not None:
-        data["environment"] = {
-            **data.get("environment", {}),
-            "ambient_f": sa.to_sim_temperature(inputs.ambient),
-        }
-    if inputs.inlet is not None:
-        data["environment"] = {
-            **data.get("environment", {}),
-            "inlet_f": sa.to_sim_temperature(inputs.inlet),
-        }
+        replace["environment"] = dict(inputs.environment)
     if inputs.loads is not None:
-        data["loads"] = dict(inputs.loads)
+        replace["loads"] = dict(inputs.loads)
     if inputs.commands is not None:
-        data["commands"] = dict(inputs.commands)
-    try:
-        scenario = sim.Scenario.model_validate(data)
-    except ValueError as e:
-        raise InputError(f"the inputs do not make a scenario: {e}") from None
-
-    notes: list[str] = []
-    doc_params = (
-        None if inputs.scenario is None else inputs.scenario.get("params")
-    )
+        replace["commands"] = dict(inputs.commands)
+    environment: dict[str, float] = {}
+    if inputs.ambient is not None:
+        environment["ambient_f"] = sa.to_sim_temperature(inputs.ambient)
+    if inputs.inlet is not None:
+        environment["inlet_f"] = sa.to_sim_temperature(inputs.inlet)
+    params = None
     if inputs.params is not None:
         params = read_params(inputs.params, "--params")
-    elif doc_params is not None:
-        params = read_params(doc_params, "the scenario's params")
-    elif live is not None and live.params is not None:
-        params = live.params
-    else:
-        params = sim.default_params()
-        notes.append(
-            "the tank size is unknown: using the 65 gal defaults "
-            "(give --params)"
+    try:
+        built = sim_live.overlay(
+            live,
+            inputs.scenario,
+            now=now,
+            # A live scenario carries its zone.
+            tz=None if live is not None else inputs.zone(),
+            params=params,
+            replace=replace,
+            over={"environment": environment} if environment else None,
         )
-    return Built(scenario, params, tuple(notes))
+    except ValueError as e:
+        raise InputError(str(e)) from None
+    notes = tuple(_OPTION_NOTES.get(n, n) for n in built.notes)
+    return Built(built.scenario, built.params, notes)
 
 
 def read_params(doc: Any, what: str) -> sim.HeaterParams: