peclet-amr 0.1.0__tar.gz

peclet_amr-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_amr-0.1.0/.clang-tidy

@@ -0,0 +1,120 @@
+# clang-tidy configuration for peclet.core
+# 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/core/.*'
+
+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_amr-0.1.0/.github/workflows/ci.yml

@@ -0,0 +1,192 @@
+name: CI
+
+# Honest CI (suite/docs/QUALITY_PLAN.md §3.D): every test the repository registers is either RUN or
+# reported by ctest as "Not Run (skipped)" — never green by early-return. peclet-amr is header-only
+# over peclet-core + peclet-morton (checked out as SIBLINGS, exactly the suite layout) and always
+# compiles through Kokkos (OpenMP + Serial host backend here, 5.1.1 cached):
+#
+#   kokkos-openmp   gcc / clang, Release, MPI ON: the whole battery — host octree + oracle, the
+#                   device (Kokkos) solver stack, the distributed octree / flow at np=1,2,4 — plus
+#                   (gcc) the Python module peclet.amr with test_amr.py serial + np=2 and the
+#                   state_hash byte gate.
+#   debug           gcc Debug, MPI ON: the same battery with assertions live (single-rank + mpi),
+#                   minus amr_flow_solver — the whole device step vs the oracle takes >40 min
+#                   unoptimised on a 4-core runner (Release covers it); listed by `ctest -N`.
+#
+# What is NOT run here, and why (nothing is hidden — `ctest -N` lists it all):
+#   * label np8   the 8-rank instances: hosted runners have 4 cores and oversubscribed np=8 halo
+#                 tests hung there (peclet-core's NBX tag-race history). np=8 is a LOCAL gate.
+#   * label bench benchmarks + measurement studies (bench_amr_flow, study_amr_*): timings and
+#                 tables, no correctness gate.
+#   * GPU backends (CUDA/HIP): no GPU on free runners.
+#   * python_state_hash reports SKIPPED: the byte gate's reference is recorded on the developer's
+#     toolchain (the last bits of a Krylov solve are compiler-specific); it gates locally.
+#   * MPI is required (there is no no-MPI configuration): core's mpi_stub covers the host halo
+#     only, and the device flow reaches the Kokkos grid halo.
+#
+# Thread bounds: the hosted runner has 4 cores / 16 GB. Single-rank suites run with
+# OMP_NUM_THREADS=2, the MPI suites with OMP_NUM_THREADS=1 (np=4 x 1 thread), ctest -j1 throughout.
+#
+# core is checked out at PECLET_CORE_REF: peclet-amr needs core's solver layer (lifted out of the AMR
+# tree on 2026-09-10), which ships in the core release AFTER v0.6.1 — until that tag exists this is
+# `main`; the release repins it (and PECLET_CORE_TAG in cmake/PecletDeps.cmake) to the tag.
+
+on:
+  push:
+    branches: [main, "**"]
+  pull_request:
+  workflow_dispatch:
+
+permissions:
+  contents: read
+
+env:
+  KOKKOS_TAG: "5.1.1"        # keep in lockstep with ../tools/bootstrap_deps.sh and cmake/PecletDeps.cmake
+  PECLET_CORE_REF: "main"    # see the header
+  MORTON_TAG: "v0.2.1"       # keep in lockstep with cmake/PecletDeps.cmake (PECLET_MORTON_TAG)
+  NANOBIND_VERSION: "2.13.0" # the suite venv's nanobind; pinned so a nanobind release cannot break CI
+  OMPI_ALLOW_RUN_AS_ROOT: 1
+  OMPI_ALLOW_RUN_AS_ROOT_CONFIRM: 1
+  OMPI_MCA_rmaps_base_oversubscribe: 1
+  PRTE_MCA_rmaps_default_mapping_policy: ":oversubscribe"
+  OMP_PROC_BIND: "false"
+  CTEST_OUTPUT_ON_FAILURE: 1
+
+jobs:
+  kokkos-openmp:
+    name: ubuntu / ${{ matrix.compiler }} / Kokkos OpenMP + MPI / Release
+    runs-on: ubuntu-24.04
+    timeout-minutes: 90
+    strategy:
+      fail-fast: false
+      matrix:
+        compiler: [gcc, clang]
+        include:
+          - compiler: gcc
+            cc: gcc
+            cxx: g++
+          - compiler: clang
+            cc: clang
+            cxx: clang++
+    env:
+      CC: ${{ matrix.cc }}
+      CXX: ${{ matrix.cxx }}
+    steps:
+      # Sibling layout, exactly as in the suite checkout: cmake/PecletDeps.cmake finds ../core and
+      # ../morton before it would fetch anything.
+      - uses: actions/checkout@v4
+        with:
+          path: amr
+      - name: Checkout core + morton (siblings)
+        uses: actions/checkout@v4
+        with:
+          repository: computational-chemical-engineering/peclet-core
+          ref: ${{ env.PECLET_CORE_REF }}
+          path: core
+      - uses: actions/checkout@v4
+        with:
+          repository: computational-chemical-engineering/peclet-morton
+          ref: ${{ env.MORTON_TAG }}
+          path: morton
+
+      - name: Install toolchain
+        run: |
+          sudo apt-get update -q
+          sudo apt-get install -y cmake ninja-build libomp-dev g++ clang libopenmpi-dev openmpi-bin \
+                                  python3-dev python3-pip
+          python3 -m pip install "nanobind==${NANOBIND_VERSION}" numpy mpi4py
+
+      - name: Cache Kokkos install
+        id: kokkos-cache
+        uses: actions/cache@v4
+        with:
+          path: ${{ github.workspace }}/kokkos-install
+          key: kokkos-${{ env.KOKKOS_TAG }}-openmp-cxx20-${{ matrix.compiler }}-${{ runner.os }}
+
+      - name: Build Kokkos (OpenMP + Serial)
+        if: steps.kokkos-cache.outputs.cache-hit != 'true'
+        run: |
+          git clone --depth 1 --branch "$KOKKOS_TAG" https://github.com/kokkos/kokkos.git /tmp/kokkos
+          cmake -S /tmp/kokkos -B /tmp/kokkos/build -G Ninja \
+            -DCMAKE_BUILD_TYPE=Release -DCMAKE_CXX_STANDARD=20 \
+            -DCMAKE_POSITION_INDEPENDENT_CODE=ON \
+            -DKokkos_ENABLE_OPENMP=ON -DKokkos_ENABLE_SERIAL=ON \
+            -DCMAKE_INSTALL_PREFIX="$GITHUB_WORKSPACE/kokkos-install"
+          cmake --build /tmp/kokkos/build -j
+          cmake --install /tmp/kokkos/build
+
+      - name: Configure (MPI + tests + Python)
+        run: |
+          cmake -S amr -B build -G Ninja -DCMAKE_BUILD_TYPE=Release \
+            -DCMAKE_PREFIX_PATH="$GITHUB_WORKSPACE/kokkos-install" \
+            -DPECLET_AMR_BUILD_TESTS=ON \
+            -DPECLET_AMR_BUILD_PYTHON=${{ matrix.compiler == 'gcc' && 'ON' || 'OFF' }} \
+            -DPython_EXECUTABLE="$(which python3)"
+
+      - name: Build
+        run: cmake --build build -j
+
+      - name: List tests
+        run: ctest --test-dir build -N
+
+      - name: Test single-rank (OMP_NUM_THREADS=2)
+        run: OMP_NUM_THREADS=2 ctest --test-dir build -LE "mpi|bench" --timeout 1800 --output-on-failure -j1
+
+      - name: Test MPI np=1,2,4 (OMP_NUM_THREADS=1; np8 excluded, see header)
+        run: OMP_NUM_THREADS=1 ctest --test-dir build -L mpi -LE "np8|bench" --timeout 1800 --output-on-failure -j1
+
+      - name: Import peclet.amr
+        if: matrix.compiler == 'gcc'
+        run: PYTHONPATH=$PWD/build python3 -c "import mpi4py.MPI, peclet.amr; print('peclet.amr', peclet.amr.execution_space)"
+
+  debug:
+    name: ubuntu / gcc / Kokkos OpenMP + MPI / Debug
+    runs-on: ubuntu-24.04
+    timeout-minutes: 120
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          path: amr
+      - uses: actions/checkout@v4
+        with:
+          repository: computational-chemical-engineering/peclet-core
+          ref: ${{ env.PECLET_CORE_REF }}
+          path: core
+      - uses: actions/checkout@v4
+        with:
+          repository: computational-chemical-engineering/peclet-morton
+          ref: ${{ env.MORTON_TAG }}
+          path: morton
+      - name: Install toolchain
+        run: |
+          sudo apt-get update -q
+          sudo apt-get install -y cmake ninja-build libomp-dev g++ libopenmpi-dev openmpi-bin
+      - name: Cache Kokkos install
+        id: kokkos-cache
+        uses: actions/cache@v4
+        with:
+          path: ${{ github.workspace }}/kokkos-install
+          key: kokkos-${{ env.KOKKOS_TAG }}-openmp-cxx20-gcc-${{ runner.os }}
+      - name: Build Kokkos (OpenMP + Serial)
+        if: steps.kokkos-cache.outputs.cache-hit != 'true'
+        run: |
+          git clone --depth 1 --branch "$KOKKOS_TAG" https://github.com/kokkos/kokkos.git /tmp/kokkos
+          cmake -S /tmp/kokkos -B /tmp/kokkos/build -G Ninja \
+            -DCMAKE_BUILD_TYPE=Release -DCMAKE_CXX_STANDARD=20 \
+            -DCMAKE_POSITION_INDEPENDENT_CODE=ON \
+            -DKokkos_ENABLE_OPENMP=ON -DKokkos_ENABLE_SERIAL=ON \
+            -DCMAKE_INSTALL_PREFIX="$GITHUB_WORKSPACE/kokkos-install"
+          cmake --build /tmp/kokkos/build -j
+          cmake --install /tmp/kokkos/build
+      - name: Configure (Debug, MPI + tests, no Python)
+        run: |
+          cmake -S amr -B build -G Ninja -DCMAKE_BUILD_TYPE=Debug \
+            -DCMAKE_PREFIX_PATH="$GITHUB_WORKSPACE/kokkos-install" \
+            -DPECLET_AMR_BUILD_TESTS=ON -DPECLET_AMR_BUILD_PYTHON=OFF
+      - name: Build
+        run: cmake --build build -j
+      - name: Test (single-rank + MPI np=1,2,4; amr_flow_solver excluded, see header)
+        run: |
+          ctest --test-dir build -N
+          OMP_NUM_THREADS=2 ctest --test-dir build -LE "mpi|bench" -E "^amr_flow_solver$" --timeout 2400 --output-on-failure -j1
+          OMP_NUM_THREADS=1 ctest --test-dir build -L mpi -LE "np8|bench" --timeout 2400 --output-on-failure -j1

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

