Metadata-Version: 2.5
Name: policyengine-us
Version: 2.56.0
Summary: US federal and state tax-benefit microsimulation model.
Author-email: PolicyEngine <hello@policyengine.org>
License-File: LICENSE
Classifier: Development Status :: 5 - Production/Stable
Classifier: License :: OSI Approved :: GNU Affero General Public License v3
Classifier: Operating System :: POSIX
Classifier: Programming Language :: Python
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Programming Language :: Python :: 3.14
Classifier: Topic :: Scientific/Engineering :: Information Analysis
Requires-Python: <3.15,>=3.11
Requires-Dist: microdf-python>=1.0.0
Requires-Dist: pandas>=3.0
Requires-Dist: policyengine-core>=3.32.27
Requires-Dist: spm-calculator<=1.0.0.post1,>=1.0.0
Requires-Dist: tables>=3.9
Requires-Dist: tqdm>=4.67.1
Provides-Extra: dev
Requires-Dist: build>=1.2.2.post1; extra == 'dev'
Requires-Dist: coverage>=7.9.2; extra == 'dev'
Requires-Dist: furo>=2024.8.6; extra == 'dev'
Requires-Dist: hypothesis>=6.100.0; extra == 'dev'
Requires-Dist: jupyter-book>=1.0.4.post1; extra == 'dev'
Requires-Dist: ruff>=0.9.0; extra == 'dev'
Requires-Dist: setuptools>=80.9.0; extra == 'dev'
Requires-Dist: towncrier>=24.8.0; extra == 'dev'
Description-Content-Type: text/markdown

# PolicyEngine US

[![codecov](https://codecov.io/gh/PolicyEngine/policyengine-us/branch/main/graph/badge.svg?token=BLoCjCf5Qr)](https://codecov.io/gh/PolicyEngine/policyengine-us)
[![PyPI version](https://badge.fury.io/py/policyengine-us.svg)](https://badge.fury.io/py/policyengine-us)
[![Code style: ruff](https://img.shields.io/endpoint?url=https://raw.githubusercontent.com/astral-sh/ruff/main/assets/badge/v2.json)](https://github.com/astral-sh/ruff)

> **For microsimulation, use [policyengine.py](https://github.com/PolicyEngine/policyengine.py).** Society-wide microsimulation — population aggregates and distributional or budgetary impacts — is moving to the managed `policyengine.py` bundle, which pins certified, calibration-gated datasets. **Direct microsimulation via `policyengine-us` (`Microsimulation()`) is deprecated** and being migrated to `policyengine.py`. This package remains the home of the US tax-benefit rules and household-level calculations. Microsimulation results are estimates — inspect dataset calibration at https://calibration-diagnostics.vercel.app/populace.


PolicyEngine US is a microsimulation model of the US state and federal tax and benefit system.

PolicyEngine US supports Python 3.11 through 3.14 and requires pandas 3 or
later. To install, run `pip install policyengine-us`.

This release requires `spm-calculator>=1.0.0,<=1.0.0.post1` (the canonical SPM threshold API).
Previously published country versions retain their original dependency metadata;
when reproducing one of those versions, include the compatible calculator
explicitly, for example:

```bash
uv pip install "policyengine-us==1.824.7" "spm-calculator==0.3.1"
```

To install PolicyEngine US as part of a certified PolicyEngine bundle, use the
bundle installer published by `policyengine`, for example:

```bash
uvx --from policyengine policyengine bundle install --country us --venv .venv
```

## Statutes, forms and agency practice

When a statute conflicts with a regulation, form, instructions, manual or
stated agency practice, PolicyEngine US's rule is to follow the statute.
Forms and instructions fill gaps where the statute is silent. Each such
conflict is recorded in the source-conflict register that PolicyEngine shares
with the Axiom Foundation, including any code that does not follow the rule
yet: `known-source-conflicts.yaml` in
[TheAxiomFoundation/rulespec-us](https://github.com/TheAxiomFoundation/rulespec-us).
For each conflict it gives what each source says, a worked example, the
reading this model takes and why, and the code and tests that implement it.
The code marks the deciding line with `# Source conflict <jurisdiction>:<id>`. See
[CONTRIBUTING.md](CONTRIBUTING.md#source-conflicts).
