obdeect project analysis#
Analysis of obdeect v0.7.2 (ray tracing only), kept for reference; names are those of v0.7.2.
Analysis of obdeect v0.7.2 (main at e4ade6a, 2026-11-06), seen as a
gamma-ray astronomer, an optics expert, a high-performance-computing (HPC)
expert and a release manager. Goal: the most precise and fastest code that is
easy to maintain, with smooth CI and good documentation.
This is a review, not a change: no tracked file was modified (README.md
included). Statements are marked [verified] when I ran or read the code to
confirm them, and [to check] when they follow from reading and need a
measurement or a second opinion before anyone acts on them.
1. Summary#
obdeect is in very good shape for a project that is seven weeks old (251 commits since 2026-09-18). The architecture follows its own rules: a standard-library-only header core, immutable compiled optical models, counter-based random numbers (Philox) that make results independent of thread count, block size and photon order, and a thin nanobind boundary. The validation against sim_telarray is thorough (D80 within 0.1-1.6 %, effective area within 0.3 %, air-shower photoelectrons within 0.5 %), and the documentation is unusually honest about limitations.
The weak points are not in the core numerics. They are:
Validation is single-reference and not reproducible from the repository. Everything is compared with sim_telarray; scripts, containers and result files live in an external workspace.
One known, uncorrected geometric inconsistency in the mirror-scatter code (non-orthogonal rotation axes on curved facets).
CI covers the happy path only: no ThreadSanitizer for the hand-written thread pool, no clang-tidy despite the guide, no Windows or Intel-Mac builds, no performance guard, no coverage, no type checking.
Release hygiene: four different version numbers in the tree, three releases in three days, broken README links, no dependency-update automation.
Performance headroom of 10-30 % is available cheaply (serial compaction, compiler flags, bunch-path duplicate work) before any SIMD work.
Scorecard#
Viewpoint |
Grade |
One-line reason |
|---|---|---|
Gamma-ray astronomer |
A- |
Production-grade parity with sim_telarray; accuracy limited by shared assumptions and missing as-built effects |
Optics expert |
B+ |
Sound geometry; scatter-axis flaw, root-finding corner cases, no refraction or polarisation |
HPC expert |
A- |
Deterministic, allocation-free hot path, near-linear scaling; compaction and flags leave easy wins |
Release manager |
B |
Good tooling (towncrier, trusted publishing, versioned docs); drift and gaps in the matrix |
Maintainability / docs |
B+ |
Clear code and docs; a few oversized headers, 12-argument kernel call, dead links |
Top 12 actions, in order#
# |
Action |
Viewpoint |
Effort |
Gain |
|---|---|---|---|---|
1 |
Add a ThreadSanitizer CI job (pool, |
HPC / release |
S |
Catches races in the only hand-written concurrency code |
2 |
Make validation reproducible: move scripts, model fixtures and reference numbers into the repo or a DOI-versioned data release |
Astronomer |
M |
Turns claims into regression tests |
3 |
Remove mirror-realisation noise from the sim_telarray comparison by feeding identical per-mirror realisations to both codes |
Astronomer / optics |
M |
D80 agreement from about 1 % to about 1e-4 |
4 |
Orthogonalise the scatter axes against the hit normal ( |
Optics |
S |
Removes a known 1.9e-2 rad geometric inconsistency |
5 |
Parallelise or remove the serial |
HPC |
S |
Measured 30 % slower than writing all rows |
6 |
Try |
HPC |
S |
Likely 5-15 %, results unchanged [to check] |
7 |
One version source of truth; fix CMake 0.2.0, CITATION 0.1.0, fallbacks |
Release |
S |
Correct citations and metadata |
8 |
Fix README links to |
Docs |
S |
Dead links on the front page |
9 |
Replace |
Maintainability |
S |
Removes a bool-ordering bug class |
10 |
Add Dependabot or Renovate for Actions and pre-commit; pin Actions consistently |
Release |
S |
Supply-chain hygiene |
11 |
Add Windows and Intel-macOS to the test or wheel matrix, or state them unsupported |
Release |
M |
Honest portability claim |
12 |
Add a deterministic work-counter performance test (Newton steps, node visits) per real model |
HPC |
M |
Catches algorithmic regressions on any runner |
Effort: S under a day, M a few days.
2. What I ran#
Check |
Result |
|---|---|
|
OK, 2.7 s wall on 12 cores |
|
6 of 6 pass, 4.2 s |
|
99 of 99 pass, 8.9 s |
|
clean |
|
clean |
|
not available here, not run |
Sphinx docs build, pre-commit, sanitizer and FMA presets |
not run |
Throughput probe (section 5.1) |
run, numbers below |
Environment finding [verified]: the first pytest run failed at collection
with CalledProcessError: cmake --build and No module named nanobind. An
editable install made earlier in another virtual environment (with
editable.rebuild = true) tried to rebuild on import obdeect and could not
find nanobind, because pip’s isolated build environment no longer exists.
AGENTS.md and docs/installation.md give pip install -e '.[dev]'; with
rebuild-on-import that needs --no-build-isolation and the build requirements
installed in the environment. Either document that, or make the failure
legible: the execute_process(... -m nanobind --cmake_dir) at
CMakeLists.txt:47 only prints a CMake traceback.
3. Gamma-ray astronomer#
3.1 What is strong#
Quantified agreement with sim_telarray over twelve telescope models, 0-4 deg field, plus measured-PSF checks (LSTN-01 D80 3.050 vs 3.052 cm).
End-to-end air-shower check (1 TeV gammas, zenith 20/40/60 deg, five telescopes): all nine points within 0.5 % and 1.5 sigma, with timing (KS test) and image-shape agreement.
docs/limitations.mdnames what is not modelled and sizes the effect (for example the camera-window focus shift, 1-3 mm for 3-10 mm PMMA).Every result carries the optical model’s SHA-256; the model is rejected if its content does not match its hash (
python/obdeect/model.py:34).
3.2 Findings#
A1. Validation is equivalence, not correctness. All twelve comparisons use
sim_telarray as the reference. A convention shared by both (for example the
scatter definition, section 4) cannot show up. The comparison already found one
such convention (point-source distance measured from the dish vertex), which
shows the method works, but only for differences. Add reference cases whose
answer is known independently: a perfect parabola on axis (zero spot), the
Davies-Cotton coma and astigmatism formulas at small field angles, a
Schwarzschild-Couder design with a published spot diagram. Some of this exists
as “photons in analytic optics” in cpp/tests/test_trace.cpp; extend it to
quantitative aberration coefficients.
A2. The quoted D80 spread is realisation noise, not code difference. The
1.6 % D80 deviation for MST and 0.6 % for LST comes from each backend drawing
its own random mirror errors (python/obdeect/compiler.py:364, Python’s
random.Random seeded per facet). The documentation says so, but it also means
the comparison cannot detect a 0.5 % error. If sim_telarray’s realised mirror
tilts and focal lengths are exported and imported as explicit per-mirror data,
both codes trace the same telescope. Only the scatter draw and photon sampling
then differ, and with 10^7 photons the agreement should be limited by about
1e-4. This is the single most valuable precision upgrade of the validation.
A3. Not reproducible from the repository. docs/VALIDATION.md cites commit
hashes, a container (obdeect-val), scripts under val/ and a “validation
workspace (phase3)”, none of which are in the tree. AGENTS.md asks for
provenance on fixtures and cross-tool comparisons. Put the scripts and the
result tables in a versioned validation/ directory, or publish them as a
DOI-referenced data release (the Zenodo record already exists for the code),
and make the tables in VALIDATION.md generated from it.
A4. As-built effects missing. Already listed in limitations.md:
misalignment of dual-mirror segments and the secondary (SST, SCT), camera-window
refraction (focus shift, section 4), and structure shadowing for LST, SST and
SCT (only the MST has a telescope_structure table; others use the empirical
telescope_transmission). For absolute effective-area work on the LST,
shadowing by the real masts and camera frame is the largest of these. This is
where obdeect can become more accurate than its reference, as the MST structure
already does.
A5. Atmospheric-transmission workaround in the shower route. With bypassed
optics, sim_telarray derives the airmass from the camera-frame direction, so
the route rescales every photon weight by the ratio of two transmissions
(VALIDATION.md, “Air-shower photons”). Without it, 7 % (40 deg) and 33-39 %
(60 deg) too many photoelectrons. This is correct but fragile: a change in
sim_telarray’s formula or a flag change silently double-counts. Add a regression
test that fails when the product of the two transmissions deviates from the
native chain by more than 0.1 %, and push the sim_telarray option request.
A6. Wavelength quantisation. lambda = floor(exact) copies sim_telarray
(bunches.hpp, wavelength_law). It shifts the mean wavelength by about
0.5 nm. Keep it, but make it an explicit option (wavelength_quantisation="sim_telarray" | "none") so the physics-exact setting is available and the parity
setting is a named choice.
A7. Timing. propagation_group_index is a single scalar
(model.hpp:75); there is no wavelength dependence and no transit time in
glass. The documented effect is 5-17 ps for 3-10 mm windows, so this is fine
for current needs. It matters only if sub-100 ps pulse shapes become a
requirement.
4. Optics expert#
4.1 What is strong#
Double precision throughout; sphere intersection uses the numerically safe form and rejects back faces explicitly (
surfaces.hpp:79-131).Aspheres evaluated in
r^2with Horner, a rigorous slope bound (slope_bound,surfaces.hpp:285) used to prove a single root, and work done near the vertex plane to avoid precision loss for sources 10^7 m away (surfaces.hpp:347).Grid acceleration structures are cross-checked against brute force in the tests, and ties are broken by lowest id so that acceleration never changes the answer.
Rounding-level changes are measured against a replay with explicit flip and difference limits (
VALIDATION.md, “Rounding-level changes”); the limits are not loosened to pass.
4.2 Findings#
O1. Scatter rotation axes are not orthonormal on curved facets [verified in
code and in the project’s own note]. reflect_at (trace.hpp:133-138) uses
the facet’s u as first rotation axis and e2 = cross(n, u) as second. On a
curved facet, u is the tangent at the vertex and is not perpendicular to the
hit normal n; VALIDATION.md records angles up to 1.9e-2 rad. rotate() is
Rodrigues’ formula, which requires unit axes, but |cross(n, u)| = cos(angle)
is less than 1 (relative error about 2e-4 at the worst facets), and the two
axes are not perpendicular. The effect on the scatter width is about 1e-4
relative to sigma, below the validation noise, which is why it was left alone
(“This property is not changed by the round”). Fix: Gram-Schmidt u against
n before use, which costs one dot product. It changes results at that
level, so run it through the existing replay gate and note it in the changelog.
O2. surface_slopes scatter is parity, not physics [to check]. For
aspheric surfaces the code perturbs the graph slopes by half the angle
(trace.hpp:127-132). Slope space is not angle space: a slope change ds
changes the normal angle by ds * cos^2(theta) radially and ds * cos(theta)
tangentially, so on a surface tilted by 40 deg (SCT secondary) the effective
reflected-ray width is about 0.6 radially and 0.77 tangentially of the nominal
value. If the SCT/SST scatter parameters were fitted with this convention it
may be self-consistent, but then the parameter’s meaning is “sim_telarray
class-2 convention”, not “RMS reflected-ray angle”, and the documentation
should say so. If it was only matched to sim_telarray, measure the PSF
anisotropy before relying on it for anything but parity.
O3. Root selection when the single-root proof does not hold
(surfaces.hpp:456-509) [to check]. In the monotone case (single_root)
the first accepted Newton root is the only root. Otherwise the code returns the
first accepted root from the first guess that converges, which need not be the
nearest, and the 64-sample bracketing fallback can miss a double root or a
grazing pair. A non-converging Newton iteration also falls through silently
to the fallback and, if that finds nothing, to a “miss”; numerical_failure is
reserved for non-finite residuals. Impact is limited to steep rays on strongly
curved secondaries, but a miss is silent. Add a property test that compares
against a dense bracketing search for random rays on the real SST and SCT
primaries and secondaries, including rays at the largest field angle, and
count how often the non-monotone branch is taken.
O4. Absolute tolerances. kMinDistanceM = 1e-9 m rejects self-hits;
kTolerance = 1e-10 m is the Newton residual; verdict margins are 1e-9 m.
All are far above double rounding for telescope-sized coordinates, but they are
absolute. A model in other units or a very large dish would need them scaled.
Collect them in one documented header with the reasoning (section 7, M5).
O5. Not traced, by design. Refraction (camera windows, lenses, Winston
cones) and polarisation (Fresnel s/p split at the 16-50 deg incidence angles
of the focal plane; the reflectivity table depends on angle but is
unpolarised). Reported focal_incidence_deg lets the downstream camera
simulation apply cone acceptance. This is a sound boundary; the risk is the
documented one: focus_offset may already contain the window shift, so adding
the window to the trace could count it twice. The audit of each telescope’s
focus_offset origin that limitations.md demands should be tracked as an
issue.
O6. Scatter statistics. Two independent Gaussians per hit, uncorrelated
between photons, the same everywhere on the mirror. Real mirrors have spatially
correlated slope errors and a wide scattering halo. For D80 and image
parameters this is fine; for the far PSF tails (D95 and beyond, NSB-like
stray light) it is a model limit worth one sentence in limitations.md.
O7. Facet geometry. Facet::intersect rejects early with a plane test
whose bound is reach + sag*sqrt(1-dn^2)/|dn|; correct and tested. The grid
visits all facets for |dz| < 0.05 and uses the bounding box of the segment
from the lowest to the highest facet height otherwise
(surfaces.hpp:199-218). For the telescope fields of view this is efficient;
for a very wide-field design the box grows and cost approaches brute force.
Not a defect, but state the assumption.
5. HPC expert#
5.1 Measured [verified]#
Apple M-series, 12 logical cores, Release build, 4 million star photons, best of
three, outputs=["status"], small synthetic telescopes from
python/tests/telescopes.py (not LST-sized):
Model |
1 thread |
2 |
4 |
8 |
|---|---|---|---|---|
single-mirror (ns/photon) |
104 |
53 |
27 |
17 |
dual-mirror (ns/photon) |
260 |
131 |
67 |
42 |
Scaling is linear up to 4 threads and 6.2x at 8 (the host mixes performance and efficiency cores). Pool and chunking work as intended.
All 14 columns versus detected_only=True, 8 threads, same photons:
Model |
all rows |
|
|---|---|---|
single-mirror |
26 ns/photon |
34 ns/photon |
dual-mirror |
47 ns/photon |
52 ns/photon |
detected_only costs 10-30 % more than writing everything (see H1). The
documented per-core numbers (LSTN-01 0.26 us/photon, SSTS-17 0.50 us/photon)
are on larger real models and I did not repeat them.
5.2 What is strong#
No allocation, I/O or virtual dispatch in the per-photon path; outputs are allocated once, first touched by the worker threads.
Counter-based RNG: determinism is by construction, not by scheduling.
Dynamic chunk scheduling (4096 photons) copes with the very different cost of photons;
ThreadPoolis owned by the caller, no global state, exceptions propagate (trace.hpp:382-401).GIL released around every long call in the bindings.
5.3 Findings#
H1. Serial compaction in detected_only [verified by measurement,
trace.hpp:478-554]. After the parallel trace, compact_chunks runs on the
calling thread, calling memmove for every chunk and every one of up to 15
columns. It is bandwidth-bound but single-threaded. Options: compact the
columns in parallel (columns are independent); or have each chunk write its
rows into a per-chunk scratch and copy once to the final offset after a prefix
sum (the same pattern trace_bunches already uses); or skip compaction when
the detected fraction exceeds a threshold and return a mask. Expected gain: the
whole 8-34 ns penalty.
H2. Compiler flags on Linux wheels [to check]. -ffp-contract=off is set
for determinism (good), but no -fno-math-errno. GCC on Linux sets errno for
sqrt, log, acos; the compiler then keeps a branch and a libm call after
each sqrtsd. The tracer calls sqrt in almost every step. -fno-math-errno
and -fno-trapping-math do not change results (they remove errno and
exception side effects, not rounding), so determinism is preserved. macOS
libm does not set errno, which is why a local macOS benchmark would not show
it. Measure with bench_trace on the manylinux build before and after. Wheels
come from GCC, so this affects what most users run.
H3. Bunch path repeats work (bunches.hpp) [verified by reading]. For a
bunch of wavelength 0, Philox is evaluated for the wavelength in the thinning
pass and again in the tracing pass; the rows_max pass walks the input a third
time only to validate and count. keep_flags is one byte per candidate photon
and roulette_draws is a std::vector<double> per chunk grown by
push_back in the worker. Because the generator is counter-based, the
roulette draw and the wavelength can be recomputed (one Philox, tens of
ns) instead of stored, removing 8 B per survivor and the per-chunk heap
growth. Measure first; a Philox call is a few percent of a trace.
H4. Thread count default [to check]. thread_count(0) is
std::thread::hardware_concurrency() (core.cpp:47). In containers, cgroup-
limited CI and batch jobs with CPU affinity this can exceed the allotted cores
and oversubscribe. In the Python layer use os.process_cpu_count() (Python
=3.13, respects affinity) as default, and honour an
OBDEECT_NUM_THREADSenvironment variable for cluster users.
H5. Two parallel_for implementations. One spawns std::threads on every
call (trace.hpp:324, used by photon_arrays in the bindings) and one uses
the pool. Both are tested, but thread creation per call is a latent cost for
small blocks. Prefer the pool everywhere and delete the spawning version, or
document why both exist.
H6. Scalar per-photon pipeline. Each photon runs the full chain in a
branchy, scalar function that returns a ~200-byte TraceResult. SIMD across
photons would help the facet-sphere test and the focal-plane step, but the
asphere Newton iteration and the obscurer traversal diverge, and the
standard-library-only rule excludes std::experimental::simd and intrinsics.
Treat this as an experiment after H1-H3: a stage-wise “wavefront” over a block
of 8-16 photons with #pragma omp simd on the facet loop, kept bit-identical by
-ffp-contract=off. I would not start here; the cheap items above are worth
more.
H7. No performance guard in CI. The benchmark tools are built only
manually (OBDEECT_BUILD_BENCH=OFF), and wall-clock benchmarks on shared
runners are noise. The project already has the right idea in
test_asphere_steps (counts of Newton steps with OBDEECT_BENCH_COUNTERS).
Extend to deterministic work counters per real model: Newton steps per photon,
obscurer node visits and exact tests, segment contains calls. Fail the test
if a counter rises by more than 2 %. These are exact on any machine.
H8. Memory scale. The default output has 14 columns, about 130 bytes per
photon; 10^9 photons would need 130 GB. trace_many, trace_emitter_blocks
and outputs= exist; make streaming blocks the documented default for large
runs and add a guard that warns above a configurable output size.
H9. Release flags. CMake Release gives -O3 -DNDEBUG. LTO is
irrelevant for a header-only core in one translation unit. PGO could give 5-10 %
on the wheel but complicates the build; skip unless the cheap items fall short.
-march=native is correctly excluded from wheels.
6. Release manager#
6.1 What is strong#
towncrier fragments, enforced by a workflow and a pre-commit check; changelog in Keep-a-Changelog form.
PyPI trusted publishing (OIDC), TestPyPI by manual dispatch, wheel smoke test with the full pytest suite inside cibuildwheel.
Versioned documentation site that keeps
devand release pages together; PR builds only builddev.CI concurrency groups cancel superseded runs; sanitizer and FMA jobs exist.
Version derived from git tags (setuptools-scm).
6.2 Findings#
R1. Four different version numbers [verified].
Place |
Value |
|---|---|
git tag / |
v0.7.2 |
|
|
|
|
|
|
A user citing from CITATION.cff cites a version that does not exist. Use
SKBUILD_PROJECT_VERSION for the CMake project version (or drop it), update
CITATION.cff as a step of the release (a small script run in the release
branch, or let the Zenodo integration own the metadata), and make the two
Python fallbacks one constant that fails loudly in CI.
R2. Release process is manual and visibly rushed. v0.7.0 and v0.7.1 were
released on 2026-11-04 and v0.7.2 on 2026-11-06, with “-rc” branches. A
release.yml would remove the guesswork: on a v* tag check that the
changelog has an entry for the tag, build and test wheels, publish to TestPyPI
automatically for -rc tags, publish to PyPI for final tags, and create the
GitHub Release from the changelog section. Add a documented release checklist
to docs/ or AGENTS.md.
R3. Platform matrix does not match the claims. AGENTS.md says
“portable”. CMake has MSVC branches (/W4 /WX), but nothing builds on
Windows. MACOSX_DEPLOYMENT_TARGET = 13.3 is set, but the only macOS runner
(macos-15) is arm64, so no Intel wheel exists. No free-threaded
(cp314t) wheel, although the GIL is already released around all long calls.
The sanitizer job and the FMA job run on one OS only. Either add Windows
(MSVC), Linux/Clang and a minimum-compiler job (the oldest GCC and Clang that
the C++20 code needs), or write the supported platforms into the docs and
classifiers. Also consider nanobind’s stable-ABI mode: with
requires-python >= 3.14 one abi3 wheel per platform would replace the
cp314 and cp315 pair and cover future versions, at a small speed cost to
measure.
R4. Test CI does the build twice and has no cache. tests.yml runs
pip install ".[plot]" (a full wheel build), then configures and builds
the C++ tree again with CMake, for six matrix cells. Add ccache (or
actions/cache on the build directory), or build once and reuse. Python 3.15
is final as of this writing, so allow-prereleases: true can go.
R5. Missing CI gates.
Gap |
Why it matters |
|---|---|
ThreadSanitizer job |
|
Sanitizer run of the Python tests |
Bindings own raw buffers via capsules ( |
|
|
Coverage report |
Cannot see untested branches ( |
Type checking and |
The Python layer is annotated but never checked |
Docs link check |
The README dead links below would be caught |
Fuzzing of |
Parser of user-supplied files |
Linux/Clang, MSVC, minimum compiler |
Only GCC (Linux) and AppleClang (macOS) are exercised |
R6. Supply chain. changelog.yml pins actions/checkout by commit SHA;
every other workflow uses floating major tags (@v7, @v8) and
pypa/gh-action-pypi-publish@release/v1. There is no Dependabot or Renovate
configuration, and .pre-commit-config.yaml pins ruff-pre-commit at v0.12.7
while pyproject.toml enables preview = true and targets py314, so hook and
local ruff versions can drift. Pin all Actions by SHA (keep the tag in a
comment, as changelog.yml does), add .github/dependabot.yml for
github-ecosystem and pip, and run pre-commit autoupdate through
pre-commit.ci or a scheduled job. The publish job is the one place where a
compromised action matters most.
R7. Packaging metadata.
Development Status :: 2 - Pre-Alphawhile a production-grade validation exists;3 - Alphaor4 - Betais the honest classifier.license = { file = "LICENSE" }is the legacy table form; PEP 639 preferslicense = "BSD-3-Clause"withlicense-files.No
[project.urls](Homepage, Documentation, Issues, Changelog): the PyPI page has no links.The sdist includes
cpp/**with tests, benchmarks and fixtures; fine for reproducibility, butdocs/,CITATION.cffandCHANGELOG.mdare absent.No
py.typed, noTyping :: Typed.
R8. CMake as a library. No install() or exported target, no
obdeect::core alias, OBDEECT_BUILD_TESTING defaults to ON even when
obdeect is a subproject (use PROJECT_IS_TOP_LEVEL), and
find_package(Python 3.14 ...) hard-codes the version. Standard-library-only
C++ is a selling point for embedding (for example in a CORSIKA or
sim_telarray reader); give it a three-line find_package story.
R9. README links are dead [verified]. README.md:14 links to
docs/USER_GUIDE.md and docs/PHYSICS.md; the files are docs/user-guide.md
and docs/optics.md. As instructed, I did not touch README.md. Suggested
change:
See the [user guide](docs/user-guide.md), the [physics](docs/optics.md) of the
photon path, and the [validation](docs/VALIDATION.md) against sim_telarray.
Also unify the file naming in docs/ (VALIDATION.md upper-case, all others
lower-case) so that links survive case-sensitive file systems.
7. Maintainability and documentation#
7.1 What is strong#
Comments explain reasoning and bounds (for example the plane pre-test and the segment verdict proof) rather than restating code.
Tests follow the stated order: analytic kernels (162 checks in
test_kernels.cpp), then traced analytic optics, then models, then cross-tool; sanitizer-clean in CI.The project documents rejected experiments (Estrin evaluation, transmission table, closed-form scatter) with numbers. This saves future maintainers days.
AGENTS.mdis specific and enforceable.
7.2 Findings#
M1. trace_photon has 12 parameters, four of them adjacent bools
(trace.hpp:175-179). apply_responses, direct, incidence_angles, classify_losses can be swapped without a compiler diagnostic, and
BlockTask and BlockRequest repeat the same flags. A
struct TraceOptions { bool apply_responses = true; ... } passed by value
costs nothing in the hot path (it inlines) and gives names at call sites. Do it
before adding the next flag.
M2. Large mixed-purpose headers. surfaces.hpp (931 lines) holds apertures,
facets, the facet grid, aspheres, segments and the segment grid;
trace.hpp (666) holds the physics, the thread pool and block I/O;
obscurers.hpp (763) holds primitives and the bounding hierarchy. Split into
aperture.hpp, facets.hpp, asphere.hpp, segments.hpp, parallel.hpp,
keeping trace.hpp as the physics. This is mechanical, helps review diffs, and
the build is fast enough (2.7 s) that compile time is not a reason to wait.
M3. Repeated literals. 6.283185307179586476925 appears in at least five
places, 0.86602540378443864676 in three, and kDegree is local to
trace.hpp. Put kTwoPi, kPi, kSqrt3Over2, kDegree in vec.hpp or a
constants.hpp.
M4. Numeric thresholds are scattered. 1e-6 (unit direction), 1e-9,
1e-10, 1e-12, 0.05 (grid dz), 0.5 (kGridMinDz), 4096 (chunk), 64
(samples, depth). Gather the ones that carry physical or proof meaning in one
header with a sentence each, and add a test that perturbs each by a factor of
10 and verifies the results are unchanged (or that the change is flagged).
M5. JSON number parsing is locale-dependent [verified in code,
json.hpp:144]. std::strtod honours LC_NUMERIC. The grammar check before
it accepts only . as separator, but under a process locale such as de_DE
strtod("1.5") parses 1 and stops. Python does not set LC_NUMERIC, but
GUI toolkits, some C extensions and embedding hosts do, and the user base is
European. Use std::from_chars (GCC 11+, MSVC 2019+; AppleClang from Xcode 16
supports double; check the minimum), or parse integer and fractional parts
with exact scaling. A two-line test with setlocale(LC_NUMERIC, "de_DE.UTF-8")
guards it.
M6. Fixtures are synthetic only. The Python tests use a small single-mirror
and an SST-like dual-mirror telescope; the native tests use analytic cases.
Real models (LST, MST with 203 structure elements, SST, SCT) exist only in
external simulation-models checkouts, so bench_trace and replay cannot be
run from a clean clone. Add compiled optical models (the format is stable
obdeect.optical-model.v2, hash-addressed) as release assets or a small data
package with provenance, then run replay against stored statistics in CI.
M7. Documentation structure. The docs set is complete (installation, user
and Python guides, optics, models, shadowing, light sources, batch tracing,
air-shower photons, limitations, validation). Improvements: a single page
“supported parameters of the simulation models and what obdeect does with each”
(accepted, ignored, rejected), because the design rule says never silently
discard fields and users will ask; a generated C++ API reference (Doxygen or
a hand-kept header map); and VALIDATION.md split into a stable method page and
a dated results page so that old commit hashes do not read as current.
M8. Small items.
ctestregisters one test per executable, so a failure intest_kernelsis one red line for 162 checks; registering sections withadd_testfilters (or using doctest/Catch2 only undertests/) would make failures local. Optional; the customcheck.hppis a fair choice for a no-dependency core.The
OBDEECT_BENCH_COUNTERSmacro and static counter singletons are fine for single-thread tests, but make the dependence explicit in the type (CountedAsphere) if they spread.numerical_failureis documented as “did not converge” but, as noted in O3, only fires on non-finite values. Align name and behaviour.
8. Suggested order of work#
Week 1 (hygiene, low risk, no change in results).
R1 (versions), R9 (README links, applied by the owner), R6 (Dependabot, SHA
pins), R4 (cache, drop prereleases), R5 first row (TSan job), M5 (locale test
and from_chars), the environment note in section 2.
Week 2-3 (performance without changing results). H1 (parallel compaction), H2 (flags, measured on the manylinux build), H3 (bunch pass cleanup), H4 (thread default), H7 (deterministic work counters), M1 (options struct).
Month 1-2 (accuracy and trust). A2 with A3 (shared mirror realisations, reproducible validation), O1 (scatter axes, with the replay gate), O3 (root-selection property test), A1 (analytic aberration references), O2 (decide and document the slope convention).
Later, only if needed. Windows and Intel-macOS wheels, stable-ABI wheels, free-threaded wheels, LST structure shadowing, SIMD wavefront experiment (H6), PGO.
9. Open questions for the maintainers#
Is
surface_slopesmeant to be the physical RMS reflected-ray angle, or the sim_telarray class-2 convention? (O2)Can sim_telarray print or accept per-mirror tilts and focal lengths, so both codes trace one realisation? (A2)
Are Windows and Intel macOS supported targets, or is “portable” meant at source level only? (R3)
Where should the validation scripts and results live long term: this repository, a sibling repository, or a Zenodo data record? (A3)
What was the origin of each telescope’s
focus_offset, window included or not? (O5)Is the nearest-root guarantee required for the non-monotone aspheric case, or is “an accepted root” enough? (O3)