obdeect 0.6.0__tar.gz

obdeect-0.6.0/.clang-format

@@ -0,0 +1,5 @@
+---
+BasedOnStyle: LLVM
+ColumnLimit: 100
+IndentWidth: 2
+SortIncludes: CaseSensitive

obdeect-0.6.0/.clang-tidy

@@ -0,0 +1,17 @@
+---
+Checks: >
+  -*,
+  bugprone-argument-comment,
+  bugprone-branch-clone,
+  bugprone-empty-catch,
+  bugprone-exception-escape,
+  bugprone-infinite-loop,
+  bugprone-macro-parentheses,
+  bugprone-suspicious-memset-usage,
+  bugprone-undefined-memory-manipulation,
+  performance-for-range-copy
+WarningsAsErrors: '*'
+HeaderFilterRegex: 'cpp/include/obdeect/.*'
+CheckOptions:
+  - key: readability-identifier-length.MinimumVariableNameLength
+    value: '2'

obdeect-0.6.0/.editorconfig

@@ -0,0 +1,12 @@
+root = true
+
+[*]
+charset = utf-8
+end_of_line = lf
+insert_final_newline = true
+indent_style = space
+indent_size = 2
+trim_trailing_whitespace = true
+
+[*.py]
+indent_size = 4

obdeect-0.6.0/.gitattributes

@@ -0,0 +1,7 @@
+* text=auto eol=lf
+
+*.cpp text diff=cpp
+*.hpp text diff=cpp
+*.py text diff=python
+*.yml text
+*.yaml text

obdeect-0.6.0/.github/workflows/ci.yml

@@ -0,0 +1,33 @@
+---
+name: CI-linter
+
+on:
+  push:
+    branches:
+      - main
+  pull_request:
+
+concurrency:
+  group: ${{ github.workflow }}-${{ github.event.pull_request.number || github.ref }}
+  cancel-in-progress: true
+
+jobs:
+  lint:
+    runs-on: ubuntu-24.04
+    steps:
+      - uses: actions/checkout@v7
+        with:
+          fetch-depth: 0
+      - uses: actions/setup-python@v7
+        with:
+          python-version: '3.14'
+      - name: Install linters
+        run: python -m pip install --upgrade pip pre-commit ruff clang-format
+      - name: Run repository hooks
+        run: pre-commit run --all-files
+      - name: Check Python formatting and lint
+        run: ruff format --check python && ruff check python
+      - name: Check C++ formatting
+        run: >-
+          find cpp -type f \( -name '*.cpp' -o -name '*.hpp' \) -print0
+          | xargs -0 clang-format --dry-run --Werror

obdeect-0.6.0/.github/workflows/docs.yml

