Tax-benefit microsimulation
PolicyEngine microsimulation
Run it hosted, from the CLI or in Python, and reproduce its numbers.
Run it in four steps
From a route in to a population-wide costing.
Pick a route: hosted MCP, CLI, or Python
The quickest route is the hosted MCP server: five tools, each with a pe-macro CLI mirror. The UK microdata credential is provisioned server-side.
# one UK household, current law
pe-macro household --country uk \
--people '[{"age":35,"employment_income":50000}]'
# a reform (basic rate to 21p), scored over the population
pe-macro population-impact --country uk \
--reform '{"gov.hmrc.income_tax.rates.uk[0].rate":0.21}'
pe-macro parameters # the levers you can write reforms againstAbout this steptable, notes
| MCP tool | CLI mirror |
|---|---|
calculate_household | pe-macro household |
household_reform_impact | pe-macro household-impact |
population_reform_impact | pe-macro population-impact |
list_reform_parameters | pe-macro parameters |
score_reform with model="microsim" | pe-macro score |
model="obr" (OBR emulator code).
CLI mirrors
The third route is the Python package, import policyengine as pe, used in the steps below.
Install
The base install is shared tooling only. Add [models] for the pinned UK + US country models, or a single country extra.
pip install policyengine # shared tooling, no country models
pip install "policyengine[models]" # + pinned UK and US models
pip install "policyengine[uk]" # UK model only
pip install "policyengine[us]" # US model onlyCalculate a household
Describe the people, pick a year, read the results. No data access or credentials needed.
import policyengine as pe
# UK: single adult earning £50,000 — current law
uk = pe.uk.calculate_household(
people=[{"age": 35, "employment_income": 50_000}],
year=2026,
)
print(uk.person[0].income_tax) # £7,486
print(uk.person[0].national_insurance) # £2,994
print(uk.household.hbai_household_net_income) # £39,520
# US: single filer in Los Angeles County, California, with a reform applied
us = pe.us.calculate_household(
people=[{"age": 35, "employment_income": 60_000}],
tax_unit={"filing_status": "SINGLE"},
household={"state_code": "CA", "county_fips": "06037"},
year=2026,
reform={"gov.irs.credits.ctc.amount.adult_dependent": 1000},
)
print(us.tax_unit.income_tax, us.household.household_net_income)About this stepnotes
US households
A US household needs its five-digit county_fips, or an explicit spm={"geography_kind": "national"}: US results include the Supplemental Poverty Measure, and a state alone does not identify its geography.
Household-level reform impact
Run with and without reform and take the difference. For the UK earner above, a 25% basic rate ({"gov.hmrc.income_tax.rates.uk[0].rate": 0.25}) adds £1,872 of income tax and cuts net income by the same amount.
Score a whole population
The same package runs whole representative datasets (the enhanced UK Family Resources Survey, the US CPS) and aggregates any variable by decile, entity or demographic. For the full budgetary, decile, poverty and regional breakdown use pe.uk.economic_impact_analysis (hosted: population_reform_impact).
import policyengine as pe
from policyengine.core import Simulation
from policyengine.outputs.aggregate import Aggregate, AggregateType
datasets = pe.uk.ensure_datasets(datasets=["enhanced_frs_2023_24"],
years=[2026], data_folder="./data")
simulation = Simulation(dataset=datasets["enhanced_frs_2023_24_2026"],
tax_benefit_model_version=pe.uk.model)
simulation.run()
agg = Aggregate(simulation=simulation, variable="universal_credit",
aggregate_type=AggregateType.SUM, entity="benunit")
agg.run()
print(f"Total UC spending: £{agg.result / 1e9:.1f}bn")About this stepnotes
HUGGING_FACE_TOKEN from an account with access to
policyengine/policyengine-uk-data.
Reproduce the headline costing
One test re-runs the validation tab’s 1p basic-rate figure. It needs the microdata token: HUGGING_FACE_TOKEN=… pytest integration/tests/test_population.py --runslow -k basic_rate.