# CLAUDE.md

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

## Project intent

Backtest the ROI of a home battery against real historical hourly data. The core question:

> "If I had owned battery X over period Y, what would it have actually saved me?"

First-class scenarios:
- **No solar, just price arbitrage** — charge when day-ahead is cheap, discharge when expensive.
- **With solar** — store surplus generation instead of exporting at low / negative prices.

Two battery archetypes to compare side-by-side, because they have very different economics:

- **Plug-in (AC-coupled, schuko-style)** — small capacity (~2 kWh typical), low continuous output (~800 W), no grid export, simple time-shifting of own consumption only. Cheap, no installer.
- **Installed (hybrid inverter / DC-coupled)** — 5–15 kWh, 3–5 kW continuous, can charge from solar DC, can export to grid. Expensive, needs an electrician.

Output should include: euro savings vs. counterfactual, simple payback period, and a sensitivity sweep across battery size / power rating / dispatch strategy.

## Decisions still open — do not silently assume

These materially change the answer. Get the user to nail them down before writing simulation code, or state the assumption loudly in every result.

- **Battery model fidelity.** Round-trip efficiency, depth-of-discharge limit, calendar + cycle degradation, idle/standby draw, inverter efficiency. Start with constants. Only add curves once results turn out sensitive to them.
- **Solar PV system parameters.** Panel kWp, tilt, azimuth, inverter clipping. The horizontal irradiance from `solar_hourly.csv` is the input; PV output is computed downstream from these parameters. Default to a flat-roof horizontal panel until the user specifies otherwise.

## Decisions made

- **Country / market**: Netherlands.
- **Backtest window**: **2023-09-01T00:00:00Z → 2024-09-01T00:00:00Z** (8784 hours, 366 days; 99.5%+ coverage on all three signals). The next year forward had a 19-day P1 outage in March 2025 and was rejected.
- **Household load profile**: real P1 meter log from user's house in InfluxDB. The relevant field (`power-current`) is **import-only** — this house has **no PV today**. For "with solar" scenarios we synthesize PV output from a horizontal irradiance signal × assumed system parameters.
- **Day-ahead prices**: raw EPEX, hourly mean, in EUR/kWh, from user's InfluxDB. **No taxes, BTW, supplier markup, or saldering math is baked into the data** — those are tariff layers added downstream (UI / cost calc). Negative hours are real and preserved.
- **Tariff modelling**: out of scope for this codebase. The simulator outputs energy flows (kWh imported, exported, charged/discharged) per hour. The UI / spreadsheet layered on top translates those into euros under whichever tariff structure is being explored.
- **Solar gap forward**: irradiance sensor offline ~2025-09-09 → ~2026-04-29. Don't pick a window ending after Sep 2025 unless this is fixed.
- **Dispatch strategy**:
  1. Build a 24h-perfect-foresight oracle as the ceiling — what's the max possible savings?
  2. Build rule-based dispatchers (e.g. price percentile thresholds, SoC bands) and measure how close they get to the oracle.
  3. Stretch goal: an LSTM (or simpler) policy trained on historical sequences to beat the rules. Don't pull in PyTorch until the rules have a measured, reproducible gap to close.

## Data sources

The user's home InfluxDB is the *origin* — what actually happened in this house. But the simulator does **not** talk to InfluxDB. The user exports CSVs once and drops them in `data/raw/`; everything downstream reads CSV. That keeps runs reproducible, reviewable in git diffs (for small fixtures), and free of network/auth concerns.

What's known to exist in InfluxDB (verify before assuming):
- Hourly day-ahead electricity prices (>2 years).
- 15-minute electricity prices (~last 4 months).
- P1 smart-meter log (>2 years), 1-min / 10-sec resolution.
- Solar irradiance / PV output, with a gap from ~September 2025 to ~2026-04-29.

Expected raw CSVs (one per signal, UTC timestamps, hourly resampled at the source if possible):

- `data/raw/prices_hourly.csv` — `timestamp, eur_per_kwh` (or `eur_per_mwh`, document which)
- `data/raw/p1_hourly.csv` — `timestamp, import_kwh, export_kwh` (or net `consumption_kwh`)
- `data/raw/solar_hourly.csv` — `timestamp, pv_kwh` (and/or `irradiance_w_m2`)

Document the exact columns and units in `docs/quick-index.md` once the export is in place. Anything resampled or derived from these files goes to `data/processed/` and must be regenerable.

If the InfluxDB export turns out to be tedious to do by hand, write a single one-off script under `scripts/export_from_influx.py` that reads connection details from `.env`. It runs once per refresh, not every simulation run.

## Stack (assumed; change if user objects)

- Python 3.12+, managed with `uv`.
- `pandas` for time series; drop to `numpy` only if the inner loop becomes the bottleneck.
- `pytest` for tests.
- `influxdb-client` only if/when we write the optional one-off export script — not a runtime dep of the simulator.
- No web framework, no ORM, no plotting library yet. Add only when there is a concrete use case.
- No PyTorch / TensorFlow yet. Only after rule-based dispatchers have a measured gap to the oracle that's worth closing.

## Common commands

To be filled in once the project has code. For now:

```
uv sync                 # install deps once pyproject.toml exists
uv run pytest           # run tests
uv run pytest tests/test_dispatch.py::test_name   # run a single test
```

## Repo layout (target)

- `src/` — simulation code
- `tests/` — pytest. Unit-test the dispatch logic and tariff calc; one integration test that runs a full year on small fixture data
- `data/raw/` — immutable downloads (gitignored except small fixtures)
- `data/processed/` — derived, regenerable
- `docs/quick-index.md` — pointer to where each concept lives in the code
- `scripts/` — one-off data fetchers (ENTSO-E, KNMI, PVGIS)

## Things to resist (anti-overengineering for this project)

- Don't build a `BatteryStrategy` interface with one implementation. Write the function. Add the interface when the second strategy lands with a name.
- Don't build a tariff DSL or YAML config. Hard-code the NL tariff structure in a function until a second country actually shows up.
- Don't build a CLI framework. `python -m batteryroi.run --year 2024` via `argparse` is enough.
- Don't add caching / parquet / duckdb until a run takes >30s and the user is actively iterating on it.
- Don't add a `Battery` dataclass with builders/factories. Plain kwargs into a function.
- Don't pre-create empty modules "for structure". Files arrive when they have content.