PolicyEngine US

1.636.3 · active · verified Thu Apr 16

PolicyEngine US is an open-source Python library that provides a comprehensive microsimulation model of the United States tax and benefit system. Built upon the PolicyEngine Core framework (a fork of OpenFisca), it accurately models federal individual income taxes, major federal benefit programs, and state income taxes for all 50 states and D.C. The library enables researchers and policymakers to estimate household-level tax liabilities and benefit eligibility, and to simulate the distributional impacts and budgetary effects of proposed policy reforms. It is actively maintained with continuous updates driven by changes in tax and benefit legislation.

Common errors

```
ModuleNotFoundError: No module named 'openfisca_us'
```
cause The library package name changed from `openfisca-us` to `policyengine-us`.

fix Install `policyengine-us` instead of `openfisca-us` and update all import statements from `openfisca_us` to `policyengine_us`, and `openfisca_core` to `policyengine_core`.
```
TypeError: 'System' object is not callable
```
cause Attempting to call the `system` object directly without using its methods (e.g., `get_system()`).

fix Use `system.get_system()` to initialize the tax-benefit system object before passing it to a `Simulation` or accessing its parameters/variables.
```
policyengine_core.exceptions.UnknownPeriodError: No data for period 'YYYY'
```
cause The requested policy year (period) might be outside the range supported by the installed `policyengine-us` version or the specific parameter/variable.

fix Check the available periods for the variables/parameters you are trying to access. The model is continuously updated, so ensure your library version is current for the latest policy years. For older years, data might not be available or require specific older versions.

Warnings

breaking The library was renamed from `openfisca-us` to `policyengine-us` in November 2022. This included changes to package names and core import paths.
Fix: Update all import statements from `openfisca_us` or `openfisca_core` to `policyengine_us` and `policyengine_core` respectively.
gotcha PolicyEngine US relies on complex underlying data, which can have caveats. For example, population impact analyses using the Current Population Survey (CPS) may have truncated high incomes or underestimated benefits. Policy may also be applied to older data years (e.g., 2022 policy on 2020 data).
Fix: Always review the data source and its limitations described in the PolicyEngine documentation. Understand that microsimulation models are approximations and consult official sources for definitive figures.
gotcha Known issues exist with state-specific tax calculations and non-conformity to federal changes (e.g., for Maine, DC, South Carolina). This can lead to discrepancies compared to other tax simulators like TAXSIM35.
Fix: For highly precise state-level analysis, cross-verify results with other sources or consult PolicyEngine's GitHub issues for known limitations and ongoing fixes.
gotcha When developing with `policyengine-us-data` (often used for generating microdata), a dependency on `torch` for certain machine learning features can cause unexpected test failures or installation issues if not properly handled in the environment.
Fix: If encountering issues related to `policyengine-us-data` or `torch`, ensure `torch` is correctly installed, or consider using pre-generated datasets if extensive data manipulation is not required. Review `policyengine-us-data`'s specific installation instructions if directly developing with it.
gotcha PolicyEngine's REST API (used if you integrate with their external service) requires client ID/secret for authentication tokens, which expire monthly. This can lead to 'Authorization failed' errors if not regularly refreshed.
Fix: Implement a token refresh mechanism in your application to obtain a new authentication token before the current one expires.

Install

pip install policyengine-us Install stable version

Imports

system
```
from policyengine_us import system
```

Person

from policyengine_core.entities import Person

Household

from policyengine_core.entities import Household

Simulation
wrong:
```
from openfisca_us.simulation import Simulation
```
correct:
```
from policyengine_core.simulation import Simulation
```
The library was renamed from openfisca-us to policyengine-us in November 2022. Core components also moved to policyengine_core.

Quickstart

This quickstart demonstrates how to define a simple household, retrieve the current US tax-benefit system, run a simulation to calculate a person's net income, and then apply a basic policy reform (Universal Basic Income) to see its impact.

from policyengine_us import system
from policyengine_core.entities import Person, Household
from policyengine_core.simulation import Simulation

# Define a simple household
# A person named 'alice' who is 40 years old and has wage income
alice = Person(age=40, wages=50000, employment_status='EMPLOYED')

# A household with Alice
household = Household(members=[alice])

# Get the current US tax-benefit system
# By default, uses the latest available policy year (e.g., 2025 as of recent updates)
sim_system = system.get_system()

# Create a simulation for the household
simulation = Simulation(household=household, system=sim_system)

# Calculate a variable, e.g., Alice's net income in 2025
alice_net_income = simulation.get_person_variable(person_id=alice.id, variable_name='net_income', period='2025')

print(f"Alice's net income in 2025: ${alice_net_income:,.2f}")

# Example of applying a simple reform (e.g., a universal basic income)
reform_code = {
    'universal_basic_income': [
        {
            'period': '2025',
            'value': 12000,
            'description': 'A universal basic income of $12,000 per year for all adults.'
        }
    ]
}

# Apply the reform to the system
reformed_system = system.get_system(reform=reform_code)

# Run simulation with the reformed system
reformed_simulation = Simulation(household=household, system=reformed_system)

alice_net_income_reformed = reformed_simulation.get_person_variable(
    person_id=alice.id, variable_name='net_income', period='2025'
)

print(f"Alice's net income in 2025 with UBI reform: ${alice_net_income_reformed:,.2f}")

view raw JSON →