Summary
Microsimulation.get_weights() in policyengine_core/simulations/microsimulation.py hardcodes f"{entity_key}_weight" to look up weights for each entity. This means every country package must define person_weight, tax_unit_weight, spm_unit_weight, benunit_weight, etc. — even though all of these just delegate to household_weight (the only calibrated weight).
This causes confusion because:
- Users and AI agents use
person_weight, spm_unit_weight, etc. for manual calculations, thinking they're distinct — but they're all just household_weight projected to the entity
- The existence of multiple weight variables makes it unclear which one to use
- It's impossible to remove the redundant weight variables without a core change
Current behavior
# microsimulation.py line ~30
weight_variable_name = f"{entity_key}_weight"
weights = self.calculate(weight_variable_name, time_period, use_weights=False)
Every entity type requires a {entity}_weight variable to exist, or Microsimulation crashes.
Proposed behavior
get_weights() should always derive from household_weight, projecting it to whichever entity is requested. Something like:
weights = self.calculate("household_weight", time_period, use_weights=False)
if entity_key != "household":
weights = self.map_to(weights, "household", entity_key)
This would:
- Eliminate the need for country packages to define per-entity weight variables
- Make it clear that
household_weight is the single source of truth
- Reduce confusion for users doing manual weighted calculations
Downstream impact
After this change, country packages could deprecate/remove:
- US:
person_weight, tax_unit_weight, spm_unit_weight, family_weight, marital_unit_weight
- UK:
person_weight, benunit_weight
The policyengine-api, policyengine.py, and data packages also reference these variables and would need updates.
Summary
Microsimulation.get_weights()inpolicyengine_core/simulations/microsimulation.pyhardcodesf"{entity_key}_weight"to look up weights for each entity. This means every country package must defineperson_weight,tax_unit_weight,spm_unit_weight,benunit_weight, etc. — even though all of these just delegate tohousehold_weight(the only calibrated weight).This causes confusion because:
person_weight,spm_unit_weight, etc. for manual calculations, thinking they're distinct — but they're all justhousehold_weightprojected to the entityCurrent behavior
Every entity type requires a
{entity}_weightvariable to exist, orMicrosimulationcrashes.Proposed behavior
get_weights()should always derive fromhousehold_weight, projecting it to whichever entity is requested. Something like:This would:
household_weightis the single source of truthDownstream impact
After this change, country packages could deprecate/remove:
person_weight,tax_unit_weight,spm_unit_weight,family_weight,marital_unit_weightperson_weight,benunit_weightThe
policyengine-api,policyengine.py, and data packages also reference these variables and would need updates.