Metadata-Version: 2.2
Name: cugrid
Version: 0.0.1.dev1
Summary: CUDA-accelerated AC power flow and ACOPF for large-scale transmission networks (20k+ buses)
License: Apache-2.0
Requires-Python: >=3.12
Provides-Extra: dev
Requires-Dist: pytest>=7; extra == "dev"
Requires-Dist: pre-commit>=4; extra == "dev"
Provides-Extra: reference
Requires-Dist: pandapower; extra == "reference"
Requires-Dist: pandas; extra == "reference"
Requires-Dist: pyarrow; extra == "reference"
Description-Content-Type: text/markdown

# cugrid

CUDA-accelerated AC power flow and ACOPF for large-scale transmission networks:
batched Newton-Raphson PF, contingency screening (N-1 / N-1-1), hosting capacity, and
curtailment optimization. See [`plans/cugrid-implementation-plan.md`](plans/cugrid-implementation-plan.md)
for the full phased plan.

**Status:** Phase 0 (scaffolding) — no solver logic yet.

## Layout

```
include/cugrid/   public C++ headers (common/: DeviceVector, error checks, timers)
src/                 io, network, pf/{cpu,cuda}, opf/{cpu,cuda}, linalg — filled in from Phase 1 onward
python/cugrid/     pybind11 module + Python package
tests/unit/          GoogleTest (C++), CPU-only, runs in CI on every PR
tests/validation/    accuracy checks vs pandapower / PowerModels (from Phase 2 onward)
tests/cases/         vendored small .m cases + generated reference solutions
scripts/             case download, pandapower/Ipopt reference generation
docs/math/           derivations (Jacobian, KKT, per-asset models)
docs/benchmarks/     performance reports
```

## Build

Requires CMake ≥ 3.24 and a C++20 compiler. CUDA (12.x) is auto-detected; the project
builds CPU-only when no `nvcc` is on `PATH` (e.g. laptops, cloud CI) and CUDA-enabled
targets simply aren't compiled.

Python tooling uses [uv](https://docs.astral.sh/uv/); the pinned interpreter version
lives in [`.python-version`](.python-version) (3.12).

### Python extension

```bash
uv sync --extra dev
uv run python -c "import cugrid; print(cugrid.hello()); print(cugrid.cuda_available())"
```

`uv sync` creates `.venv/`, installs the pinned Python if needed, and builds the pybind11
extension in editable mode via scikit-build-core. Re-run `uv sync` after touching C++
sources under `python/cugrid/` or `include/`; plain `uv run` does not rebuild automatically.

### C++ unit tests (CPU-only, GoogleTest fetched via CMake)

```bash
cmake -S . -B build -DCUGRID_BUILD_PYTHON=OFF
cmake --build build
ctest --test-dir build --output-on-failure
```

### Force CUDA on/off

```bash
cmake -S . -B build -DCUGRID_ENABLE_CUDA=ON   # requires nvcc + CUDA Toolkit on PATH
cmake -S . -B build -DCUGRID_ENABLE_CUDA=OFF  # CPU-only even if a CUDA compiler is present
```

### Lint / pre-commit

Ruff (Python) and clang-format (C++) run via [pre-commit](https://pre-commit.com/):

```bash
uv sync --extra dev
uv run pre-commit install       # runs the hooks on `git commit`
uv run pre-commit run --all-files
```

## Reference solutions

```bash
uv sync --extra reference
uv run python scripts/make_reference.py --cases case9 case118 --out tests/cases
```

Generates pandapower PF results (`V, θ` per bus; branch flows) that the CPU/GPU solvers
are validated against (Phase 2+).
