pyRadMC 0.2.0__tar.gz

pyradmc-0.2.0/.github/PULL_REQUEST_TEMPLATE.md

@@ -0,0 +1,20 @@
+<!--
+The PR title becomes the squash-commit subject on develop. It should follow
+AGENTS.md 9.2:  type(scope): imperative description
+(description <= 50 chars; whole line <= 72)
+The description below becomes the commit body: wrap lines at 72.
+-->
+
+## What and why
+
+<!-- The physics / the reasoning, not the diff. Measurements go here. -->
+
+## Checklist
+
+- [ ] A failing test motivated this change (AGENTS.md 2.1)
+- [ ] `pre-commit run --all-files` and `pytest` pass locally
+- [ ] Docs, README and docstrings this change made stale are updated
+- [ ] If a user-visible capability: a runnable example under `examples/`
+- [ ] If it can move a computed dose: `CHANGELOG.md` entry + the measurement
+- [ ] If it touches `ECUT`/`PCUT`/truncation/step defaults: the dosimetric-effect
+      test of AGENTS.md 2.8 is included

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

@@ -0,0 +1,158 @@
+name: CI
+
+# GitHub is the primary remote (AGENTS.md 9): task branches squash-merge into develop
+# through pull requests, and releases merge rc/* into main. The DKFZ GitLab mirror runs
+# its own validate-only pipeline (.gitlab-ci.yml).
+on:
+  push:
+    # rc/** included so a release candidate builds its wheel even before the PR exists.
+    branches: [main, develop, "rc/**"]
+  pull_request:
+    branches: [main, develop]
+  workflow_dispatch:
+
+concurrency:
+  group: ci-${{ github.ref }}
+  cancel-in-progress: true
+
+permissions:
+  contents: read
+
+env:
+  PIP_DISABLE_PIP_VERSION_CHECK: "1"
+  FORCE_COLOR: "1"
+
+jobs:
+  quality:
+    name: lint, format, types
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.13"
+          cache: pip
+          cache-dependency-path: pyproject.toml
+      # The warp extra is installed for mypy: it type-checks the engine modules that
+      # import warp, even though the kernels themselves are exempt (AGENTS.md 5).
+      - run: pip install -e ".[warp,dev]"
+      - uses: actions/cache@v4
+        with:
+          path: ~/.cache/pre-commit
+          key: pre-commit-${{ hashFiles('.pre-commit-config.yaml') }}
+      # Run the hook definitions rather than re-listing the tools here. The pinned revs
+      # in .pre-commit-config.yaml are then the single authority: CI and a developer's
+      # commit hook cannot disagree, and neither can drift onto a new linter release.
+      # (mypy is a `language: system` hook, so it uses the environment installed above.)
+      - run: pre-commit run --all-files --show-diff-on-failure
+
+  test:
+    name: tests (py${{ matrix.python }}, ${{ matrix.os }})
+    runs-on: ${{ matrix.os }}
+    strategy:
+      fail-fast: false
+      matrix:
+        os: [ubuntu-latest]
+        python: ["3.10", "3.11", "3.12", "3.13"]
+        include:
+          # Coverage wherever it is nearly free, which is every job on 3.12+: the
+          # sysmon core below costs 1.01x, so these keep measuring (Codecov merges
+          # the uploads for a commit). It is dropped only from 3.10 and 3.11, where
+          # sys.monitoring does not exist and coverage.py falls back to the C tracer
+          # -- measured at 2.09x on the full fast suite, which is what made running
+          # it on all five jobs expensive. These merge into the matrix combinations
+          # they name rather than adding jobs, since every key here matches one.
+          - os: ubuntu-latest
+            python: "3.12"
+            coverage: true
+          - os: ubuntu-latest
+            python: "3.13"
+            coverage: true
+          # The maintainer develops on Windows, and several past bugs were
+          # Windows-specific (path handling, subprocess behaviour). One job keeps that
+          # platform honest without quadrupling the matrix -- and it carries coverage
+          # so that a Windows-only branch still reaches the report.
+          - os: windows-latest
+            python: "3.13"
+            coverage: true
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: ${{ matrix.python }}
+          cache: pip
+          cache-dependency-path: pyproject.toml
+      - run: pip install -e ".[warp,dev]"
+      # Runners have no CUDA device: warp runs on CPU and the gpu-marked tests skip
+      # themselves via wp.is_cuda_available(). The validation and perf tiers are
+      # excluded by the default addopts; validation runs on its own schedule.
+      # COVERAGE_CORE=sysmon puts coverage.py on CPython's sys.monitoring (3.12+)
+      # instead of its C tracer, which is what makes coverage affordable at all here:
+      # same suite, 630 s under the tracer against 308 s under sysmon and 304 s with
+      # no coverage — 2.09x overhead down to 1.01x. Set at job level and inert on the
+      # jobs that pass no --cov, which are exactly the pre-3.12 ones, so no job ever
+      # asks for a core it lacks. (No branch coverage is configured; that is the one
+      # feature the sysmon core does not support.)
+      - env:
+          COVERAGE_CORE: sysmon
+        run: pytest -q ${{ matrix.coverage && '--cov' || '' }} --junitxml=junit.xml -o junit_family=legacy
+      - name: Upload coverage to Codecov
+        if: ${{ matrix.coverage && !cancelled() }}
+        uses: codecov/codecov-action@v5
+        with:
+          token: ${{ secrets.CODECOV_TOKEN }}
+      # Same action twice: codecov deprecated test-results-action@v1 in favor of
+      # codecov-action with report_type, run once per report kind.
+      - name: Upload test results to Codecov
+        if: ${{ !cancelled() }}
+        uses: codecov/codecov-action@v5
+        with:
+          report_type: test_results
+          token: ${{ secrets.CODECOV_TOKEN }}
+
+  docs:
+    name: docs build
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.13"
+          cache: pip
+          cache-dependency-path: pyproject.toml
+      - run: pip install -e ".[docs]"
+      # --strict turns broken references and missing nav entries into failures. The API
+      # reference is generated from the source, so a renamed public symbol breaks the
+      # docs build here rather than silently emptying a page on ReadTheDocs.
+      - run: mkdocs build --strict
+
+  build:
+    name: build distributions
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.13"
+          cache: pip
+      - run: pip install build twine
+      - run: python -m build
+      - run: twine check dist/*
+      # Installing the built wheel into a clean environment is the only check that
+      # catches a package that imports fine from the source tree but ships broken:
+      # a missing py.typed, a subpackage left out of the wheel, a bad entry point.
+      - name: verify the wheel installs and imports standalone
+        run: |
+          python -m venv /tmp/fresh
+          /tmp/fresh/bin/pip install dist/*.whl
+          /tmp/fresh/bin/python -c "
+          import pyradmc, pathlib
+          print('version', pyradmc.__version__)
+          assert (pathlib.Path(pyradmc.__file__).parent / 'py.typed').is_file(), 'py.typed missing from wheel'
+          assert pyradmc.VoxelGrid is not None
+          print('public names:', len(pyradmc.__all__))
+          "
+      - uses: actions/upload-artifact@v4
+        with:
+          name: distributions
+          path: dist/

pyradmc-0.2.0/.github/workflows/release.yml

@@ -0,0 +1,114 @@
+name: Release
+
+# Tagging is the release action: the tag lands on an rc/* merge commit on main, per the
+# release flow of AGENTS.md 9.4. A manual dispatch builds and verifies only — the
+# publish jobs are gated on a v* tag ref, so nothing can reach PyPI without one.
+on:
+  push:
+    tags: ["v*"]
+  workflow_dispatch:
+
+permissions:
+  contents: read
+
+env:
+  PIP_DISABLE_PIP_VERSION_CHECK: "1"
+
+jobs:
+  build:
+    name: build and verify
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.13"
+          cache: pip
+
+      # The version is single-sourced from pyradmc/__init__.py, so a tag is a *claim*
+      # about it that nothing else checks. A mismatch here would publish a release whose
+      # artifacts report a different version than the tag they were cut from — and every
+      # RunProvenance record stamped by that build would carry the wrong number. Refuse.
+      - name: tag must match pyradmc.__version__
+        if: startsWith(github.ref, 'refs/tags/')
+        run: |
+          tag="${GITHUB_REF_NAME#v}"
+          version=$(python -c "import re,pathlib; print(re.search(r'__version__ = \"([^\"]+)\"', pathlib.Path('pyradmc/__init__.py').read_text()).group(1))")
+          echo "tag=$tag  __version__=$version"
+          if [ "$tag" != "$version" ]; then
+            echo "::error::tag v$tag does not match pyradmc.__version__ ($version)"
+            exit 1
+          fi
+
+      # A stale CITATION.cff is how a release ends up being cited as the previous one.
+      - name: CITATION.cff version must match the release
+        if: startsWith(github.ref, 'refs/tags/')
+        run: |
+          tag="${GITHUB_REF_NAME#v}"
+          cited=$(grep -E '^version:' CITATION.cff | head -1 | sed 's/version:[[:space:]]*//' | tr -d '"')
+          echo "tag=$tag  CITATION.cff=$cited"
+          if [ "$tag" != "$cited" ]; then
+            echo "::error::CITATION.cff says $cited but the tag is v$tag; update it before releasing"
+            exit 1
+          fi
+
+      - run: pip install build twine
+      - run: python -m build
+      - run: twine check dist/*
+
+      - name: verify the wheel installs and imports standalone
+        run: |
+          python -m venv /tmp/fresh
+          /tmp/fresh/bin/pip install dist/*.whl
+          /tmp/fresh/bin/python -c "
+          import pyradmc, pathlib
+          assert (pathlib.Path(pyradmc.__file__).parent / 'py.typed').is_file()
+          print('ok', pyradmc.__version__)
+          "
+
+      - uses: actions/upload-artifact@v4
+        with:
+          name: distributions
+          path: dist/
+
+  publish:
+    name: publish to PyPI
+    needs: build
+    # Only ever from a version tag: a workflow_dispatch run stops after build.
+    if: success() && startsWith(github.ref, 'refs/tags/v')
+    runs-on: ubuntu-latest
+    # Trusted publishing (OIDC): PyPI verifies this workflow's identity directly, so
+    # there is no long-lived API token to store or rotate. Configure the publisher once
+    # at https://pypi.org/manage/project/pyradmc/settings/publishing/ with
+    # owner e0404, repository pyRadMC, workflow release.yml, environment pypi.
+    environment:
+      name: pypi
+      url: https://pypi.org/p/pyRadMC
+    permissions:
+      id-token: write
+    steps:
+      - uses: actions/download-artifact@v4
+        with:
+          name: distributions
+          path: dist/
+      - uses: pypa/gh-action-pypi-publish@release/v1
+
+  github-release:
+    name: GitHub release
+    needs: publish
+    if: success() && startsWith(github.ref, 'refs/tags/v')
+    runs-on: ubuntu-latest
+    permissions:
+      contents: write
+    steps:
+      - uses: actions/download-artifact@v4
+        with:
+          name: distributions
+          path: dist/
+      - uses: softprops/action-gh-release@v2
+        with:
+          files: dist/*
+          generate_release_notes: true
+          body: |
+            See [CHANGELOG.md](https://github.com/e0404/pyRadMC/blob/main/CHANGELOG.md)
+            for what changed, including anything that can move a computed dose.

pyradmc-0.2.0/.github/workflows/validation.yml

@@ -0,0 +1,55 @@
+name: Validation tier
+
+# Deliberately NOT on push: the validation tier is slow, needs the ~120 MB EPICS
+# libraries, and gates physics rather than code. AGENTS.md section 7 requires it to pass
+# before a release, so it runs on a schedule (to catch rot) and on demand (before
+# tagging), not on every commit.
+on:
+  schedule:
+    - cron: "0 3 * * 1" # Mondays, 03:00 UTC
+  workflow_dispatch:
+
+permissions:
+  contents: read
+
+jobs:
+  validation:
+    name: validation tier (with EPICS libraries)
+    runs-on: ubuntu-latest
+    timeout-minutes: 120
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.13"
+          cache: pip
+          cache-dependency-path: pyproject.toml
+      - run: pip install -e ".[warp,dev]"
+
+      # Cached so a scheduled run does not re-fetch 120 MB from the IAEA every week.
+      # The cache key carries the pinned digests, so changing a pin necessarily misses
+      # the cache and re-downloads — which is the correct behaviour, since a changed pin
+      # means the libraries themselves are supposed to be different.
+      - name: cache EPICS libraries
+        id: epics-cache
+        uses: actions/cache@v4
+        with:
+          path: ~/.cache/pyradmc/epics
+          key: epics-2023-${{ hashFiles('pyradmc/data/tabulated/build.py') }}
+
+      # download_library verifies every file against its pinned SHA-256 and fails
+      # closed. This is also what exercises the pins themselves in CI: a silent upstream
+      # revision shows up here as a hard failure rather than as drift in a dose gate.
+      - name: fetch and verify EPICS libraries
+        run: |
+          python -c "
+          from pyradmc.data.tabulated import build
+          for which in ('epdl', 'eedl'):
+              print(which, '->', build.download_library(which))
+          "
+
+      - name: run the validation tier
+        env:
+          PYRADMC_EPDL_PATH: ~/.cache/pyradmc/epics/EPDL2023.ALL
+          PYRADMC_EEDL_PATH: ~/.cache/pyradmc/epics/EEDL2023.ALL
+        run: pytest -m validation -q

pyradmc-0.2.0/.gitignore

@@ -0,0 +1,51 @@
+__pycache__/
+*.py[cod]
+.venv/
+.pytest_cache/
+.mypy_cache/
+.ruff_cache/
+.hypothesis/
+build/
+dist/
+*.egg-info/
+.benchmarks/
+
+# Compiled tabulated cross-section tables: derived from the (uncommitted, user-side)
+# EPICS libraries by pyradmc.data.tabulated.build, so not tracked.
+*.npz
+
+# Phase-space demo outputs derive from an external (proprietary, machine-local)
+# phase-space file and are not reproducible in the repo, so they are not tracked.
+examples/phasespace_demo.png
+examples/phasespace_demo.csv
+site/
+
+# Vendor beam data and anything fitted from it. The workbook a head is commissioned
+# against is licensed to its owner, not to this repository, and at ~500 KB it slips
+# under the check-added-large-files gate rather than being caught by it. The fitted
+# radial-fluence table is derived from those measured profiles, so it travels with
+# them: the shipped default is the analytic cone, and PRIMARY_FLUENCE_FILE is the hook
+# for the table you fit against your own data.
+*.xlsx
+examples/halcyon_primary_fluence.dat
+
+# Everything the examples render. They are regenerable by definition -- that is what an
+# example is -- and tracking them cost ~5 MB of binaries that no reader of the repository
+# opens from here, churned on every re-run, and went stale against the scripts that write
+# them. The figures the README embeds live in docs/assets/ instead, which is where a
+# documentation asset belongs; an example's own output is not one.
+examples/*.png
+examples/*.csv
+
+# Local scratch: comparison scripts, sweeps and figures that need the vendor workbook,
+# plus the run logs they were driven from. Not reproducible here, so not tracked.
+local_*
+*.log
+
+.vscode/
+
+# Coverage and test-result artifacts (pytest --cov / --junitxml, uploaded to Codecov in CI)
+.coverage
+.coverage.*
+coverage.xml
+junit.xml

pyradmc-0.2.0/.gitlab-ci.yml

@@ -0,0 +1,93 @@
+# GitLab CI for the DKFZ GitLab mirror. GitHub (github.com/e0404/pyRadMC) is the
+# primary remote (AGENTS.md 9): pull requests, reviews and releases happen there.
+#
+# This pipeline VALIDATES ONLY — there is deliberately no deploy stage. Releases
+# (PyPI, GitHub Releases) and the documentation build run from GitHub, where trusted
+# publishing and ReadTheDocs are wired up; see .github/workflows/release.yml. Keeping
+# publication in exactly one place is what prevents two pipelines racing to upload the
+# same version.
+#
+# The validation tier is not here either: it needs the ~120 MB EPICS libraries and runs
+# on a schedule in .github/workflows/validation.yml.
+
+stages: [check, test, build]
+
+default:
+  image: python:3.13-slim
+  # Warp and SciPy wheels are large; caching pip keeps repeat pipelines cheap.
+  cache:
+    key:
+      files: [pyproject.toml]
+    paths: [.cache/pip]
+  before_script:
+    - python -V
+    - pip install --quiet --upgrade pip
+
+variables:
+  PIP_CACHE_DIR: "$CI_PROJECT_DIR/.cache/pip"
+  PIP_DISABLE_PIP_VERSION_CHECK: "1"
+
+workflow:
+  rules:
+    - if: $CI_PIPELINE_SOURCE == "merge_request_event"
+    - if: $CI_COMMIT_BRANCH == "main"
+    - if: $CI_COMMIT_BRANCH == "develop"
+    - if: $CI_PIPELINE_SOURCE == "web"
+
+quality:
+  stage: check
+  variables:
+    PRE_COMMIT_HOME: "$CI_PROJECT_DIR/.cache/pre-commit"
+  cache:
+    key:
+      files: [.pre-commit-config.yaml]
+    paths: [.cache/pre-commit, .cache/pip]
+  script:
+    - pip install --quiet -e ".[warp,dev]"
+    # Run the hook definitions rather than re-listing the tools. The pinned revs in
+    # .pre-commit-config.yaml are the single authority, so this pipeline, the GitHub
+    # one, and a developer's commit hook cannot disagree or drift onto a new release.
+    - pre-commit run --all-files --show-diff-on-failure
+  before_script:
+    - python -V
+    - pip install --quiet --upgrade pip
+    - git config --global --add safe.directory "$CI_PROJECT_DIR"
+
+tests:
+  stage: test
+  parallel:
+    matrix:
+      - PYTHON_VERSION: ["3.10", "3.11", "3.12", "3.13"]
+  image: python:$PYTHON_VERSION-slim
+  script:
+    - pip install --quiet -e ".[warp,dev]"
+    # No CUDA device on a standard runner: warp runs on CPU and the gpu-marked tests
+    # skip themselves. The default addopts already exclude the validation and perf tiers.
+    - pytest -q --junitxml=report.xml
+  artifacts:
+    when: always
+    reports:
+      junit: report.xml
+    expire_in: 1 week
+
+docs:
+  stage: check
+  script:
+    - pip install --quiet -e ".[docs]"
+    # --strict only; the built site is not published from here.
+    - mkdocs build --strict
+
+build:
+  stage: build
+  script:
+    - pip install --quiet build twine
+    - python -m build
+    - twine check dist/*
+    # The wheel must import from a clean environment — this catches a missing py.typed
+    # or a subpackage left out of the wheel, which a source-tree import never would.
+    - python -m venv /tmp/fresh
+    - /tmp/fresh/bin/pip install --quiet dist/*.whl
+    - /tmp/fresh/bin/python -c "import pyradmc, pathlib; assert (pathlib.Path(pyradmc.__file__).parent / 'py.typed').is_file(); print(pyradmc.__version__)"
+  artifacts:
+    paths: [dist/]
+    expire_in: 1 week

pyradmc-0.2.0/.pre-commit-config.yaml

@@ -0,0 +1,51 @@
+# Pre-commit gates: fast, file-scoped checks only.
+#
+#     pip install -e ".[dev]" && pre-commit install
+#
+# Deliberately NO test run. The suite takes minutes, and a gate slow enough to be
+# resented is a gate that gets bypassed with --no-verify. Tests are CI's job — see
+# .github/workflows/ci.yml and .gitlab-ci.yml, which run the fast tiers on every push to
+# main and develop, and the validation tier on its own schedule.
+#
+# Run against everything (not just staged files) with:  pre-commit run --all-files
+default_language_version:
+  python: python3
+
+repos:
+  - repo: https://github.com/pre-commit/pre-commit-hooks
+    rev: v6.0.0
+    hooks:
+      - id: trailing-whitespace
+        # The EGSnrc benchmark is stored verbatim; reformatting reference data would
+        # silently change what the validation tier compares against.
+        exclude: ^tests/validation/data/
+      - id: end-of-file-fixer
+        exclude: ^tests/validation/data/
+      - id: check-yaml
+      - id: check-toml
+      - id: check-merge-conflict
+      - id: check-case-conflict
+      - id: check-added-large-files
+        # The committed example figures run to ~230 KB; this catches an accidental
+        # cross-section table or phase-space file, which are the real risks.
+        args: [--maxkb=512]
+
+  - repo: https://github.com/astral-sh/ruff-pre-commit
+    rev: v0.15.1
+    hooks:
+      - id: ruff-check
+        args: [--fix]
+      - id: ruff-format
+
+  - repo: local
+    hooks:
+      # Run from the project environment, not an isolated one: mypy --strict needs the
+      # real NumPy, SciPy and Warp stubs to say anything true, and it is configured
+      # whole-package in pyproject.toml (kernels exempt), so it does not take filenames.
+      - id: mypy
+        name: mypy --strict (non-kernel code)
+        entry: mypy pyradmc
+        language: system
+        types: [python]
+        pass_filenames: false
+        require_serial: true

pyradmc-0.2.0/.readthedocs.yaml

@@ -0,0 +1,27 @@
+# ReadTheDocs build configuration.
+#
+# RTD builds from the primary remote, github.com/e0404/pyRadMC.
+version: 2
+
+build:
+  os: ubuntu-24.04
+  tools:
+    python: "3.13"
+
+mkdocs:
+  configuration: mkdocs.yml
+  # Broken references and missing nav entries fail the build. The API reference is
+  # generated from the source, so a renamed or removed public symbol is caught here
+  # rather than silently rendering an empty page.
+  fail_on_warning: true
+
+python:
+  install:
+    # The docs extra pulls mkdocs-material and mkdocstrings; the package itself is
+    # installed because mkdocstrings imports it to read signatures and docstrings.
+    # No warp extra: mkdocstrings resolves the lazily re-exported names through the
+    # TYPE_CHECKING block, so the API reference builds without a CUDA toolchain.
+    - method: pip
+      path: .
+      extra_requirements:
+        - docs