---
name: policyengine-uk
description: PolicyEngine-UK tax and benefit microsimulation patterns, situation creation, and common workflows
---

# PolicyEngine-UK

PolicyEngine-UK models the UK tax and benefit system, including devolved variations for Scotland and Wales.

## For Users 👥

### What is PolicyEngine-UK?

PolicyEngine-UK is the "calculator" for UK taxes and benefits. When you use policyengine.org/uk, PolicyEngine-UK runs behind the scenes.

**What it models:**

**Direct taxes:**
- Income tax (UK-wide, Scottish, and Welsh variations)
- National Insurance (Classes 1, 2, 4)
- Capital gains tax
- Dividend tax

**Property and transaction taxes:**
- Council Tax
- Stamp Duty Land Tax (England/NI)
- Land and Buildings Transaction Tax (Scotland)
- Land Transaction Tax (Wales)

**Universal Credit:**
- Standard allowance
- Child elements
- Housing cost element
- Childcare costs element
- Carer element
- Work capability elements

**Legacy benefits (being phased out):**
- Working Tax Credit
- Child Tax Credit
- Income Support
- Income-based JSA/ESA
- Housing Benefit

**Other benefits:**
- Child Benefit
- Pension Credit
- Personal Independence Payment (PIP)
- Disability Living Allowance (DLA)
- Attendance Allowance
- State Pension

**See full list:** https://policyengine.org/uk/parameters

### Understanding Variables

When you see results in PolicyEngine, these are variables:

**Income variables:**
- `employment_income` - Gross employment earnings/salary
- `self_employment_income` - Self-employment profits
- `pension_income` - Private pension income
- `property_income` - Rental income
- `savings_interest_income` - Interest from savings
- `dividend_income` - Dividend income

**Tax variables:**
- `income_tax` - Total income tax liability
- `national_insurance` - Total NI contributions
- `council_tax` - Council tax liability

**Benefit variables:**
- `universal_credit` - Universal Credit amount
- `child_benefit` - Child Benefit amount
- `pension_credit` - Pension Credit amount
- `working_tax_credit` - Working Tax Credit (legacy)
- `child_tax_credit` - Child Tax Credit (legacy)

**Summary variables:**
- `household_net_income` - Income after taxes and benefits
- `disposable_income` - Income after taxes
- `equivalised_household_net_income` - Adjusted for household size

## For Analysts 📊

### Installation and Setup

```bash
# Install PolicyEngine-UK
pip install policyengine-uk

# Or with uv (recommended)
uv pip install policyengine-uk
```

### Quick Start

```python
from policyengine_uk import Simulation

# Create a household
situation = {
    "people": {
        "person": {
            "age": {2025: 30},
            "employment_income": {2025: 30000}
        }
    },
    "benunits": {
        "benunit": {
            "members": ["person"]
        }
    },
    "households": {
        "household": {
            "members": ["person"],
            "region": {2025: "LONDON"}
        }
    }
}

# Calculate taxes and benefits
sim = Simulation(situation=situation)
income_tax = sim.calculate("income_tax", 2025)[0]
universal_credit = sim.calculate("universal_credit", 2025)[0]

print(f"Income tax: £{income_tax:,.0f}")
print(f"Universal Credit: £{universal_credit:,.0f}")
```

### Web App to Python

**Web app URL:**
```
policyengine.org/uk/household?household=12345
```

**Equivalent Python (conceptually):**
The household ID represents a situation dictionary. To replicate in Python, you'd create a similar situation.

### When to Use This Skill

- Creating household situations for tax/benefit calculations
- Running microsimulations with PolicyEngine-UK
- Analyzing policy reforms and their impacts
- Building tools that use PolicyEngine-UK (calculators, analysis notebooks)
- Debugging PolicyEngine-UK calculations

## For Contributors 💻

### Repository

**Location:** PolicyEngine/policyengine-uk

**To see current implementation:**
```bash
git clone https://github.com/PolicyEngine/policyengine-uk
cd policyengine-uk

# Explore structure
tree policyengine_uk/
```

**Key directories:**
```bash
ls policyengine_uk/
# - variables/   - Tax and benefit calculations
# - parameters/  - Policy rules (YAML)
# - reforms/     - Pre-defined reforms
# - tests/       - Test cases
```

## Core Concepts

### 1. Situation Dictionary Structure

PolicyEngine UK requires a nested dictionary defining household composition:

