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

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

@@ -2,6 +2,153 @@
 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)
+==========================
+
+Added
+-----
+- **A bottom loss in the standby model** (#187). Over one installation's 407
+  quiet windows across ten months, a window that opens stratified loses
+  heat at the bottom: its gap widens, its lower probe falls about 40 %
+  faster than a mixed tank's, and its upper probe hardly moves. One UA
+  on the whole tank could not represent it, and the fitted UA was a
+  blend that cooled a mixed tank too fast, as after a cold season's full
+  recoveries. ``LossParams`` gains ``bottom_loss_btu_hr`` and
+  ``bottom_gate_f``: heat leaving the lower zone, of which the lower
+  probe sees ``1 - exp(-gap / gate)`` (``sim.physics.tank.
+  bottom_loss_reach``). The standby walk (``decay.project_decay``) and
+  the recovery integrator charge it to the lower zone. A bottom loss of
+  0.0, the default and what stored parameter sets carry, reproduces the
+  model before it.
+- ``sim.calibration.fit_loss`` fits the UA law and the bottom loss
+  together, through the standby walk, on the quiet windows opening with
+  a gap of 10 °F or less (``loss_windows``); ``fit_standby`` uses it.
+  On the installation above, the lower probe's median error over ten
+  hours fell from 1.25 to 0.77 °F from March to October and from 1.67
+  to 1.05 °F over the winter (1.15 °F trained without the winter).
+  ``StandbyWindow`` carries each window's probes and air, and
+  ``standby_ends`` and ``standby_error`` walk a loss over windows.
+- The report has the bottom loss and its gate, and ``keep_better``
+  judges them with the standby loss, on the probes' error in each
+  held-out window's fall, °F/h.
+
+Changed
+-------
+- The standby loss is fitted only on quiet windows opening with a gap of
+  10 °F or less: a wider gap is a draw's front closing, which the gap's
+  time constant describes.
+- ``keep_better`` scores the standby group on the probes' error in each
+  held-out window's fall, walked as the simulation walks it, in place of
+  the error in log UA, so a loss with a bottom term and one without are
+  scored alike.
+- The zone gap time constant is fitted with the bottom loss opening the
+  gaps it relaxes (``fit_gap_tau``'s ``loss``, ``gap_paths``), in turn
+  with the loss until it settles: a gap the bottom loss widens read as a
+  pure relaxation pushed the constant long. ``keep_better`` judges the
+  constant before the standby loss and fits and scores the loss on the
+  constant kept.
+
 Version 9.8.0 (2026-10-21)
 ==========================
 

{nwp500_python-9.8.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.8.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.8.0 → nwp500_python-9.10.0}/docs/explanation/simulator.rst

@@ -78,7 +78,11 @@ zone (about half the tank's mass). Once the gap between the zones
 closes, the tank heats as one body. In standby the gap relaxes on a
 fitted time constant. Standby loss follows a jacket law,
 ``UA(dT) = ua_ref * (max(dT, 5) / 50) ^ n``, with the ambient as the
-other side.
+other side, on the whole tank. A bottom loss ``Q_b`` leaves the lower
+zone alone: the lower probe sees the share ``1 - exp(-gap / gate)`` of
+it, so a stratified tank's lower zone falls faster and its gap opens,
+while a mixed tank hides it below the probe. With ``Q_b = 0`` the loss
+is the jacket law alone.
 
 **The elements.** They follow the device's own rules
 (:doc:`heating-elements`): per-mode entry thresholds, a dead time,

{nwp500_python-9.8.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.
 
@@ -139,16 +140,23 @@ fitted or kept the base's value, and why:
 
    * - Term
      - Fitted from
-   * - Standby loss and its exponent
+   * - Standby loss, its exponent, the bottom loss and its gate
      - 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.
+       heating or hot water in use, that open with a gap of 10 °F or
+       less between the probes. A window counts only if its fit tracks
+       the probes within 2 °F. Each window's upper and lower probe are
+       walked from its start as the simulation walks them, and the
+       terms are fitted to where the probes ended. 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. The
+       bottom loss needs 10 windows that open with a gap of 1 °F or
+       more; with fewer it is 0, and the loss is the jacket law
+       alone.
    * - 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.
+       more. The bottom loss opens the gaps it relaxes, so the two are
+       fitted in turn until the constant settles.
    * - 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
@@ -214,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
@@ -240,8 +248,12 @@ fit as ``params`` with ``keep_better=True``:
 
 Each group of terms holds out its latest evidence from its refit:
 
-- the standby loss and its exponent: its quiet windows;
-- the zone gap time constant: its windows that open a gap;
+- the standby loss, its exponent, the bottom loss and its gate: its
+  quiet windows, scored on the probes' error in each window's fall,
+  °F/h;
+- the zone gap time constant: its windows that open a gap, judged
+  before the standby loss, which is then fitted and scored on the
+  constant kept;
 - the compressor constant and the evaporator approach: its reached
   recoveries;
 - the power scale: the metered compressor cycles it can use;
@@ -263,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
@@ -356,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.8.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.8.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,
@@ -169,6 +170,8 @@ Hot water and the heat book
       metered_withdrawn, metered_lead,
       path_to_end, with_power, snapshots, recoveries, quiet_windows,
       busy_intervals, fit_window, fit_ua_law, fit_gap_tau, with_standby,
+      fit_loss, LossFit, loss_windows, standby_ends, standby_error,
+      walk_tau, gap_paths, gap_error,
       with_compressor, UA_SEARCH_BOUNDS, UA_EXPONENT_BOUNDS, DRAW_LEAD
 
 .. automodule:: nwp500.sim.profile
@@ -182,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
 
@@ -250,7 +250,7 @@ The pieces the entry points are built from.
       vapor_enthalpy, dew_point_f
 
 .. automodule:: nwp500.sim.physics.tank
-   :members: ua_at
+   :members: ua_at, bottom_loss_reach, bottom_loss_drop_f
 
 .. automodule:: nwp500.sim.physics.element
    :members: mode_recovery, ModeRecovery, mode_plan, ModePlan,
@@ -289,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
@@ -299,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
 
 
@@ -310,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.8.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.8.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(