cugrid 0.0.1.dev1__tar.gz

cugrid-0.0.1.dev1/.clang-format

@@ -0,0 +1,4 @@
+BasedOnStyle: Google
+ColumnLimit: 120
+DerivePointerAlignment: false
+PointerAlignment: Left

cugrid-0.0.1.dev1/.github/workflows/ci.yml

@@ -0,0 +1,55 @@
+name: CI
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+
+jobs:
+  lint:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+      - uses: pre-commit/action@v3.0.1
+
+  cpu-tests:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: astral-sh/setup-uv@v5
+        with:
+          enable-cache: true
+      - name: Install build tooling
+        # The runner's system Python is externally managed (PEP 668), so `uv pip
+        # install --system` is rejected; use a throwaway venv and put it on PATH.
+        run: |
+          uv venv .venv-tools
+          uv pip install --python .venv-tools/bin/python cmake ninja
+          echo "$PWD/.venv-tools/bin" >> "$GITHUB_PATH"
+      - name: Configure (CPU-only)
+        # No CUDA toolchain on GitHub-hosted runners: CUGRID_ENABLE_CUDA auto-detects
+        # off. GPU kernels are exercised on a separate self-hosted/manual GPU stage.
+        run: cmake -S . -B build -G Ninja -DCUGRID_BUILD_TESTS=ON -DCUGRID_BUILD_PYTHON=OFF
+      - name: Build
+        run: cmake --build build
+      - name: Test
+        run: ctest --test-dir build --output-on-failure
+
+  python-build:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: astral-sh/setup-uv@v5
+        with:
+          enable-cache: true
+      - name: uv sync
+        run: uv sync --extra dev
+      - name: Smoke test the extension
+        run: uv run python -c "import cugrid; print(cugrid.hello()); print('cuda_available =', cugrid.cuda_available())"
+
+  # GPU kernel build + tests require a CUDA toolkit and are not available on
+  # GitHub-hosted runners. Run manually or wire to a self-hosted GPU runner:
+  #   cmake -S . -B build -DCUGRID_ENABLE_CUDA=ON && cmake --build build && ctest --test-dir build

cugrid-0.0.1.dev1/.github/workflows/publish.yml

@@ -0,0 +1,39 @@
+name: Publish to PyPI
+
+on:
+  push:
+    tags: ["v*"]
+
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: astral-sh/setup-uv@v5
+        with:
+          enable-cache: true
+      - name: Build sdist and wheel
+        # No CUDA toolchain on GitHub-hosted runners, same as the `python-build`
+        # CI job: CUGRID_ENABLE_CUDA auto-detects off and this produces a
+        # CPU-only wheel. GPU users build from source until a self-hosted GPU
+        # release stage exists.
+        run: uv build
+      - uses: actions/upload-artifact@v4
+        with:
+          name: dist
+          path: dist/
+
+  publish:
+    needs: build
+    runs-on: ubuntu-latest
+    environment: pypi
+    steps:
+      - uses: actions/download-artifact@v4
+        with:
+          name: dist
+          path: dist/
+      - uses: astral-sh/setup-uv@v5
+      - name: Publish to PyPI
+        env:
+          UV_PUBLISH_TOKEN: ${{ secrets.PYPI_TOKEN }}
+        run: uv publish

cugrid-0.0.1.dev1/.gitignore

@@ -0,0 +1,20 @@
+build/
+build-*/
+cmake-build-*/
+_skbuild/
+dist/
+*.egg-info/
+__pycache__/
+*.pyc
+.venv/
+venv/
+*.so
+*.pyd
+*.parquet
+*.npz
+.cache/
+.pytest_cache/
+.ruff_cache/
+.idea/
+.DS_Store
+CMakeUserPresets.json

cugrid-0.0.1.dev1/.pre-commit-config.yaml