@@ -0,0 +1,51 @@
+name: Documentation
+
+# Build the Doxygen API docs (README.md + the header-only C++20 API in include/ + the Python
+# binding TU) and publish them to GitHub Pages. Requires Pages to be enabled for the repository with
+# "Source: GitHub Actions" (Settings -> Pages). Runs on every push to main; can also be run manually.
+
+on:
+  push:
+    branches: [main]
+    paths:
+      - 'include/**'
+      - 'python/**'
+      - 'docs/**'
+      - 'README.md'
+      - '.github/workflows/docs.yml'
+  workflow_dispatch:
+
+permissions:
+  contents: read
+  pages: write
+  id-token: write
+
+# allow one concurrent deployment; cancel an in-progress run for a newer push
+concurrency:
+  group: pages
+  cancel-in-progress: true
+
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - name: Install Doxygen + Graphviz
+        run: sudo apt-get update && sudo apt-get install -y doxygen graphviz
+      - name: Build documentation
+        run: doxygen docs/Doxyfile
+      - name: Upload Pages artifact
+        uses: actions/upload-pages-artifact@v5
+        with:
+          path: docs/html
+
+  deploy:
+    needs: build
+    runs-on: ubuntu-latest
+    environment:
+      name: github-pages
+      url: ${{ steps.deployment.outputs.page_url }}
+    steps:
+      - name: Deploy to GitHub Pages
+        id: deployment
+        uses: actions/deploy-pages@v5

