69 photon recon improvements

[along4]

This pull request introduces a major refactor of the photon reconstruction and clustering configuration models and their usage across the codebase, aligning naming conventions, improving clarity, and supporting more flexible clustering settings. The changes affect both the YAML configuration files and Python code, and include updates to error handling, model validation, and the internal structure of clustering configuration.

Key changes:

1. Model and Type Renaming and Refactoring

• Replaces all references to Tpx3PhotonReconstructionConfiguration, Tpx3PhotonClusteringSettings, and related types with new HermesTpx3PhotonReconstructionConfiguration, HermesTpx3PhotonClustering, and HermesTpx3PhotonClusteringSettings models, updating field names and structure for clarity and extensibility. This includes renaming result and summary types to HermesTpx3PhotonReconstructionResult and HermesTpx3PhotonReconstructionSummary. [1] [2] [3] [4] [5] [6] [7] [8] [9] [10] [11]

2. Clustering Algorithm Configuration Overhaul

• The clustering_algorithm field is now an object (HermesTpx3PhotonClustering) with name, save_photon_pixels, and settings subfields, instead of a flat string or simple settings dict. The YAML configuration files are updated accordingly, and logic is added to correctly serialize and pass these settings to the clusterer binary. [1] [2] [3] [4] [5]

3. Field and Parameter Renaming

• Changes field names such as pixel_parquet_files to pixel_files throughout the codebase and configuration files for consistency. [1] [2] [3] [4]

4. Error Handling and Exception Renaming

• Refactors exception classes related to photon reconstruction to use the HermesPhotonReconstructionError naming pattern, clarifying their association and improving error reporting. [1] [2] [3] [4] [5]

5. Documentation and Example Updates

• Updates documentation and example scripts to use the new configuration models and field names, ensuring consistency and correctness in usage examples and README files. [1] [2] [3]

These changes modernize and clarify the photon reconstruction configuration, making it easier to extend and maintain in the future.

[Copilot]

Pull request overview

This PR refactors the TPX3/SPIDR photon reconstruction configuration and results models to use new Hermes*-prefixed types and a structured clustering configuration object, and updates runners/tests/examples/docs accordingly.

Changes:

• Renames/refactors reconstruction and clustering models (including moving save_photon_pixels under a new HermesTpx3PhotonClustering wrapper).
• Updates photon reconstruction runner logic to serialize the new clustering config shape for the clusterer binary.
• Updates workflow dispatch behavior and broad test/example YAML usage to match the new schema.

Reviewed changes

Copilot reviewed 18 out of 18 changed files in this pull request and generated 2 comments.

Show a summary per file

File	Description
tests/unit/hermes/workflows/test_workflow.py	Adds coverage for Workflow.run() dispatch and empty-record rejection; adjusts unimplemented acquisition test.
tests/unit/hermes/state/models/test_hermes_tpx3_spidr.py	Updates state-model tests to new HermesTpx3* names and new clustering wrapper shape.
tests/unit/hermes/runner/analysis/hermes/test_timewalk_calibration.py	Renames clustering settings type in calibration tests.
tests/unit/hermes/runner/analysis/hermes/test_photon_reconstruction.py	Updates photon reconstruction tests for new exception names and clustering config wrapper.
tests/unit/hermes/runner/analysis/hermes/test_event_reconstruction.py	Updates event reconstruction tests for new HermesTpx3* model names and new photon clustering wrapper.
tests/unit/examples/analysis/test_two_stage.py	Updates example tests and YAML snippet to new config shape and renamed result/count models.
tests/unit/examples/analysis/test_timewalk_calibration_example.py	Updates example test to renamed clustering settings model.
src/hermes/workflows/workflow.py	Implements Workflow.run() dispatch behavior and return value.
src/hermes/state/models/analysis/hermes_tpx3_spidr.py	Introduces HermesTpx3PhotonClustering wrapper and renames/refactors reconstruction, settings, summaries, and results models.
src/hermes/runner/analysis/hermes/timewalk_calibration.py	Updates calibration code to renamed clustering settings model.
src/hermes/runner/analysis/hermes/run.py	Updates runner to renamed photon reconstruction error/result types.
src/hermes/runner/analysis/hermes/photon_reconstruction.py	Updates reconstruction execution to use clustering wrapper and renamed error/result/summary types.
src/hermes/runner/analysis/hermes/event_reconstruction.py	Updates event reconstruction types to renamed models.
examples/analysis/two_stage/two_stage_config.yaml	Updates example config to new pixel_files + structured clustering_algorithm object.
examples/analysis/timewalk_calibration/run_timewalk_calibration.py	Updates example script to renamed clustering settings model.
examples/analysis/timewalk_calibration/README.md	Updates documentation references for the renamed clustering settings model.
examples/analysis/end_to_end/raw-to-events.yaml	Updates end-to-end example YAML to new clustering configuration structure.
docs/architecture/state-model.md	Updates architecture doc naming, but still contains mismatches vs the actual implemented model names/fields.

Suppressed comments (2)

docs/architecture/state-model.md:641

• This documented reconstruction model block uses type names (HermesTpx3PhotonReconstructionConfiguration, PhotonReconstructorProgram) that do not exist in the code; the runtime model is HermesTpx3PhotonReconstruction with a BinaryProgram. Consider aligning these names with src/hermes/state/models/analysis/hermes_tpx3_spidr.py so the architecture doc matches the actual configuration schema.

HermesTpx3PhotonReconstructionConfiguration
  program: PhotonReconstructorProgram
  pixel_files: auto | list[FileReference]
  clustering_algorithm: HermesTpx3PhotonClustering

docs/architecture/state-model.md:676

• The documented fields for HermesTpx3PhotonReconstructionResult (photon_count/rejected_count/warnings/errors) do not match the actual model, which stores input_file/output_file/status and optional counts. Update this section so it reflects src/hermes/state/models/analysis/hermes_tpx3_spidr.py and the runner’s usage.

HermesTpx3PhotonReconstructionResult
  status: completed | skipped | failed
  photon_count: int
  rejected_count: int

---

💡 Add a code-review agent skill or configure MCP servers for context-aware, tailored reviews. Learn more in the docs.