File size: 2,576 Bytes
de46a3c 916755e d93a2db de46a3c 916755e de46a3c 916755e de46a3c 916755e de46a3c 916755e de46a3c 916755e de46a3c 916755e 8344837 916755e 8344837 916755e de46a3c 916755e 8344837 916755e de46a3c 916755e de46a3c | 1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 | # Migration and model-family roadmap
## Frozen ROOT-GNN baseline
The `root-gnn-parity-baseline` tag records the completed migration of the
active ROOT-GNN behavior into `src/gnn4colliders.models.root_gnn`. The
campaign covered full event preprocessing and graph parity, binary objectives
and metrics, deterministic fine-tuning, full-split training, checkpoint reload
and resume, reproducibility, and serialized graph-cache checks.
The historical implementation is no longer in the active source tree. Its
observable behavior is represented by committed fixtures, tests, and the
one-way checkpoint/metadata compatibility adapters. New work must not add
imports from historical implementation paths.
## Shared contracts
New model families should consume these boundaries:
- `EventSample` and named `EventMetadata` from `data`;
- shared collider feature builders from `features`;
- a representation-specific sample/batch type from the relevant adapter;
- task-owned loss, score, prediction, and metric semantics;
- the shared `Trainer`, checkpoint, reproducibility, and inference APIs.
The graph path is the current ROOT-GNN representation. A sequence or token
model should add a separate representation boundary rather than placing
sequence behavior in graph modules or generic data code.
## Transformer model-family milestone
The first `root_transformer` vertical slice is implemented with:
1. Define a small `SequenceSample` contract and deterministic fixture.
2. Implement token construction using shared event/features infrastructure.
3. Add the transformer model under `models/root_transformer/`.
4. Connect it to the existing binary task and trainer on a tiny fixture.
5. Add checkpoint, prediction, and reproducibility tests.
The first implementation is available as
`model=root_transformer/transformer`. It can train on an existing graph cache
by adapting node features into ordered sequence tokens; this is a migration
bridge while a native sequence cache and DDP sequence loader are evaluated.
Native sequence-cache storage and distributed sequence loading remain follow-up
work; do not generalize shared interfaces until those use cases require it.
## Validation requirements
Every new model family must provide unit tests for its representation and
model, a small end-to-end integration test, checkpoint reload coverage, and a
deterministic repeatability check. Scientific behavior that is intentionally
shared with ROOT-GNN should be compared against the frozen reference fixture;
architecture-specific behavior should have its own reference outputs.
|