{"id":8434,"library":"policyengine-us","title":"PolicyEngine US","description":"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.","status":"active","version":"1.636.3","language":"en","source_language":"en","source_url":"https://github.com/PolicyEngine/policyengine-us","tags":["tax simulation","microsimulation","public policy","economics","government","social benefits","us"],"install":[{"cmd":"pip install policyengine-us","lang":"bash","label":"Install stable version"}],"dependencies":[{"reason":"Core microsimulation framework.","package":"policyengine-core","optional":false},{"reason":"Provides microdata for simulations; can introduce complex dependencies like `torch` for specific features.","package":"policyengine-us-data","optional":true}],"imports":[{"symbol":"system","correct":"from policyengine_us import system"},{"symbol":"Person","correct":"from policyengine_core.entities import Person"},{"symbol":"Household","correct":"from policyengine_core.entities import Household"},{"note":"The library was renamed from openfisca-us to policyengine-us in November 2022. Core components also moved to policyengine_core.","wrong":"from openfisca_us.simulation import Simulation","symbol":"Simulation","correct":"from policyengine_core.simulation import Simulation"}],"quickstart":{"code":"from policyengine_us import system\nfrom policyengine_core.entities import Person, Household\nfrom policyengine_core.simulation import Simulation\n\n# Define a simple household\n# A person named 'alice' who is 40 years old and has wage income\nalice = Person(age=40, wages=50000, employment_status='EMPLOYED')\n\n# A household with Alice\nhousehold = Household(members=[alice])\n\n# Get the current US tax-benefit system\n# By default, uses the latest available policy year (e.g., 2025 as of recent updates)\nsim_system = system.get_system()\n\n# Create a simulation for the household\nsimulation = Simulation(household=household, system=sim_system)\n\n# Calculate a variable, e.g., Alice's net income in 2025\nalice_net_income = simulation.get_person_variable(person_id=alice.id, variable_name='net_income', period='2025')\n\nprint(f\"Alice's net income in 2025: ${alice_net_income:,.2f}\")\n\n# Example of applying a simple reform (e.g., a universal basic income)\nreform_code = {\n    'universal_basic_income': [\n        {\n            'period': '2025',\n            'value': 12000,\n            'description': 'A universal basic income of $12,000 per year for all adults.'\n        }\n    ]\n}\n\n# Apply the reform to the system\nreformed_system = system.get_system(reform=reform_code)\n\n# Run simulation with the reformed system\nreformed_simulation = Simulation(household=household, system=reformed_system)\n\nalice_net_income_reformed = reformed_simulation.get_person_variable(\n    person_id=alice.id, variable_name='net_income', period='2025'\n)\n\nprint(f\"Alice's net income in 2025 with UBI reform: ${alice_net_income_reformed:,.2f}\")\n","lang":"python","description":"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."},"warnings":[{"fix":"Update all import statements from `openfisca_us` or `openfisca_core` to `policyengine_us` and `policyengine_core` respectively.","message":"The library was renamed from `openfisca-us` to `policyengine-us` in November 2022. This included changes to package names and core import paths.","severity":"breaking","affected_versions":"< 1.0 (before Nov 2022)"},{"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.","message":"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).","severity":"gotcha","affected_versions":"All versions"},{"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.","message":"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.","severity":"gotcha","affected_versions":"All versions"},{"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.","message":"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.","severity":"gotcha","affected_versions":"Versions requiring `policyengine-us-data` for L0 penalty features (specific versions not fully specified but noted as a breaking change in issue #6303)"},{"fix":"Implement a token refresh mechanism in your application to obtain a new authentication token before the current one expires.","message":"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.","severity":"gotcha","affected_versions":"All versions interacting with the PolicyEngine REST API"}],"env_vars":null,"last_verified":"2026-04-16T00:00:00.000Z","next_check":"2026-07-15T00:00:00.000Z","problems":[{"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`.","cause":"The library package name changed from `openfisca-us` to `policyengine-us`.","error":"ModuleNotFoundError: No module named 'openfisca_us'"},{"fix":"Use `system.get_system()` to initialize the tax-benefit system object before passing it to a `Simulation` or accessing its parameters/variables.","cause":"Attempting to call the `system` object directly without using its methods (e.g., `get_system()`).","error":"TypeError: 'System' object is not callable"},{"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.","cause":"The requested policy year (period) might be outside the range supported by the installed `policyengine-us` version or the specific parameter/variable.","error":"policyengine_core.exceptions.UnknownPeriodError: No data for period 'YYYY'"}]}