policyengine-uk-rust

Quick start

Install the Python package (Python 3.10+, pip or uv):

pip install policyengine-uk-compiled
# or
uv add policyengine-uk-compiled

Single-household simulation

The quickest way to explore the model is with a single constructed household:

from policyengine_uk_compiled import PolicyEngineUK

engine = PolicyEngineUK()

# A single person earning £40,000
household = engine.single_person(employment_income=40_000)
result = engine.calculate(household)

print(result["income_tax"])          # → 5486.0
print(result["national_insurance"])  # → 2692.0
print(result["universal_credit"])    # → 0.0

Population simulation with FRS

For aggregate costings you need microdata. The package downloads pre-cleaned FRS CSVs automatically on first use:

from policyengine_uk_compiled import PolicyEngineUK

engine = PolicyEngineUK(dataset="frs", year=2023)
baseline = engine.run()

print(f"Income tax revenue: £{baseline['program_breakdown']['income_tax'] / 1e9:.1f}bn")
print(f"UC spending:        £{baseline['program_breakdown']['universal_credit'] / 1e9:.1f}bn")

Running a reform

Reforms are a dict that overrides specific parameters. Unchanged parameters keep their baseline values.

reform = {
    "universal_credit": {
        "taper_rate": 0.50          # baseline is 0.55
    }
}

result = engine.run(reform=reform)
baseline = engine.run()

net_cost = (result["budgetary_impact"]["net_cost"]
            - baseline["budgetary_impact"]["net_cost"])
print(f"UC taper 55→50%: £{net_cost / 1e9:.2f}bn/yr")

Python API

Household constructors

The wrapper provides convenience constructors for common household types:

# Single person
household = engine.single_person(
    employment_income=35_000,
    age=35,
)

# Couple (joint assessment for UC purposes)
household = engine.couple(
    employment_income_1=40_000,
    employment_income_2=20_000,
    num_children=2,
)

# Single parent
household = engine.single_parent(
    employment_income=25_000,
    num_children=1,
    rent=900,          # monthly, affects UC housing element
)

Custom households

For non-standard cases or batch processing, construct the payload directly:

import json
from policyengine_uk_compiled import PolicyEngineUK

engine = PolicyEngineUK()

payload = {
    "persons": [
        {"age": 40, "employment_income": 60_000, "is_female": False},
        {"age": 38, "employment_income": 0, "is_female": True},
    ],
    "benunits": [{"person_ids": [0, 1], "is_couple": True}],
    "households": [{"benunit_ids": [0], "rent": 1200}],
}

result = engine.calculate_custom(payload)
print(result)

Marginal tax rates

# MTR at a given income point
mtr = engine.marginal_tax_rate(
    household=engine.single_person(employment_income=50_000),
    income_type="employment_income",
    delta=100,   # £100 increment used for numerical derivative
)
print(f"MTR at £50k: {mtr:.1%}")   # → ~42.0%

Reform parameters

All reform keys are optional — only the parameters you specify are changed. The full parameter tree is available via engine.baseline_params(year).

# Income tax: raise higher rate threshold
reform = {"income_tax": {"higher_rate_threshold": 55_000}}

# NI: change primary threshold
reform = {"national_insurance": {"primary_threshold": 10_000}}

# UC: multiple changes
reform = {
    "universal_credit": {
        "taper_rate": 0.50,
        "work_allowance_with_housing": 500,
        "work_allowance_without_housing": 750,
    }
}

# Scottish income tax: modify a rate band
reform = {
    "income_tax": {
        "scottish_brackets": [
            {"rate": 0.19, "threshold": 0},
            {"rate": 0.20, "threshold": 14_876},
            {"rate": 0.21, "threshold": 26_561},
            {"rate": 0.42, "threshold": 43_662},
            {"rate": 0.45, "threshold": 75_000},
        ]
    }
}

Dataset management

from policyengine_uk_compiled import ensure_dataset

# Download FRS clean CSVs if not already present
ensure_dataset("frs", year=2023)

# Download EFRS (Enhanced FRS — needed for wealth/stamp duty/CGT)
ensure_dataset("efrs", year=2023)

# Available datasets: "frs", "spi", "lcfs", "was", "efrs"

Key classes and functions

CLI reference

After cargo build --release, the binary is at ./target/release/policyengine-uk-rust.

Core flags

Data extraction flags

Examples

# Baseline aggregate simulation
./policyengine-uk-rust --data ~/.policyengine-uk-data/frs \
  --year 2025 --output json

# Reform: UC taper 55% → 50%
./policyengine-uk-rust --data ~/.policyengine-uk-data/frs \
  --year 2025 --output json \
  --policy-json '{"universal_credit": {"taper_rate": 0.50}}'

# Per-household microdata
./policyengine-uk-rust --data ~/.policyengine-uk-data/frs \
  --year 2025 --output-microdata-stdout

# Extract FRS 2023 from raw tabs
./policyengine-uk-rust --frs raw/frs_2023/tab/ \
  --year 2023 --extract data/frs/2023/

