Drop every contained period from the fast cache when deleting or setting a period

[MaxGhenis]

Problem

Holder.delete_arrays(period) deletes every stored period that period contains. Deleting "2012" also deletes "2012-01" to "2012-12", and any period deletes an ETERNITY variable's one value. set_input handlers likewise store every month of an annual input.

The simulation's _fast_cache (checked at the top of calculate) was evicted by popping only the exact (variable, period) key. So calculate kept returning values storage had deleted or replaced.

Found by the adversarial review (GPT-6.1 Sol, 2026-10-01) of #562. It reproduces on master 7950c01 and b78b0ba. Each case below returns the stale value on master and the right one here:

Path	Case	master	This PR
delete_arrays	Monthly float input with auto-carry-over: set_input("m","2012-01",[100]), calculate("m","2012-02"), delete_arrays("m","2012"), set_input("m","2012-01",[200]). get_array("m","2012-02") is None.	calculate("m","2012-02") is 100	200, as in a fresh simulation
delete_arrays	ETERNITY formula 2 × e: calculate for 2013, delete_arrays it for 2012, set e to 7	10	14
set_input	ETERNITY input calculated for 2012 (default 0), then set_input(..., "2013", [5]). Storage holds 5.	0	5
set_input	Cache-blacklisted monthly variable with set_input_divide_by_period: February calculated (0), then set_input(..., "2012", [1200]). Storage holds 100.	0	100
purge_cache_of_invalid_values	Monthly formula m + 1 calculated for 2012-02, then (name, "2012") invalidated and purged, then m set to 20	11	21

Fix

Simulation._evict_fast_cache(variable_name, period=None) drops each of the variable's fast-cache entries whose period period contains, using the same Period.contains test as InMemoryStorage.delete. It drops all of the variable's entries when period is None or the variable is defined for ETERNITY. delete_arrays, set_input and purge_cache_of_invalid_values call it instead of popping one key.

• Scope. The fast cache belongs to one simulation object (clone, and so get_branch, start a new one), so the scope matches delete_arrays: this simulation, not its branches.
• Cost. With an empty cache it returns at once, so building a simulation from a dataset does no extra work. Otherwise it scans the cache once per call. delete_arrays without a period already rebuilt the whole dict.
• No new eviction triggers. Every entry it drops is one storage no longer holds or has just replaced.

Invariants (Hypothesis properties in test_fast_cache_contained_periods_property.py)

1. The fast cache never changes what calculate returns. Random sequences of set_input, calculate and delete_arrays run on two simulations; one empties its fast cache before every calculate. Every result agrees (value, or error type), and so does every stored value at the end.
   • Variables: a monthly input with a formula on it, a monthly input split from annual values, a yearly input, and an ETERNITY input with a formula.
   • Periods: months, years and ETERNITY.
   • Sequences span all variables or focus on one of them.
2. delete_arrays drops from the fast cache exactly what it drops from storage. Afterwards the variable's fast-cache periods equal its stored periods, for any mix of day, month, year and multi-unit periods. Other variables' entries are untouched, so nothing is evicted needlessly.

Tests

• tests/core/test_fast_cache_contained_periods.py: 7 example tests.
  • 6 fail on master b78b0ba.
  • The 7th pins that deleting a month keeps the rest of the year cached.
• tests/core/test_fast_cache_contained_periods_property.py: the two properties.
  • Both fail on master. Shrunk example: calculate a monthly input for 2012-01 (default 0), delete_arrays it for ETERNITY, calculate again. master answers from the stale entry and never stores the value again.
  • The module starts with pytest.importorskip("hypothesis"), because the smoke job installs no dev dependencies.
• Shared variables and builder: tests/fixtures/fast_cache_contained_periods.py.
• Mutation check (each mutant applied to a copy and run against the new tests plus test_fast_cache.py and test_fast_cache_guards.py): all 7 mutants killed.
  • Exact-key pop in each of the three call sites.
  • No ETERNITY rule.
  • Reversed containment.
  • No eviction when a period is given.
  • Evicting the whole variable (killed by the two "keeps what it does not contain" tests and property 2).
