add CLAUDE.md for Claude Code guidance

# CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

## Project Overview

Powersheds is a hydropower cascade simulator combining Rust performance with a Python interface. It simulates river-reservoir cascades at hourly resolution, computing storage, pool elevation, head, releases, spills, routing lags, and power generation driven by plant-level power schedules. The simulation is driven by hourly inflows (total inflows for headwater reservoirs; incremental/side inflows for in-network reservoirs) and target hourly power generation time series for each hydropower dam. The purpose of the model is computation of infeasible power generation, as measured by violations in power generation after accounting for water-related constraints in the simulation.

**Status**: v0.1 beta; v1.0 scheduled for September 2026.

## Build Commands

```bash

# Create virtual environment (recommended)

uv venv .venv --python 3.12

uv sync --frozen

# Activate: .\.venv\Scripts\Activate.ps1 (Windows) or source .venv/bin/activate (Unix)

# Build and install in editable mode (after activating venv)

maturin develop

# Build release wheel

maturin build --release

pip install target/wheels/powersheds-*.whl

```

After any Rust code changes, run `maturin develop` to recompile.

## Architecture

**Rust-Python Bridge**: Core simulator written in Rust for speed, exposed to Python via PyO3.

**Entry Point**: `powersheds.simulate_cascade(cascade_data: dict) -> dict[str, Result]`

**Source Structure**:

- `src/lib.rs` - Main module: data structures (`ReservoirData`, `RiverData`, `ConfluenceData`), `simulate_cascade()` orchestration, per-timestep reservoir simulation

- `src/helpers.rs` - Interpolation functions: `interpolate_elevation()`, `interpolate_storage()`, bilinear HPF interpolation for power/release computation

**Three Object Types**:

- **Reservoir**: Pool elevation from storage-elevation curves, head calculation, release/power via bilinear HPF interpolation, storage/capacity constraints

- **River**: Lag-based flow routing with legacy flows for initialization

- **Confluence**: Instantaneous flow merging (no lag)

**Simulation Order**: Objects execute in user-specified order (lower `simulation_order` runs first), enabling flexible cascade topologies.

**Key Algorithm Flow** (per timestep):

1. Sort objects by simulation order

2. For each reservoir: interpolate pool elevation → compute head → bilinear HPF lookup for target release → constrain release → update storage → compute actual power

3. Rivers delay flows by `lag` hours; confluences pass through immediately

4. Upstream releases/spills become downstream inflows

## Units

- Storage: Mm³ (Million Cubic Meters)

- Releases: Mm³/hr

- Head/Elevations: meters

- Power: MW

- HPF flows (`hpf_q`): m³/s (cumecs)

## Example

The `examples/Cumberland/` directory contains a full working example with 8 reservoirs. Run the Quarto notebook:

```r

reticulate::use_virtualenv(".venv", required = TRUE)

# quarto render examples/Cumberland/script.qmd

```

## Dependencies

- **Build**: maturin 1.9.4 (Rust-to-Python bridge)

- **Rust**: PyO3 0.23.3

- **Python**: pandas, numpy, scipy, matplotlib, PyYAML, pyarrow (pinned in `uv.lock`)