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 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; the pinned interpreter version lives in .python-version (3.12).

Python extension

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)

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

Force CUDA on/off

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:

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

Reference solutions

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+).