# Build EFRS
./policyengine-uk-rust --extract-efrs data/efrs/2023 \
  --data data/frs --year 2023 \
  --was-dir raw/was/round_7/ \
  --lcfs-dir raw/lcfs/2021/

# Inspect baseline parameters
./policyengine-uk-rust --year 2025 --export-params-json | python -m json.tool | less

Datasets

Five microdata sources are supported. The two-step flow for FRS/LCFS/WAS/SPI is: (1) extract raw survey tabs to clean CSVs, (2) simulate with --data. EFRS is a composite built from FRS + WAS + LCFS.

Getting data

FRS and EFRS pre-cleaned CSVs are downloaded automatically when you call ensure_dataset() in Python or on first use of the engine. They come from gs://policyengine-uk-microdata/.

SPI, LCFS, and WAS must be obtained from the UK Data Service under project ecf0b3c4-29d2-4d8a-931d-0e3773a4ac0b. Download the tab zips and unzip before extracting.

EFRS — Enhanced FRS

EFRS imputes wealth from WAS and consumption from LCFS onto FRS microdata using random forest models. It is needed to model wealth taxes, stamp duty, and CGT. Pre-built CSVs are on GCS; rebuild with:

python scripts/rebuild_all.py --only efrs

Or build manually:

./policyengine-uk-rust --extract-efrs data/efrs/2023 \
  --data data/frs --year 2023 \
  --was-dir raw/was/round_7/ \
  --lcfs-dir raw/lcfs/2021/

FRS year coverage

FRS 2023 is the primary microdata year. The engine accepts the fiscal year as the --year argument, which also determines which parameters/YYYY_YY.yaml file is loaded. You can uprate an older dataset to a later year's prices using --uprate-to.

Parameters

All tax and benefit parameters live in parameters/YYYY_YY.yaml — one file per fiscal year. They are loaded at runtime so reforms take effect without recompiling.

Inspecting parameters

# From the CLI
./policyengine-uk-rust --year 2025 --export-params-json | python -m json.tool

# From Python
engine = PolicyEngineUK(year=2025)
params = engine.baseline_params(2025)
print(params["universal_credit"]["taper_rate"])   # → 0.55

Structure

Top-level keys in the parameter tree:

Legislative reference

Every parameter value is cross-referenced to its enabling legislation in LEGISLATIVE_REFERENCE.md. This includes the specific Act, statutory instrument, and regulation for each figure, making it straightforward to verify correctness and trace any change.

Adding a new year

Copy the most recent parameters/YYYY_YY.yaml, update the values to reflect the new fiscal year's enacted rates, and add citations. The engine picks up the new file automatically based on the --year argument.

Limitations

These are structural model constraints, not implementation bugs. They affect how results should be interpreted and compared with official estimates.

UC caseload undercount

The FRS under-reports UC receipt. UC is only awarded to benefit units that reported UC in the FRS (on_uc=True) or under full take-up (--full-take-up); benefit units with reported legacy benefit receipt stay on the legacy system.

Practical effect: UC reform costings from this model will undercount relative to OBR/DWP estimates, in proportion to the FRS under-reporting of the UC caseload.

No realised capital gains data

No UK household survey records realised capital gains, so capital_gains defaults to zero on all datasets. CGT reform modelling requires manually populating this field via --stdin-data or a bespoke dataset.

LCFS sample size

LCFS has ~4,200 households, so aggregate totals from LCFS-based simulations are small. Consumption pattern relativities are correct, but absolute spending totals should not be interpreted as national aggregates without appropriate uprating.

SPI — no household structure

The SPI is a person-level dataset with no household or benefit unit structure. Benefit and decile outputs are therefore not produced. Always use --persons-only when simulating on SPI.

Benefit cap and UC migration

The model applies the benefit cap deterministically and routes benefit units to UC or legacy purely from reported receipt. In practice, legacy-to-UC managed migration is phased and capped household incomes interact with transitional protection — neither of which is modelled.

Contributing

Build and test

cargo build --release
cargo test

Repository layout

Releasing

Versions are managed via pyproject.toml and towncrier-style changelog fragments in changelog.d/. Do not edit CHANGELOG.md or Cargo.toml versions directly — CI updates these automatically.

To ship a change, drop a fragment file in changelog.d/ with the naming convention <slug>.<type>:

Example: create changelog.d/uc-taper-fix.fixed with a one-sentence description of the change. CI infers the version bump from fragment types, updates pyproject.toml, and publishes to PyPI.

After publishing, trigger a redeploy of the chat app:

gh workflow run redeploy-on-package-update.yml --repo PolicyEngine/policyengine-uk-chat

Updating parameters for a new fiscal year

1. Copy the most recent parameters/YYYY_YY.yaml to the new year.
2. Update all values, citing the relevant Act or statutory instrument.
3. Cross-reference every change in LEGISLATIVE_REFERENCE.md.
4. Run cargo test — existing snapshot tests will catch any regressions in prior years.

Changelog

Recent releases. Full history is in CHANGELOG.md.

See CHANGELOG.md for the complete release history.