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

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

@@ -2,6 +2,90 @@
 Changelog
 =========
 
+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)
+==========================
+
+Added
+-----
+- **Refine a fit without making it worse** (``keep_better=True`` on
+  ``sim_calibrate.calibrate`` and ``calibrate_changes``, #184). Each
+  group of terms holds out its latest evidence from its refit (the last
+  fifth, once it has 10 items) and keeps the existing values unless the
+  refit scores better there, by the error its own fit minimizes. The
+  terms in a group are kept or replaced together. ``Calibrated.judged``
+  records each judgement, and the report's reasons give both scores.
+  ``sim_calibrate.score(done, params)`` scores any parameters on that
+  held-out evidence.
+- ``sim.calibration.split_recoveries``, ``recovery_minutes``,
+  ``power_cycles`` and ``cop_cycles``: the evidence the compressor and
+  power fits use, and their predictions, which ``fit_compressor``,
+  ``fit_power_scale`` and ``fit_cop_scale`` now take from.
+
+Fixed
+-----
+- **The report names compressor runs without an air temperature.**
+  A recovery is timed against the air, so a run with none (no air
+  given, and no heater ambient reading while the compressor runs) is
+  left out of the recoveries. The report blamed the heater instead:
+  "0 recoveries reached their target". ``Calibrated`` now counts the
+  runs (``n_runs``, ``n_runs_without_air``), and the compressor term's
+  reason and the notes say how many had no air
+  (``sim_calibrate.air_unread_note``).
+- ``sim.calibration.with_standby`` quotes the fitted UA at the ΔT the
+  law was fitted at (50 °F). It kept the ``ua_ref_delta_t_f`` of the
+  parameters it was given, so a refit applied over parameters quoted at
+  another ΔT ran as a different loss law.
+- ``sim.calibration.fit_cop_scale`` takes the integrator's COP on the
+  heater's own tank (``HeaterParams.tank``), as the simulation does. It
+  used the default tank's mass, so a heater with another tank was fitted
+  against a COP the simulation does not run.
+
 Version 9.7.0 (2026-10-21)
 ==========================
 

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

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

{nwp500_python-9.7.0 → nwp500_python-9.9.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.7.0 → nwp500_python-9.9.0}/docs/how-to/calibrate-simulator.rst

@@ -139,16 +139,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
@@ -223,6 +230,48 @@ Assistant integration, can calibrate the same way:
 4. Store ``params_to_document(done.calibration.params)``, and show the
    ``report(done)`` rows and ``done.notes``.
 
+Refine an existing fit
+----------------------
+
+A fit made on months of history should not give way to one made on the
+last ten days unless the new one predicts better. Pass the existing
+fit as ``params`` with ``keep_better=True``:
+
+.. code-block:: python
+
+   done = sim_calibrate.calibrate(
+       recorded(days), ambient=65.0, params=existing, keep_better=True
+   )
+   for j in done.judged:
+       print(j.group, j.kept, j.base_error, j.refit_error, j.why)
+
+Each group of terms holds out its latest evidence from its refit:
+
+- 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;
+- the COP terms: the cycles the COP fit can use (without a meter of
+  draws, those no water was drawn around).
+
+Once a group has 10 items, the latest fifth (at least 2) is held out.
+The refit replaces the existing values only where it scores better on
+them, by the error its own fit minimizes. With fewer items the existing
+values stay. The terms in a group are kept or replaced together, and the
+report's reasons say which, with both scores.
+``sim_calibrate.score(done, params)`` gives those errors for any
+parameters.
+
+Use it over a fit of this heater. The defaults are another heater's fit,
+and ``keep_better`` keeps them wherever there is too little evidence to
+judge by. A group the existing fit lists as unfitted takes its refit, as
+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.
@@ -294,6 +343,12 @@ leave out what your installation does not record. ``read_heater_history``:
 - notes a value it could not read, and an entity whose history starts
   after ``start``.
 
+A recovery is timed against the air, so the compressor and power fits
+need an air temperature over each compressor run: the air beside the
+heater (``record=``, ``air`` or ``ambient``), or the heater's own reading
+(``ambient`` in ``HeaterEntities``). Runs without one are no recovery,
+and the report says how many there were.
+
 Give ``anti_legionella`` where it is recorded. Without it an
 anti-legionella cycle is not kept out of the recoveries, and the notes
 say so.

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

@@ -150,7 +150,8 @@ Hot water and the heat book
 
 .. automodule:: nwp500.sim.calibration
    :members: calibrate, Calibration, fit_standby, StandbyFit, StandbyWindow,
-      fit_compressor, CompressorFit, clean_draws, CleanDraw, crossing,
+      fit_compressor, CompressorFit, split_recoveries, recovery_minutes,
+      clean_draws, CleanDraw, crossing,
       demonstrated, frontier, capacity, held_out, fit_evidence,
       EvidenceFit, cold_lower_cap, RecordedBook, fit_book_terms, BookFit,
       book_error_bands, book_error_btu, empty_point,
@@ -163,11 +164,13 @@ Hot water and the heat book
       element_off_points, element_power, element_grid, element_runs,
       fit_element_rates, ElementRateFit, day_ci,
       energy_saver_off_deficit, upper_start_edge, fit_power,
-      PowerFit, fit_power_scale,
+      PowerFit, fit_power_scale, power_cycles, cop_cycles, CopCycle,
       fit_cop_scale, solve_cop_fit, solve_cop_scale, draw_free_withdrawn,
       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
@@ -249,7 +252,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,
@@ -299,6 +302,7 @@ Recorded history
 
 .. automodule:: nwp500.sim_calibrate
    :members: calibrate, calibrate_changes, Calibrated, report, Term, max_gap,
+      score, Judged, HeldOut, GROUPS, air_unread_note,
       CalibrationInputError, DEFAULT_HUMIDITY_PCT, GAP_SAMPLES, MIN_GAP,
       DEFAULT_BASE_NOTE, NO_AIR_NOTE
 

{nwp500_python-9.7.0 → nwp500_python-9.9.0}/src/nwp500/sim/api.py

@@ -78,7 +78,7 @@ from nwp500.sim.inputs import (
     Schedules,
     Settings,
 )
-from nwp500.sim.params import HeaterParams
+from nwp500.sim.params import TAU_GAP_PRIOR_H, HeaterParams
 from nwp500.sim.physics.compressor import MAX_MINUTES, predict_physics_detailed
 from nwp500.sim.physics.element import (
     DEVICE_MODE,
@@ -224,10 +224,6 @@ LOW_CONFIDENCE_FLOOR = 0.6
 #: start was never searched (the TOU-opening start still was), so an
 #: answer may miss a start the heater makes.
 HP_LOWER_ON_UNKNOWN = "hp_lower_on_unknown"
-#: The gap time constant served when the parameters carry none
-#: (``TankParams.stratification_gap_tau_h``), h: history puts it near
-#: 60 h on this product.
-TAU_GAP_PRIOR_H = 60.0
 #: Draws opened a gap that closes on that prior, not a fitted constant:
 #: under no draws it only shapes how an existing gap closes.
 TAU_GAP_PRIOR = "tau_gap_prior"