```python
situation = {
    "people": {
        "person_id": {
            "age": {2025: 35},
            "employment_income": {2025: 30000},
            # ... other person attributes
        }
    },
    "benunits": {
        "benunit_id": {
            "members": ["person_id", ...]
        }
    },
    "households": {
        "household_id": {
            "members": ["person_id", ...],
            "region": {2025: "SOUTH_EAST"}
        }
    }
}
```

**Key Rules:**
- All entities must have consistent member lists
- Use year keys for all values: `{2025: value}`
- Region must be one of the ITL 1 regions (see below)
- All monetary values in pounds (not pence)
- UK tax year runs April 6 to April 5 (but use calendar year in code)

**Important Entity Difference:**
- UK uses **benunits** (benefit units): a single adult OR couple + dependent children
- This is the assessment unit for most means-tested benefits
- Unlike US which uses families/marital_units/tax_units/spm_units

### 2. Creating Simulations

```python
from policyengine_uk import Simulation

# Create simulation from situation
simulation = Simulation(situation=situation)

# Calculate variables
income_tax = simulation.calculate("income_tax", 2025)
universal_credit = simulation.calculate("universal_credit", 2025)
household_net_income = simulation.calculate("household_net_income", 2025)
```

**Common Variables:**

**Income:**
- `employment_income` - Gross employment earnings
- `self_employment_income` - Self-employment profits
- `pension_income` - Private pension income
- `property_income` - Rental income
- `savings_interest_income` - Interest income
- `dividend_income` - Dividend income
- `miscellaneous_income` - Other income sources

**Tax Outputs:**
- `income_tax` - Total income tax liability
- `national_insurance` - Total NI contributions
- `council_tax` - Council tax liability
- `VAT` - Value Added Tax paid

**Benefits:**
- `universal_credit` - Universal Credit
- `child_benefit` - Child Benefit
- `pension_credit` - Pension Credit
- `working_tax_credit` - Working Tax Credit (legacy)
- `child_tax_credit` - Child Tax Credit (legacy)
- `personal_independence_payment` - PIP
- `attendance_allowance` - Attendance Allowance
- `state_pension` - State Pension

**Summary:**
- `household_net_income` - Income after taxes and benefits
- `disposable_income` - Income after taxes
- `equivalised_household_net_income` - Adjusted for household size

### 3. Using Axes for Parameter Sweeps

To vary a parameter across multiple values:

```python
situation = {
    # ... normal situation setup ...
    "axes": [[{
        "name": "employment_income",
        "count": 1001,
        "min": 0,
        "max": 100000,
        "period": 2025
    }]]
}

simulation = Simulation(situation=situation)
# Now calculate() returns arrays of 1001 values
incomes = simulation.calculate("employment_income", 2025)  # Array of 1001 values
taxes = simulation.calculate("income_tax", 2025)  # Array of 1001 values
```

**Important:** Remove axes before creating single-point simulations:
```python
situation_single = situation.copy()
situation_single.pop("axes", None)
simulation = Simulation(situation=situation_single)
```

### 4. Policy Reforms

```python
from policyengine_uk import Simulation

# Define a reform (modifies parameters)
reform = {
    "gov.hmrc.income_tax.rates.uk.brackets[0].rate": {
        "2025-01-01.2100-12-31": 0.25  # Increase basic rate to 25%
    }
}

# Create simulation with reform
simulation = Simulation(situation=situation, reform=reform)
```

## Common Patterns

### Pattern 1: Single Person Household Calculation

```python
from policyengine_uk import Simulation

situation = {
    "people": {
        "person": {
            "age": {2025: 30},
            "employment_income": {2025: 30000}
        }
    },
    "benunits": {
        "benunit": {
            "members": ["person"]
        }
    },
    "households": {
        "household": {
            "members": ["person"],
            "region": {2025: "LONDON"}
        }
    }
}

sim = Simulation(situation=situation)
income_tax = sim.calculate("income_tax", 2025)[0]
national_insurance = sim.calculate("national_insurance", 2025)[0]
universal_credit = sim.calculate("universal_credit", 2025)[0]
```

### Pattern 2: Couple with Children

