Skip to content

feat(python): add GUNTAM Python-callable seeding example#5551

Open
EliMe5 wants to merge 8 commits into
acts-project:mainfrom
EliMe5:custom-python-seeding-implementation
Open

feat(python): add GUNTAM Python-callable seeding example#5551
EliMe5 wants to merge 8 commits into
acts-project:mainfrom
EliMe5:custom-python-seeding-implementation

Conversation

@EliMe5

@EliMe5 EliMe5 commented Jun 5, 2026

Copy link
Copy Markdown
Contributor

feat(python): add GUNTAM Python-callable seeding example

Add a PythonCallable seeding mode that allows reconstruction seeding to be
provided by a Python function.

Expose the event-data bindings needed by Python seeders to construct seeds
from Python, including mutable space point proxies, mutable seed proxies,
seed-spacepoint container assignment, and tests for the ownership path.

Add a GUNTAM ONNX seeding example using the OpenDataDetector workflow. The
integration is implemented for GUNTAM, while the PythonCallable interface
and ONNX example structure are intended to support other externally provided
ONNX seeding models as well.

--- END COMMIT MESSAGE ---

This PR adds:

  • SeedingAlgorithm.PythonCallable support through the reconstruction helpers
  • mutable SpacePointContainer2 / MutableSpacePointProxy2 bindings
  • mutable SeedContainer2 / MutableSeedProxy2 bindings, including seed creation and space-point container assignment
  • IndexSourceLink constructor and makeSourceLink bindings in the examples module
  • tests for mutable event-data bindings and seed/space-point container ownership
  • a GUNTAM ONNX-based PythonCallable seeding example using the ODD workflow

Local validation:

  • rebased onto latest origin/main
  • pytest Python/Core/tests/test_event_data.py passed
  • py_compile passed on both example scripts
  • ran onnx_seeding.py with a GUNTAM model for 2 particle-gun events, single thread; full chain completed successfully through Fatras, digitization, seeding, CKF, ambiguity resolution, and vertex fitting

cc @benjaminhuth @Corentin-Allaire

@github-actions github-actions Bot added the Component - Examples Affects the Examples module label Jun 5, 2026
@github-actions github-actions Bot added this to the next milestone Jun 5, 2026
@github-actions

github-actions Bot commented Jun 5, 2026

Copy link
Copy Markdown
Contributor

📊: Physics performance monitoring for aa2dcac

Full contents

physmon summary

❗️: Downstream build failure

  • eic-shell EICrecon (cc @acts-project/epic-contacts)

@Corentin-Allaire Corentin-Allaire left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Here are a few comments on the PR. One thionk I am not 100% sure is if we want to push Examples/Scripts/Python/onnx_seeding.py as is to the repo ?

Comment thread Examples/Scripts/Python/guntam_transformer_seeder.py Outdated
Comment thread Examples/Scripts/Python/guntam_transformer_seeder.py Outdated
Comment thread Examples/Scripts/Python/guntam_transformer_seeder.py Outdated
Comment thread Python/Core/src/EventData.cpp
@EliMe5 EliMe5 force-pushed the custom-python-seeding-implementation branch 2 times, most recently from f6426a7 to 54aa262 Compare June 10, 2026 15:35
@andiwand andiwand marked this pull request as draft June 11, 2026 08:09
@andiwand

Copy link
Copy Markdown
Contributor

drafting for now until we have a conclusion on #5571 which takes load off the gitlab ci

@benjaminhuth

Copy link
Copy Markdown
Member

@EliMe5 Can we disentangle #5571 and this PR? i.e., one only introducing the necessary bindings with the current ownership model here, and then adding the guard features later in a PR?

@EliMe5

EliMe5 commented Jun 11, 2026

Copy link
Copy Markdown
Contributor Author

@EliMe5 Can we disentangle #5571 and this PR? i.e., one only introducing the necessary bindings with the current ownership model here, and then adding the guard features later in a PR?

@benjaminhuth I could try, but the code requires some of the guardrails (particularly the missing py::keep_alive I added), which would be hard to untangle with the other changes and bloat this pull request a bit.

EliMe5 added 8 commits June 23, 2026 10:03
- Add `SeedingAlgorithm.PythonCallable` configuration path.
- Introduce `customSeeder` and `customSeederConfig` parameters.
- Provide general interface for external/ML seeding functions.
- r_max, z_max, score_threshold, and providers are now config parameters
  with the previous hardcoded values as defaults (500 mm, 1000 mm, 0.35,
  CPUExecutionProvider).
- Remove z-degeneracy filter (_filter_degenerate_triplets / _Z_EPS): no
  longer needed after binding lifetime fixes removed the defensive crash-
  avoidance path.
- Move duplicate-index check into _filter_valid_seeds (sanity check, not
  a physics cut).
- Pre-allocate all seed proxies in one pass before filling to avoid
  repeated container growth inside the fill loop.
- GPU support: pass providers=["CUDAExecutionProvider", "CPUExecutionProvider"]
  to use GPU with CPU fallback.
…exing

Replace the per-seed Python loop over orig_idx with a single NumPy fancy
indexing operation (orig_idx[seeds_v], shape N×3), then call .tolist() per
row inside the fill loop.
SpacePointIndex2 = std::uint32_t; using int64 caused an implicit
sign/range coercion on every assignSpacePointIndices call.
Adds a transverse-separation degeneracy check to _filter_valid_seeds to
drop seeds where two spacepoints are numerically coincident in the xy plane
— these produce degenerate track parameters that crash the CKF at high
event counts. Also renames the internal 'hits' variable to 'filtered_sp_xyz'
to avoid confusion with Acts::SimHit (truth-level pre-digitization data).
@EliMe5 EliMe5 force-pushed the custom-python-seeding-implementation branch from 54aa262 to aa2dcac Compare June 23, 2026 08:39
@sonarqubecloud

Copy link
Copy Markdown

@EliMe5 EliMe5 marked this pull request as ready for review June 23, 2026 11:32

@benjaminhuth benjaminhuth left a comment

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Looks good! Only minor comment (maybe also a bit matter of taste): I think right now it onnx_seeding.py suggests some generality which it does not have, its really just running guntam. So maybe merging the two py files into one called guntam_transformer_seeder.py makes sense?
But not critical.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

Component - Examples Affects the Examples module

Projects

None yet

Development

Successfully merging this pull request may close these issues.

4 participants