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

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

@@ -2,6 +2,205 @@
 Changelog
 =========
 
+Version 9.12.0 (2026-10-23)
+===========================
+
+Added
+-----
+
+- **The heater's own entities in the sources file** (#232).
+  ``[home_assistant.heater]`` names them (``heard``, ``upper`` and
+  ``lower`` required), so the CLI fits and anchors the projected air to
+  the heater's reading while its compressor runs where no air entity
+  does.
+- **The idle cabinet air, said** (#232). ``Environment.ambient_cabinet``
+  marks air taken from the heater's own reading while the compressor
+  was idle, about 6 °F warm, and answers give the reason
+  ``ambient_from_idle_cabinet``.
+- **The heater's own air in the book** (#236). With no air reading,
+  ``book_from_history``, ``book_from_changes`` and
+  ``HomeAssistantBook`` take the heater's own air reading once its
+  compressor has run 5 minutes (``sim_adapters.settled_air``,
+  ``HEATER_AIR_SETTLE``), held until the next run, rather than 65 °F
+  throughout. ``HomeAssistantBook`` notes it.
+- **The standby loss from the heater's own air** (#236). With no air
+  given, calibration fits the standby loss on the heater's own reading
+  once its compressor has run 5 minutes, interpolated from one run to
+  the next, over the quiet windows with a run within
+  ``HEATER_AIR_BRACKET`` (6 h) of both ends: the law's level only, on
+  the base's exponent. ``Calibrated.air`` is ``"heater"``, and a note
+  says how many windows qualified and their share of the quiet hours.
+  It was left unfitted. ``fit_ua_law``, ``fit_loss``, ``fit_standby``
+  and ``calibration.calibrate`` take a fixed exponent.
+- **The book prices a circulation run by a circuit volume.**
+  ``CirculationParams.book_circuit_gal``: with it, the heat book
+  charges a run its first gallons up to that volume, runs closer than
+  ``run_gap_min`` one run, each at the tank's upper probe less the air;
+  without it, ``loss_btu_per_gal`` per gallon as before. ``fit_book``
+  fits the volume in place of the loss per gallon (``book_circuit_gal``
+  on its result), and ``fit_book_terms`` with ``circuit=True``. At one
+  installation, over 284 re-anchors, the book's error on pairs with a
+  run fell 14 % against a refitted loss per gallon (1741 against 2023
+  BTU), and on held-out months from 3184 to 2454 BTU, the volume
+  steady at 1.1 to 1.5 gal where the loss per gallon moved from 59 to
+  120. It is an effective volume, apart from ``displaced_gal``.
+  ``SITE_CIRCULATION`` carries one installation's, and the book's
+  heat-pump rate and slope are refitted with it (4338 BTU/h, 66.0
+  BTU/h/°F; the UA stays 2.88).
+
+- **The heater's heard spans, given** (#230). ``book_from_changes``
+  takes ``heard=``, the spans the heater was heard over, for a record
+  that keeps no instant for each response. A gap between spans breaks
+  the book as a silence between instants does, and the heater is heard
+  at ``at`` only inside a span.
+- **The air fit carried across reads** (#221).
+  ``sim_home_assistant.fit_location_air`` is the fit
+  ``HomeAssistantEnvironment`` makes where it is given no model, with
+  its notes, as a call of its own. ``HomeAssistantEnvironment`` takes
+  it back as ``fitted_air``, projects through it, and notes its r and
+  lag on every ``read`` without fitting again. A caller that reads
+  every few minutes fits on its own cadence.
+- **The heat book kept current from Home Assistant** (#227).
+  ``sim_home_assistant.HomeAssistantBook`` holds the heater's and the
+  household flow's history, reading only what is new on each ``read``,
+  and books from it with no request (``book``, for an executor). The
+  flow is the household's draws as delivered through the mixing valve.
+  The circulation's speed, an inlet probe and the demand entity, each
+  optional, give the runs, the inlet and the conversion at the mains
+  (``BookAnswer.inlet_measured``). ``mains_plateau`` and ``known_runs``
+  are the inlet's plateau and the pump's runs from a ``History``, as
+  ``HomeAssistantEnvironment`` reads them. ``book_from_changes`` and
+  ``book_steps_from_changes`` take ``air_outages``: while the air is
+  unknown the book takes the default air, not the last reading.
+- **The CPU work off the event loop** (#225). ``fit_location_air`` and
+  ``HomeAssistantEnvironment`` take ``run=`` (``Run``), which runs a
+  piece of work and awaits its result, such as Home Assistant's
+  ``hass.async_add_executor_job``. The fit, the samples of the heater's
+  air and the inlet's plateau go through it. Without it they run
+  inline (``inline``), as before.
+- **A history kept current** (#223). ``sim_home_assistant.HeaterHistory``,
+  ``sim_home_assistant.History`` and ``sim_adapters.ChangeRows`` take
+  ``extended(newer)``, which merges a later read in by instant (the
+  later read's row winning at a shared instant) and joins the outages,
+  and ``since(start)``, which trims to ``start`` and keeps each value in
+  force there. A caller that books every few minutes reads only what is
+  new and books from what it holds. ``sim_adapters.merge_changes``,
+  ``changes_since``, ``join_spans`` and ``spans_since`` do it for one
+  series.
+
+Changed
+-------
+
+- ``SITE_CIRCULATION.meter_share`` is 0. The book's flow is the
+  household's draws alone, which no circulation run passes, so the
+  example terms take nothing off it. A caller whose meter carries the
+  loop's water still sets its own share.
+
+- **Readiness with no evidence and no book** (#234). A tank whose probes
+  are within the book's ``uniform_band_f`` reads its full-tank floor
+  from its probes (``Deliverable.basis`` ``probes``), at any
+  temperature. Any other tank reads 0 with the reason
+  ``no_evidence_for_state``, which says the gallons are unknown, not
+  none, in place of ``colder_than_all_evidence``.
+- The 50 and 80 gal defaults scale the book's empty point
+  (``BookParams.empty_btu``) and the full tank's hidden cold water
+  (``ReadinessParams.full_hidden_gal``) by tank size, as they scale its
+  volume (#234). Both were the 65 gal tank's at every size.
+- Circulation runs given with params that have no circulation terms are
+  priced at one installation's (``SITE_CIRCULATION``), and the answer
+  says so in ``defaults_used`` (#232). They raised in every walk, and a
+  book left them unpriced. ``sim_adapters.with_circulation_terms`` does
+  this for the books.
+- A status in Standby is Power Off, as the NaviLink app counts it (#232).
+  It raised.
+- ``book_from_changes`` books from the flow's first reading when its
+  history starts later than the window, rather than raising (#232).
+- ``known_runs`` returns the pump's runs from its first reading and the
+  span before it as unknown, rather than nothing for a history shorter
+  than the span (#232). The inlet's plateau skips a draw in that span,
+  and ``HomeAssistantBook`` takes no anchor before it.
+- ``read_heater_history`` leaves out a heating flag entity with no
+  history at all, with a note, rather than leaving the whole record
+  unobserved (#232).
+
+- The simulate how-to's ``book_from_changes`` example passes the
+  circulation's runs and flow, and says to pass the household's draws,
+  separated from any circulation in the meter, with ``meter_share`` 0.
+- With a model, given or fitted, and no fresh reading of the air beside
+  the heater, ``HomeAssistantEnvironment`` anchors the projection to
+  ``heater``'s newest air reading from the last hour while its
+  compressor ran, on every ``read``. It anchored to one only on the
+  read that fitted the model (#221).
+
+Fixed
+-----
+
+- ``simulate`` and ``time_to_ready`` convert a book's heat to gallons at
+  the scenario's inlet (``Environment.inlet_f``) where one is given, as
+  the walk's draws take it (#234). The gallons ignored a measured inlet,
+  and with a book a colder inlet gave warmer delivered water.
+- ``fit_location_air`` fits to the heater's own air when the air entity
+  can't be read or gives no fit (#232).
+- Calibration's recoveries outside a partial air record read the
+  heater's own air, rather than being dropped (#232).
+- The simulate how-to's and ``sim_live``'s ``compose`` example falls
+  back to the 65 gal defaults when the feature info doesn't arrive
+  (#232). It passed None to ``simulate``.
+- ``HomeAssistantBook`` says when the flow is unknown now (#232).
+
+- **A heater read missing a heating flag is unobserved** (#227).
+  ``read_heater_history`` reads a day at a time; a window with nothing
+  of the compressor, an element or the heat source (each opens with
+  the value in force) now leaves the heater unobserved over it, with a
+  note, rather than holding the flag from before.
+- ``sim_adapters.book_from_changes`` read its flow as a sampled meter:
+  a reading held 60 seconds (``FLOW_HOLD``) and the inlet's an hour,
+  and flow rows more than an hour apart refused the book as a silent
+  meter. A history of changes writes a row only when a value changes,
+  so a steady draw counted for a minute and an hour at 0 gal/min was
+  refused. Its flows, inlet and air now hold until the next change. It
+  takes ``flow_outages``, a span with no anchor before it counting, as
+  for a heater unheard, and ``inlet_outages``. No flow reading in force
+  at the window's start is a ``ValueError`` (#219).
+- ``sim_home_assistant.pump_runs`` ended a run 5 minutes after its last
+  speed reading. A pump at a steady speed writes no row, so a long run
+  read as 5 minutes. A speed now holds until it changes; ``stale``
+  (``PUMP_STALE``) keeps the old rule for a sampled speed (#219).
+
+Version 9.11.0 (2026-10-22)
+===========================
+
+Added
+-----
+- **The air from a weather entity without a model** (#214). With a
+  weather entity and no ``location_air`` model,
+  ``sim_home_assistant.HomeAssistantEnvironment`` fits one
+  (``sim.location_air.fit``) on the last 3 days
+  (``LOCATION_AIR_WINDOW``) of the air entity's readings, or with
+  ``heater=`` the heater's own air reading while its compressor runs,
+  against the weather entity's outdoor temperature, each reading from
+  the unit it was recorded in (``HomeAssistantClient.outdoor_history``,
+  ``parse_outdoor_history``). It projects the forecast through the fit
+  when the readings the outdoor history covers span a day and follow
+  the outdoor air at r 0.5 or more, and keeps it as ``fitted_air``.
+  ``nwp-cli simulate --sources`` fits one the same way when the sources
+  file has no ``[location_air]``.
+
+Fixed
+-----
+- ``sim.params.params_from_document`` raised ``TypeError`` for a list
+  field given as something else (``unfitted``, the draw domain ranges,
+  readiness ``evidence``), past the ``ValueError`` it documents and
+  that ``sim_live.overlay`` and ``nwp-cli simulate`` handle. It read a
+  string, null or bool in a number field without complaint. Each is
+  now a ``ValueError`` naming the field (#212).
+- ``HomeAssistantEnvironment`` found no inlet plateau for a probe that
+  held one value through a long draw's tail. Home Assistant's history
+  writes a row only when a value changes, so the tail had one reading
+  or none, under the plateau's 3. The probe's history is now read as
+  the value in force every 10 seconds (``held``, ``PROBE_STEP``)
+  (#216).
+
 Version 9.10.0 (2026-10-22)
 ===========================
 

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

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

@@ -96,9 +96,23 @@ Idle, it reads the cabinet, about 6 °F warm. So give one of these:
   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.
+Without the air, the command fits the standby loss on the heater's own
+reading, taken once the compressor has run 5 minutes and drawn straight
+from one run's reading to the next across the idle span between them.
+Only quiet windows with a run within 6 hours of both ends are fitted:
+they fall mostly overnight, and a reading held from the day's last run
+would read the night warm. Those windows span too narrow a range of
+tank-to-air difference to fit the loss law's shape, so only its level is
+fitted, on the base's exponent. A note says how many windows qualified
+and what share of the quiet hours they hold. Expect the loss to read
+somewhat high: at one installation, against a sensor beside the heater,
+it read about 12 % high, as the night air dips below the line between
+an evening run and a morning one, and the running reading is itself a
+little warm. A sensor beside the heater (``--air``) avoids both.
+With no such reading at all, 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 %.
@@ -205,7 +219,8 @@ read in order without holding every status:
        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
+standby loss is then fitted on the heater's own reading between runs,
+and ``done.air`` is ``"heater"``. 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
@@ -373,8 +388,11 @@ 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
+UA, and, with a circulation pump, what each run takes: its first
+gallons, up to the book's circuit volume
+(``CirculationParams.book_circuit_gal``), each at the tank's upper
+probe less the air, the loop having cooled to the air since the last
+run. ``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
@@ -402,8 +420,8 @@ draws as hot water drawn, and each run at the loop's flow.
 
 ``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).
+takes it. ``fit.book_circuit_gal`` is the circuit volume for your
+``CirculationParams`` (None without a loop).
 
 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
@@ -415,18 +433,22 @@ pair:
   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 book's circuit volume:** on 10 pairs with a run between, with
+  the book's terms fitted at each volume tried. Runs closer than
+  ``run_gap_min`` are one run. It is an effective volume, smaller than
+  the loop's own (``displaced_gal``): at one installation 1.4 gal
+  against 6.4. Fit and keep them apart. With fewer pairs, the loop is
+  priced as ``params.circulation`` prices it, 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
+circuit volume on its bound (``sim.calibration.BOOK_CIRCUIT_GAL_BOUNDS``)
+leaves the loop 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.
 
@@ -435,10 +457,10 @@ 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
+Book with the same inputs. Runs are priced at the circuit volume, 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
+since the draws hold none of the loop's water; without one, 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.
 
@@ -447,13 +469,13 @@ read outside the runs.
    from nwp500.sim.params import CirculationParams
 
    book = None
-   loss = fit.loss_btu_per_gal
-   if loss is not None or not runs:
+   volume = fit.book_circuit_gal
+   if volume is not None or not runs:
        loop = None
-       if loss is not None:
+       if volume is not None:
            loop = CirculationParams(
-               displaced_gal=..., flow_gpm=..., loss_btu_per_gal=loss,
-               meter_share=0.0,
+               displaced_gal=..., flow_gpm=..., loss_btu_per_gal=...,
+               book_circuit_gal=volume, meter_share=0.0,
            )
        book = sa.book_from_changes(
            history.rows, history.observed, replace(params, circulation=loop),

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

@@ -142,6 +142,13 @@ pass it with ``--sources`` (or set ``NWP500_SOURCES``):
    circulation_speed = "sensor.circulation_pump_speed"
    weather = "weather.forecast_home"
 
+   [home_assistant.heater]   # optional: the heater's own entities
+   heard = "sensor.water_heater_last_status"
+   upper = "sensor.water_heater_upper_tank_temperature"
+   lower = "sensor.water_heater_lower_tank_temperature"
+   compressor = "binary_sensor.water_heater_compressor"
+   ambient = "sensor.water_heater_ambient_temperature"
+
    [location_air]   # optional: air = damping x outdoor(t - lag) + offset
    damping = 0.638
    lag_hours = 2.0
@@ -159,16 +166,24 @@ give:
 
 - **the air:** the hourly forecast projected through the
   ``[location_air]`` model, shifted to pass through a reading beside the
-  heater that is at most an hour old. Without a model, that reading is
-  held over the span; without a fresh one, the projection is
-  unshifted. Fit a model for your own heater with
-  ``sim.location_air.fit``;
+  heater that is at most an hour old; without a fresh one, the
+  projection is unshifted. Without a ``[location_air]`` model, one is
+  fitted on the last 3 days of the ``air`` entity's readings against
+  the ``weather`` entity's outdoor temperature. Without an ``air``
+  entity, or one that gives no fit, the ``[home_assistant.heater]``
+  table's ``ambient`` reading while its ``compressor`` runs is fitted
+  instead, and the projection is shifted to pass through its newest
+  such reading. It is used when the
+  readings span a day and follow the outdoor air at r 0.5 or more; a
+  note gives the fit. Otherwise, and without a ``weather`` entity, the
+  reading beside the heater is held over the span;
 - **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
   ``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.
+  circulation pump with no speed reading leaves no estimate, and a draw
+  before its first reading is skipped.
 
 A reading's age is from when Home Assistant last heard the sensor
 report (``last_reported``). Over the REST API, Home Assistant serves
@@ -182,6 +197,41 @@ 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``
 and ``--environment`` override what the sources give.
 
+From Python, ``sim_home_assistant.HomeAssistantEnvironment`` reads the
+same parts. Given ``heater=``, a ``HeaterEntities`` with ``ambient`` and
+``compressor``, it fits the model without an ``air`` entity: on the
+heater's own air reading every 10 minutes while the compressor runs,
+where the reading was taken 2 minutes or more into the run (earlier, or
+idle, it reads the cabinet), and not while the sensor was unavailable.
+With a model, given or fitted, and no fresh reading beside the heater,
+each ``read`` anchors the projection to the heater's newest such
+reading from the last hour. ``fitted_air`` holds the fit once ``read``
+has run.
+
+A caller that builds a new environment every few minutes needn't refit
+each time. Fit on your own cadence, and pass the fit on:
+
+.. code-block:: python
+
+   fitted, notes = await ha.fit_location_air(
+       client, entities, now=now, heater=heater_entities
+   )   # hourly, say; None (and notes why) without enough history
+
+   environment = ha.HomeAssistantEnvironment(
+       client, entities, start=now, until=now + horizon, now=now,
+       heater=heater_entities, fitted_air=fitted,
+   )
+
+Given ``fitted_air``, the environment projects through it, notes its r
+and lag on every ``read``, and doesn't fit again.
+
+The fit, the samples of the heater's air and the inlet's plateau are
+CPU work: the fit alone takes about 100 ms on 3 days of 30-second
+readings. To keep it off an event loop, pass ``run=``, a callable that
+runs a function and awaits its result, to ``fit_location_air`` and
+``HomeAssistantEnvironment``. In Home Assistant that is
+``hass.async_add_executor_job``. Without it, the work runs inline.
+
 
 Fetch what the heater reports
 =============================
@@ -214,7 +264,10 @@ A scenario starts from four things the library already reads:
            heater=sim_live.LiveHeaterSource(mqtt, device),
            schedules=sim_live.LiveScheduleSource(mqtt, api, device),
        )
-       return sim.simulate(composed.scenario, composed.params)
+       # Without the feature info the tank size is unknown: the 65 gal
+       # defaults stand in.
+       params = composed.params or sim.default_params()
+       return sim.simulate(composed.scenario, params)
 
 ``environment=`` and ``loads=`` take any source with an ``async
 read()``; ``sim_live.Given(value)`` is one for a value in hand. Without
@@ -222,7 +275,7 @@ read()``; ``sim_live.Given(value)`` is one for a value in hand. Without
 gets no reply raises ``sim_live.LiveReadError``; so does the schedule
 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=...)``.
+unknown), so the example falls back to ``sim.default_params()``. 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:
@@ -875,14 +928,106 @@ with the instants the heater was heard from:
        params,
        at=now,
        flow=draws_gpm,        # gal/min, whatever the preferred units
+       flow_outages=flow_down,  # when the flow entity was unavailable
+       circulation=runs,      # [(start, end), ...], if you circulate
+       circulation_flow=pump_flow,  # the loop's gal/min while it runs
    )
 
-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.
+``flow`` is the household's draws. If your meter also carries the
+circulation's water, separate the household's draws from it yourself
+and pass those, with ``CirculationParams.meter_share`` 0, so the book
+takes nothing off them again. Clean up the loop's flow before passing it
+too (drop readings below the pump's floor, or one taken mid-ramp): while
+a run is on, each step takes the last reading in force (a run before
+any reading takes ``CirculationParams.flow_gpm``).
+
+Like the history's rows, its ``flow``, ``circulation_flow``, ``inlet``
+and ``air`` are changes: each value holds until the next, so a steady
+draw is one row and an hour at 0 gal/min none. They are gal/min and °F,
+whatever the preferred units. A span the heater wasn't heard from (an
+outage, or a silence much longer than its usual reporting), or the flow
+was unknown (``flow_outages``, from the history's ``outages``), breaks
+the book: it is walked only from an anchor after the last one, and is
+None while the heater isn't heard now. A record that keeps no instant
+for each of the heater's responses passes ``heard=``, the spans the
+heater was heard over, and an empty ``observed``: a gap between two
+spans breaks the book the same way, and the heater is heard now only
+inside a span. With no flow reading in force
+at the start of the window it books over, it raises ``ValueError``.
+An inlet reading holds except through ``inlet_outages``.
+
+To keep a book current as you walk every few minutes, keep the history
+rather than the book. Read only what is new since your last read,
+extend what you hold with it, trim it to the book's window, and book
+again from memory:
+
+.. code-block:: python
+
+   newer = await ha.read_heater_history(client, entities, last_read, now)
+   history = history.extended(newer).since(now - timedelta(hours=72))
+   flows = flows.extended(
+       await client.read_history([FLOW], last_read, now)
+   ).since(now - timedelta(hours=72))
+   last_read = now
+
+``HeaterHistory`` and ``History`` both take ``extended`` and ``since``.
+A read opens with the value in force at its start; as each value holds
+until the next change, that row changes nothing. Where both reads have
+a row at one instant, the later read's is kept. ``since`` keeps each
+value in force at the cut. 72 hours is ``BookParams.history_h``, the
+oldest anchor a book reads.
+
+``sim_home_assistant.HomeAssistantBook`` does all of that from Home
+Assistant's entities:
+
+.. code-block:: python
+
+   keeper = ha.HomeAssistantBook(
+       client,
+       heater_entities,                 # ha.HeaterEntities
+       "sensor.hot_water_draw_flow",   # the household's draws
+       ha.Entities(
+           circulation_speed="sensor.circulation_pump_speed",
+           inlet="sensor.cold_supply_temperature",
+           demand="binary_sensor.hot_water_demand",
+       ),
+   )
+
+   await keeper.read(now)       # all 72 h the first time, then what's new
+   answer = await hass.async_add_executor_job(keeper.book, now, params)
+   readiness = sim.time_to_ready(
+       scenario, params, book=answer.booked,
+       inlet_measured=answer.inlet_measured,
+   )
+
+``read`` reads the history since the last read and holds it; a read
+that fails is noted, and the next one reads from where it would have
+started. Until then, ``book`` takes the flow as unknown since the last
+read that worked, rather than holding its last value, and after a
+failed read of the heater it gives no book. An optional
+entity whose unit can't be read is left out of the book. With no air
+entity, or one that gives no reading, the book takes the heater's own
+air reading (``HeaterEntities.ambient``) once its compressor has run 5
+minutes, and holds it until the next run, and a note says so. Idle, that
+sensor reads the cabinet, about 6 °F warm, so an idle reading is never
+taken. Before the first run, and while an air entity that gives readings
+is unavailable or reads in a unit the book doesn't read, the book takes
+the default air (65 °F). ``book`` books from what it holds, with no
+request, so it can run in an executor. ``answer.notes`` say what the book rests on, or why
+there is none.
+
+The flow is the household's hot water draws, without the circulation's
+water, in gal/min or any unit ``to_gpm`` reads. It is the water
+delivered at the taps, through the mixing valve: the book prices a
+delivered gallon at the valve's delivery line
+(``DrawParams.delivery_intercept_f`` and ``delivery_slope``), not as
+water withdrawn from the tank. As none of the flow is circulation,
+``book`` takes ``CirculationParams.meter_share`` as 0. A flow entity that reports a draw late
+reaches the book late: the book holds what the history holds at
+``read``. Each of the other entities is optional:
+``circulation_speed`` gives the circulation's runs, ``inlet`` the inlet
+the book converts at, ``inlet`` with ``demand`` the mains, and ``air``
+the air beside the heater.
 
 Without a meter, start one only when you know the tank is full and
 quiet (``sa.full_tank_book``).
@@ -1023,15 +1168,18 @@ to a day apart. Each pair's booked heat is checked against the probes':
        circulation=runs, circulation_flow=pump_flow, params=params,
    )
    book = calibration.RecordedBook(steps, p, params.circulation, start=since)
-   fit = calibration.fit_book_terms(book, book.reanchors(), p)
+   fit = calibration.fit_book_terms(book, book.reanchors(), p, circuit=True)
    p = replace(p, hp_btu_per_h=fit.hp_btu_per_h,
                hp_btu_per_h_per_f=fit.hp_btu_per_h_per_f,
                ua_btu_per_h_f=fit.ua_btu_per_h_f)
-   bands = calibration.book_error_bands(book, p, fit.loss_btu_per_gal)
-   empty, crossings = calibration.empty_point(book, p, fit.loss_btu_per_gal)
-   zone = calibration.zone_empty_point(book, p, fit.loss_btu_per_gal)
-
-``book_error_btu(book, p, fit.loss_btu_per_gal)`` gives the book's
+   v = fit.book_circuit_gal
+   bands = calibration.book_error_bands(book, p, 0.0, v)
+   empty, crossings = calibration.empty_point(book, p, 0.0, circuit_gal=v)
+   zone = calibration.zone_empty_point(book, p, 0.0, circuit_gal=v)
+
+With ``circuit=True`` the runs are priced at a circuit volume
+(``CirculationParams.book_circuit_gal``) fitted in place of a loss per
+gallon. ``book_error_btu(book, p, 0.0, v)`` gives the book's
 error bands: the 90th percentile of its error pooled over re-anchors an
 hour to ``max_anchor_age_h`` apart, and the 18 to 24 h band's past it,
 each rounded up to 100 BTU. ``cold_lower_cap(draws,

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

@@ -154,7 +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,
+      fit_terms_l1, BOOK_TERMS, BOOK_TERM_BOUNDS, BOOK_CIRCUIT_GAL_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,
@@ -305,17 +305,22 @@ Recorded history
       fit_book, BookTermsFit, MIN_BOOK_PAIRS, MIN_RUN_PAIRS,
       score, Judged, HeldOut, GROUPS, air_unread_note,
       CalibrationInputError, DEFAULT_HUMIDITY_PCT,
-      DEFAULT_BASE_NOTE, NO_AIR_NOTE
+      DEFAULT_BASE_NOTE, NO_AIR_NOTE, HEATER_AIR_BRACKET
 
 
 Home Assistant sources
 ======================
 
 .. automodule:: nwp500.sim_home_assistant
-   :members: HomeAssistantEnvironment, HomeAssistantClient, record_inputs,
-      RecordInputs, INLET_LOOKBACK, Sources, Entities, sources_from, State, parse_state,
+   :members: HomeAssistantEnvironment, HomeAssistantClient, fit_location_air,
+      Run, inline, HomeAssistantBook, BookAnswer, BOOK_WINDOW,
+      mains_plateau, known_runs,
+      record_inputs,
+      RecordInputs, INLET_LOOKBACK, PROBE_STEP, held, LOCATION_AIR_WINDOW,
+      LOCATION_AIR_MIN_SPAN, LOCATION_AIR_MIN_R, RUN_SETTLE, Sources,
+      Entities, sources_from, State, parse_state,
       parse_history, parse_outages, parse_states, History, history_for,
-      parse_forecast, read_heater_history, HeaterEntities, HeaterHistory,
+      parse_forecast, parse_outdoor_history, read_heater_history, HeaterEntities, HeaterHistory,
       HISTORY_WINDOW, to_w, to_wh,
       pump_runs, demand_spans, busy, covers_start, percent,
       fresh, to_f, to_gpm, to_gal, to_rpm, HomeAssistantError