peclet-voro 0.1.0__tar.gz

peclet_voro-0.1.0/.clang-format

@@ -0,0 +1,62 @@
+# Google C++ Style Guide – clang-format configuration
+# https://google.github.io/styleguide/cppguide.html
+#
+# Applied to files under include/ and tests/.
+
+BasedOnStyle: Google
+Language: Cpp
+
+# Column limit
+ColumnLimit: 100
+
+# Indentation
+IndentWidth: 2
+TabWidth: 2
+UseTab: Never
+ContinuationIndentWidth: 4
+
+# Braces
+BreakBeforeBraces: Attach
+
+# Alignment
+AlignAfterOpenBracket: Align
+AlignConsecutiveAssignments: false
+AlignConsecutiveDeclarations: false
+AlignTrailingComments: true
+
+# Include sorting
+IncludeBlocks: Regroup
+SortIncludes: CaseInsensitive
+
+# Pointer/reference alignment
+PointerAlignment: Left
+ReferenceAlignment: Left
+
+# Spaces
+SpaceBeforeParens: ControlStatements
+SpaceInEmptyParentheses: false
+SpacesInAngles: false
+SpacesInContainerLiterals: false
+
+# Short-form options (Google defaults)
+AllowShortFunctionsOnASingleLine: Inline
+AllowShortIfStatementsOnASingleLine: false
+AllowShortLoopsOnASingleLine: false
+AllowShortCaseLabelsOnASingleLine: false
+
+# Template
+SpaceAfterTemplateKeyword: true
+
+# Constructor initializer lists
+BreakConstructorInitializers: BeforeComma
+ConstructorInitializerIndentWidth: 4
+
+# Class access modifiers
+AccessModifierOffset: -1
+
+# Namespace
+NamespaceIndentation: None
+CompactNamespaces: false
+
+# Comments
+ReflowComments: true

peclet_voro-0.1.0/.clang-tidy

