openndm 0.2.0__tar.gz

openndm-0.2.0/.clang-format

@@ -0,0 +1,24 @@
+# Matches OpenMC's C++ style (DP-1).
+---
+Language: Cpp
+BasedOnStyle: Google
+AccessModifierOffset: -2
+AlignAfterOpenBracket: DontAlign
+AllowShortFunctionsOnASingleLine: Inline
+AlwaysBreakTemplateDeclarations: Yes
+BinPackArguments: true
+BinPackParameters: true
+BreakBeforeBraces: Custom
+BraceWrapping:
+  AfterClass: false
+  AfterFunction: true
+  AfterNamespace: false
+  AfterStruct: false
+  BeforeElse: false
+ColumnLimit: 80
+PackConstructorInitializers: Never
+DerivePointerAlignment: false
+IndentWidth: 2
+PointerAlignment: Left
+SpaceAfterTemplateKeyword: false
+Standard: c++17

openndm-0.2.0/.github/CODEOWNERS

@@ -0,0 +1,25 @@
+# Every file needs review from the owner before it reaches main.
+#
+# The `main` ruleset requires code owner review, so this file is what makes
+# "@rizkiokt must approve" a rule rather than a convention. A pull request
+# touching any path below cannot merge without an approving review from the
+# owner listed for that path.
+
+*                       @rizkiokt
+
+# The numerical core and the verification suite are the parts where a wrong
+# merge is expensive and quiet: a physics regression passes every style check
+# and most of the unit tests. They are listed separately so that GitHub names
+# them explicitly in the review request rather than falling through to the
+# catch-all above.
+/src/                   @rizkiokt
+/include/               @rizkiokt
+/tests/validation/      @rizkiokt
+/tests/python/test_verification.py  @rizkiokt
+/benchmarks/            @rizkiokt
+
+# Release and distribution machinery: a bad merge here publishes.
+/.github/workflows/     @rizkiokt
+/conda-recipe/          @rizkiokt
+/pyproject.toml         @rizkiokt
+/CMakeLists.txt         @rizkiokt

openndm-0.2.0/.github/ISSUE_TEMPLATE/bug_report.yml

