Feature/globals

[francois-drielsma]

Summary

This PR introduces a new spine.constants package, migrates internal code away from spine.utils.globals, and fixes a full-chain HDF5 writer regression that could crash during truth-object serialization. It also updates the docs to expose the new constants module and cleans up several documentation issues.

Main changes

• Add spine.constants as the canonical home for:
  • tensor column conventions
  • categorical enums
  • label maps
  • physical constants
  • sentinel values
• Move enum parsing into spine.constants.factory
• Migrate internal imports from spine.utils.globals / spine.utils.enums to spine.constants
• Keep spine.utils.globals and spine.utils.enums as deprecated compatibility shims
• Update data-model enum handling so enum classes are the source of truth
• Add explicit neutrino interaction scheme support:
  • LArSoftNuInteractionType
  • GenieNuInteractionType
  • NuInteractionScheme
• Store source-native neutrino interaction codes while tagging the interpretation scheme explicitly
• Add Numba-friendly slice-bound constants while preserving tuple selectors for general code
• Fix full-chain HDF5 writer crashes by normalizing truth-path integer array dtypes before serialization
• Keep enum-backed scalar serialization aligned with other scalar ints (int64)

Validation

Validated in ghcr.io/deeplearnphysics/spine:latest with config/test_full_chain.yaml.

Full-chain stability

• Fixed the writer-backed full-chain crash on truth-object HDF5 serialization
• Clean-main baseline needed a minimal local dtype patch on the truth path to complete the same writer-backed run
• After that patch, both runs completed successfully

Output comparison

Compared current output against the minimally patched clean-main baseline.

Result:

• loss / accuracy: identical across all 3 iterations
• Exact HDF5 match for:
  • run_info
  • meta
  • points
  • points_label
  • depositions
  • depositions_label
  • reco_particles
  • truth_particles
  • reco_interactions
• Only intentional remaining difference:
  • truth_interactions.interaction_scheme added in current output

Important test-gap note

The regression fixed here was on the writer-backed full-chain path.

Existing CI passed because the current full-chain regression test removes io.writer and only checks deterministic loss/accuracy. It does not exercise end-to-end HDF5 output serialization.

Schema / compatibility notes

• Scalar enum-backed fields now serialize consistently with other scalar integer fields (int64)
• Variable-length integer ID/index arrays remain int32
• truth_interactions.interaction_scheme is a new stored field
• spine.utils.globals compatibility remains temporarily, but all internal code now uses spine.constants

Docs

Docs were updated to:

• add spine.constants to the API docs
• fix several existing documentation issues and navigation gaps

Follow-ups

• Add a writer-enabled full-chain regression test so CI covers HDF5 output creation directly
• Remove deprecated spine.utils.globals / spine.utils.enums compatibility once downstream users have migrated

[codecov]

Codecov Report

❌ Patch coverage is 87.32143% with 71 lines in your changes missing coverage. Please review.
✅ Project coverage is 44.98%. Comparing base (1c9a2ab) to head (baa9c37).
⚠️ Report is 6 commits behind head on main.

Files with missing lines	Patch %	Lines
src/spine/vis/out.py	0.00%	19 Missing ⚠️
src/spine/utils/gnn/cluster.py	28.57%	10 Missing ⚠️
src/spine/utils/gnn/network.py	11.11%	8 Missing ⚠️
src/spine/utils/energy_loss.py	16.66%	5 Missing ⚠️
src/spine/construct/manager.py	20.00%	4 Missing ⚠️
src/spine/math/graph.py	0.00%	4 Missing ⚠️
src/spine/utils/globals.py	0.00%	3 Missing ⚠️
src/spine/construct/particle.py	66.66%	2 Missing ⚠️
src/spine/data/larcv/neutrino.py	91.30%	2 Missing ⚠️
src/spine/model/singlep.py	0.00%	2 Missing ⚠️
... and 10 more

Additional details and impacted files

@@            Coverage Diff             @@
##             main     #126      +/-   ##
==========================================
+ Coverage   44.41%   44.98%   +0.56%     
==========================================
  Files         283      289       +6     
  Lines       21933    22194     +261     
==========================================
+ Hits         9742     9983     +241     
- Misses      12191    12211      +20     

Flag	Coverage Δ
unittests	44.98% <87.32%> (+0.56%)	⬆️

Flags with carried forward coverage won't be shown. Click here to find out more.

Files with missing lines	Coverage Δ
src/spine/ana/__init__.py	100.00% <ø> (ø)
src/spine/ana/calib/mcs.py	25.00% <100.00%> (ø)
src/spine/ana/diag/track.py	16.47% <100.00%> (ø)
src/spine/ana/metric/cluster.py	14.94% <100.00%> (ø)
src/spine/ana/metric/point.py	16.12% <100.00%> (ø)
src/spine/ana/metric/segment.py	12.16% <100.00%> (ø)
src/spine/config/meta.py	23.76% <ø> (ø)
src/spine/constants/__init__.py	100.00% <100.00%> (ø)
src/spine/constants/columns.py	100.00% <100.00%> (ø)
src/spine/constants/enums.py	100.00% <100.00%> (ø)
... and 91 more

🚀 New features to boost your workflow:

• ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.