@@ -0,0 +1,120 @@
+# clang-tidy configuration for peclet.voro
+# https://clang.llvm.org/extra/clang-tidy/
+#
+# Enable a curated set of checks aligned with the Google C++ Style Guide and
+# modern C++ best practices.  A few checks are disabled because the current
+# code base uses patterns (e.g. VLAs as GCC extensions, raw owning pointers in
+# legacy geometry code) that would generate too much noise before the code is
+# further modernised.
+
+Checks: >
+  clang-diagnostic-*,
+  clang-analyzer-*,
+  cppcoreguidelines-avoid-goto,
+  cppcoreguidelines-init-variables,
+  cppcoreguidelines-narrowing-conversions,
+  cppcoreguidelines-no-malloc,
+  google-build-explicit-make-pair,
+  google-build-namespaces,
+  google-explicit-constructor,
+  google-global-names-in-headers,
+  google-readability-avoid-underscore-in-googletest-name,
+  google-readability-casting,
+  google-readability-todo,
+  google-runtime-int,
+  google-runtime-operator,
+  modernize-avoid-bind,
+  modernize-loop-convert,
+  modernize-make-shared,
+  modernize-make-unique,
+  modernize-pass-by-value,
+  modernize-redundant-void-arg,
+  modernize-replace-auto-ptr,
+  modernize-shrink-to-fit,
+  modernize-use-bool-literals,
+  modernize-use-default-member-init,
+  modernize-use-emplace,
+  modernize-use-equals-default,
+  modernize-use-equals-delete,
+  modernize-use-nodiscard,
+  modernize-use-nullptr,
+  modernize-use-override,
+  modernize-use-using,
+  performance-faster-string-find,
+  performance-for-range-copy,
+  performance-implicit-conversion-in-loop,
+  performance-inefficient-algorithm,
+  performance-inefficient-string-concatenation,
+  performance-inefficient-vector-operation,
+  performance-move-const-arg,
+  performance-move-constructor-init,
+  performance-no-automatic-move,
+  performance-trivially-destructible,
+  performance-type-promotion-in-math-fn,
+  performance-unnecessary-copy-initialization,
+  performance-unnecessary-value-param,
+  readability-braces-around-statements,
+  readability-const-return-type,
+  readability-container-size-empty,
+  readability-delete-null-pointer,
+  readability-else-after-return,
+  readability-function-size,
+  readability-identifier-naming,
+  readability-implicit-bool-conversion,
+  readability-misleading-indentation,
+  readability-misplaced-array-index,
+  readability-non-const-parameter,
+  readability-redundant-access-specifiers,
+  readability-redundant-control-flow,
+  readability-redundant-declaration,
+  readability-redundant-member-init,
+  readability-redundant-preprocessor,
+  readability-redundant-smartptr-get,
+  readability-redundant-string-cstr,
+  readability-redundant-string-init,
+  readability-simplify-subscript-expr,
+  readability-static-accessed-through-instance,
+  readability-static-definition-in-anonymous-namespace,
+  readability-string-compare,
+  readability-uniqueptr-delete-release,
+  -cppcoreguidelines-pro-bounds-array-to-pointer-decay,
+  -cppcoreguidelines-pro-bounds-constant-array-index,
+  -cppcoreguidelines-pro-bounds-pointer-arithmetic,
+  -cppcoreguidelines-pro-type-reinterpret-cast,
+  -cppcoreguidelines-pro-type-vararg,
+  -google-runtime-references,
+  -readability-magic-numbers
+
+WarningsAsErrors: ''
+
+HeaderFilterRegex: 'include/peclet/voro/.*'
+
+FormatStyle: file
+
+CheckOptions:
+  - key: readability-identifier-naming.NamespaceCase
+    value: lower_case
+  - key: readability-identifier-naming.ClassCase
+    value: CamelCase
+  - key: readability-identifier-naming.StructCase
+    value: CamelCase
+  - key: readability-identifier-naming.TemplateParameterCase
+    value: CamelCase
+  - key: readability-identifier-naming.FunctionCase
+    value: camelBack
+  - key: readability-identifier-naming.VariableCase
+    value: camelBack
+  - key: readability-identifier-naming.ClassMemberCase
+    value: camelBack
+  - key: readability-identifier-naming.ClassMemberPrefix
+    value: 'm_'
+  - key: readability-identifier-naming.PrivateMemberPrefix
+    value: 'm_'
+  - key: readability-identifier-naming.ConstantCase
+    value: kCamelCase
+  - key: readability-identifier-naming.EnumConstantCase
+    value: kCamelCase
+  - key: readability-function-size.LineThreshold
+    value: '200'
+  - key: readability-function-size.StatementThreshold
+    value: '100'

peclet_voro-0.1.0/.github/agents/scientific-coder.agent.md

