rate-design-platform

Simulation platform for electric rate design (heat-pump-friendly rates, Bill Alignment Test). Runs CAIRO on ResStock building loads and Cambium marginal costs; outputs calibrated tariffs, customer bills, and BAT results to S3 for use in reports2. Covers New York and Rhode Island.

Where things are

Path	Purpose
rate_design/	Jurisdiction-specific logic. ny/hp_rates/ and ri/hp_rates/ each have a Justfile (main task interface), config/ (tariffs, tariff_maps, marginal_costs, scenarios), and scenario entrypoints (e.g. run_scenario.py).
data/	Data pipelines: fetch, convert, and upload datasets (Cambium, ResStock, EIA, HUD, FRED, etc.) to S3. Each subdir has its own Justfile.
utils/	Shared code by phase: pre/ (tariff mapping, scenario YAMLs, marginal costs), mid/ (post-CAIRO steps), post/ (e.g. LMI discounts).
context/	Reference docs and papers (BAT, Cambium, ResStock, CAIRO).
tests/	Pytest tests.
infra/	Terraform and scripts for EC2/dev.

Large inputs/outputs (buildstock, CAIRO cases) are gitignored; sync via S3 or keep local. See AGENTS.md for detailed layout and S3 paths.

Install

From the repo (development / running simulations):

just install

Uses uv for Python (see pyproject.toml). CAIRO is a private Git dependency; set GH_PAT for clone.

As a library dependency (from PyPI):

pip install rate-design-platform
# or
uv add rate-design-platform

Note: The CAIRO simulation engine is a private Git dependency that cannot be distributed through PyPI. Install from the repo using just install if you need to run CAIRO simulations directly. See CHANGELOG.md for details. Optional env vars (e.g. ARCADIA_APP_ID, HUD_API_KEY, EIA_API_KEY) are in .env.example—copy to .env and fill as needed. For AWS (S3), run just aws to refresh SSO when needed.

Pre-commit hooks: just install installs git pre-commit hooks that enforce formatting (including Justfile formatting) at every git commit. If you already have the repo cloned and skipped just install, run this once to install them:

uv run prek install --install-hooks

Without the hooks, Justfile formatting issues will only be caught by CI, not locally.

Run sims

Use Just from the jurisdiction directory. Examples:

• RI: cd rate_design/ri/hp_rates && just run-scenario 1 (and other run numbers; see that Justfile).
• NY: Pre-steps in rate_design/ny/hp_rates/Justfile: create scenario YAMLs, write tariff maps, create marginal-cost data; then run the scenario (see recipes and run_scenario.py there).

Root Justfile: just check (lint/format/typecheck), just test (pytest). For full task list, run just in the root or in a jurisdiction folder.