perf: cache window bounds and replace deepcopy on window lists (-21% planning) (#4536)

* perf(plan): replace copy.deepcopy on window lists with a shallow clone

Window dicts only ever hold primitives (start/end/average/target/id/key), so
copy.deepcopy's generic recursive walk is doing no work that a per-dict .copy()
does not - measured 30.0us vs 1.6us per call on a 48-window list, 18.5x.

Adds utils.clone_windows() and uses it for the 13 planning-path deepcopy call
sites, plus a plain .copy() for the flat {minute: float} load forecast in
calculate_marginal_costs.

The copies exist for isolation, not just duplication: thread_run_prediction_export
writes export_window[window_n]["start"] in place, and plan_window_snapshot /
preclip_new are restored later. clone_windows keeps that contract - each dict is
copied, so in-place writes cannot leak either way - and the new tests pin it.

This is performance-neutral on the benchmark: 20 scenarios A/B, 3 reps each, came
out within noise (-0.4% median against ~6% run-to-run spread), because these call
sites were only ~1.5% of plan time. Kept for the explicit isolation contract and
the reduced allocation churn (deepcopy invocations -30%, total calls -3.4%), not
for a speed claim.

Verified byte-identical: all 20 random scenarios unchanged on metric, cost, and
all three PV futures (+0.0000 across the board).

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>

* perf(kernel): cache window bounds instead of re-deriving them per simulation

A search runs thousands of simulations over the same charge/export windows,
varying only the limits, but every call re-derived the window start/end bounds
from the window dicts - four ctypes arrays for the kernel scenario and two tuples
for the prediction cache key. That was the largest single block of Python time in
a plan.

Caches them in prediction_kernel keyed on the identity of the window list, with
the derived fields built lazily so a caller that only wants the hash tuple never
pays to build the ctypes arrays. Hit rate on the benchmark is ~94%.

Correctness rests on every mutation of a window's start/end invalidating the
cache, so the 16 in-place assignments on the planning path now go through
set_window_start()/set_window_end(). The guard is run_window_cache_tests, which
replays a full calculate_plan with VALIDATE_WINDOW_CACHE on - that re-derives the
bounds on every cache hit and raises on any stale entry, so a future bare
window["start"] = ... on this path fails the suite rather than silently
simulating the wrong window geometry. The test also asserts the validator itself
catches a planted stale entry, so it cannot pass vacuously.

Pool workers unpickle fresh window lists every call and can never hit the cache,
where leaving it on cost ~3% of a pooled plan, so Pool() now runs
disable_window_cache as its worker initialiser. The cache is bounded and pins the
lists it keys on, so a caller that never repeats a list cannot grow it without
limit or alias a freed list's id() onto the wrong entry.

Measured on random scenario 0 (median of 3):
  threads=0     2366.3ms -> 1839.0ms   -22.3%
  threads=auto  2134.0ms -> 2146.8ms   +0.6% (noise)
C++ share of plan time rises from 43.7% to 56.2%; pk_run itself is unchanged at
19,209 calls of 55.0us, which is what confirms the simulation work is identical.
The 20 scenario benchmark drops 42.6s -> 33.4s.

Verified byte-identical: all 20 random scenarios unchanged on metric, cost and
all three PV futures, and kernel_parity passes.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>

* fix(kernel): key the window bounds cache on the window count as well as identity

Addresses two of the three review comments on this PR.

A window list that grows or shrinks in place keeps its id(), so identity alone was
not enough to decide a cache hit. run_prediction_kernel passes n_charge/n_export
from len(window_list) alongside the cached arrays, so a stale shorter array would
be read past its end by the C kernel - a memory-safety failure rather than merely
a wrong plan. The count is now part of the hit condition.

Nothing on the planning path resizes a window list today, so this guards the class
rather than fixing a live defect. The test proves it would have bitten: before the
change, appending to a cached list left a one-entry bounds array against two
windows, and popping left window_bound_tuple returning the longer tuple.

Also corrects the correctness note, which pointed at Plan.set_window_start() and
Prediction.set_window_start(). Neither exists - they are module functions here -
and after the rebase the prediction path does not use them at all, since
_prepare_export applies a trial start copy-on-write to a window dict and list of
its own.

The third comment, to build the bound tuple from a generator rather than a list
comprehension, is not taken: measured over 50k calls at 200 windows, the generator
is 19.3% slower (307ms against 366ms), because it pays per-item interpreter
overhead the specialised list comprehension avoids.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>

---------

Co-authored-by: Claude Opus 5 (1M context) <noreply@anthropic.com>

Author: springfall2008

.cspell/custom-dictionary-workspace.txt

@@ -528,6 +528,7 @@ undiscounted
 unnormalised
 unparseable
 unpickled
+unpickles
 unpushed
 unsmoothed
 unstaged

apps/predbat/plan.py

@@ -22,14 +22,8 @@
 byte-identical plan comparison is what keeps it that way.
 """
 
-from operator import itemgetter
-
 from const import PREDICT_STEP
-from prediction_kernel import BatchJob, kernel_supported, run_prediction_kernel_batch
-
-# Pulls (start, end) from a window dict; used to build the prediction cache key without a Python
-# level loop over every window
-window_bounds = itemgetter("start", "end")
+from prediction_kernel import BatchJob, kernel_supported, run_prediction_kernel_batch, window_bound_tuple
 
 
 def prediction_cache_key(charge_limit, charge_window, export_limits, export_window, pv_scenario, end_record, step):
@@ -39,13 +33,18 @@ def prediction_cache_key(charge_limit, charge_window, export_limits, export_wind
     different keys depending on which path reached it. Built as one tuple hash to keep the per-window
     hashing in C rather than looping in Python, which matters because it runs on every simulation
     with a few hundred windows.
+
+    The window bound tuples come from the identity-keyed cache in prediction_kernel, so a fan-out
+    that varies only the limits derives them once rather than once per simulation. That cache is kept
+    honest by set_window_start/set_window_end invalidating it; run_window_cache_tests replays a full
+    plan with VALIDATE_WINDOW_CACHE on to prove no mutation escapes them.
     """
     return hash(
         (
             tuple(charge_limit),
-            tuple(map(window_bounds, charge_window)),
+            window_bound_tuple(charge_window),
             tuple(export_limits),
-            tuple(map(window_bounds, export_window)),
+            window_bound_tuple(export_window),
             pv_scenario,
             end_record,
             step,

apps/predbat/prediction_batch.py

@@ -389,6 +389,126 @@ def int32_array(values):
     return (ctypes.c_int32 * len(backing)).from_buffer(backing)
 
 
+# ---------------------------------------------------------------------------
+# Window bounds cache
+#
+# A search re-runs thousands of simulations over the same charge/export windows, changing only the
+# limits. The start/end bounds handed to the kernel are therefore identical call after call, but
+# were re-derived from the window dicts every time - measured as the largest single block of Python
+# time in a plan. They are cached here, keyed on the identity of the window list.
+#
+# CORRECTNESS: the cache is only sound while no window's start or end changes underneath it. Every
+# such mutation must call invalidate_window_cache() - route them through the set_window_start() and
+# set_window_end() helpers below rather than assigning window["start"] or window["end"] directly.
+# The prediction path does not need them: _prepare_export applies a trial start copy-on-write, to a
+# window dict and list of its own, so nothing the cache has seen is touched. run_window_cache_tests replays a full plan with VALIDATE_WINDOW_CACHE on, which
+# re-derives the bounds on every hit and fails on any stale entry, so a missed invalidation is a
+# test failure rather than a silently wrong plan.
+#
+# Entries pin their window list (so a freed list cannot have its id() reused by a later
+# allocation, which would alias to the wrong entry) and the cache is bounded, so a caller that
+# never repeats a list - a forked pool worker, which unpickles fresh lists every call - thrashes
+# harmlessly within the bound instead of growing without limit.
+# ---------------------------------------------------------------------------
+WINDOW_CACHE_MAX = 16
+VALIDATE_WINDOW_CACHE = False
+WINDOW_CACHE_ENABLED = True
+_WINDOW_BOUNDS_CACHE = {}
+
+
+def disable_window_cache():
+    """Turn the window bounds cache off in this process - used as the pool worker initialiser.
+
+    A worker unpickles fresh window lists on every call, so it can never hit the cache; leaving it
+    on there only pays the failed lookup. Measured at ~3% of a pooled plan.
+    """
+    global WINDOW_CACHE_ENABLED
+    WINDOW_CACHE_ENABLED = False
+    _WINDOW_BOUNDS_CACHE.clear()
+
+
+def invalidate_window_cache():
+    """Drop all cached window bounds - must be called whenever a window's start or end changes"""
+    _WINDOW_BOUNDS_CACHE.clear()
+
+
+def set_window_start(window, start):
+    """Set a window's start time, invalidating any cached bounds derived from it.
+
+    Use this instead of assigning window["start"] directly - see the window bounds cache notes
+    above for why a bare assignment is unsafe.
+    """
+    if window["start"] != start:
+        window["start"] = start
+        _WINDOW_BOUNDS_CACHE.clear()
+
+
+def set_window_end(window, end):
+    """Set a window's end time, invalidating any cached bounds derived from it - see set_window_start"""
+    if window["end"] != end:
+        window["end"] = end
+        _WINDOW_BOUNDS_CACHE.clear()
+
+
+def _window_cache_entry(window_list):
+    """Return the cache entry [window_list, starts, ends, bounds_tuple] for a window list.
+
+    The derived fields start as None and are filled in on first use, so a caller that only wants
+    the hash tuple never pays to build the ctypes arrays, and vice versa.
+    """
+    key = id(window_list)
+    entry = _WINDOW_BOUNDS_CACHE.get(key)
+    # The window count is part of the hit condition, not just the identity: a list that grows or
+    # shrinks in place keeps its id(), and run_prediction_kernel passes n_charge/n_export from
+    # len(window_list) alongside these arrays. A stale shorter array would then be read past its end
+    # by the C kernel - a memory-safety failure rather than merely a wrong plan. Bare start/end
+    # writes are handled by set_window_start/set_window_end instead; nothing on the planning path
+    # resizes a window list today, so this is a guard against the class rather than a live fix.
+    if entry is not None and entry[0] is window_list and entry[4] == len(window_list):
+        if VALIDATE_WINDOW_CACHE:
+            _validate_entry(window_list, entry)
+        return entry
+    if len(_WINDOW_BOUNDS_CACHE) >= WINDOW_CACHE_MAX:
+        _WINDOW_BOUNDS_CACHE.clear()
+    entry = [window_list, None, None, None, len(window_list)]
+    _WINDOW_BOUNDS_CACHE[key] = entry
+    return entry
+
+
+def window_bound_arrays(window_list):
+    """Return (start_array, end_array) as ctypes int32 arrays for a window list, cached by identity.
+
+    The returned arrays are shared with other callers and must not be modified.
+    """
+    if not WINDOW_CACHE_ENABLED:
+        return int32_array([window["start"] for window in window_list]), int32_array([window["end"] for window in window_list])
+    entry = _window_cache_entry(window_list)
+    if entry[1] is None:
+        entry[1] = int32_array([window["start"] for window in window_list])
+        entry[2] = int32_array([window["end"] for window in window_list])
+    return entry[1], entry[2]
+
+
+def window_bound_tuple(window_list):
+    """Return a tuple of (start, end) pairs for a window list, cached by identity (prediction cache key)"""
+    if not WINDOW_CACHE_ENABLED:
+        return tuple([(window["start"], window["end"]) for window in window_list])
+    entry = _window_cache_entry(window_list)
+    if entry[3] is None:
+        entry[3] = tuple([(window["start"], window["end"]) for window in window_list])
+    return entry[3]
+
+
+def _validate_entry(window_list, entry):
+    """Re-derive the bounds and raise if the cached entry is stale (VALIDATE_WINDOW_CACHE only)"""
+    starts = [window["start"] for window in window_list]
+    ends = [window["end"] for window in window_list]
+    if entry[1] is not None and (starts != list(entry[1]) or ends != list(entry[2])):
+        raise AssertionError("Stale window bounds cache (arrays): a window changed without invalidate_window_cache().\n  starts cached {} actual {}\n  ends   cached {} actual {}".format(list(entry[1]), starts, list(entry[2]), ends))
+    if entry[3] is not None and tuple(zip(starts, ends)) != entry[3]:
+        raise AssertionError("Stale window bounds cache (tuple): a window changed without invalidate_window_cache().\n  cached {}\n  actual {}".format(entry[3], tuple(zip(starts, ends))))
+
+
 def kernel_context_free(handle):
     """Free a kernel context by handle (used as a weakref finaliser)"""
     if KERNEL_LIB and handle:
@@ -774,11 +894,9 @@ def run_prediction_kernel(pred, charge_limit, charge_window, export_window, expo
     # The window fields keep their list comprehensions - map(itemgetter(...)) measured *slower* here at these
     # list lengths, the per-item call overhead outweighing what the comprehension costs.
     scenario.charge_limit = double_array(charge_limit)
-    scenario.charge_start = int32_array([window["start"] for window in charge_window])
-    scenario.charge_end = int32_array([window["end"] for window in charge_window])
+    scenario.charge_start, scenario.charge_end = window_bound_arrays(charge_window)
     scenario.export_limits = double_array(export_limits)
-    scenario.export_start = int32_array([window["start"] for window in export_window])
-    scenario.export_end = int32_array([window["end"] for window in export_window])
+    scenario.export_start, scenario.export_end = window_bound_arrays(export_window)
     # A cached run discards the per-minute SoC series (see the `if not cache` block below), so the
     # buffer is not allocated and the kernel is told to skip filling it. That skips a round_py per
     # step, which is snprintf+strtod and the single most expensive thing in the kernel's hot loop -