@@ -0,0 +1,23 @@
+repos:
+  - repo: https://github.com/pre-commit/pre-commit-hooks
+    rev: v6.0.0
+    hooks:
+      - id: trailing-whitespace
+      - id: end-of-file-fixer
+      - id: check-merge-conflict
+      - id: check-added-large-files
+      - id: check-yaml
+      - id: check-toml
+      - id: mixed-line-ending
+
+  - repo: https://github.com/astral-sh/ruff-pre-commit
+    rev: v0.15.20
+    hooks:
+      - id: ruff
+        args: [--exit-non-zero-on-fix]
+
+  - repo: https://github.com/pre-commit/mirrors-clang-format
+    rev: v18.1.8
+    hooks:
+      - id: clang-format
+        types_or: [c++, c]

cugrid-0.0.1.dev1/.python-version

@@ -0,0 +1 @@
+3.12

cugrid-0.0.1.dev1/CLAUDE.md

@@ -0,0 +1,113 @@
+# CLAUDE.md
+
+This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
+
+## Instructions:
+
+- do not include claude code in commit message and PR message
+
+## What this is
+
+`cugrid` is a CUDA-accelerated AC power flow / ACOPF solver for large-scale (20k+ bus) transmission
+networks: batched Newton-Raphson PF, N-1/N-1-1 contingency screening, hosting capacity, and
+curtailment optimization. See [`plans/cugrid-implementation-plan.md`](plans/cugrid-implementation-plan.md)
+for the full phased roadmap, workload definitions, and architecture (the "screening funnel").
+
+**Current state:** Phase 0 (scaffolding) only — no network model or solver logic exists yet. The
+codebase is a build skeleton: common C++ utilities, a pybind11 hello-world extension, and CI.
+
+## Commands
+
+Python tooling uses [uv](https://docs.astral.sh/uv/), pinned to the version in `.python-version` (3.12).
+
+```bash
+# Python extension: build + install editable, then run
+uv sync --extra dev
+uv run python -c "import cugrid; print(cugrid.hello()); print(cugrid.cuda_available())"
+
+# Re-run after touching any C++ source under python/cugrid/ or include/ — `uv run`
+# alone does not rebuild the extension.
+uv sync --extra dev
+
+# C++ unit tests (CPU-only, GoogleTest fetched via CMake FetchContent)
+cmake -S . -B build -DCUGRID_BUILD_PYTHON=OFF
+cmake --build build
+ctest --test-dir build --output-on-failure
+
+# Run a single test by name
+ctest --test-dir build -R ScopedTimer.LabelIsPreserved --output-on-failure
+
+# Force CUDA on/off regardless of auto-detection
+cmake -S . -B build -DCUGRID_ENABLE_CUDA=ON    # requires nvcc + CUDA Toolkit on PATH
+cmake -S . -B build -DCUGRID_ENABLE_CUDA=OFF
+
+# Lint (ruff + clang-format, run via pre-commit; see .pre-commit-config.yaml)
+uv run pre-commit install       # one-time: installs the git commit hook
+uv run pre-commit run --all-files
+
+# Generate pandapower PF reference solutions used by validation tests
+uv sync --extra reference
+uv run python scripts/make_reference.py --cases case9 case118 --out tests/cases
+```
+
+## Architecture
+
+### CUDA is optional and auto-detected — never assume it's present
+
+The top-level `CMakeLists.txt` runs `check_language(CUDA)` *before* `project()` and sets
+`CUGRID_ENABLE_CUDA` from whether a CUDA compiler was actually found, not from the platform. This
+machine (and most dev/CI machines) has no CUDA toolkit, so every change must build and pass tests
+in CPU-only mode. When `CUGRID_ENABLE_CUDA` is on, the `cugrid_common` interface target gets
+`CUGRID_HAVE_CUDA` defined and links `CUDA::cudart`; `CUGRID_HAVE_NVTX` is
+added separately if `CUDA::nvtx3` exists. All CUDA-only code (`include/cugrid/common/device_vector.hpp`,
+anything under `src/*/cuda/`) must be wrapped in `#ifdef CUGRID_HAVE_CUDA` so the file still compiles
+(as a no-op) in CPU-only builds — see `error_check.hpp` and `device_vector.hpp` for the pattern.
+`timer.hpp`'s `ScopedTimer` is the one common utility that works unconditionally (chrono-based),
+with NVTX emission compiled in only under `CUGRID_HAVE_NVTX`.
+
+### Build topology
+
+- `cugrid_common` (CMakeLists.txt) is a header-only INTERFACE target: include path + `cxx_std_20`
+  + the CUDA/NVTX defines above. Every future target (CPU or GPU, library or test) links against it
+  rather than repeating include/define logic.
+- The pybind11 module compiles to `_core` (from `python/cugrid/_bindings.cpp`) and is imported by
+  `python/cugrid/__init__.py` as `cugrid._core`. Native code lives under
+  `python/cugrid/` only for the bindings shim; the actual C++ implementation goes in `src/` and
+  `include/cugrid/`, and the bindings link against it — don't grow business logic inside
+  `_bindings.cpp`.
+- `CUGRID_BUILD_TESTS` (GoogleTest, fetched) and `CUGRID_BUILD_PYTHON` (pybind11 module) are
+  independent CMake options so CI can build/test the C++ side without touching Python packaging,
+  and `pip`/`uv` installs skip the GoogleTest fetch (`pyproject.toml` sets
+  `CUGRID_BUILD_TESTS=OFF` for the scikit-build-core path).
+
+### Planned source layout (see `plans/cugrid-implementation-plan.md` §3 and §5)
+
+`src/{io,network,pf/cpu,pf/cuda,opf/cpu,opf/cuda,linalg,common}` currently hold only `.gitkeep` —
+they exist to match the plan's phase-by-phase build-out:
+- Every CUDA kernel gets a CPU twin in the parallel `cpu/` directory, validated against pandapower
+  first (design principle: CPU reference before GPU port).
+- All device data is Structure-of-Arrays (SoA), flat arrays indexed by bus/branch/gen ID — never
+  per-object structs on GPU.
+- APIs are batch-first from Phase 1 onward (`n_scenarios` dimension, default 1) — this is a
+  deliberate constraint from the plan because retrofitting batching later is expensive, and the
+  whole roadmap (N-1, N-1-1, 8760-hour time series, hosting capacity) is one shape of batched
+  scenario sweep with different filtering.
+- Symbolic factorization (sparsity pattern) is computed once per topology and reused; only numeric
+  refactorization happens per iteration/scenario. Outages are modeled as low-rank Woodbury updates
+  to the base-case factorization (Phase 4), not full re-factorization.
+
+### CI shape
+
+Three independent GitHub Actions jobs (`.github/workflows/ci.yml`): `lint` (runs
+`.pre-commit-config.yaml` via `pre-commit/action` — ruff + clang-format + the standard
+pre-commit-hooks), `cpu-tests` (raw CMake/CTest build with `CUGRID_BUILD_PYTHON=OFF`, uses
+`astral-sh/setup-uv`), `python-build` (`uv sync` + import smoke test, uses `astral-sh/setup-uv`).
+None of these have a CUDA toolchain — GPU kernels are validated on a self-hosted/manual GPU stage,
+not GitHub-hosted runners. `cpu-tests` installs `cmake`/`ninja` into a throwaway `uv venv` and adds
+it to `$GITHUB_PATH`, rather than `uv pip install --system`, because the runner's system Python is
+PEP 668 externally-managed.
+
+## Code style
+
+- Repo-wide `.clang-format`: Google style, 120-column limit, left-aligned pointers.
+- C++ namespace is `cugrid::common` (mirrors `include/cugrid/`), not `gridcuda`.

cugrid-0.0.1.dev1/CMakeLists.txt

@@ -0,0 +1,72 @@
+cmake_minimum_required(VERSION 3.24)
+
+include(CheckLanguage)
+check_language(CUDA)
+if(CMAKE_CUDA_COMPILER)
+  set(_cugrid_cuda_default ON)
+else()
+  set(_cugrid_cuda_default OFF)
+endif()
+
+# Auto-detected: ON if a CUDA compiler is on PATH, OFF otherwise (e.g. CPU-only dev
+# machines, cloud CI). Override explicitly with -DCUGRID_ENABLE_CUDA=ON/OFF.
+option(CUGRID_ENABLE_CUDA "Build CUDA kernels" ${_cugrid_cuda_default})
+option(CUGRID_BUILD_TESTS "Build C++ unit tests (GoogleTest, fetched)" ON)
+option(CUGRID_BUILD_PYTHON "Build the pybind11 extension module" ON)
+
+if(CUGRID_ENABLE_CUDA AND NOT CMAKE_CUDA_COMPILER)
+  message(WARNING "CUGRID_ENABLE_CUDA=ON but no CUDA compiler was found on PATH; building CPU-only.")
+  set(CUGRID_ENABLE_CUDA OFF)
+endif()
+
+if(CUGRID_ENABLE_CUDA)
+  project(cugrid LANGUAGES CXX CUDA)
+else()
+  project(cugrid LANGUAGES CXX)
+endif()
+
+set(CMAKE_CXX_STANDARD 20)
+set(CMAKE_CXX_STANDARD_REQUIRED ON)
+set(CMAKE_CXX_EXTENSIONS OFF)
+set(CMAKE_POSITION_INDEPENDENT_CODE ON)
+
+if(NOT CMAKE_BUILD_TYPE AND NOT CMAKE_CONFIGURATION_TYPES)
+  set(CMAKE_BUILD_TYPE RelWithDebInfo CACHE STRING "Build type" FORCE)
+endif()
+
+# Header-only interface target: include path + language standard + optional
+# CUDA/NVTX defines. Every cugrid target (CPU or GPU) links against this.
+add_library(cugrid_common INTERFACE)
+target_include_directories(cugrid_common INTERFACE
+  $<BUILD_INTERFACE:${CMAKE_CURRENT_SOURCE_DIR}/include>
+  $<INSTALL_INTERFACE:include>)
+target_compile_features(cugrid_common INTERFACE cxx_std_20)
+
+if(CUGRID_ENABLE_CUDA)
+  set(CMAKE_CUDA_STANDARD 20)
+  set(CMAKE_CUDA_STANDARD_REQUIRED ON)
+  find_package(CUDAToolkit REQUIRED)
+
+  target_compile_definitions(cugrid_common INTERFACE CUGRID_HAVE_CUDA)
+  target_link_libraries(cugrid_common INTERFACE CUDA::cudart)
+
+  if(TARGET CUDA::nvtx3)
+    target_compile_definitions(cugrid_common INTERFACE CUGRID_HAVE_NVTX)
+    target_link_libraries(cugrid_common INTERFACE CUDA::nvtx3)
+  endif()
+endif()
+
+if(CUGRID_BUILD_PYTHON)
+  find_package(Python 3.12 COMPONENTS Interpreter Development.Module REQUIRED)
+  find_package(pybind11 CONFIG REQUIRED)
+
+  pybind11_add_module(_core python/cugrid/_bindings.cpp)
+  target_link_libraries(_core PRIVATE cugrid_common)
+
+  install(TARGETS _core DESTINATION cugrid)
+endif()
+
+if(CUGRID_BUILD_TESTS)
+  enable_testing()
+  add_subdirectory(tests/unit)
+endif()

cugrid-0.0.1.dev1/PKG-INFO

@@ -0,0 +1,92 @@
+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+).

