Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
23 commits
Select commit Hold shift + click to select a range
1df03fd
folds: typing.Union for the SeedLike alias (Python 3.9)
aniketkhanal Oct 22, 2026
adaf9e9
loader: read selector columns at the file dtype, cast to float32 when…
aniketkhanal Oct 22, 2026
050030d
loader, validator: fold ids of EVENT/fold must be exactly 0..K-1
aniketkhanal Oct 22, 2026
31b33bf
loader: folds are needed only to select a fold
aniketkhanal Oct 22, 2026
46c4202
train: ghost batches of the fine-tuning stage divide the batch size
aniketkhanal Oct 22, 2026
fa881d6
train: finetune_layers must match at least one trainable parameter
aniketkhanal Oct 22, 2026
9e6fa2b
train: early stopping needs a validation AUC
aniketkhanal Oct 22, 2026
887f4d4
network: extra features of the context role reach the context objects
aniketkhanal Oct 22, 2026
befdcaa
train: the regular batch schedule picks a ghost-batch count that divi…
aniketkhanal Oct 22, 2026
4ec1aa8
docs: Zenodo DOI of the training samples (10.5281/zenodo.23567532)
aniketkhanal Oct 22, 2026
3494253
H5Dataset: record the file slot of every role slot (selected)
aniketkhanal Oct 22, 2026
ca6127c
Add corenet-report: one self-contained HTML results page per run
aniketkhanal Oct 22, 2026
41195a3
tests: corenet-report on 2-epoch synthetic runs (TARGETS, gaps, multi…
aniketkhanal Oct 22, 2026
b606c99
docs: Report.md, README Report subsection, report step in the HH4b an…
aniketkhanal Oct 22, 2026
489834f
report: compare interchangeable sibling nodes (H1/H2) as a set in the…
aniketkhanal Oct 22, 2026
6d4542a
pixi.lock: re-solved after adding matplotlib-base (job 49597275)
aniketkhanal Oct 22, 2026
205be7e
report: ruff format and lint fixes; mean over folds without the empty…
aniketkhanal Oct 22, 2026
a0790ed
report: readable small weights in the statistics table, staggered N l…
aniketkhanal Oct 22, 2026
e4b2e24
report: drop the not-produced section and the wall-time mention; READ…
aniketkhanal Oct 22, 2026
c729476
report: drop the 'Not produced' section and the wall-time note; a fig…
aniketkhanal Oct 22, 2026
6168c62
release metadata: .zenodo.json for the GitHub–Zenodo integration, aut…
aniketkhanal Oct 22, 2026
e7b5cf4
ruff format
aniketkhanal Oct 22, 2026
c1638c8
ruff: noqa for the runtime Union alias, raw regex in a test
aniketkhanal 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
15 changes: 15 additions & 0 deletions .zenodo.json
Original file line number Diff line number Diff line change
@@ -0,0 +1,15 @@
{
"title": "CoReNet: Combinatorial Residual Networks for multijet topologies",
"upload_type": "software",
"description": "Reference implementation of CoReNet, a configuration-driven combinatorial residual network for jet assignment and event classification in multijet final states, with the HH to bbbb and HH to bbWW examples of the accompanying paper.",
"creators": [
{"name": "Khanal, Aniket", "affiliation": "Carnegie Mellon University", "orcid": "0009-0007-5557-9821"},
{"name": "Alison, John", "affiliation": "Carnegie Mellon University", "orcid": "0000-0003-0843-1641"},
{"name": "Gomez Espinosa, Alejandro", "affiliation": "Carnegie Mellon University", "orcid": "0000-0002-9443-7769"}
],
"license": "MIT",
"keywords": ["jet assignment", "Higgs boson pair production", "machine learning", "CMS", "CoReNet"],
"related_identifiers": [
{"identifier": "10.5281/zenodo.23567532", "relation": "isSupplementedBy", "resource_type": "dataset"}
]
}
16 changes: 13 additions & 3 deletions CITATION.cff
Original file line number Diff line number Diff line change
@@ -1,4 +1,4 @@
# Placeholder: the owner fills in authors, DOI and references before the release.
# The software DOI and the preferred-citation (article) are filled in after the first release.
cff-version: 1.2.0
message: "If you use CoReNet, please cite it as below."
title: "CoReNet: Combinatorial Residual Network"
Expand All @@ -8,7 +8,17 @@ date-released: "YYYY-MM-DD" # to be confirmed
license: MIT
repository-code: "https://github.com/[owner]/CoReNet" # to be confirmed
authors:
- family-names: "[to be confirmed]"
given-names: "[to be confirmed]"
- family-names: "Khanal"
given-names: "Aniket"
orcid: "https://orcid.org/0009-0007-5557-9821"
affiliation: "Carnegie Mellon University"
- family-names: "Alison"
given-names: "John"
orcid: "https://orcid.org/0000-0003-0843-1641"
affiliation: "Carnegie Mellon University"
- family-names: "Gomez Espinosa"
given-names: "Alejandro"
orcid: "https://orcid.org/0000-0002-9443-7769"
affiliation: "Carnegie Mellon University"
# doi: "10.xxxx/zenodo.xxxxxxx" # to be confirmed
# preferred-citation: # to be confirmed (article describing the architecture)
36 changes: 31 additions & 5 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -21,8 +21,8 @@ pixi shell # activate; or prefix every command with `pixi
pixi itself is a single static binary (`curl -fsSL https://pixi.sh/install.sh | sh`) that needs no root
access, so the same commands work on a laptop and on a cluster front end.

This installs the command-line tools `corenet-validate`, `corenet-train`, `corenet-evaluate` and
`corenet-export` (each has `--help`), and the Python package `corenet`. The unit tests run with
This installs the command-line tools `corenet-validate`, `corenet-train`, `corenet-evaluate`,
`corenet-export` and `corenet-report` (each has `--help`), and the Python package `corenet`. The unit tests run with
`pytest tests`.

## Dependencies
Expand All @@ -35,6 +35,7 @@ This installs the command-line tools `corenet-validate`, `corenet-train`, `coren
| h5py | 3.0 | input and prediction files |
| PyYAML | 5.4 | configuration files |
| scikit-learn | 1.0 | AUC / ROC in `corenet-evaluate` |
| matplotlib | 3.5 | figures of `corenet-report` |
| onnx, onnxruntime | 1.14, 1.15 | `corenet-export` (optional extra `export`) |
| pytest | 7 | tests (optional extra `test`) |

Expand Down Expand Up @@ -62,9 +63,12 @@ corenet-evaluate --checkpoint runs/hh4b/model_fold0.pkl --input examples/data/hh
# 4. export to TorchScript and ONNX, and check the exported models against PyTorch
corenet-export --checkpoint runs/hh4b/model_fold0.pkl --input examples/data/hh4b_small.h5 \
--output-dir runs/hh4b/export

# 5. one HTML page with the training curves, ROC curves, pairings and input checks of the run
corenet-report --run-dir runs/hh4b --input examples/data/hh4b_small.h5 --output runs/hh4b/report.html
```

The same four commands with `bbww` in place of `hh4b` run the HH → bb̄WW example.
The same five commands with `bbww` in place of `hh4b` run the HH → bb̄WW example.
[docs/HH4b.md](docs/HH4b.md) walks through the HH → bb̄bb̄ example step by step;
[docs/BBWW.md](docs/BBWW.md) does the same for HH → bb̄WW against tt̄.

Expand All @@ -90,15 +94,15 @@ combine: [HH]

`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. \
file, and only these, are fed to it, for the `b` jets and for the `other` jets alike. \
`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
separately on Zenodo ([doi:10.5281/zenodo.23567532](https://doi.org/10.5281/zenodo.23567532)); download them into `examples/data/` as `hh4b_all.h5` and
`bbww_all.h5`.

## Usage
Expand Down Expand Up @@ -169,6 +173,7 @@ Output:
|---|---|
| `eval_fold0.h5.json` | the metrics |
| `eval_fold0.h5` | the predictions, as below |
| `report.html` | every result of the run on one page, written by `corenet-report` ([Report](#report) below) |

| dataset in `eval_fold0.h5` | content |
|---|---|
Expand Down Expand Up @@ -222,6 +227,27 @@ and `event` (N, 2); for HH → bb̄WW `b` (N, 5, 2), `q` (N, 5, 2), `lepton` (N,
| `views_<hypothesis>` | (N, V) | probability of every pairing of a hypothesis with several pairings |
| `head_<output>` | (N,) | the extra binary score of every output after the first |

### Report

```bash
corenet-report --run-dir runs/bbww --input examples/data/bbww_all.h5 --output runs/bbww/report.html
```

* `--folds 0 1`: report these folds only (default: every fold found in the run directory).
* `--max-events 500000`: events of the input file used for the input and weight distributions (random subsample above it; `0` = all).
* `--config my_config.yaml`: event description to use instead of the one stored in the checkpoint.

To see the training and validation folds in the ROC and score figures (overtraining check), first write the
predictions of every event with `corenet-evaluate ... --output runs/bbww/eval_fold0.h5 --fold -1`.

Output:

| file | content |
|---|---|
| `report.html` | self-contained page: run summary, training curves, ROC / AUC / score distributions, view probabilities and pairing accuracy against `TARGETS`, the inputs as the network embeds them, the raw inputs and the event weights ([docs/Report.md](docs/Report.md)) |

Open `report.html` in any browser; from a cluster, copy it to your machine first (`scp <host>:runs/bbww/report.html .`).

```python
import onnxruntime as ort
from corenet import load_config
Expand Down
11 changes: 9 additions & 2 deletions docs/BBWW.md
Original file line number Diff line number Diff line change
Expand Up @@ -11,7 +11,7 @@ with its own score.

`examples/data/bbww_small.h5` (20,000 events: 1,198 HH, 18,802 tt̄; 10.2 MB) is a random subsample of
`examples/data/bbww_all.h5` (292,285 events: 17,511 HH, 274,774 tt̄; 149 MB), which is distributed
separately ([DOI / URL to be added]); download it into `examples/data/`. The layout
separately on Zenodo ([doi:10.5281/zenodo.23567532](https://doi.org/10.5281/zenodo.23567532)); download it into `examples/data/`. The layout
([Dataset.md](./Dataset.md)):

| path | shape | meaning |
Expand Down Expand Up @@ -127,7 +127,14 @@ corenet-evaluate --checkpoint runs/bbww_full/model_fold0.pkl --input examples/da
--output runs/bbww_full/eval_fold0.h5
```

```bash
corenet-report --run-dir runs/bbww_full --input examples/data/bbww_all.h5 --output runs/bbww_full/report.html
```

writes the results page of the run ([Report.md](./Report.md)).

The commands, their options and their output files are the same as in the
[HH → bb̄bb̄ guide](./HH4b.md). The prediction file additionally holds `views/tt` (the two tt̄
pairings) and `heads/ttbar` (the tt̄ score), and `class_probabilities` has three columns (rest,
signal, ttbar). The exported model takes `b`, `q`, `lepton`, `met` and `event`.
signal, ttbar). The exported model takes `b`, `q`, `lepton`, `met` and `event`. The report adds the
confusion matrix of the three classes, the ROC curve of every class against the rest and of the tt̄ score.
9 changes: 6 additions & 3 deletions docs/Dataset.md
Original file line number Diff line number Diff line change
Expand Up @@ -67,16 +67,19 @@ 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.** 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
* **Folds.** The cross-validation fold of an event is `EVENT/fold` when the file has that column; the
ids of `K` folds must be exactly `0 .. K-1`. Without the column, 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`).
`(k + 1) % n_folds`). Only selecting a fold needs the folds: `corenet-evaluate --fold -1` and
`corenet-export` also work on a file with neither `EVENT/fold` nor `--n-folds` (the events then
carry fold -1 in the prediction file).
* **Event identifier.** `EVENT/event` is copied to the prediction files and is the input of the
`squares(event) % n_folds` rule.

Expand Down
5 changes: 3 additions & 2 deletions docs/EventInfo.md
Original file line number Diff line number Diff line change
Expand Up @@ -37,7 +37,8 @@ objects:

* `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.
`eta`, `phi` and `mass` as the kinematics and any other feature as an additional input. This holds
for every line taken from the collection, also one used only as `context:` (`other` below).
* `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.)
Expand Down Expand Up @@ -118,7 +119,7 @@ written as:
| `W_lep: [lepton, met]` | the leptonic W, formed from the lepton and the missing momentum |

`context: <name>` inside a hypothesis lets its first particles (the Higgs candidates above) also see
the jets of that name, that is, the whole event.
the jets of that name, that is, the whole event, with all the `features` of their collection.

Nothing has to be declared about symmetries or combinatorics: products of the same kind are
interchangeable (the two b of a Higgs, the two Higgs bosons of HH) and a jet is never used twice in one
Expand Down
16 changes: 15 additions & 1 deletion docs/HH4b.md
Original file line number Diff line number Diff line change
Expand Up @@ -9,7 +9,7 @@ and export. Every command is run from the repository root in the pixi environmen

The repository ships `examples/data/hh4b_small.h5` (20,000 events, 8.1 MB), a random subsample of the
full file `examples/data/hh4b_all.h5` (454,261 events: 417,978 multijet, 36,283 HH; 184 MB). The full
file is distributed separately ([Zenodo DOI to be added]); download it into `examples/data/`. Both
file is distributed separately on Zenodo ([doi:10.5281/zenodo.23567532](https://doi.org/10.5281/zenodo.23567532)); download it into `examples/data/`. Both
files have the same layout ([Dataset.md](./Dataset.md)):

| path | shape | dtype | meaning |
Expand Down Expand Up @@ -174,6 +174,20 @@ exported model takes the jets already assigned (`b`, `other`) and the event quan
of the b jets has to be reproduced wherever the model is deployed; see Exporting in the
[README](../README.md).

## Report

```bash
corenet-evaluate --checkpoint runs/hh4b_full/model_fold0.pkl --input examples/data/hh4b_all.h5 \
--output runs/hh4b_full/eval_fold0.h5 --fold -1
corenet-report --run-dir runs/hh4b_full --input examples/data/hh4b_all.h5 --output runs/hh4b_full/report.html
```

writes one HTML page with the training curves, the ROC curves and AUC per fold, the signal-score
distributions on the test and training folds, the probabilities of the three pairings and their
accuracy against `TARGETS`, the inputs as the network embeds them, the raw inputs and the event weights
([Report.md](./Report.md)). The first command is optional: it gives the training and validation folds
their own curves.

## Changing things

| to change | where | example |
Expand Down
4 changes: 2 additions & 2 deletions docs/Options.md
Original file line number Diff line number Diff line change
Expand Up @@ -34,10 +34,10 @@ Changing one of these gives a different network: validate the file with `corenet
| `freeze_epoch` | `--freeze-epoch` | 15 | start of the fine-tuning stage: from this epoch on only the layers named by `finetune_layers` are trained (a value ≥ `epochs` disables this) |
| `finetune_layers` | `--finetune-layers PREFIX [PREFIX ...]` | `head_main.`, `head_reduce.`, `aux_heads.` (the output layers) | parameter-name prefixes that stay trainable from `freeze_epoch` on; `none` (the word, alone; `[]` in the file) freezes nothing |
| `finetune_lr` | `--finetune-lr` | unset | learning rate set at `freeze_epoch`; the `lr_milestones` after it multiply this value by `lr_gamma`; unset keeps the schedule |
| `finetune_batch_size` | `--finetune-batch-size` | unset | batch size from `freeze_epoch` on (the ghost batches of the stage are kept, capped so that none has fewer than 8 events); unset keeps the schedule |
| `finetune_batch_size` | `--finetune-batch-size` | unset | batch size from `freeze_epoch` on; the ghost batches of the stage are kept when they divide it, else the largest smaller number that does, so that every ghost batch has at least 8 events; unset keeps the schedule |
| `class_norm` | `--class-norm` / `--no-class-norm` | true | give every class the same total weight in training |
| `seed` | `--seed` | 42 | random seed; fold `k` uses `seed + k` |
| `early_stop_patience` | `--early-stop-patience` | 0 | stop when the validation AUC (on the `--exclude-folds` fold) has not improved for this many epochs, and keep the weights of the best epoch; 0 trains every epoch |
| `early_stop_patience` | `--early-stop-patience` | 0 | stop when the validation AUC (on the `--exclude-folds` fold) has not improved for this many epochs, and keep the weights of the best epoch; 0 trains every epoch. The validation fold must differ from the held-out fold and hold events of class 1 and of another class, otherwise the run stops with an error |
| `rest_order` | `--rest-order` | `pt` | order of the jets taken by a `rest` line: `pt`, or `selector` to keep the order of the previous candidate line on the same collection (e.g. `b: jets btag 4`) |

Write floating-point numbers with a decimal point (`0.005` or `5.0e-3`): YAML reads `5e-3` as a string,
Expand Down
Loading
Loading