```python
situation = {
    "people": {
        "parent_1": {
            "age": {2025: 35},
            "employment_income": {2025: 35000}
        },
        "parent_2": {
            "age": {2025: 33},
            "employment_income": {2025: 25000}
        },
        "child_1": {
            "age": {2025: 8}
        },
        "child_2": {
            "age": {2025: 5}
        }
    },
    "benunits": {
        "benunit": {
            "members": ["parent_1", "parent_2", "child_1", "child_2"]
        }
    },
    "households": {
        "household": {
            "members": ["parent_1", "parent_2", "child_1", "child_2"],
            "region": {2025: "NORTH_WEST"}
        }
    }
}

sim = Simulation(situation=situation)
child_benefit = sim.calculate("child_benefit", 2025)[0]
universal_credit = sim.calculate("universal_credit", 2025)[0]
```

### Pattern 3: Marginal Tax Rate Analysis

```python
# Create baseline with axes varying income
situation_with_axes = {
    "people": {
        "person": {
            "age": {2025: 30}
        }
    },
    "benunits": {"benunit": {"members": ["person"]}},
    "households": {
        "household": {
            "members": ["person"],
            "region": {2025: "LONDON"}
        }
    },
    "axes": [[{
        "name": "employment_income",
        "count": 1001,
        "min": 0,
        "max": 100000,
        "period": 2025
    }]]
}

sim = Simulation(situation=situation_with_axes)
incomes = sim.calculate("employment_income", 2025)
net_incomes = sim.calculate("household_net_income", 2025)

# Calculate marginal tax rate
import numpy as np
mtr = 1 - (np.gradient(net_incomes) / np.gradient(incomes))
```

### Pattern 4: Regional Comparison

```python
regions = ["LONDON", "SCOTLAND", "WALES", "NORTH_EAST"]
results = {}

for region in regions:
    situation = create_situation(region=region, income=30000)
    sim = Simulation(situation=situation)
    results[region] = {
        "income_tax": sim.calculate("income_tax", 2025)[0],
        "national_insurance": sim.calculate("national_insurance", 2025)[0],
        "total_tax": sim.calculate("income_tax", 2025)[0] +
                     sim.calculate("national_insurance", 2025)[0]
    }
```

### Pattern 5: Policy Reform Impact

```python
from policyengine_uk import Microsimulation, Reform

# Define reform: Increase basic rate to 25%
class IncreaseBasicRate(Reform):
    def apply(self):
        def modify_parameters(parameters):
            parameters.gov.hmrc.income_tax.rates.uk.brackets[0].rate.update(
                period="year:2025:10", value=0.25
            )
            return parameters
        self.modify_parameters(modify_parameters)

# Run microsimulation
baseline = Microsimulation()
reformed = Microsimulation(reform=IncreaseBasicRate)

# Calculate revenue impact
baseline_revenue = baseline.calc("income_tax", 2025).sum()
reformed_revenue = reformed.calc("income_tax", 2025).sum()
revenue_change = (reformed_revenue - baseline_revenue) / 1e9  # in billions

# Calculate household impact
baseline_net_income = baseline.calc("household_net_income", 2025)
reformed_net_income = reformed.calc("household_net_income", 2025)
```

## Helper Scripts

This skill includes helper scripts in the `scripts/` directory:

```python
from policyengine_uk_skills.situation_helpers import (
    create_single_person,
    create_couple,
    create_family_with_children,
    add_region
)

# Quick situation creation
situation = create_single_person(
    income=30000,
    region="LONDON",
    age=30
)

# Create couple
situation = create_couple(
    income_1=35000,
    income_2=25000,
    region="SCOTLAND"
)
```

## Common Pitfalls and Solutions

### Pitfall 1: Member Lists Out of Sync

**Problem:** Different entities have different members
```python
# WRONG
"benunits": {"benunit": {"members": ["parent"]}},
"households": {"household": {"members": ["parent", "child"]}}
```

**Solution:** Keep all entity member lists consistent:
```python
# CORRECT
all_members = ["parent", "child"]
"benunits": {"benunit": {"members": all_members}},
"households": {"household": {"members": all_members}}
```

### Pitfall 2: Forgetting Year Keys

**Problem:** `"age": 35` instead of `"age": {2025: 35}`

**Solution:** Always use year dictionary:
```python
"age": {2025: 35},
"employment_income": {2025: 30000}
```

### Pitfall 3: Wrong Region Format

**Problem:** Using lowercase or incorrect region names

**Solution:** Use uppercase ITL 1 region codes:
```python
# CORRECT regions:
"region": {2025: "LONDON"}
"region": {2025: "SCOTLAND"}
"region": {2025: "WALES"}
"region": {2025: "NORTH_EAST"}
"region": {2025: "SOUTH_EAST"}
```

### Pitfall 4: Axes Persistence