cugrid-0.0.1.dev1/README.md

@@ -0,0 +1,77 @@
+# 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+).

cugrid-0.0.1.dev1/include/cugrid/common/device_vector.hpp

@@ -0,0 +1,96 @@
+#pragma once
+
+#include <cstddef>
+#include <utility>
+#include <vector>
+
+#include "cugrid/common/error_check.hpp"
+
+#ifdef CUGRID_HAVE_CUDA
+#include <cuda_runtime.h>
+#endif
+
+namespace cugrid::common {
+
+#ifdef CUGRID_HAVE_CUDA
+
+// Owns a device-resident array of `T` allocated with cudaMalloc. Move-only.
+// All device data in cugrid is flat and SoA; this is the single allocation
+// primitive the rest of the codebase builds on.
+template <typename T>
+class DeviceVector {
+ public:
+  DeviceVector() = default;
+
+  explicit DeviceVector(std::size_t count) : size_(count) {
+    if (size_ > 0) {
+      CUGRID_CUDA_CHECK(cudaMalloc(&data_, size_ * sizeof(T)));
+    }
+  }
+
+  DeviceVector(const T* host_src, std::size_t count) : DeviceVector(count) { copy_from_host(host_src, count); }
+
+  ~DeviceVector() { reset(); }
+
+  DeviceVector(const DeviceVector&) = delete;
+  DeviceVector& operator=(const DeviceVector&) = delete;
+
+  DeviceVector(DeviceVector&& other) noexcept : data_(other.data_), size_(other.size_) {
+    other.data_ = nullptr;
+    other.size_ = 0;
+  }
+
+  DeviceVector& operator=(DeviceVector&& other) noexcept {
+    if (this != &other) {
+      reset();
+      data_ = other.data_;
+      size_ = other.size_;
+      other.data_ = nullptr;
+      other.size_ = 0;
+    }
+    return *this;
+  }
+
+  void copy_from_host(const T* host_src, std::size_t count) {
+    CUGRID_CUDA_CHECK(cudaMemcpy(data_, host_src, count * sizeof(T), cudaMemcpyHostToDevice));
+  }
+
+  void copy_to_host(T* host_dst, std::size_t count) const {
+    CUGRID_CUDA_CHECK(cudaMemcpy(host_dst, data_, count * sizeof(T), cudaMemcpyDeviceToHost));
+  }
+
+  std::vector<T> to_host() const {
+    std::vector<T> out(size_);
+    if (size_ > 0) {
+      copy_to_host(out.data(), size_);
+    }
+    return out;
+  }
+
+  void zero() {
+    if (size_ > 0) {
+      CUGRID_CUDA_CHECK(cudaMemset(data_, 0, size_ * sizeof(T)));
+    }
+  }
+
+  [[nodiscard]] T* data() noexcept { return data_; }
+  [[nodiscard]] const T* data() const noexcept { return data_; }
+  [[nodiscard]] std::size_t size() const noexcept { return size_; }
+  [[nodiscard]] bool empty() const noexcept { return size_ == 0; }
+
+ private:
+  void reset() {
+    if (data_ != nullptr) {
+      cudaFree(data_);  // noexcept context: log-and-ignore rather than throw from a destructor
+      data_ = nullptr;
+    }
+    size_ = 0;
+  }
+
+  T* data_ = nullptr;
+  std::size_t size_ = 0;
+};
+
+#endif  // CUGRID_HAVE_CUDA
+
+}  // namespace cugrid::common