@@ -0,0 +1,65 @@
+---
+description: "Use when: writing C++ or CUDA simulation code, CFD methods, particle-based methods, Voronoi tessellations, neighbor lists, numerical solvers, performance optimization, GPU kernels, parallelization, MPI parallelization, scientific computing, physics-based simulations, computational fluid dynamics, DEM, SPH, lattice Boltzmann."
+tools: [read, edit, search, execute, web, todo, agent]
+user-invocable: true
+---
+
+You are a scientific programmer with deep expertise in C++, CUDA, and Python. You specialize in computational fluid dynamics (CFD) and particle-based simulation methods (DEM, SPH, Voronoi-based dynamics). Your top priorities are **performance**, **computational efficiency**, and **physical correctness**.
+
+## Priorities
+
+1. **Physical correctness** — Simulations must reproduce the correct physics. Verify conservation laws, boundary conditions, and numerical stability.
+2. **Performance** — Minimize unnecessary copies, prefer cache-friendly data layouts, use SIMD-friendly patterns, and exploit parallelism. Profile before optimizing.
+3. **Code structure** — Clean separation of concerns. Header-only libraries where appropriate. Logical file and namespace organization.
+4. **Documentation** — All C++ code uses Doxygen (`/** */` style) for classes, methods, and non-trivial members. All Python code uses high-quality docstrings (Google style).
+
+## C++ Guidelines
+
+- Follow the **Google C++ Style Guide** as the baseline.
+- For any C++ edits, ensure the result is clang-format clean before finishing. Use the repo's `.clang-format` via `bash tools/clang_format_check.sh`.
+- Match the CI formatter version. Prefer `clang-format-18`; if `clang-format-18` is not on `PATH`, set `CLANG_FORMAT_BIN` explicitly to a clang-format 18 binary before running the check.
+- Do not stop after C++ changes until the clang-format check passes.
+- Use modern C++ (C++17/20) idioms: `std::span`, structured bindings, `constexpr`, `if constexpr`, range-based loops.
+- Prefer value semantics and move semantics over raw pointers.
+- Use `Eigen` for linear algebra (vector/matrix ops, geometry). Prefer fixed-size matrices (`Eigen::Matrix3d`) in hot loops to avoid heap allocation.
+- Use `Boost` utilities (e.g., `boost::multi_array`, `boost::geometry`, `boost::program_options`) when already in the project or when the standard library is insufficient.
+- **MPI**: prefer non-blocking communication (`MPI_Isend`/`MPI_Irecv`) to overlap computation and communication. Use `MPI_Datatype` for structured sends. Always call `MPI_Finalize` on all error paths via RAII wrappers. Validate domain decomposition and halo exchange correctness before optimizing.
+- Mark hot-path functions with `inline` or `__forceinline` / `__attribute__((always_inline))` where measured beneficial.
+- Use `#pragma once` for header guards.
+- Template metaprogramming only when it provides clear performance or correctness benefits.
+- All public APIs documented with Doxygen: `@brief`, `@param`, `@return`, `@tparam` as needed.
+
+## CUDA Guidelines
+
+- Minimize host-device transfers; batch data movement.
+- Use shared memory for frequently accessed data within thread blocks.
+- Prefer coalesced global memory access patterns.
+- Use `__restrict__` pointers in kernel arguments.
+- Keep kernels focused — one computation per kernel unless fusion is measured faster.
+- Use appropriate block sizes (multiples of warp size, typically 128 or 256).
+- Error-check all CUDA API calls with a macro wrapper.
+
+## Python Guidelines
+
+- Write Pythonic code with type hints for function signatures.
+- **NumPy**: use vectorized operations and broadcasting over explicit Python loops. Mind memory layout (`C`/`F` order) for performance.
+- **SciPy**: prefer `scipy.sparse` for large sparse systems, `scipy.integrate` for ODE/PDE solving, `scipy.spatial` for spatial queries.
+- **Numba**: use `@numba.njit` or `@numba.cuda.jit` for hot loops that cannot be vectorized with NumPy alone. Avoid Python objects inside JIT-compiled functions.
+- **Matplotlib**: produce publication-quality plots with labeled axes, units, and colorbars. Use `plt.style.use` for consistent styling.
+- Google-style docstrings with Args, Returns, and Raises sections.
+- Use `dataclasses` or `pydantic` for structured data.
+
+## Numerical Methods Awareness
+
+- Be mindful of floating-point precision: prefer `double` for accumulations, use Kahan summation where needed.
+- Verify that time integration schemes match the required order of accuracy.
+- Check CFL / stability conditions when implementing explicit schemes.
+- Ensure neighbor lists and spatial data structures handle periodic boundary conditions correctly.
+
+## Constraints
+
+- DO NOT sacrifice correctness for performance without explicit user approval.
+- DO NOT add dependencies unless the user requests them or the project already uses them.
+- DO NOT use `using namespace std;` in headers.
+- DO NOT ignore compiler warnings — treat them as errors.
+- ONLY optimize after profiling confirms a bottleneck; never speculate.

peclet_voro-0.1.0/.github/workflows/ci.yml