• Full suite (Python 3.13): 1,152 passed, 4 skipped, 1 xfailed. Country-template YAML tests: 39 passed. uvx ruff format --check . and uvx ruff check . pass.
• PE-US/PE-UK single-year A/B (core master b78b0ba vs this branch, same country code and data): outputs are bitwise identical, so no published number moves.
  • PE-UK (main c7e826ea5, Enhanced FRS 2026): 36 of 36 arrays identical, including marginal_tax_rate; user CPU 9.49 s vs 9.45 s.
  • PE-US (main fbe24ad1b3, Enhanced CPS 2026, 3,000-household subsample, with marginal_tax_rate, which creates a branch per adult and calls delete_arrays and set_input on it): 25 of 25 arrays identical; income tax $1,962.456bn on both.
  • Eviction cost in the PE-US run: 12,460 calls, 0.002 s in total. The cache was empty in all but 202 calls and never held more than one entry when scanned.
  • Wall times on the shared host were too noisy to compare.

Not in this PR

• On-disk derivative() overwriting the source's input (the same review's other finding). OnDiskStorage.clone shares .npy files, so the clone's set_input overwrote the parent's file: derivative [0], input afterwards [101].
  • Give each disk-backed holder storage its own directory #558 fixes it with copy-on-write storage directories.
  • The review's exact repro passes on Give each disk-backed holder storage its own directory #558 (derivative [1], input stays [100], carry-over 100) and is a regression test there (test_derivative_of_a_carried_over_input_leaves_it).
• OnDiskStorage.delete(period) removing only the exact key (OnDiskStorage.delete(period) deletes only that exact period, not the periods within it #564). With disk storage, deleting "2012" leaves "2012-01" and "2012-02" in storage, so the first table row still returns 100 from disk. Delete the periods within a deleted period from disk storage #565 fixes that.
  • Whichever of Delete the periods within a deleted period from disk storage #565 and this PR lands second adds the end-to-end disk test (the first row on a disk-backed simulation), which needs both fixes.
• Values calculated from a deleted or replaced input (for example a 2013 value carried over from 2012) stay in holder storage, as before: Make set_input on a branch drop values calculated from the input it replaces #560 and Carry over only inputs, the latest at or before the requested period #562.
• Holder.delete_arrays and Holder.set_input called directly (code that bypasses Simulation) still leave the simulation's fast cache alone, as before. Direct callers on current mains (PE-US fbe24ad1b3, PE-UK c7e826ea5):
  • PE-US system.py (input renames) and PE-UK Simulation.move_values run while the simulation is built, before anything is calculated.
  • PE-US tob_revenue_oasdi.py and tob_revenue_medicare_hi.py call holder.set_input on a branch created a moment before, whose fast cache is still empty.
  • PE-US tools/branched_simulation.py is imported but not used.
  • PE-UK utils/solve_private_school_attendance_factor.py deletes on a fresh Microsimulation's baseline before calculating.
  • PE-UK utils/dependencies.py (an analysis helper, not part of model runs) deletes through the holder right after calculate, so a later calculate without map_to reads the old value from the fast cache. That is a bug in the helper, to fix there with sim.delete_arrays; this PR doesn't change it.

Overlap with other PRs

• Keep the record of set_input values in step with storage #561 adds lines to the Simulation.delete_arrays docstring above the :param line this PR edits. They are separate hunks.
• Make set_input on a branch drop values calculated from the input it replaces #560 adds drop_computed_arrays right after delete_arrays, and its store-history helpers right after set_input, next to the eviction lines this PR replaces. Whichever lands second keeps both sides of those two hunks. Make set_input on a branch drop values calculated from the input it replaces #560 also changes when _calculate writes into _fast_cache, which this PR doesn't touch.
• The session making spirals and STOCK caches order-safe (branch fix-stock-option-caches) leaves the eviction line in purge_cache_of_invalid_values to this PR. It may change the holder-deletion branch scope on the line before.

axiom: n/a: core cache infrastructure, no policy change

🤖 Generated with Claude Code