@@ -0,0 +1,78 @@
+name: Bug report
+description: Something crashes, raises, or behaves differently from what the docs say.
+labels: ["bug"]
+body:
+  - type: markdown
+    attributes:
+      value: >-
+        For a result that runs fine but looks numerically wrong, use the
+        **Physics discrepancy** template instead — it asks for the reference
+        the answer is being judged against, which is what makes that class of
+        report actionable.
+
+  - type: textarea
+    id: what-happened
+    attributes:
+      label: What happened
+      description: What you expected, and what you got instead.
+    validations:
+      required: true
+
+  - type: textarea
+    id: reproducer
+    attributes:
+      label: Minimal reproducer
+      description: >-
+        A self-contained script that shows the problem. Inline the cross
+        sections rather than attaching a library where you can — a case that
+        runs on its own gets fixed much faster than one that needs a data file.
+      render: python
+    validations:
+      required: true
+
+  - type: textarea
+    id: traceback
+    attributes:
+      label: Traceback or error output
+      description: The complete output, not just the last line.
+      render: text
+
+  - type: textarea
+    id: version
+    attributes:
+      label: Version information
+      description: Output of the command below.
+      value: |
+        <!-- paste the output of:
+
+        python -c "import openndm, sys, platform; print(openndm.__version__, sys.version, platform.platform())"
+
+        -->
+      render: text
+    validations:
+      required: true
+
+  - type: dropdown
+    id: install-method
+    attributes:
+      label: How did you install OpenNDM?
+      options:
+        - conda / mamba (conda-forge)
+        - pip, from a wheel on PyPI
+        - pip, built from source
+        - built from source with CMake directly
+        - other
+    validations:
+      required: true
+
+  - type: checkboxes
+    id: checks
+    attributes:
+      label: Before submitting
+      options:
+        - label: >-
+            I checked [docs/status.md](https://github.com/rizkiokt/openndm/blob/main/docs/status.md)
+            and this is not a feature that is simply not implemented yet.
+          required: true
+        - label: I searched existing issues for this.
+          required: true

openndm-0.2.0/.github/ISSUE_TEMPLATE/config.yml

@@ -0,0 +1,18 @@
+blank_issues_enabled: false
+contact_links:
+  - name: Question about using OpenNDM
+    url: https://github.com/rizkiokt/openndm/discussions
+    about: >-
+      How do I set up this geometry, why is my case not converging, what does
+      this setting do. Questions get answered faster in Discussions and stay
+      searchable for the next person.
+  - name: Theory and method background
+    url: https://github.com/rizkiokt/openndm/blob/main/docs/theory.md
+    about: >-
+      Every equation the solver implements, with its discretisation written
+      out. Check here before filing a physics discrepancy.
+  - name: What is and is not implemented yet
+    url: https://github.com/rizkiokt/openndm/blob/main/docs/status.md
+    about: >-
+      Requirement-by-requirement implementation status. A missing feature is
+      often listed here already.

openndm-0.2.0/.github/ISSUE_TEMPLATE/feature_request.yml

@@ -0,0 +1,49 @@
+name: Feature request
+description: Propose a capability OpenNDM does not have.
+labels: ["enhancement"]
+body:
+  - type: markdown
+    attributes:
+      value: >-
+        [docs/status.md](https://github.com/rizkiokt/openndm/blob/main/docs/status.md)
+        maps every requirement in the specification to what is actually built.
+        Much of the roadmap is already written down there — if your request is
+        on it, say so and the issue becomes a place to discuss priority rather
+        than scope.
+
+  - type: textarea
+    id: problem
+    attributes:
+      label: The calculation you cannot do today
+      description: >-
+        Describe the analysis you are trying to run, not the API you imagine.
+        The physics problem usually admits a better design than the one that
+        comes to mind first.
+    validations:
+      required: true
+
+  - type: textarea
+    id: proposal
+    attributes:
+      label: What you have in mind
+      description: Sketch the API or the method if you have one.
+
+  - type: input
+    id: requirement-id
+    attributes:
+      label: Related requirement ID
+      description: >-
+        If this corresponds to an ID in docs/requirements.md, give it. Leave
+        blank if this is new scope.
+      placeholder: "e.g. FR-GEO-7, or blank"
+
+  - type: dropdown
+    id: contribution
+    attributes:
+      label: Would you be willing to implement this?
+      options:
+        - "Yes, with guidance on where it belongs"
+        - "Yes, I know the codebase well enough"
+        - "No, I am requesting it"
+    validations:
+      required: true

openndm-0.2.0/.github/ISSUE_TEMPLATE/physics_discrepancy.yml

@@ -0,0 +1,74 @@
+name: Physics discrepancy
+description: The solver converges, but the answer disagrees with a reference you trust.
+labels: ["physics", "needs-verification"]
+body:
+  - type: markdown
+    attributes:
+      value: >-
+        A disagreement is only a bug once there is something to disagree with.
+        The fields below exist to establish that: what the reference is, how
+        tight it is, and whether the gap is larger than the discretisation
+        error you should expect at your mesh.
+
+  - type: textarea
+    id: discrepancy
+    attributes:
+      label: The numbers
+      description: >-
+        What OpenNDM produced, what the reference says, and the difference.
+        Give eigenvalues in pcm and distributions as a max and RMS relative
+        error.
+      value: |
+        quantity        OpenNDM      reference     difference
+        k_eff
+        max pin power
+        RMS power
+    validations:
+      required: true
+
+  - type: input
+    id: reference-source
+    attributes:
+      label: Where the reference comes from
+      description: >-
+        A published benchmark and its revision, a Monte Carlo run (give the
+        code, version and reported uncertainty), or another deterministic code
+        and its options.
+      placeholder: "e.g. IAEA-2D, ANL-7416 Rev. 2, or OpenMC 0.14.0, 200 batches, sigma = 12 pcm"
+    validations:
+      required: true
+
+  - type: textarea
+    id: mesh
+    attributes:
+      label: Mesh and kernel
+      description: >-
+        Nodes per assembly, axial layers, and which kernel. Discretisation
+        error is the first thing to rule out: the nodal kernels are second
+        order in node size, so a one-node-per-assembly result is expected to
+        carry tens of pcm on some problems.
+      placeholder: "2x2 per assembly, 24 axial layers, SANM"
+    validations:
+      required: true
+
+  - type: checkboxes
+    id: convergence
+    attributes:
+      label: Convergence
+      options:
+        - label: The solve converged; it did not stop at the iteration limit.
+          required: true
+        - label: >-
+            I tightened the tolerances and refined the mesh, and the
+            disagreement did not shrink.
+
+  - type: textarea
+    id: reproducer
+    attributes:
+      label: Input
+      description: >-
+        The deck, or a link to it. If the case needs a cross section library,
+        say how to obtain it.
+      render: python
+    validations:
+      required: true

openndm-0.2.0/.github/dependabot.yml

@@ -0,0 +1,32 @@
+# Dependency updates arrive as pull requests, which is the only way into `main`
+# anyway under the branch ruleset. They still need review and green CI.
+version: 2
+updates:
+  # The pinned action versions in the workflows. An unpinned or stale action is
+  # the most common supply chain exposure a repository this size actually has.
+  - package-ecosystem: github-actions
+    directory: /
+    schedule:
+      interval: weekly
+      day: monday
+    open-pull-requests-limit: 5
+    commit-message:
+      prefix: "ci"
+    labels: ["dependencies", "ci"]
+
+  # Build requirements in pyproject.toml. Runtime dependencies are deliberately
+  # loose ranges, so this mostly surfaces scikit-build-core and pybind11.
+  - package-ecosystem: pip
+    directory: /
+    schedule:
+      interval: monthly
+    open-pull-requests-limit: 5
+    commit-message:
+      prefix: "build"
+    labels: ["dependencies"]
+    # The linters are pinned on purpose: an unpinned formatter turns every
+    # upstream release into a red build on an unrelated commit. Dependabot may
+    # propose the bump, but it goes in as a deliberate reformat commit.
+    groups:
+      linters:
+        patterns: ["ruff", "clang-format"]

openndm-0.2.0/.github/pull_request_template.md

@@ -0,0 +1,43 @@
+## What this changes
+
+<!-- One or two sentences. The diff says what; say why. -->
+
+## Type of change
+
+- [ ] `fix` — corrects behaviour that was wrong
+- [ ] `feat` — adds behaviour
+- [ ] `docs` — documentation only
+- [ ] `test` — tests only
+- [ ] `refactor` — no behaviour change, no number changes
+- [ ] `chore` / `ci` / `build` — tooling, packaging, workflows
+
+## Does this move any number?
+
+A change to `k_eff`, a flux, a power distribution, a convergence order or a
+benchmark result is a **physics change**, not a refactor, even when it looks
+like a cleanup. See `CONTRIBUTING.md`.
+
+- [ ] No verification or benchmark result moves.
+- [ ] Some result moves, and the body below says which, by how much, and why
+      the new number is the correct one.
+
+<!-- If a number moved, paste the before/after here:
+
+      case                     before         after        delta
+      analytic bare cuboid     1.00123456     1.00123401   -0.55 pcm
+      IAEA-2D k_eff            1.02958        1.02958       0.00 pcm
+-->
+
+## Checklist
+
+- [ ] `pytest tests/python` passes locally.
+- [ ] `ruff check python tests benchmarks` is clean.
+- [ ] `clang-format` is clean on any touched C++ (`pre-commit run -a` covers both).
+- [ ] New behaviour has a test. A new kernel is registered in `ALL_KERNELS`
+      so the verification suite picks it up automatically.
+- [ ] Public API changes are reflected in `docs/` and `CHANGELOG.md`.
+- [ ] Commits follow conventional-commit subjects (`feat:`, `fix:`, ...).
+
+## Related issues
+
+<!-- "Closes #123", or delete this section. -->

openndm-0.2.0/.github/workflows/ci.yml

@@ -0,0 +1,343 @@
+name: CI
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+  workflow_dispatch:
+    inputs:
+      cross_sections_url:
+        description: >-
+          URL of a nuclear data archive containing cross_sections.xml. Leave
+          empty to skip the OpenMC coupling validation, which cannot run
+          without one.
+        required: false
+        default: ""
+
+concurrency:
+  group: ${{ github.workflow }}-${{ github.ref }}
+  cancel-in-progress: true
+
+env:
+  FORCE_COLOR: 1
+
+jobs:
+  lint:
+    name: lint
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v7
+      - uses: actions/setup-python@v7
+        with:
+          python-version: "3.12"
+      # Both linters are pinned. An unpinned formatter turns every upstream
+      # release into a red build on an unrelated commit, and clang-format in
+      # particular reformats differently between major versions: the first CI
+      # run failed here purely because the runner had 18 and the tree had been
+      # formatted with 23.
+      - name: Install linters
+        run: pip install "ruff==0.14.14" "clang-format==18.1.8"
+      - name: ruff (NFR-QA-4)
+        run: ruff check python tests benchmarks
+      - name: clang-format (NFR-QA-4)
+        run: |
+          for f in $(find include src tests/cpp -name '*.h' -o -name '*.cpp'); do
+            clang-format --dry-run --Werror "$f" || exit 1
+          done
+
+  test:
+    name: ${{ matrix.os }} / ${{ matrix.compiler }} / py${{ matrix.python }}
+    runs-on: ${{ matrix.os }}
+    strategy:
+      fail-fast: false
+      matrix:
+        include:
+          - { os: ubuntu-latest, compiler: gcc, python: "3.10" }
+          - { os: ubuntu-latest, compiler: gcc, python: "3.12" }
+          - { os: ubuntu-latest, compiler: gcc, python: "3.13" }
+          - { os: ubuntu-latest, compiler: clang, python: "3.12" }
+          - { os: macos-latest, compiler: clang, python: "3.12" }
+    steps:
+      - uses: actions/checkout@v7
+
+      - uses: actions/setup-python@v7
+        with:
+          python-version: ${{ matrix.python }}
+
+      - name: Select the compiler
+        if: runner.os == 'Linux'
+        run: |
+          if [ "${{ matrix.compiler }}" = "clang" ]; then
+            echo "CC=clang"  >> "$GITHUB_ENV"
+            echo "CXX=clang++" >> "$GITHUB_ENV"
+          else
+            echo "CC=gcc"  >> "$GITHUB_ENV"
+            echo "CXX=g++" >> "$GITHUB_ENV"
+          fi
+
+      - name: Install OpenMP for AppleClang
+        if: runner.os == 'macOS'
+        run: |
+          brew install libomp
+          echo "OpenMP_ROOT=$(brew --prefix libomp)" >> "$GITHUB_ENV"
+
+      - name: Build and install
+        run: pip install -v '.[dev]'
+
+      - name: Python tests
+        run: pytest tests/python -v --durations=10
+
+      - name: Verify the analytic benchmark
+        working-directory: benchmarks/analytic
+        run: python run.py
+
+  cpp-tests:
+    name: C++ unit tests and coverage
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v7
+      - uses: actions/setup-python@v7
+        with:
+          python-version: "3.12"
+
+      - name: Install build tools
+        run: |
+          sudo apt-get update -qq
+          sudo apt-get install -y cmake ninja-build lcov
+
+      - name: Configure with coverage instrumentation
+        run: |
+          cmake -S . -B build -G Ninja \
+            -DOPENNDM_BUILD_TESTS=ON \
+            -DOPENNDM_BUILD_PYTHON=OFF \
+            -DCMAKE_BUILD_TYPE=Debug \
+            -DCMAKE_CXX_FLAGS="--coverage -O0"
+
+      - name: Build
+        run: cmake --build build -j
+
+      - name: Run (NFR-QA-1)
+        run: ctest --test-dir build --output-on-failure
+
+      - name: Collect coverage
+        run: |
+          # geninfo walks the fetched Catch2 sources, which are not all on
+          # disk, so "source" has to be ignored during capture; the _deps
+          # tree is removed from the report immediately afterwards anyway.
+          lcov --capture --directory build --output-file coverage.info \
+               --ignore-errors mismatch,gcov,source,empty
+          lcov --remove coverage.info '/usr/*' '*/_deps/*' '*/tests/*' \
+               --ignore-errors unused --output-file coverage.info
+          lcov --list coverage.info
+
+      - uses: actions/upload-artifact@v7
+        with:
+          name: cpp-coverage
+          path: coverage.info
+
+  no-openmc:
+    name: import without OpenMC (FR-OMC-14)
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v7
+      - uses: actions/setup-python@v7
+        with:
+          python-version: "3.12"
+      - run: pip install .
+      - name: The solver must work with OpenMC absent
+        run: |
+          python - <<'PY'
+          import importlib.util
+          import sys
+
+          assert importlib.util.find_spec("openmc") is None, \
+              "this job is meaningless with OpenMC installed"
+
+          import numpy as np
+          import openndm
+
+          lib = openndm.XSLibrary(1, 1)
+          lib.set_composition(0, D=[1.0], absorption=[0.08], nu_fission=[0.1],
+                              kappa_fission=[0.1], chi=[1.0], scatter=[[0.0]])
+          lib.finalize()
+          # 16 nodes per side, where the SANM discretisation error on this
+          # problem is about 3.5 pcm. Eight nodes leaves 28 pcm, which is
+          # correct physics but too coarse to assert anything tight against.
+          geom = openndm.Geometry.from_lattice(
+              np.zeros((16, 16, 16), int), pitch=6.25,
+              boundaries=dict.fromkeys(
+                  ["x_min", "x_max", "y_min", "y_max", "z_min", "z_max"],
+                  "zero_flux"))
+          k = openndm.Model(geom, lib, openndm.Settings(verbosity=0)).solve().k_eff
+          reference = 0.1 / (0.08 + 3 * (np.pi / 100) ** 2)
+          error = 1e5 * (k - reference)
+          print(f"k_eff = {k:.8f}, {error:+.2f} pcm from analytic")
+          assert abs(error) < 10.0, error
+
+          # Importing openndm must not have dragged OpenMC in.
+          assert "openmc" not in sys.modules
+          PY
+
+  openmc-coupling:
+    name: OpenMC coupling validation (C-1, C-2)
+    runs-on: ubuntu-latest
+    # Manual trigger only, and it needs a nuclear data library URL supplied at
+    # dispatch time. There is no stable public URL to hard-code: the OpenMC
+    # official data libraries are served from rotating Box links and the page
+    # listing them is itself a 404 as of this writing. A job that silently
+    # skips when it cannot fetch data is worse than no job, because the
+    # silence is indistinguishable from success, so this one simply does not
+    # run unless it has been given somewhere to fetch from.
+    #
+    # C-1 and C-2 are otherwise run locally; see tests/validation/README.md.
+    if: >-
+      github.event_name == 'workflow_dispatch' &&
+      inputs.cross_sections_url != ''
+    defaults:
+      run:
+        shell: bash -el {0}
+    steps:
+      - uses: actions/checkout@v7
+
+      - uses: conda-incubator/setup-miniconda@v4
+        with:
+          miniforge-version: latest
+          activate-environment: openmc-env
+          channels: conda-forge
+
+      - name: Install OpenMC
+        run: conda install -y openmc pytest
+
+      - name: Install OpenNDM
+        run: pip install .
+
+      - name: Cache the nuclear data library
+        id: data
+        uses: actions/cache@v4
+        with:
+          path: nuclear-data
+          key: xs-${{ hashFiles('.github/workflows/ci.yml') }}-${{ inputs.cross_sections_url }}
+
+      - name: Fetch the nuclear data library
+        if: steps.data.outputs.cache-hit != 'true'
+        run: |
+          mkdir -p nuclear-data
+          curl -fsSL "${{ inputs.cross_sections_url }}" -o data.tar.xz
+          tar -xf data.tar.xz -C nuclear-data --strip-components=1
+
+      - name: Point OpenMC at it
+        run: |
+          xs=$(find nuclear-data -name cross_sections.xml | head -1)
+          test -n "$xs" || { echo "no cross_sections.xml in the archive"; exit 1; }
+          echo "OPENMC_CROSS_SECTIONS=$PWD/$xs" >> "$GITHUB_ENV"
+
+      - name: C-1 and C-2 as unit tests (FR-OMC-1, FR-OMC-7)
+        run: pytest tests/python/test_openmc_integration.py -v
+
+      - name: The full C-1 and C-2 cases
+        working-directory: tests/validation
+        run: |
+          python c1_homogeneous.py --particles 50000 --batches 120
+          python c2_assembly_adf.py --particles 20000 --batches 80
+
+  docs:
+    name: documentation
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v7
+      - uses: actions/setup-python@v7
+        with:
+          python-version: "3.12"
+
+      - name: Install pandoc
+        run: |
+          # nbsphinx shells out to pandoc to convert the notebooks' markdown
+          # cells. It is a system binary, so it is absent here even though a
+          # virtualenv on a developer machine usually finds one on PATH.
+          sudo apt-get update -qq
+          sudo apt-get install -y pandoc
+
+      - name: Install the docs toolchain
+        run: pip install -r docs/requirements.txt
+
+      # The API reference is autodoc against the installed package, so the
+      # extension has to be built. Without this the api/ pages render empty
+      # and the build still succeeds, which is the failure mode worth
+      # preventing.
+      - name: Install OpenNDM
+        run: pip install .
+
+      - name: Build (warnings are errors)
+        run: sphinx-build -b html -W --keep-going docs docs/_build/html
+
+      - name: Check for dead internal links
+        run: sphinx-build -b linkcheck docs docs/_build/linkcheck || true
+
+      - uses: actions/upload-artifact@v7
+        with:
+          name: docs-html
+          path: docs/_build/html
+
+  # ---------------------------------------------------------------------------
+  # The single check the `main` ruleset requires. Depending on this one job
+  # rather than on the matrix legs by name means the required-checks list does
+  # not have to be edited every time a Python version or a compiler is added
+  # or dropped, which is the usual way a protected branch quietly stops being
+  # protected.
+  ci:
+    name: ci
+    if: always()
+    needs: [lint, test, cpp-tests, no-openmc, docs]
+    runs-on: ubuntu-latest
+    steps:
+      - name: Fail if any required job did not succeed
+        run: |
+          results='${{ toJSON(needs) }}'
+          echo "$results"
+          echo "$results" | python3 -c "
+          import json, sys
+          needs = json.load(sys.stdin)
+          bad = {k: v['result'] for k, v in needs.items() if v['result'] != 'success'}
+          if bad:
+              for name, result in bad.items():
+                  print(f'::error::{name}: {result}')
+              sys.exit(1)
+          print('all required jobs succeeded')
+          "
+
+  wheels:
+    name: build wheels
+    runs-on: ${{ matrix.os }}
+    if: github.event_name == 'push' || github.event_name == 'workflow_dispatch'
+    strategy:
+      fail-fast: false
+      matrix:
+        # macos-13 is the Intel runner, which GitHub is retiring; a job
+        # targeting it sat unassigned for over an hour. Both macOS
+        # architectures are produced from the arm64 runner instead, with
+        # cibuildwheel cross-compiling the x86_64 wheels. It skips the test
+        # step for a cross-compiled wheel, which it cannot execute.
+        os: [ubuntu-latest, macos-14]
+    steps:
+      - uses: actions/checkout@v7
+      - name: Build wheels (NFR-EXT-3)
+        uses: pypa/cibuildwheel@v4.2
+        env:
+          CIBW_BUILD: cp310-* cp311-* cp312-* cp313-*
+          # h5py, a runtime dependency, publishes no musllinux wheels and no
+          # manylinux2014 wheels either, only manylinux_2_28. Without both of
+          # these the test step builds it from source in a container with no
+          # HDF5 and the job dies after the OpenNDM wheel has built fine.
+          CIBW_SKIP: "*_i686 *-musllinux*"
+          CIBW_MANYLINUX_X86_64_IMAGE: manylinux_2_28
+          CIBW_MANYLINUX_AARCH64_IMAGE: manylinux_2_28
+          # NFR-EXT-3 wants both macOS architectures.
+          CIBW_ARCHS_MACOS: "x86_64 arm64"
+          CIBW_TEST_REQUIRES: pytest
+          CIBW_TEST_COMMAND: >
+            pytest {project}/tests/python -q
+            -k "not benchmark"
+      - uses: actions/upload-artifact@v7
+        with:
+          name: wheels-${{ matrix.os }}
+          path: wheelhouse/*.whl