@@ -0,0 +1,126 @@
+name: CI
+
+on:
+  push:
+    branches: [main, master, develop]
+  pull_request:
+    branches: [main, master, develop]
+
+permissions:
+  contents: read
+
+jobs:
+  # ── Kokkos device build & test ───────────────────────────────────────────────
+  # The library is the Kokkos device path; it depends on the core and morton
+  # sibling repos (checked out next to voro) and a Kokkos install. This builds the
+  # OpenMP backend from source and runs the device test suite.
+  kokkos-openmp:
+    name: Build & test (Kokkos OpenMP)
+    runs-on: ubuntu-24.04
+    permissions:
+      contents: read
+    steps:
+      - name: Checkout voro
+        uses: actions/checkout@v4
+        with:
+          path: voro
+
+      - name: Checkout core (sibling)
+        uses: actions/checkout@v4
+        with:
+          repository: computational-chemical-engineering/peclet-core
+          path: core
+
+      - name: Checkout morton (sibling)
+        uses: actions/checkout@v4
+        with:
+          repository: computational-chemical-engineering/peclet-morton
+          path: morton
+
+      - name: Install dependencies
+        run: |
+          sudo apt-get update -q
+          sudo apt-get install -y cmake ninja-build libomp-dev g++
+
+      - name: Build & install Kokkos (OpenMP + Serial)
+        run: |
+          git clone --depth 1 --branch 4.5.00 https://github.com/kokkos/kokkos.git /tmp/kokkos
+          cmake -S /tmp/kokkos -B /tmp/kokkos/build -G Ninja \
+            -DCMAKE_BUILD_TYPE=Release \
+            -DCMAKE_INSTALL_PREFIX=$HOME/kokkos-install \
+            -DKokkos_ENABLE_OPENMP=ON \
+            -DKokkos_ENABLE_SERIAL=ON
+          cmake --build /tmp/kokkos/build --parallel
+          cmake --install /tmp/kokkos/build
+
+      - name: Configure (VORFLOW_KOKKOS=ON)
+        working-directory: voro
+        run: |
+          cmake -B build -G Ninja \
+            -DCMAKE_BUILD_TYPE=Release \
+            -DPECLET_VORO_KOKKOS=ON \
+            -DPECLET_VORO_BUILD_TESTS=ON \
+            -DCMAKE_PREFIX_PATH=$HOME/kokkos-install
+
+      - name: Build
+        working-directory: voro
+        run: cmake --build build --parallel
+
+      - name: Run device tests
+        working-directory: voro
+        run: |
+          export OMP_PROC_BIND=false
+          ctest --test-dir build \
+            -R "test_kokkos_smoke|test_tessellation_invariants|test_convexcell_unit|test_convexcell_adj|test_pervertex_geometry|test_include_graph|bench_dynamic_update_gates" \
+            --output-on-failure --timeout 600
+
+  # ── Format Check ─────────────────────────────────────────────────────────────
+  clang-format:
+    name: clang-format check
+    runs-on: ubuntu-24.04
+    permissions:
+      contents: read
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+
+      - name: Install clang-format
+        run: |
+          sudo apt-get update -q
+          sudo apt-get install -y clang-format-18
+
+      - name: Check formatting
+        run: |
+          CLANG_FORMAT_BIN=clang-format-18 bash tools/clang_format_check.sh
+
+  # ── Doxygen ──────────────────────────────────────────────────────────────────
+  documentation:
+    name: Doxygen documentation
+    runs-on: ubuntu-24.04
+    permissions:
+      contents: read
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+
+      - name: Install dependencies
+        run: |
+          sudo apt-get update -q
+          sudo apt-get install -y cmake ninja-build doxygen graphviz
+
+      - name: Configure CMake
+        run: |
+          cmake -B build \
+            -DCMAKE_BUILD_TYPE=Release \
+            -DPECLET_VORO_BUILD_TESTS=OFF \
+            -DPECLET_VORO_BUILD_DOCS=ON \
+            -G Ninja
+
+      - name: Build documentation
+        run: cmake --build build --target docs
+
+      - name: Upload documentation
+        uses: actions/upload-artifact@v4
+        with:
+          name: doxygen-html
+          path: build/docs/html

peclet_voro-0.1.0/.github/workflows/docs.yml

@@ -0,0 +1,71 @@
+name: Doxygen Documentation
+
+on:
+  push:
+    branches: [main, master]
+  workflow_dispatch:
+
+# Only one deployment can run at a time; cancel in-progress runs if a new one
+# is triggered so that the published site always reflects the latest commit.
+concurrency:
+  group: pages
+  cancel-in-progress: false
+
+permissions:
+  contents: read
+
+jobs:
+  # ── Build HTML documentation ──────────────────────────────────────────────
+  build:
+    name: Build documentation
+    runs-on: ubuntu-24.04
+    permissions:
+      contents: read
+
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+
+      - name: Install dependencies
+        run: |
+          sudo apt-get update -q
+          sudo apt-get install -y \
+            cmake \
+            ninja-build \
+            libboost-dev \
+            doxygen \
+            graphviz
+
+      - name: Configure CMake
+        run: |
+          cmake -B build \
+            -DCMAKE_BUILD_TYPE=Release \
+            -DPECLET_VORO_BUILD_TESTS=OFF \
+            -DPECLET_VORO_BUILD_DOCS=ON \
+            -G Ninja
+
+      - name: Build Doxygen HTML
+        run: cmake --build build --target docs
+
+      - name: Upload Pages artifact
+        uses: actions/upload-pages-artifact@v3
+        with:
+          path: build/docs/html
+          jekyll: false
+
+  # ── Deploy to GitHub Pages ────────────────────────────────────────────────
+  deploy:
+    name: Deploy to GitHub Pages
+    runs-on: ubuntu-24.04
+    needs: build
+    permissions:
+      pages: write
+      id-token: write
+    environment:
+      name: github-pages
+      url: ${{ steps.deployment.outputs.page_url }}
+
+    steps:
+      - name: Deploy to GitHub Pages
+        id: deployment
+        uses: actions/deploy-pages@v4