peclet_amr-0.1.0/.github/workflows/quality.yml

@@ -0,0 +1,45 @@
+name: Quality
+
+# Code-quality gates. Python hard-fails on critical errors only. The C++ clang-format check is
+# BLOCKING from the package's first push (suite/docs/QUALITY_PLAN.md §3.D.7): clang-format is pinned
+# to 18.1.8 (the suite venv's version, installed from PyPI — the apt package drifts) and the whole
+# tree — include/ tests/ python/ benchmarks/ — is formatted against the suite-wide .clang-format
+# (the AMR tree was reformatted once on relocation, 2026-09-10; core had excluded it until then).
+
+on:
+  push:
+    branches: [main, "**"]
+  pull_request:
+  workflow_dispatch:
+
+jobs:
+  python-lint:
+    name: ruff (critical errors)
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v6
+        with:
+          python-version: "3.12"
+      - run: pip install ruff
+      - name: Ruff critical-error check
+        run: |
+          ruff check . --select E9,F63,F7,F82 \
+            --exclude ".venv,venv,build,build_*,__pycache__,_deps,extern"
+
+  cpp-format:
+    name: clang-format 18.1.8 (blocking)
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v6
+        with:
+          python-version: "3.12"
+      - run: pip install "clang-format==18.1.8"
+      - name: clang-format dry-run (uses the repo .clang-format)
+        run: |
+          files=$(git ls-files 'include/*.hpp' 'tests/*.hpp' 'tests/*.cpp' 'benchmarks/*.cpp' 'python/*.cpp')
+          [ -z "$files" ] && { echo "no C++ sources"; exit 0; }
+          clang-format --version
+          echo "$files" | wc -l
+          clang-format --dry-run --Werror $files

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

