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.

1

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 against
About this steptable, notes
The five tools and their CLI mirrors
MCP toolCLI mirror
calculate_householdpe-macro household
household_reform_impactpe-macro household-impact
population_reform_impactpe-macro population-impact
list_reform_parameterspe-macro parameters
score_reform with model="microsim"pe-macro score
Every number from this model is a static score. For the GDP feedback, pass the same reform with model="obr" (OBR emulator code).

CLI mirrors

The third route is the Python package, import policyengine as pe, used in the steps below.

2

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 only
3

Calculate 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.

4

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
UK population microdata is gated. To run UK population examples locally, set 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.