peclet_voro-0.1.0/.github/workflows/release.yml

@@ -0,0 +1,53 @@
+name: Release
+
+# Build the sdist + self-contained OpenMP CPU wheels and publish to PyPI (peclet-voro) on a version tag.
+# Uses PyPI Trusted Publishing (OIDC) — configure the publisher on PyPI first; no API token secret needed.
+# The wheels FetchContent-build Kokkos (OpenMP+Serial) + the core & morton headers inside each build
+# (PECLET_VENDOR_DEPS=ON, from pyproject's [tool.cibuildwheel]); GPU/HIP + MPI are the source (sdist) path.
+
+on:
+  push:
+    tags: ["v*"]
+  workflow_dispatch:
+
+jobs:
+  sdist:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+      - run: pip install build
+      - run: python -m build --sdist
+      - uses: actions/upload-artifact@v4
+        with:
+          name: sdist
+          path: dist/*.tar.gz
+
+  wheels:
+    name: wheels (manylinux_2_28 x86_64)
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      # cibuildwheel reads [tool.cibuildwheel] from pyproject.toml (PECLET_VENDOR_DEPS=ON): each wheel
+      # compiles Kokkos as a subproject, so builds are slow but self-contained.
+      - uses: pypa/cibuildwheel@v2.21
+      - uses: actions/upload-artifact@v4
+        with:
+          name: wheels-linux
+          path: wheelhouse/*.whl
+
+  publish:
+    needs: [sdist, wheels]
+    runs-on: ubuntu-latest
+    if: github.event_name == 'push' && startsWith(github.ref, 'refs/tags/v')
+    environment: pypi
+    permissions:
+      id-token: write   # required for trusted publishing
+    steps:
+      - uses: actions/download-artifact@v4
+        with:
+          path: dist
+          merge-multiple: true
+      - uses: pypa/gh-action-pypi-publish@release/v1

peclet_voro-0.1.0/.gitignore

@@ -0,0 +1,51 @@
+# ── CMake build directories ───────────────────────────────────────────────────
+build/
+build*/
+build_*/
+cmake-build-*/
+CMakeCache.txt
+CMakeFiles/
+cmake_install.cmake
+CTestTestfile.cmake
+install_manifest.txt
+_CPack_Packages/
+
+# ── Generated CMake / package files (keep the .cmake.in template) ─────────────
+*.cmake
+!cmake/vorflowConfig.cmake.in
+
+# ── Compiled objects and binaries ─────────────────────────────────────────────
+*.o
+*.d
+*.a
+*.so
+*.dylib
+
+# ── Simulation output data files ─────────────────────────────────────────────
+pos_[0-9]*.dat
+intf_[0-9]*.dat
+GNUPlotfile.txt
+
+# ── Doxygen generated output ─────────────────────────────────────────────────
+docs/html/
+docs/latex/
+
+# ── Benchmark output ──────────────────────────────────────────────────────────
+benchmarks/results/
+benchmarks/archive_pending/
+
+# ── IDE / editor artifacts ───────────────────────────────────────────────────
+.vscode/
+.idea/
+*.swp
+*.swo
+*~
+.DS_Store
+Thumbs.db
+.codex
+build_*.log
+cuda_report_*.log
+.venv/
+
+# keep the vendored deps helper (the *.cmake rule above would ignore it)
+!cmake/PecletDeps.cmake