**Problem:** Axes remain in situation when creating single-point simulation

**Solution:** Remove axes before single-point simulation:
```python
situation_single = situation.copy()
situation_single.pop("axes", None)
```

### Pitfall 5: Missing Benunits

**Problem:** Forgetting to include benunits (benefit units)

**Solution:** Always include benunits in UK simulations:
```python
# UK requires benunits
situation = {
    "people": {...},
    "benunits": {"benunit": {"members": [...]}},  # Required!
    "households": {...}
}
```

## Regions in PolicyEngine UK

UK uses ITL 1 (International Territorial Level 1, formerly NUTS 1) regions:

**Regions:**
- `NORTH_EAST` - North East England
- `NORTH_WEST` - North West England
- `YORKSHIRE` - Yorkshire and the Humber
- `EAST_MIDLANDS` - East Midlands
- `WEST_MIDLANDS` - West Midlands
- `EAST_OF_ENGLAND` - East of England
- `LONDON` - London
- `SOUTH_EAST` - South East England
- `SOUTH_WEST` - South West England
- `WALES` - Wales
- `SCOTLAND` - Scotland
- `NORTHERN_IRELAND` - Northern Ireland

**Regional Tax Variations:**

**Scotland:**
- Has devolved income tax with 6 bands (starter 19%, basic 20%, intermediate 21%, higher 42%, advanced 45%, top 47%)
- Scottish residents automatically calculated with Scottish rates

**Wales:**
- Has Welsh Rate of Income Tax (WRIT)
- Currently maintains parity with England/NI rates

**England/Northern Ireland:**
- Standard UK rates: basic 20%, higher 40%, additional 45%

## Key Parameters and Values (2025/26)

### Income Tax
- **Personal Allowance:** £12,570
- **Basic rate threshold:** £50,270
- **Higher rate threshold:** £125,140
- **Rates:** 20% (basic), 40% (higher), 45% (additional)
- **Personal allowance tapering:** £1 reduction for every £2 over £100,000

### National Insurance (Class 1)
- **Lower Earnings Limit:** £6,396/year
- **Primary Threshold:** £12,570/year
- **Upper Earnings Limit:** £50,270/year
- **Rates:** 12% (between primary and upper), 2% (above upper)

### Universal Credit
- **Standard allowance:** Varies by single/couple and age
- **Taper rate:** 55% (rate at which UC reduced as income increases)
- **Work allowance:** Amount you can earn before UC reduced

### Child Benefit
- **First child:** Higher rate
- **Subsequent children:** Lower rate
- **High Income Charge:** Tapered withdrawal starting at £60,000

## Version Compatibility

- Use `policyengine-uk>=1.0.0` for 2025 calculations
- Check version: `import policyengine_uk; print(policyengine_uk.__version__)`
- Different years may require different package versions

## Debugging Tips

1. **Enable tracing:**
   ```python
   simulation.trace = True
   result = simulation.calculate("variable_name", 2025)
   ```

2. **Check intermediate calculations:**
   ```python
   gross_income = simulation.calculate("gross_income", 2025)
   disposable_income = simulation.calculate("disposable_income", 2025)
   ```

3. **Verify situation structure:**
   ```python
   import json
   print(json.dumps(situation, indent=2))
   ```

4. **Test with PolicyEngine web app:**
   - Go to policyengine.org/uk/household
   - Enter same inputs
   - Compare results

## Additional Resources

- **Documentation:** https://policyengine.org/uk/docs
- **API Reference:** https://github.com/PolicyEngine/policyengine-uk
- **Variable Explorer:** https://policyengine.org/uk/variables
- **Parameter Explorer:** https://policyengine.org/uk/parameters

## Examples Directory

See `examples/` for complete working examples:
- `single_person.yaml` - Single person household
- `couple.yaml` - Couple without children
- `family_with_children.yaml` - Family with dependents
- `universal_credit_sweep.yaml` - Analyzing UC with axes

## Key Differences from US System

1. **Benefit Units:** UK uses `benunits` (single/couple + children) instead of US multiple entity types
2. **Universal Credit:** Consolidated means-tested benefit (vs separate SNAP, TANF, etc. in US)
3. **National Insurance:** Separate from income tax with own thresholds (vs US Social Security tax)
4. **Devolved Taxes:** Scotland and Wales have different income tax rates
5. **Tax Year:** April 6 to April 5 (vs calendar year in US)
6. **No State Variation:** Council Tax is local, but most taxes/benefits are national (vs 50 US states)