cugrid-0.0.1.dev1/include/cugrid/common/error_check.hpp

@@ -0,0 +1,38 @@
+#pragma once
+
+#include <stdexcept>
+#include <string>
+
+#ifdef CUGRID_HAVE_CUDA
+#include <cuda_runtime.h>
+
+namespace cugrid::common {
+
+class CudaError : public std::runtime_error {
+ public:
+  CudaError(cudaError_t code, const char* expr, const char* file, int line)
+      : std::runtime_error(build_message(code, expr, file, line)), code_(code) {}
+
+  [[nodiscard]] cudaError_t code() const noexcept { return code_; }
+
+ private:
+  static std::string build_message(cudaError_t code, const char* expr, const char* file, int line) {
+    return std::string("CUDA error: ") + cudaGetErrorString(code) + " (" + std::to_string(static_cast<int>(code)) +
+           ") at " + file + ":" + std::to_string(line) + " in `" + expr + "`";
+  }
+
+  cudaError_t code_;
+};
+
+inline void check_cuda(cudaError_t code, const char* expr, const char* file, int line) {
+  if (code != cudaSuccess) {
+    throw CudaError(code, expr, file, line);
+  }
+}
+
+}  // namespace cugrid::common
+
+// Wraps a CUDA runtime call, throwing cugrid::common::CudaError on failure.
+#define CUGRID_CUDA_CHECK(expr) ::cugrid::common::check_cuda((expr), #expr, __FILE__, __LINE__)
+
+#endif  // CUGRID_HAVE_CUDA