[MaxGhenis]

On master, a formula that reads a variable with options=[ADD] or options=[DIVIDE] raises this error in a Microsimulation, though a Simulation computes it:

TypeError: Microsimulation.calculate_add() got an unexpected keyword argument 'decode_enums'

A policyengine-us impact run hit the error on spm_unit("snap", period, options=[ADD]) in mt_liheap_categorical_eligibility.py (PolicyEngine/policyengine-us#10141 (comment)). On policyengine-us main (PolicyEngine/policyengine-us@2b39b88e2f), 21 formulas read with options=[ADD], and each raises the error whenever a Microsimulation computes it.

Cause

Population.__call__ has passed decode_enums=False with every read since 0abe43a (December 2022), and it sends reads with options=[ADD] or options=[DIVIDE] to calculate_add or calculate_divide (population.py#L147-L163). Simulation.calculate_add and calculate_divide take it (simulation.py#L2057-L2062, #L2126-L2131), but Microsimulation overrides both without it (microsimulation.py#L84-L118), so Python rejects the call.

Plain reads go to calculate, which takes the flag. When a formula reads a monthly flow over a year or a yearly flow over a month, Simulation._calculate calls calculate_add or calculate_divide without the flag (simulation.py#L1741-L1753), so those reads kept working.

Fix

Both overrides now take decode_enums: bool = False, Simulation's default, and pass it to super(). Simulation.calculate_add and calculate_divide accept the flag without using it, and the new parameter goes last, so every call that worked before returns the same values.

Invariants and tests

tests/fixtures/microsimulation_option_reads.py adds to the country template nine formulas that read with ADD or DIVIDE. They read person and household variables, sum members' values into households, compare a sum with zero and call the add helper. tests/core/test_microsimulation_option_reads_property.py checks two properties with Hypothesis:

• A Microsimulation's unweighted reads equal a Simulation's, or both raise the same type of error. Hypothesis generates one to four households of one to three people, with weights and monthly and yearly inputs, and up to six reads in sequence. The reads cover the formulas, the population calls they make, calculate_add and calculate_divide with either value of decode_enums, and plain reads at months, years and a three-month period (200 examples).
• Each formula returns what the same arithmetic gives in NumPy, in both classes (100 examples).

Example tests in tests/core/test_microsimulation_option_reads.py check hand-computed values for each formula, the weights on a weighted result, seven population calls, and both methods with each value of decode_enums.

On master, 23 of the new tests fail with the TypeError, and Hypothesis shrinks the first property to ("calculate", "allowance_divided", "2022"). On this branch the new tests pass, apart from one strict xfail, and so do the full suite (uv run pytest tests: 2,873 passed, 4 skipped, 4 xfailed) and ruff format --check ..

A policyengine-us Microsimulation hasn't run on this branch, because the machine that built it caps memory for local microsimulation runs. Each of the 21 policyengine-us formulas reaches Microsimulation.calculate_add through Population.__call__, then clips, compares, divides or adds the result, or sums it over a group with spm_unit.sum, .all or add. Those operations return the same values for a MicroSeries as for an array.

Not changed here

• Simulation.calculate_add and calculate_divide read each term with self.calculate, which in a Microsimulation decodes Enums and applies weights by default (simulation.py#L2093-L2096, #L2152-L2160). So an Enum read with DIVIDE at a year returns labels in a Microsimulation and an EnumArray in a Simulation, and test_enum_read_with_divide_in_a_microsimulation_matches_a_simulation records the difference as a strict xfail. No policyengine-us formula reads an Enum this way: the 21 formulas read 41 variables, all floats.
• In a Microsimulation these reads return a MicroSeries, as reads that Simulation._calculate sends to calculate_add already do on master. Its .sum() and .mean() apply weights, and none of the 21 formulas calls either on the read.
• For a simulation class that doesn't subclass core's Microsimulation but has "micro" in its name, such as policyengine-uk's, Population.__call__ passes unweighted=True to the calculate methods. Simulation.calculate_add and calculate_divide don't accept that argument, but on policyengine-uk main (PolicyEngine/policyengine-uk@1d4d020aa) no formula reads with ADD or DIVIDE.

impact: no output moves for any variable that computed before; the 21 PE-US formulas that crashed in Microsimulation now compute

axiom: n/a: core infrastructure fix

🤖 Generated with Claude Code