@@ -0,0 +1,61 @@
+---
+name: CI-docs
+# Publish dev and release documentation together, preserving root URLs.
+
+on:
+  pull_request:
+  push:
+    branches:
+      - main
+    tags:
+      - "v*"
+  workflow_dispatch:
+
+concurrency:
+  group: ${{ github.workflow }}-${{ github.event.pull_request.number || 'pages' }}
+  cancel-in-progress: true
+
+jobs:
+  build:
+    runs-on: ubuntu-24.04
+    permissions:
+      contents: read
+    steps:
+      - uses: actions/checkout@v7
+        with:
+          fetch-depth: 0
+      - uses: actions/setup-python@v7
+        with:
+          python-version: "3.14"
+      - name: Install obdeect with the documentation tools
+        run: python -m pip install --upgrade pip && python -m pip install ".[docs]"
+      - name: Test documentation publishing
+        run: |
+          python -m pip install pytest
+          python -m pytest -q python/tests/test_docs_versions.py
+      - name: Build versioned site
+        env:
+          DOCS_BASE_URL: https://${{ github.repository_owner }}.github.io/${{ github.event.repository.name }}
+        run: |
+          args=(--output docs/_build/site --base-url "$DOCS_BASE_URL")
+          if [[ "$GITHUB_REF" == refs/tags/* ]]; then
+            args+=(--dev-ref origin/main)
+          fi
+          python docs/build_versions.py "${args[@]}"
+      - uses: actions/upload-pages-artifact@v5
+        with:
+          path: docs/_build/site
+
+  deploy:
+    if: github.event_name != 'pull_request' && (github.ref == 'refs/heads/main' || startsWith(github.ref, 'refs/tags/v'))
+    needs: build
+    runs-on: ubuntu-24.04
+    permissions:
+      pages: write
+      id-token: write
+    environment:
+      name: github-pages
+      url: ${{ steps.deployment.outputs.page_url }}
+    steps:
+      - id: deployment
+        uses: actions/deploy-pages@v5

obdeect-0.6.0/.github/workflows/pypi.yml

@@ -0,0 +1,98 @@
+---
+name: Build and publish obdeect
+
+on:
+  pull_request:
+  push:
+    tags:
+      - "v*"
+  workflow_dispatch:
+    inputs:
+      publish_testpypi:
+        description: Publish the built distributions to TestPyPI
+        required: false
+        type: boolean
+        default: false
+
+permissions:
+  contents: read
+
+jobs:
+  wheels:
+    strategy:
+      fail-fast: false
+      matrix:
+        os: [ubuntu-24.04, ubuntu-24.04-arm, macos-15]
+    runs-on: ${{ matrix.os }}
+    steps:
+      - uses: actions/checkout@v7
+        with:
+          ref: ${{ github.ref }}
+      - uses: actions/setup-python@v7
+        with:
+          python-version: "3.14"
+      - name: Install wheel tooling
+        run: python -m pip install --upgrade cibuildwheel
+      - name: Build and smoke-test wheels
+        env:
+          CIBW_BUILD: "cp314-*"
+          CIBW_TEST_REQUIRES: "pytest scipy"
+          CIBW_TEST_COMMAND: python -m pytest {project}/python/tests -q
+        run: python -m cibuildwheel --output-dir wheelhouse
+      - uses: actions/upload-artifact@v7
+        with:
+          name: wheels-${{ matrix.os }}
+          path: wheelhouse/*.whl
+
+  sdist:
+    runs-on: ubuntu-24.04
+    steps:
+      - uses: actions/checkout@v7
+        with:
+          ref: ${{ github.ref }}
+      - uses: actions/setup-python@v7
+        with:
+          python-version: "3.14"
+      - name: Build source distribution
+        run: |
+          python -m pip install --upgrade build
+          python -m build --sdist --outdir dist
+      - uses: actions/upload-artifact@v7
+        with:
+          name: sdist
+          path: dist/*.tar.gz
+
+  publish:
+    if: github.event_name == 'push' && startsWith(github.ref, 'refs/tags/v')
+    needs: [wheels, sdist]
+    runs-on: ubuntu-24.04
+    environment: pypi
+    permissions:
+      id-token: write
+    steps:
+      - uses: actions/download-artifact@v8
+        with:
+          path: dist
+          merge-multiple: true
+      - name: Publish distributions to PyPI
+        uses: pypa/gh-action-pypi-publish@release/v1
+
+  publish-testpypi:
+    if: >-
+      ${{
+        github.event_name == 'workflow_dispatch' && inputs.publish_testpypi
+      }}
+    needs: [wheels, sdist]
+    runs-on: ubuntu-24.04
+    environment: testpypi
+    permissions:
+      id-token: write
+    steps:
+      - uses: actions/download-artifact@v8
+        with:
+          path: dist
+          merge-multiple: true
+      - name: Publish distributions to TestPyPI
+        uses: pypa/gh-action-pypi-publish@release/v1
+        with:
+          repository-url: https://test.pypi.org/legacy/

obdeect-0.6.0/.github/workflows/tests.yml

@@ -0,0 +1,54 @@
+---
+name: CI-tests
+
+on:
+  push:
+    branches:
+      - main
+  pull_request:
+
+concurrency:
+  group: ${{ github.workflow }}-${{ github.event.pull_request.number || github.ref }}
+  cancel-in-progress: true
+
+permissions:
+  contents: read
+
+jobs:
+  build-and-test:
+    strategy:
+      fail-fast: false
+      matrix:
+        runner: [ubuntu-24.04, macos-15]
+    runs-on: ${{ matrix.runner }}
+    steps:
+      - uses: actions/checkout@v7
+      - uses: actions/setup-python@v7
+        with:
+          python-version: '3.14'
+      - name: Install Python package and test dependencies
+        run: python -m pip install --upgrade pip && python -m pip install . pytest scipy
+      - name: Configure and build
+        run: cmake -S . -B build -DCMAKE_BUILD_TYPE=Release && cmake --build build --parallel
+      - name: Run native and Python tests
+        run: ctest --test-dir build --output-on-failure && pytest python/tests
+  fma:
+    runs-on: ubuntu-24.04
+    steps:
+      - uses: actions/checkout@v7
+      - name: Configure, build, and test with OBDEECT_USE_FMA
+        run: >-
+          cmake -S . -B build-fma -DCMAKE_BUILD_TYPE=Release -DOBDEECT_USE_FMA=ON
+          && cmake --build build-fma --parallel
+          && ctest --test-dir build-fma --output-on-failure
+  sanitizers:
+    runs-on: ubuntu-24.04
+    steps:
+      - uses: actions/checkout@v7
+      - name: Configure, build, and test with sanitizers
+        run: >-
+          cmake -S . -B build-sanitize -DCMAKE_BUILD_TYPE=Debug
+          -DCMAKE_CXX_FLAGS="-fsanitize=address,undefined -fno-omit-frame-pointer"
+          -DCMAKE_EXE_LINKER_FLAGS="-fsanitize=address,undefined"
+          && cmake --build build-sanitize --parallel
+          && ctest --test-dir build-sanitize --output-on-failure

obdeect-0.6.0/.gitignore

@@ -0,0 +1,32 @@
+# CMake and native build products
+/build/
+/out/
+/compile_commands.json
+/tmp_planning/
+*.o
+*.obj
+*.a
+*.so
+*.dylib
+*.dll
+
+# Generated trace and visualisation products
+*.npz
+*.html
+
+# Python
+__pycache__/
+*.py[cod]
+.pytest_cache/
+.ruff_cache/
+.venv/
+*.egg-info/
+/dist/
+
+# IDE and operating-system files
+.DS_Store
+.vscode/
+.idea/
+
+# Documentation build
+/docs/_build/

obdeect-0.6.0/.pre-commit-config.yaml

@@ -0,0 +1,64 @@
+---
+default_language_version:
+  python: python3.14
+
+repos:
+- repo: https://github.com/pre-commit/pre-commit-hooks
+  rev: v5.0.0
+  hooks:
+  - id: check-yaml
+  - id: check-json
+  - id: end-of-file-fixer
+  - id: trailing-whitespace
+- repo: https://github.com/astral-sh/ruff-pre-commit
+  rev: v0.12.7
+  hooks:
+  - id: ruff-check
+    args: [--fix]
+  - id: ruff-format
+# Github action
+- repo: https://github.com/rhysd/actionlint
+  rev: v1.7.12
+  hooks:
+  - id: actionlint
+# https://pyproject-fmt.readthedocs.io/en/latest/
+- repo: https://github.com/tox-dev/pyproject-fmt
+  rev: "v2.29.2"
+  hooks:
+  - id: pyproject-fmt
+# codespell
+- repo: https://github.com/codespell-project/codespell
+  rev: v2.4.3
+  hooks:
+  - id: codespell
+    args: [
+      "--ignore-words-list=als,hel",
+    ]
+# markdownlint
+- repo: https://github.com/igorshubovych/markdownlint-cli
+  rev: v0.49.1
+  hooks:
+  - id: markdownlint
+    args: ["--disable", "MD041"]
+# yamllint
+- repo: https://github.com/adrienverge/yamllint.git
+  rev: v1.38.0
+  hooks:
+  - id: yamllint
+    args:
+      [
+        "--strict",
+        "-d",
+        '{extends: default, rules: {line-length: {max: 300}, indentation: {spaces: 2, indent-sequences: consistent}, truthy: {allowed-values: ["true", "false", "on", "off"]}}}'
+      ]
+# towncrier
+- repo: https://github.com/twisted/towncrier
+  rev: 25.8.0
+  hooks:
+  - id: towncrier-check
+    files: ^docs/changes/
+# shellcheck
+- repo: https://github.com/shellcheck-py/shellcheck-py
+  rev: v0.11.0.1-1
+  hooks:
+  - id: shellcheck

obdeect-0.6.0/AGENTS.md

@@ -0,0 +1,83 @@
+# obdeect Agent Guide
+
+## Scope
+
+`obdeect` is a portable C++20 optical ray tracer with a thin Python interface.
+It traces photons from a defined entrance surface to a focal/sensor surface.
+Air-shower generation, electronics, triggers, and event writing are out of
+scope. Read the relevant code and tests first; use the workspace plans and
+validation matrix for architectural or scientific changes.
+
+## Design rules
+
+- Never ever modify the main README.md. Suggest instead changes, don't apply them.
+- Terminology: this project is for gamma-ray astronomy. Always call the
+  compiled telescope geometry and optical-response artifact an "optical model".
+- Keep it simple, efficient, deterministic, and portable. Prefer small,
+  explicit data structures and testable physical kernels over frameworks,
+  global state, hidden defaults, or abstraction in the hot path.
+- Keep the core C++ standard-library-only. Python, plotting, file import, and
+  external-simulator dependencies belong at the boundary, never in a trace
+  kernel.
+- Use immutable compiled optical models and contiguous SoA photon buffers. After
+  output buffers are sized, the per-photon path must not allocate, perform I/O,
+  call Python, or dispatch virtually.
+- Make units, frames, random seeds, statuses, and loss accounting explicit.
+  Reject invalid or unsupported input; never silently discard fields.
+
+## Data, not telescope-specific code
+
+- Do not hardwire CTAO names, telescope geometry, model versions, file paths,
+  or optical/physics parameters into the core, public API, or defaults.
+- Geometry, response tables, trace modes, and conventions are validated input
+  data. Model import produces a generic, provenance-recorded IR.
+- CTAO support is an explicit importer/adapter or versioned fixture only. It
+  must not be required to build, test, or run the generic engine, and it must
+  never be an implicit fallback.
+- Use python >3.14. Do not fall back to earlier versions.
+
+## Changes and validation
+
+- Make the narrowest complete change and preserve unrelated work.
+- Do not add anything under `docs/changes/` for current work. Leave that
+  directory untouched unless the user explicitly asks for a changelog or
+  release-note change.
+- Add or update a focused test for every behavioural change. Establish analytic
+  kernel and primitive tests before optical-model, cross-tool, or performance tests.
+- Preserve results across photon ordering, blocks, and thread counts. Record
+  provenance for fixtures and cross-tool comparisons.
+- Do not weaken tolerances or replace golden data to hide a discrepancy. Keep
+  examples and fixtures clearly labelled and configuration-driven.
+- When renaming a public concept, update implementation symbols, imports,
+  exception types, serialized keys, fixture variables, and test call sites
+  together. Do not leave obsolete geometry terminology in optical-model tests.
+
+## Build, test, and lint
+
+Run from this directory. Configure before static analysis so the compilation
+database is current.
+
+```bash
+cmake --preset debug
+cmake --build --preset debug
+ctest --test-dir build/debug --output-on-failure
+python -m pytest python/tests
+ruff format --check python
+ruff check python
+find cpp -type f \( -name '*.cpp' -o -name '*.hpp' \) -print0 | \
+xargs -0 clang-format --dry-run --Werror
+```
+
+Ruff is configured with a 100-character line limit. Run `ruff format` before
+`ruff check`, and manually wrap long strings or boolean expressions that the
+formatter leaves unchanged.
+
+After renames, search the affected Python files for removed symbols and run
+the focused tests before the full suite. A clean handoff requires both
+`ruff format --check python` and `ruff check python`; do not rely on a passing
+test run alone because stale test references can fail collection or linting.
+
+Run `clang-tidy -p build/debug cpp/src/<changed-file>.cpp` for changed C++
+translation units when available, and `pre-commit run --all-files` before
+handoff. Start with the smallest relevant test; run the full checks for shared
+kernels, interfaces, configuration, or tooling changes.

obdeect-0.6.0/CHANGELOG.md

@@ -0,0 +1,123 @@
+# Changelog
+
+This project follows [Keep a Changelog](https://keepachangelog.com/en/1.1.0/)
+and uses semantic versioning after the first stable release.
+
+## [0.6.0]
+
+### Changed
+
+- The PyPI distribution is named `obdeect`. Install with `pip install obdeect`.
+  The repository is hosted in the `gammasim` organisation.
+
+## [0.5.0]
+
+Maintenance release: CI workflows and changelog. No change to the code or the Python API.
+
+### Changed
+
+- The documentation workflow uses `actions/deploy-pages` v5 (Node.js 24).
+- The publishing workflow uses `actions/download-artifact` v8. A download whose hash does not
+  match the expected hash now fails the workflow.
+- The changelog is rebuilt from the git history for all releases from 0.1.0 on.
+
+## [0.4.0]
+
+Performance release for the optical ray tracer, with additions to the Python API and the
+command line. The optical-model format is unchanged (`obdeect.optical-model.v2`).
+
+### Added
+
+- `OpticalModel.trace` keyword arguments `outputs`, `detected_only`, `classify_losses` and `pool`.
+- `ThreadPool` (persistent worker pool) and `trace_many` (several telescopes in one call).
+- `trace_bunches`, tracing of CORSIKA-style photon bunches.
+- `OpticalModel.obscurer_hits` and the command `obdeect obscurers`: the obscurers on the path
+  of each photon, counted as `crossed`, `first` and `sole`.
+- Optional fused multiply-add build, `-DOBDEECT_USE_FMA=ON` (x86-64, `-mfma`; off by default).
+- CI job that builds and tests with `OBDEECT_USE_FMA=ON`.
+- Documentation site (Sphinx, MyST Markdown) with the user guide, shadowing, telescope and optical
+  element descriptions, light sources, batch tracing, physics limitations and the Python API.
+  Figures show the telescope structure and the deviations from sim_telarray.
+- Versioned documentation: development and tagged versions are published together to GitHub Pages,
+  with a version switcher.
+
+### Changed
+
+- Obscurers are indexed per optical leg: a bounding-box hierarchy for every leg, and a uniform
+  x-y grid for the incoming leg and for the legs after the primary, walked cell by cell along the
+  ray.
+- Aspheric mirrors stop at the single root of the ray when the slope bound guarantees one root.
+  A root in a segment gap is a miss, without scanning the aperture. Hits are unchanged.
+- Segment membership on aspheric mirrors uses a cell grid with cached verdicts.
+- Asphere sag and slope are evaluated as polynomials in r² (rounding-level change).
+- `telescope_transmission` is checked by `response_bound`, which raises `ModelError` for an
+  unsupported transmission instead of accepting it.
+- Replay comparison has tiers, used to check results across builds.
+- Source comments and docstrings describe obdeect's own conventions instead of sim_telarray's.
+  No change in behaviour.
+
+### Fixed
+
+- Secondary baffle: a fourth value not below R1 is read as the outer radius, as in sim_telarray,
+  instead of as the wall thickness. No current model uses this value.
+- Bunch acceptance rejects axes that are not finite or not increasing; wavelength density nodes
+  must start above 0 nm.
+- A failure while starting the thread pool no longer leaves joinable threads behind; an
+  exception in a task is rethrown to the caller and the remaining chunks are skipped.
+
+## [0.3.0]
+
+Phase 2: calibration light.
+
+### Added
+
+- Point emitters: `emitter_photons` makes weighted photons towards a target disk, with Poisson
+  statistics.
+- `trace_emitter` and `trace_emitter_blocks`, which trace emitter light in blocks of 250,000
+  photons, so memory stays bounded.
+- Direct tracing of photons that start inside the telescope (flashers), with `trace(direct=True)`.
+- Documentation of the hand-off of photon bunches to sim_telarray for dual-mirror telescopes.
+
+### Changed
+
+- Segment footprint frames are computed once per optical model. Results are bit-identical; SST
+  tracing is about 1.7 times faster.
+
+## [0.2.1]
+
+### Added
+
+- Linux arm64 wheels.
+
+## [0.2.0]
+
+Phase 1: optical models for in-process use by simtools, with sim_telarray equivalence.
+
+### Added
+
+- Python API and `obdeect` command line with `compile`, `trace` and `plot`.
+- Compilation of CTAO optical models from simulation-models: mirror lists, telescope structure
+  (one table with explicit shapes), telescope transmission, camera transport, patch productions.
+- Photon diagnostics and CTAO validation scripts.
+- Deterministic optical transport.
+
+### Changed
+
+- Detector and ray-tracing seeds are separate.
+- Legacy optical-model seeds are read compatibly.
+
+### Fixed
+
+- Optical input validation and deterministic boundary selection.
+- GCC header portability and the macOS wheel deployment target.
+
+## [0.1.0]
+
+First version: a C++20 ray tracer with a Python package.
+
+### Added
+
+- C++20 artificial 400-nm source, spherical primary and focal-screen tracer.
+- Simple MST-inspired camera and four-mast pre-primary shadow model.
+- CSV trace-path output and optional Matplotlib diagnostic plot.
+- CMake, Python packaging, tests, linting CI, BSD-3-Clause license and citation metadata.

obdeect-0.6.0/CITATION.cff

@@ -0,0 +1,13 @@
+cff-version: 1.2.0
+message: "If you use obdeect, please cite it using the metadata below."
+title: "obdeect: Ray tracing for imaging atmospheric Cherenkov telescopes"
+version: 0.1.0
+date-released: 2026-09-18
+license: BSD-3-Clause
+type: software
+authors:
+  - given-names: Gernot
+    family-names: Maier
+    affiliation: DESY
+    orcid: 'https://orcid.org/0000-0001-9868-4700'
+abstract: "A C++20 IACT-only prototype for tracing photons through telescope optics and structure."