policyengine.py for US tax and benefit analysis

pip install "policyengine[us]"

import policyengine as pe

result = pe.us.calculate_household(
    # One dict per person - keys are any person-level variable on the US model.
    # Adults default to the same tax unit and household.
    people=[
        {"age": 35, "employment_income": 40000},  # primary earner
        {"age": 33},                              # spouse
        {"age": 8},                               # dependent
        {"age": 5},                               # dependent
    ],
    # Tax-unit inputs (filing status, etc.)
    tax_unit={"filing_status": "JOINT"},
    # Household inputs. state_code is essentially always needed.
    household={"state_code": "TX"},
    # Year determines which parameter values apply.
    year=2026,
)

# Attribute access on the typed result. Group entities (tax_unit, spm_unit,
# household) are single objects; person sections are lists (result.person[0]).
print(f"Net income: ${result.household.household_net_income:,.0f}")
print(f"EITC: ${result.tax_unit.eitc:,.0f}")
print(f"SNAP: ${result.spm_unit.snap:,.0f}")

Net income: $51,261
EITC: $5,454
SNAP: $3,205

import policyengine as pe
from policyengine.core import Simulation

year = 2026
# ensure_datasets downloads from HuggingFace on first run, caches locally,
# and returns a {"<stem>_<year>": Dataset} dict.
datasets = pe.us.ensure_datasets(
    datasets=["hf://policyengine/policyengine-us-data/enhanced_cps_2024.h5"],
    years=[year],
    data_folder="./data",
)
dataset = datasets[f"enhanced_cps_2024_{year}"]

# pe.us.model is the country model version pinned by this policyengine.py release.
simulation = Simulation(dataset=dataset, tax_benefit_model_version=pe.us.model)
# ensure() loads a cached run if available, otherwise runs and caches.
simulation.ensure()

output = simulation.output_dataset.data
print(output.household[["household_net_income", "household_tax"]].head())

         weight  household_net_income  household_tax
0      0.000000         162787.765625   49123.687500
1  94409.679688          13163.706055   -1462.839600
2      0.000000          14824.270508       0.000000
3      0.000000         144380.109375   33226.578125
4      0.000000         157499.937500   31022.513672

# Old mental model:
#   from policyengine_us import Microsimulation
#   sim = Microsimulation(dataset=...)
#
# New policyengine.py mental model:
#   import policyengine as pe
#   datasets = pe.us.ensure_datasets(...)
#   simulation = Simulation(dataset=dataset, tax_benefit_model_version=pe.us.model)
import policyengine as pe
from policyengine.core import Simulation

dataset = datasets[f"enhanced_cps_2024_{year}"]
simulation = Simulation(dataset=dataset, tax_benefit_model_version=pe.us.model)
simulation.ensure()

print(simulation.release_bundle["bundle_id"])
print(type(simulation.output_dataset.data.household).__name__)

us-4.0.0
MicroDataFrame

# Step 1: pin the exact policyengine.py release in your environment.
# pip install "policyengine[us]==4.3.0"

# Step 2: capture the certified runtime bundle next to every output you save.
import json
from pathlib import Path

import policyengine as pe
from policyengine.core import Simulation

datasets = pe.us.ensure_datasets(years=[2026], data_folder="./data")
dataset = next(iter(datasets.values()))
simulation = Simulation(dataset=dataset, tax_benefit_model_version=pe.us.model)
simulation.ensure()

bundle = simulation.release_bundle

Path("outputs").mkdir(exist_ok=True)
Path("outputs/release_bundle.json").write_text(json.dumps(bundle, indent=2, default=str))

print("bundle_id:", bundle["bundle_id"])
print("country:", bundle["country_id"])
print("model:", bundle["model_package"], bundle["model_version"])
print("data:", bundle["data_package"], bundle["data_version"])
print("dataset:", bundle["dataset_filepath"])

bundle_id: us-4.0.0
country: us
model: policyengine-us 1.653.3
data: policyengine-us-data 1.73.0
dataset: ./data/enhanced_cps_2024_year_2026.h5