Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
89 changes: 89 additions & 0 deletions CLAUDE.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,89 @@
# CLAUDE.md — grc-tech-evaluation

## Repo Overview

Standalone evaluation workspace for comparing six power-system modeling tools.
This is NOT an installable Python package — each `evaluations/<tool>/` directory
is an independent project with its own virtualenv and dependency set.

No ZGE internal dependencies. No connection to the trading platform repos.

## Directory Layout

- `evaluation_guides/` — Rubric and test protocol (read-only reference)
- `data/networks/` — Shared MATPOWER .m case files used by all tools
- `evaluations/<tool>/` — One directory per tool under evaluation
- `evaluations/<tool>/results/<dimension>/` — Test outputs organized by rubric dimension

## Execution Environment

**Never run code, tests, linters, or pre-commit locally.** Always use the devcontainer.
All commands (pytest, julia, octave, pre-commit, etc.) must run inside the container.

Use the `dc-exec` helper (`.devcontainer/dc-exec`) which works from both the main
checkout and any git worktree:

```bash
# Open a shell inside the devcontainer
.devcontainer/dc-exec bash

# Run a one-off command
.devcontainer/dc-exec <command>

# Run in a specific container directory
.devcontainer/dc-exec -C /workspace/evaluations/pypsa uv run python -c "import pypsa"
```

`dc-exec` finds the container via `git worktree list` + Docker labels, so it works
from `.claude/worktrees/<name>/` where `devcontainer exec --workspace-folder .` cannot.

## Per-Tool Setup

### Python tools (pypsa, pandapower, gridcal)

```bash
cd evaluations/<tool>
uv sync
uv run python verify_install.py
```

Do NOT use `pip install` — these are uv-managed projects.

### Julia tools (powermodels, powersimulations)

```bash
cd evaluations/<tool>
julia --project=. -e 'using Pkg; Pkg.instantiate()'
julia --project=. verify_install.jl
```

**Julia startup is slow by design.** `Pkg.instantiate()` compiles packages to native code on first run
(can take many minutes). Subsequent runs reuse the precompiled cache but still pay a 5–15s load
tax per invocation to deserialize it.

For repeated evaluation runs, stay in the REPL and `include()` your script instead of re-launching:

```julia
# start once
julia --project=.

# then inside the REPL, re-run without restart overhead:
julia> include("my_eval_script.jl")
```

### MATPOWER (Octave)

```bash
cd evaluations/matpower
bash setup.sh # downloads MATPOWER 8.1
octave verify_install.m
```

## Conventions

- Python 3.12, Julia 1.10
- Ruff for Python linting (line-length = 100)
- Conventional commits enforced by pre-commit
- Each tool has isolated dependencies — no shared virtualenv
- Results go in `evaluations/<tool>/results/<dimension>/`
- The seven rubric dimensions: gate, expressiveness, extensibility, scalability, accessibility, maturity, supply_chain
28 changes: 28 additions & 0 deletions data/fnm/.gitignore
Original file line number Diff line number Diff line change
@@ -0,0 +1,28 @@
# FNM Data Files — NDA-restricted, never commit
*.raw
*.RAW
*.csv
*.CSV
*.parquet
*.m

# Intermediate and reference output directories
intermediate/**
!intermediate/
!intermediate/README.md
!intermediate/schemas/
!intermediate/schemas/*.json
reference/**
!reference/
!reference/*/
!reference/pass_conditions.json

# Allow tracked infrastructure files
!manifest.json
!README.md
!**/README.md
!scripts/**/*.py
!scripts/**/*.m
!docs/**/*.md
!docs/**/*.json
!.gitignore
51 changes: 51 additions & 0 deletions data/fnm/README.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,51 @@
# FNM Data Directory

This directory contains artifacts related to the Full Network Model (FNM) ingestion
pipeline. The FNM data itself is NDA-restricted and **must never be committed to version
control**.

## Directory Layout

```
data/fnm/
├── manifest.json # Machine-readable list of expected FNM source files
├── .gitignore # Blocks all FNM data files from version control
├── README.md # This file
├── intermediate/ # Parser output (Parquet, intermediate formats)
├── reference/ # Phase 3 verification / reference solution datasets
├── docs/ # Reference documentation for PSS/E record types, supplemental CSVs
└── scripts/ # Python modules for parsing, validation, and manifest I/O
```

## NDA Restrictions

FNM source files (PSS/E RAW files and supplemental CSVs) are provided under NDA.
They must not be committed, shared publicly, or stored in any unencrypted location outside
approved infrastructure.

The `.gitignore` in this directory blocks all data file extensions (`*.raw`, `*.csv`,
`*.parquet`, `*.m`) and the `intermediate/` and `reference/` directories from being tracked.

## FNM_PATH Environment Variable

All FNM-dependent code is gated by the `FNM_PATH` environment variable. Set it to the
directory containing the FNM source files:

```bash
export FNM_PATH=/path/to/fnm/source/files
```

When `FNM_PATH` is not set, FNM-dependent tests are skipped and parsers will raise errors
if invoked directly.

## Obtaining FNM Source Files

FNM source files must be obtained through the ISO's authorized distribution channels.
Contact the data engineering team for access. The `manifest.json` file lists all expected
source files with descriptions.

## Manifest

The `manifest.json` file enumerates every expected FNM source file. Use the
`scripts/manifest_io.py` module to load, validate, and update the manifest
programmatically rather than editing the JSON directly.
1 change: 1 addition & 0 deletions data/fnm/__init__.py
Original file line number Diff line number Diff line change
@@ -0,0 +1 @@
from __future__ import annotations
11 changes: 11 additions & 0 deletions data/fnm/docs/README.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,11 @@
# FNM Documentation Directory

This directory contains reference documentation for FNM data formats, PSS/E record types,
and supplemental CSV schemas. Documentation here supports developers working with the
FNM ingestion pipeline.

## Contents (populated by later phases)

- PSS/E v31 RAW format record type documentation
- Supplemental CSV field descriptions and schemas
- Data dictionary mapping FNM fields to internal representations
Loading
Loading