File size: 5,160 Bytes
916755e c20af2a e74a91a 916755e 5ae003d 916755e | 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 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 79 80 81 82 83 84 85 86 87 88 89 90 91 92 93 94 95 96 97 98 99 100 101 102 103 104 105 106 107 108 109 110 111 112 113 114 115 116 117 118 119 120 121 122 123 124 125 126 127 128 129 130 131 132 133 134 | # Configuration guide
The CLI composes the installed `gnn4colliders.configs/config.yaml` with semantic
Hydra groups. A config
describes experiment intent; it does not contain arbitrary Python module or
class import paths.
## Groups
| Group | Purpose |
| --- | --- |
| `data` | ROOT source or graph-cache path, batch settings, and fold splits |
| `model` | Model family and supported ROOT-GNN constructor settings |
| `task` | Binary or multiclass loss, score, and metric semantics |
| `trainer` | Device, seed, epochs, optimizer, scheduler, and early stopping |
| `checkpoint` | Output directory, resume checkpoint, or pretrained checkpoint |
| `inference` | Checkpoint, split, output path, and output format |
| `environment` | Device and experiment output root |
| `distributed` | Single-process/DDP selection and process-group backend |
The active model groups are `root_gnn/edge_network` and
`root_gnn/fine_tuned_edge_network`. The active task groups are
`pretraining_multiclass`, `binary_classification`, and `tth_cp_finetune`.
## Preparation
`prepare` requires `data.files`, `data.cache.path`, `data.feature_branches`,
`data.object_types`, and `data.scales`. `feature_branches` follows the shared
seven-column feature contract: one branch/constant specification per output
column and one entry per configured object type. `CALC_E` and `NODE_TYPE` are
reserved derived specifications. `object_types` entries are `vector` or
`single`. Preparation reads the configured tree in file order and writes a
versioned `GraphSampleCache`.
Example overrides are easiest to maintain in a YAML file for real datasets:
```yaml
# project-local example: data/my_events.yaml
files: [data/events.root]
tree_name: Events
cache:
path: cache/events.pt
feature_branches:
- [jet_pt]
- [jet_eta]
- [jet_phi]
- CALC_E
- [1.0]
- [0.0]
- NODE_TYPE
object_types: [vector]
scales: [1, 1, 1, 1, 1, 1, 1]
fold_var: eventNumber
weight_var: weight
```
Then compose it with `data=my_events`. The cache stores processed graph
samples, labels, globals, named metadata, and feature/graph/cache schema
versions. Changing the feature or graph schema requires a new compatible cache;
loading a mismatched schema raises an error.
## Common overrides
```bash
uv run gnn4colliders train \
data.cache.path=cache/events.pt \
data.batch_size=64 \
trainer.max_epochs=50 \
trainer.seed=123 \
environment.output_root=outputs/my_run
```
`data.batch_size` is per process. `data.splits.train_folds`,
`validation_folds`, and `test_folds` define conventional train/validation/test
selection and must be disjoint. Model/task mismatches are rejected during
config validation; binary tasks require `model.out_size=1`, while multiclass
tasks require `model.out_size=task.num_classes`.
## Hugging Face ROOT data
Training preparation can resolve ROOT files directly from a pinned Hugging Face
dataset. Use `data.source` instead of local `data.files`:
```yaml
source:
type: huggingface
repo_id: HWresearch/Delphes
repo_type: dataset
revision: 76a6c362bfba8e766ba7255a5c08a55257f78d0e
files:
- path: testing/ttH_NLO_64.root
label: 0
sha256: 89d69eae9cd4d28a5d414d77bbc07185ea5b7de03481fdafe28899e2f3a09dec
size_bytes: 15050
```
The resolver uses the Hugging Face cache, downloads only configured files, and
verifies optional size and SHA-256 metadata before ROOT ingestion. Ready-to-use
configurations are `config_hf_smoke` for the 64-event fixture and
`config_hf_delphes` for the pinned 12-process pretraining sources:
```bash
uv run gnn4colliders prepare --config-name config_hf_smoke
uv run gnn4colliders prepare --config-name config_hf_delphes
```
The full Delphes configuration may download a large dataset. It is never used
by the default configuration and is cached by the Hub client for later runs.
`data.num_workers` controls local process parallelism during `prepare`. The
default is `0` (single-process). Positive values split the ordered event range
into independent temporary graph-cache shards and merge them deterministically;
workers do not write the final cache concurrently. This setting does not launch
distributed preparation and should be benchmarked on the target machine.
## Checkpoints and resolved configuration
Training writes `epoch_####.pt` and the fully resolved configuration at
`<environment.output_root>/resolved_config.yaml`. A checkpoint includes schema
version, model weights/config, task config, trainer/optimizer/scheduler state,
early stopping state, metadata, and optional RNG state. Set
`checkpoint.resume=/path/to/epoch_####.pt` to continue a run. Set
`checkpoint.pretrained=/path/to/epoch_####.pt` with the fine-tuned model group
to load weights into a new task head; these options are mutually exclusive.
## Environment profiles
`environment=local` selects CPU by default. `environment=macos` selects the
Apple MPS device for the portable PyTorch ROOT-GNN backend.
`environment=perlmutter` selects
the CUDA device and a conventional output-root pattern. Profiles should hold
device/output policy only; site-specific module loads and filesystem paths
belong in a launcher or shell environment.
|