Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
33 commits
Select commit Hold shift + click to select a range
dc98d45
trid readme
Oct 8, 2026
13ffeb2
clarify features list
Oct 8, 2026
430a042
clarify features list
Oct 8, 2026
b984343
clarify features list
Oct 8, 2026
025a585
clarify features list
Oct 8, 2026
76bf2fe
update features list
Oct 8, 2026
6170be1
update features list
Oct 8, 2026
e8da7f1
define skipped features
Oct 8, 2026
0e781c1
add option to read columns for just selection and not training
Oct 8, 2026
014d3d6
add early stop
Oct 21, 2026
69bb2cf
update documentation with njets change
Oct 21, 2026
9c1bba5
update input config file structure
Oct 21, 2026
ebae23f
update input config file structure
Oct 21, 2026
0365908
add dynamic njets option
Oct 21, 2026
6dfd2cd
add early stopping function
Oct 21, 2026
d6f1a4f
update validation function with new changes
Oct 21, 2026
cd79743
update tests for new config structure
Oct 21, 2026
fcfcd93
add fold as configurable parameter
Oct 21, 2026
c260de0
update dataset documentation
Oct 21, 2026
5c327ed
make training recipe configurable
Oct 21, 2026
e12d9b3
update training recipe rules
Oct 21, 2026
dc1b339
make evaluation consistent with user specified n_folds
Oct 21, 2026
6c26ea3
add support for dynamic number of folds
Oct 21, 2026
421eaeb
update features list
Oct 21, 2026
f175488
make n_jets dynamic input
Oct 21, 2026
8ba6b85
make training recipe configurable
Oct 21, 2026
05ccf86
update validation for dynamic training recipe
Oct 21, 2026
cea1b7d
update tests with checkpoint support
Oct 21, 2026
27d3204
update readme
Oct 22, 2026
68b1529
update new fold setup
Oct 22, 2026
a917c24
create fold with hash rule
Oct 22, 2026
b5dad13
update new fold creation rule
Oct 22, 2026
6744a67
update fold rule
Oct 22, 2026
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
118 changes: 82 additions & 36 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -72,7 +72,7 @@ The decay chain of the HH → bb̄bb̄ example is

```yaml
objects:
jets: {features: [pt, eta, phi, mass, btag], max: 12} # INPUTS/Source (alias of "jets") in the H5 file
jets: {features: [pt, eta, phi, mass], max: 12} # INPUTS/Source (alias of "jets") in the H5 file
b: jets btag 4 # the 4 highest-btag jets
other: jets rest 8 # up to 8 remaining jets
event: [nSelJets, HT] # computed from the jet collection
Expand All @@ -88,43 +88,69 @@ outputs:
combine: [HH]
```

`jets` is the jet collection, with up to 12 jets per event; the listed `features` are the columns to
read from the input file. `btag` is only used to pick which jets are treated as b-jet candidates
(`b: jets btag 4`, the four jets most likely to be b jets); it is not an input to the network. The
file holds all jets of the event, and the b jets are chosen when it is loaded, so one file serves any
way of choosing them. [docs/EventInfo.md](docs/EventInfo.md) explains every
line of such a file and [docs/Dataset.md](docs/Dataset.md) the input file.
`jets` is the jet collection: `max: 12` is the number of jet slots read per event, and the input file must
have at least that many. The listed `features` are the inputs of the network: these columns of the input
file, and only these, are fed to it. \
`jets btag 4` selects the four jets with the highest `btag` (alternatively `jets pt 4` would select the four
leading jets): any column of the jets in the file can be used this way, and `jets mass 2 lowest` would take the
two jets with the lowest value instead. The selector reads its column from the file for this selection only; it
need not be a feature, and a feature named `btag` would be one more network input. The input
file holds all jets of the event, and the b jets are chosen when it is loaded. For more details on specifying the event decay, check [docs/EventInfo.md](docs/EventInfo.md), and for the input file itself, check [docs/Dataset.md](docs/Dataset.md).

The full-statistics files (454,261 HH → bb̄bb̄ events, 292,285 HH → bb̄WW events) are distributed
separately ([DOI / URL to be added]); download them into `examples/data/` as `hh4b_all.h5` and
`bbww_all.h5`.

## Usage

Three steps: describe the final state ([docs/EventInfo.md](docs/EventInfo.md)), prepare the input
file ([docs/Dataset.md](docs/Dataset.md)), and choose the settings ([docs/Options.md](docs/Options.md)).
Then check the two files against each other:
1. Describe the final state in a configuration file ([docs/EventInfo.md](docs/EventInfo.md)).
2. Prepare the input file ([docs/Dataset.md](docs/Dataset.md)).
3. Choose the network and training settings ([docs/Options.md](docs/Options.md)).
4. Before training, check that the configuration and the input file are correct and consistent with each other:

```bash
corenet-validate --config my_config.yaml --input my_data.h5
```
```bash
corenet-validate --config my_config.yaml --input my_data.h5
```

checks the event description against the input file; `--json report.json` also writes the report to a file.
The report ends with `valid` or `NOT VALID`; `--json report.json` also writes it to a file.

The validator only reads the file, so it can run on a machine without a GPU: pixi checks the environment's
CUDA requirement against the host driver, and `CONDA_OVERRIDE_CUDA=12.0 pixi run corenet-validate ...`
lifts that check.

### Training

```bash
corenet-train --config examples/bbww/bbww.yaml --input examples/data/bbww_all.h5 \
--fold 0 --exclude-folds 1 --output-dir runs/bbww --device cuda
--fold 0 --exclude-folds 1 --output-dir runs/bbww
```

`--fold k` holds out the events of fold `k` for testing (`--fold -1`, the default, trains one model per
fold in turn); the folds in `--exclude-folds` are kept out of training and used for validation. For each fold
the output directory receives the checkpoint `model_fold{k}.pkl` (self-contained: the evaluation and
the export need no configuration file), the training history `history_fold{k}.json` and the
predictions on the held-out fold `predictions_fold{k}.h5`. Epochs, learning rate, batch size and the
other settings are changed with flags (`--epochs`, `--lr`, ...) or in the configuration file; see
[docs/Options.md](docs/Options.md) and `corenet-train --help`.
* `--fold 0`: hold out fold 0 for testing. With `--fold -1` (the default), train one model per fold in turn.
* `--exclude-folds 1`: keep fold 1 out of the training and use it for validation. `--exclude-folds next`
uses the fold `(k + 1) % n_folds` of the held-out fold `k`.
* `--n-folds 5`: take the fold of an event as `squares(event) % 5`, a hash of the event number in
`EVENT/event`, instead of the `EVENT/fold` column ([docs/Dataset.md](docs/Dataset.md)); `--fold-seed`
(default 0) selects the hash key. The rule, the number of folds and the seed are stored in the
checkpoint and reused by `corenet-evaluate`. With 5 folds and seed 0 the rule equals the
`EVENT/fold` column of the example files.
* `--early-stop-patience 5`: stop when the validation AUC has not improved for 5 epochs and keep the best epoch.
* `--freeze-epoch 15 --finetune-layers head_main. head_reduce. aux_heads. --finetune-lr 1.0e-3 --finetune-batch-size 4096`:
the fine-tuning stage; from epoch 15 on only the parameters whose names start with the given prefixes
(default: the output layers; `none` freezes nothing) are trained, at this learning rate and batch size
(default: the schedule continues).
* `--epochs`, `--lr`, `--seed`, ...: override the training settings of the configuration file.
See [docs/Options.md](docs/Options.md) or `corenet-train --help`.

The folds come from the input file: the `EVENT/fold` column, or `squares(event) % K` with
`--n-folds K` ([docs/Dataset.md](docs/Dataset.md)). The example files have 5 folds in `EVENT/fold`.

Per fold `k`, the output directory receives:

| file | content |
|---|---|
| `model_fold{k}.pkl` | checkpoint; evaluation and export need no configuration file |
| `history_fold{k}.json` | training settings and per-epoch history |
| `predictions_fold{k}.h5` | predictions on the held-out fold |

### Evaluation

Expand All @@ -133,12 +159,24 @@ corenet-evaluate --checkpoint runs/bbww/model_fold0.pkl --input examples/data/bb
--output runs/bbww/eval_fold0.h5
```

evaluates the fold that was held out in training (`--fold k` for another fold, `--fold -1` for every
event of the file) and writes the metrics to `eval_fold0.h5.json` and the predictions to `eval_fold0.h5`:
`class_probabilities` (one column per class, column 1 is the signal score), `views/<hypothesis>` (the
pairing probabilities, for example the three pairings of the four b jets), `heads/<output>` (the extra
score of every further output), the ROC curve `roc/{fpr,tpr,threshold}`, and the event labels,
weights and folds. `--unweighted` ignores the event weights in the metrics.
* `--fold k`: evaluate fold `k` instead of the fold held out in training. `--fold -1` evaluates every event of the file.
* `--unweighted`: ignore the event weights in the metrics.
* `--device cuda`: evaluate on the GPU (default: CPU).

Output:

| file | content |
|---|---|
| `eval_fold0.h5.json` | the metrics |
| `eval_fold0.h5` | the predictions, as below |

| dataset in `eval_fold0.h5` | content |
|---|---|
| `class_probabilities` | one column per class; column 1 is the signal score |
| `views/HH`, `views/tt` | probability of every assignment of the jets to the particles of that hypothesis: for HH → bb̄bb̄ the three ways of pairing the four b jets into two Higgs bosons, for HH → bb̄WW the two ways of assigning the b jets to the top quarks of tt̄ |
| `heads/ttbar` | the tt̄ score (one dataset per auxiliary output) |
| `roc/{fpr,tpr,threshold}` | the ROC curve of the signal score |
| `EVENT/{index,event,label,weight,fold}` | row index in the input file, event number, label, weight and fold of every evaluated event |

### Exporting

Expand All @@ -147,10 +185,17 @@ corenet-export --checkpoint runs/bbww/model_fold0.pkl --input examples/data/bbww
--output-dir runs/bbww/export
```

writes a TorchScript file (`model_fold0.pt`), an ONNX file (`model_fold0.onnx`, dynamic batch size)
and a JSON description of the inputs and outputs, then reloads both and checks that they reproduce
the PyTorch outputs on events of `--input` to within `--atol` (1e-4). `--formats torchscript` or
`--formats onnx` exports only one of the two; `--opset` sets the ONNX opset (17).
* `--formats torchscript` or `--formats onnx`: export only one of the two formats.
* `--opset 17`: ONNX opset version.
* `--n-events 1024`, `--atol 1e-4`: number of events of `--input` on which the exported models are checked against PyTorch, and the tolerance.

Output, in `--output-dir`:

| file | content |
|---|---|
| `model_fold0.pt` | TorchScript model |
| `model_fold0.onnx` | ONNX model, dynamic batch size |
| `model_fold0.json` | description of the inputs and outputs |

Note that the exported model starts after the jets have been assigned: it takes the jets already
assigned to the b quarks, the light quarks and so on. An application outside this package has to
Expand All @@ -160,13 +205,14 @@ assign the jets the same way (for `b: jets btag 4`, the four jets most likely to

| input | shape | content |
|---|---|---|
| one per set of assigned jets, e.g. `b`, `other` | (N, features + 1, n) | the file's features of the `n` jets, in configuration order, plus a presence flag |
| one per set of assigned jets, e.g. `b`, `other` | (N, features + 1, n) | the `features` of the `n` jets, in configuration order, plus a presence flag |
| one per single object, e.g. `lepton`, `met` | (N, features + 1, 1) | the same for a single object |
| `event` | (N, n_event) | the event quantities (`nSelJets`, `HT`, ...) |

For HH → bb̄bb̄ the inputs are `b` (N, 6, 4), `other` (N, 6, 8) and `event` (N, 2); for HH → bb̄WW
`b` (N, 6, 2), `q` (N, 6, 2), `lepton` (N, 7, 1), `met` (N, 3, 1) and `event` (N, 2). The
exported model takes the same inputs as the training file, without any preprocessing step.
`features` is the number of features listed for the collection in the configuration; a column read only
by a selector (`btag`) is not an input. For HH → bb̄bb̄ the inputs are `b` (N, 5, 4), `other` (N, 5, 8)
and `event` (N, 2); for HH → bb̄WW `b` (N, 5, 2), `q` (N, 5, 2), `lepton` (N, 7, 1), `met` (N, 3, 1) and
`event` (N, 2). The exported model takes the same inputs as the training file, without any preprocessing step.

#### Outputs

Expand Down
8 changes: 5 additions & 3 deletions docs/BBWW.md
Original file line number Diff line number Diff line change
Expand Up @@ -28,7 +28,7 @@ The decay-chain part of `examples/bbww/bbww.yaml`:

```yaml
objects:
jets: {features: [pt, eta, phi, mass, btag], max: 12} # INPUTS/Jets
jets: {features: [pt, eta, phi, mass], max: 12} # INPUTS/Jets
b: jets btag 2 # the 2 highest-btag jets
q: jets rest 2 # the 2 leading remaining jets
lepton: {features: [pt, eta, phi, mass, isE, isM]} # INPUTS/Lepton, a single object (max 1)
Expand Down Expand Up @@ -70,8 +70,10 @@ training:

### `objects`

* `jets`: the jet collection, up to 12 jets per event, read from `INPUTS/Jets`.
* `b: jets btag 2`: the two jets most likely to be b jets.
* `jets`: the jet collection, up to 12 jets per event, read from `INPUTS/Jets`; the four kinematic
columns are its network inputs.
* `b: jets btag 2`: the two jets most likely to be b jets; the rule reads `INPUTS/Jets/btag` for this
choice only.
* `q: jets rest 2`: the two leading remaining jets, the light-quark jets.
* `lepton`: a single object per event; `isE` and `isM` tell the network whether it is an electron or a
muon.
Expand Down
36 changes: 26 additions & 10 deletions docs/Dataset.md
Original file line number Diff line number Diff line change
Expand Up @@ -29,8 +29,8 @@ event description. Next to each key is the expected shape and data type.
- EVENT
---- label : [NUM_EVENTS, ] : int (or CLASSIFICATIONS/EVENT/signal)
---- weight : [NUM_EVENTS, ] : float (optional)
---- fold : [NUM_EVENTS, ] : int (needed for training)
---- event : [NUM_EVENTS, ] : int (optional event identifier)
---- fold : [NUM_EVENTS, ] : int (optional: cross-validation fold; else --n-folds)
---- event : [NUM_EVENTS, ] : int (event number; needed with --n-folds)
---- other_scalar : [NUM_EVENTS, ] : float (any quantity named under `event:`)
```

Expand All @@ -44,9 +44,11 @@ of shape `[NUM_EVENTS, MAX_JETS]`. Every event is stored with the same number of
slot with `False`. Store all jets of the event, not only the b-jet candidates: which jets are the b
jets is decided by the event description when the file is loaded, so one file serves any choice.

The feature names are the ones used in the event description. `pt`, `eta`, `phi` and `mass` are the
kinematics; `btag` is only used to pick the b-jet candidates; any other feature (`isE`, `isM`, ...) is
an additional input for that object.
The column names are the ones used in the event description. The columns listed as `features` there
are the inputs of the network: `pt`, `eta`, `phi` and `mass` are the kinematics, any other feature
(`isE`, `isM`, ...) is an additional input for that object. Any column of a collection can be named in a
candidate line (`btag` for `b: jets btag 4`, [EventInfo.md](./EventInfo.md)); it is read for that choice
only and need not be a feature; listing it under `features` would make it an input as well.

## Single objects

Expand All @@ -65,9 +67,18 @@ A collection named `x` is read from `INPUTS/x`, matched case-insensitively, or f
of the event description in order (`1` = signal in both examples).
* **Weights.** `EVENT/weight` is the event weight (1 when absent). Each class is normalised during
training, so only the relative weights within a class matter. Negative weights count as 0.
* **Folds.** `EVENT/fold` is the cross-validation fold of the event. `corenet-train --fold k` holds
out fold `k` for testing and `--exclude-folds j` uses fold `j` for validation.
* **Event identifier.** `EVENT/event` is copied to the prediction files.
* **Folds.** The cross-validation fold of an event is `EVENT/fold` when the file has that column.
Without it, pass `--n-folds K` to `corenet-train` (and to `corenet-validate`): the fold is then
`squares(event) % K`, a hash of the event number in `EVENT/event` (integers ≥ 0) with the Squares
counter-based generator (`corenet.data.folds.fold_of`; `--fold-seed`, default 0, selects the hash
key), so any subset of a sample gets the same folds and no random split is ever made. With
`--n-folds K` an existing `EVENT/fold` column is ignored. The rule used (`EVENT/fold` or
`squares(event) % n_folds`), the number of folds and the seed are stored in the checkpoint, so
`corenet-evaluate` applies the same rule to any file. `corenet-train --fold k` holds out fold `k`
for testing and `--exclude-folds j` uses fold `j` for validation (`--exclude-folds next`: fold
`(k + 1) % n_folds`).
* **Event identifier.** `EVENT/event` is copied to the prediction files and is the input of the
`squares(event) % n_folds` rule.

## Example

Expand All @@ -82,9 +93,14 @@ follow this layout:
`EVENT/event`.

They are random subsamples of the full files `hh4b_all.h5` and `bbww_all.h5`, written with
`python scripts/make_small_h5.py <full> <small> --events 20000`. Check any file against an event
description with
`python scripts/make_small_h5.py <full> <small> --events 20000`. Their `EVENT/fold` column equals the
fold rule with 5 folds and seed 0 (`--n-folds 5 --fold-seed 0`), so the column and `--n-folds 5`
give the same folds on these files; `corenet-validate --n-folds 5` reports that agreement. Check any
file against an event description with

```bash
corenet-validate --config examples/bbww/bbww.yaml --input examples/data/bbww_small.h5
```

On a machine without a GPU (no CUDA driver), prefix the command with `CONDA_OVERRIDE_CUDA=12.0`; the
validator only reads the file.
35 changes: 25 additions & 10 deletions docs/EventInfo.md
Original file line number Diff line number Diff line change
Expand Up @@ -28,30 +28,37 @@ members are the candidate jets of the decay chain.

```yaml
objects:
jets: {features: [pt, eta, phi, mass, btag], max: 12}
jets: {features: [pt, eta, phi, mass], max: 12}
b: jets btag 4
other: jets rest 8
lepton: {features: [pt, eta, phi, mass, isE, isM]}
met: {features: [pt, phi]}
```

* `jets`: the jet collection, with up to 12 jets per event. The listed features are the columns to
read from the input file ([Dataset.md](./Dataset.md)). `btag` is only used to pick which jets are
treated as b-jet candidates; it is not an input to the network.
* `b: jets btag 4`: the four jets most likely to be b jets, taken from the jet collection.
* `jets`: the jet collection, with up to 12 jets per event. The listed features are the inputs of the
network: exactly these columns of the input file ([Dataset.md](./Dataset.md)) are fed to it, `pt`,
`eta`, `phi` and `mass` as the kinematics and any other feature as an additional input.
* `b: jets btag 4`: the four jets most likely to be b jets, taken from the jet collection. The `btag`
rule reads the `btag` column of the file for this choice only; it need not be a feature. (Listing
`btag` under `features` would make it one more input of the network.)
* `other: jets rest 8`: up to eight of the remaining jets.
* `lepton`: a single object per event (no `max`), with two extra inputs `isE` and `isM`.
* `met`: the missing transverse momentum, a single object given by `pt` and `phi`.

A collection has `features` (required) and `max` (the number of jets per event, default 1). A
single object enters the decay chains by its own name; a collection with several jets is used
through candidate lines of the form `<name>: <collection> <rule> <n>`:
through candidate lines of the form `<name>: <collection> <column> <n>`, where `<column>` is any
per-jet column of the collection's group in the input file (`btag`, `pt`, `mass`, ...):

| rule | the `n` jets taken |
| line | the `n` jets taken |
|---|---|
| `btag` | the `n` jets most likely to be b jets (needs a `btag` feature) |
| `pt` | the `n` leading jets |
| `rest` | up to `n` of the jets not taken by an earlier line |
| `<column> <n>` | the `n` jets with the highest value of the column (`jets btag 4`: the four jets most likely to be b jets; `jets pt 4`: the four leading jets); ties go to the higher `pt` |
| `<column> <n> lowest` | the `n` jets with the lowest value of the column (`jets mass 2 lowest`), ties again to the higher `pt` |
| `rest <n>` | up to `n` of the jets not taken by an earlier line, leading `pt` first ([Options.md](./Options.md): `rest_order`) |

`rest` is the only reserved word; every other word in that position names a column. The column (and
`pt`) is read from the input file for the selection only and need not be a feature; the network sees
the `features`. Nothing else may follow `<n>` but `lowest`.

Lines are filled in order and a jet is used by at most one line. An event with fewer jets than needed
is kept; the missing ones are simply absent.
Expand All @@ -65,6 +72,14 @@ event: [nSelJets, HT]
Optional per-event quantities. `nSelJets` (the number of jets) and `HT` (their scalar momentum sum)
are computed from the jet collection; any other name is read from the input file.

```yaml
min_jets: 4
```

Optional, default 4: the minimum number of jets per event in your selection. The jet multiplicity enters
the network as `log(nSelJets - (min_jets - 1))`, so that the minimum multiplicity maps to zero; an event
with fewer jets than `min_jets` would give a non-finite input.

## `hypotheses`

The second **required** section: the decay chain of each process, as a tree over the candidate
Expand Down
Loading
Loading