@@ -0,0 +1,42 @@
+name: Release
+
+# Publish peclet-amr to PyPI on a version tag via Trusted Publishing (OIDC) — configure the publisher
+# on PyPI first; no API token secret needed. SDIST ONLY, like peclet-core: peclet.amr links MPI (its
+# DistributedOctree runs over MPI_COMM_WORLD, driven by mpi4py) and a Kokkos backend, whose ABI/arch
+# make a portable binary wheel impossible. Consumers `pip install peclet-amr` and build against their
+# site MPI + Kokkos prefix (cmake/PecletDeps.cmake fetches the peclet-core / peclet-morton headers
+# at their pinned tags), or use the suite containers. See ../docs/RELEASE.md.
+
+on:
+  push:
+    tags: ["v*"]
+  workflow_dispatch:
+
+jobs:
+  sdist:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v6
+        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
+
+  publish:
+    needs: [sdist]
+    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_amr-0.1.0/.gitignore

@@ -0,0 +1,21 @@
+build/
+build_*/
+build-*/
+*.o
+*.so
+.cache/
+compile_commands.json
+
+# Generated Doxygen output (built in CI, published to Pages)
+docs/html/
+
+# Python build/test artifacts
+__pycache__/
+*.pyc
+*.egg-info/
+dist/
+
+# Scratch output of the examples / studies
+*.vtu
+*.log
+!docs/data/*.log

peclet_amr-0.1.0/CITATION.cff

@@ -0,0 +1,31 @@
+cff-version: 1.2.0
+message: "If you use this software, please cite it using the metadata below."
+title: "peclet-amr: block-local-Morton AMR octree and collocated cut-cell Navier–Stokes solver"
+abstract: >-
+  Header-only C++20 adaptive-mesh-refinement package of the peclet suite: a per-block linear octree
+  on Morton codes with 2:1 balance, solution-adaptive refinement and an ORB-distributed (MPI) variant
+  with leaf halos and weighted-ORB rebalancing; on it, a collocated-projection incompressible
+  Navier–Stokes solver with a cut-cell immersed boundary (ghost projection, mixed-level cut band),
+  geometric multigrid (PCG / BiCGStab), scalar transport and VTU output. Kokkos device backends
+  (CUDA / HIP / OpenMP) and nanobind Python bindings (peclet.amr). Relocated out of peclet-core with
+  its history on 2026-09-10.
+type: software
+authors:
+  - family-names: Peters
+    given-names: Frank
+    email: e.a.j.f.peters@gmail.com
+    affiliation: "Eindhoven University of Technology"
+version: 0.1.0
+date-released: 2026-09-12
+license: MIT
+repository-code: "https://github.com/computational-chemical-engineering/peclet-amr"
+keywords:
+  - adaptive mesh refinement
+  - octree
+  - Morton codes
+  - cut-cell immersed boundary
+  - incompressible Navier–Stokes
+  - multigrid
+  - MPI
+  - Kokkos
+  - GPU computing