Skip to content

Derive reform tax-benefit systems from the built default system - #11129

Draft
anth-volk wants to merge 2 commits into
mainfrom
derive-reform-systems-from-baseline
Draft

anth-volk wants to merge 2 commits into
mainfrom
derive-reform-systems-from-baseline

Conversation

@anth-volk

Copy link
Copy Markdown
Contributor

Warning

Draft: do not merge. This PR stays in draft until both required dependencies below are met.

Dependencies

Required

Dependency State Why this PR needs it Follow-up here
PolicyEngine/policyengine-core#660, merged and released Open; not in a core release It links scale brackets and homogenized parameter nodes to their parents. Without those links, a reform changes the modified flags on different ancestors in a cloned parameter tree than in a loaded one, so a derived system does not match a full build. Raise the policyengine-core minimum in pyproject.toml and update uv.lock to that release
PolicyEngine/policyengine-us#11126, merged Open It removes a test assertion that brackets[1].parent is None, which fails on the core release above. Rebase onto it; that test change stays out of this PR

Related, not required

PolicyEngine/policyengine-us#11121 also edits policyengine_us/tools/per_capita_uprating.py and changes which structural reforms build. Whichever PR merges second resolves any text conflict. If it merges first, the comparison below is rerun with it included.

CI: this branch still installs the locked core version (uv.lock has 3.36.0), which has no parent links. Tests that compare a derived system with a full build are expected to fail until the core dependency is met.

What and why

Creating a Simulation or Microsimulation with reform= and no tax_benefit_system= builds a new CountryTaxBenefitSystem, which reloads about 12,000 parameter files and 12,300 variable files. Almost none of that work depends on the reform.

_prepare_spm_system now asks the built default system to derive the reform's system:

  1. Clone the default parameter tree and undo the per-capita uprating step that the default build ran last.
  2. Restore the variable registry from before the reform-dependent steps.
  3. Run those steps (_apply_reforms) on the copy, including structural-reform detection at start_instant.
  4. Apply with_parameter_barrier, as before.

It uses a full build when derivation cannot give the same result: the default system's variable registry or per-capita parameter nodes changed, a parameter is marked modified, or the system class has its own constructor.

Who is affected: .py passes reform= without a system, so its household calculations and microsimulations use this path. API v1 society-wide simulations reach it through the simulation API and .py. Household calculations in API v1 and the household API do not: they clone their own system, apply the reform and pass tax_benefit_system=.

Known limit: changes to the shared default system that set no modified flag are not detected, such as add_child, merge, assignments to values_list[i].value, and metadata or variable attribute edits. A derived system includes them, as simulations sharing the default system already do; a full build would not. The can_derive_reform_systems docstring records this. A text search of the default branches of API v1, the household API, the simulation API, .py and app-v2 found no code that edits a policyengine-us system in place.

Evidence

Comparison with a full build: 846 reforms, no differences. The code compared has the same tree as this PR's first commit (1269314122). It ran on core commit 1ce7fd23, an earlier commit of policyengine-core#660.

Outcome Reforms
Same system and simulation results 825
Full build rejects the reform; derivation raises the same error type and message 20
Same VariableNameConflictError in the simulation steps 1

The default system was unchanged throughout. The corpus contains no stored production policies.

Build time per reform system (local macOS):

Measurement Full build Derived
Median over the comparison, 2 workers 9.61 s 3.54 s
Separate clean processes 6.8 s 2.75 to 3.1 s

These are not Modal or Linux CI measurements.

Not yet covered: policyengine-core#660 has moved 4 commits past 1ce7fd23. The 20 new tests pass on its current head (84e4d33e), but the 846-reform comparison has not been rerun there.

Test plan

  • 20 new tests in policyengine_us/tests/core/test_derived_reform_system.py, run by node ID against policyengine-core#660 at 84e4d33e: all pass
  • Rerun those tests on the released core version
  • Rerun the 846-reform comparison on the released core version, after rebasing
  • For policy changes: not applicable, this changes how a system is built and no policy
  • Source-conflict register: not applicable
  • ruff format on the changed Python files
  • Changelog fragment in changelog.d/

Test cost: the new file took 145.8 s elapsed, 124.9 s user CPU and a peak of 4.89 GB resident memory on macOS with Python 3.14. This is not a Linux CI measurement. The file falls in the rest-python core group, which already measured 13.3 GB in CI run 38141803955 against a target of about 10 GB per process, so it may need its own group in REST_PYTHON_GROUPS. That decision waits for this group's CI report.

axiom: n/a: changes how the tax-benefit system is constructed, with no policy change

🤖 Generated with Claude Code

anth-volk and others added 2 commits November 19, 2026 00:32
Creating a Simulation or Microsimulation with a reform and no supplied
tax-benefit system rebuilt CountryTaxBenefitSystem from every parameter
and variable file. Copy the built default system instead, return it to
its state before the reform-dependent steps, and run those steps on the
copy. Fall back to a full build when the default system has changed in
a way that would make the copy differ.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

This branch has not been deployed

No deployments
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant