Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
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
2 changes: 1 addition & 1 deletion .zenodo.json
Original file line number Diff line number Diff line change
@@ -1,5 +1,5 @@
{
"title": "CoReNet: Combinatorial Residual Networks for multijet topologies",
"title": "CoReNet: Combinatorial Residual Network",
"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, HH to bbWW and ttH examples.",
"creators": [
Expand Down
2 changes: 1 addition & 1 deletion CITATION.cff
Original file line number Diff line number Diff line change
Expand Up @@ -20,5 +20,5 @@ authors:
given-names: "Alejandro"
orcid: "https://orcid.org/0000-0002-9443-7769"
affiliation: "Carnegie Mellon University"
# doi: "10.xxxx/zenodo.xxxxxxx" # to be confirmed
doi: "10.5281/zenodo.23577720"
# preferred-citation: # to be confirmed (article describing the architecture)
40 changes: 30 additions & 10 deletions CONTRIBUTING.md
Original file line number Diff line number Diff line change
Expand Up @@ -14,21 +14,11 @@ cd CoReNet

### 2. Environment Setup

#### Option A: Using Pixi (Recommended on Linux with CUDA GPU)
```bash
pixi install
pixi shell
```

#### Option B: Using Pip / Virtual Environment (CPU / Local Dev)
```bash
python -m venv .venv
source .venv/bin/activate
pip install --upgrade pip
pip install torch --index-url https://download.pytorch.org/whl/cpu
pip install -e ".[test,export,lint]"
```

---

## Code Quality & Standards
Expand Down Expand Up @@ -68,6 +58,36 @@ To run with test coverage:
pytest --cov=corenet tests/
```

### Parity with the research code

```bash
CORENET_REFERENCE_REPO=/path/to/research-checkout pytest tests/reference -s
```

- `CORENET_REFERENCE_REPO`: checkout of the research repository; its `src/hcr` is imported, `data/h5/{hh4b,bbww}_all.h5` and the checkpoints under `models/` are read. Without it these tests are skipped.

The tests require identical configurations, parameter counts, initial weights, loader tensors, eval-mode outputs and checkpoint evaluation. Training-mode outputs are not compared with the research code, because CoReNet embeds the slots of one leaf role in one node together (they share the ghost-batch statistics); the golden-file test below covers them.

### Golden files of the training-mode numerics

`pytest tests` runs `tests/test_training_regression.py`: training-mode outputs, first-step gradients, five SGD steps and the eval-mode outputs after them, on 1,024 events of `examples/data/{hh4b,bbww}_small.h5`, on the CPU with one thread, compared with `tests/golden/{hh4b,bbww}.npz`.

After an intentional change of the training-mode numerics, or of `examples/data/{hh4b,bbww}_small.h5`:

1. Regenerate the golden files:
```bash
python scripts/make_golden.py
```
- `hh4b` or `bbww`: regenerate this case only (default: both)
2. Read the printed change per stage against the old files and the two noise probes. The script writes nothing if a probe exceeds a tenth of the test tolerance or the files exceed 2 MB.
3. Run `pytest tests/test_training_regression.py`.
4. Commit `tests/golden/*.npz` in the same commit as the change and give the reason in the commit message.

| file | content |
|---|---|
| `tests/golden/hh4b.npz` | HH → 4b: initial weights, frozen input statistics, training-mode outputs, first-step gradients, losses, weights after five SGD steps, eval-mode outputs |
| `tests/golden/bbww.npz` | the same for HH → bbWW |

---

## Pull Request Guidelines
Expand Down
16 changes: 14 additions & 2 deletions README.md
Original file line number Diff line number Diff line change
@@ -1,4 +1,5 @@
# CoReNet: Combinatorial Residual Network
[![DOI](https://zenodo.org/badge/DOI/10.5281/zenodo.23577720.svg)](https://doi.org/10.5281/zenodo.23577720)

[![CI](https://github.com/cms-cmu/CoReNet/actions/workflows/ci.yml/badge.svg)](https://github.com/cms-cmu/CoReNet/actions/workflows/ci.yml)

Expand All @@ -19,7 +20,7 @@ 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.
access. The environment is built for Linux (x86-64) with an NVIDIA GPU (CUDA 12).

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
Expand Down Expand Up @@ -94,6 +95,11 @@ outputs:
combine: [HH]
```

The optional `labels:` section names the labels to train on, in label order (e.g.
`labels: [multijet, HH, ttbar]`: label 0 = multijet, 1 = HH, 2 = ttbar). Without it the classes are
"rest" (label 0) plus the outputs in order; with it every output name must be one of the labels and the
main score is the class of the first output ([EventInfo.md](docs/EventInfo.md)).

`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, for the `b` jets and for the `other` jets alike. \
Expand Down Expand Up @@ -143,7 +149,10 @@ corenet-train --config examples/bbww/bbww.yaml --input examples/data/bbww_all.h5
* `--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).
(default: the schedule continues); `--finetune-reset-optimizer` starts a new optimizer and learning-rate
schedule at that epoch instead of continuing the main stage's.
* `--masked-classes SR=d4`: for the events with `EVENT/SR` true, remove the class `d4` from the
softmax in training (a blinded signal region); the evaluation uses all classes ([docs/Options.md](docs/Options.md)).
* `--epochs`, `--lr`, `--seed`, ...: override the training settings of the configuration file.
See [docs/Options.md](docs/Options.md) or `corenet-train --help`.

Expand Down Expand Up @@ -269,4 +278,7 @@ class_probabilities, views_HH = sess.run(None, feeds)

If you use this software for a publication, please cite it as given in [CITATION.cff](CITATION.cff)
(to be completed) and the paper describing the method: [paper reference / arXiv to be added].
The software is archived on Zenodo with the concept DOI
[10.5281/zenodo.23577720](https://doi.org/10.5281/zenodo.23577720) (version 1.0.0:
10.5281/zenodo.23577721); [CITATION.cff](CITATION.cff) holds the citation.
Released under the MIT licence ([LICENSE](LICENSE)).
3 changes: 1 addition & 2 deletions docs/BBWW.md
Original file line number Diff line number Diff line change
Expand Up @@ -65,7 +65,6 @@ training:
attention_gate: true
kv_projection: true
phase_symmetric: true
reflect_eta: false
```

### `objects`
Expand Down Expand Up @@ -101,7 +100,7 @@ Two outputs, hence three classes: 0 = rest, 1 = signal (HH), 2 = tt̄; the examp

### `training`

All network settings at their defaults except `reflect_eta: false`.
All network settings at their defaults.
`examples/bbww/bbww_hyperparameters.yaml` writes every setting out ([Options.md](./Options.md)).

## Training, evaluation and export
Expand Down
10 changes: 9 additions & 1 deletion docs/Dataset.md
Original file line number Diff line number Diff line change
Expand Up @@ -43,6 +43,8 @@ of shape `[NUM_EVENTS, MAX_JETS]`. Every event is stored with the same number of
`MAX_JETS`, so events with fewer jets are padded; `MASK` marks a real jet with `True` and a padding
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 loader turns `MASK` into the last channel of every object tensor (+1 real, -1 padding); for the
`context` objects this channel is fed to the network as given (+1/-1 from the loader).

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
Expand All @@ -64,7 +66,9 @@ A collection named `x` is read from `INPUTS/x`, matched case-insensitively, or f

* **Labels.** `EVENT/label` (or, when absent, `CLASSIFICATIONS/EVENT/signal`) holds the class of the
event: `0` for background not described by a hypothesis ("rest"), and `1, 2, ...` for the outputs
of the event description in order (`1` = signal in both examples).
of the event description in order (`1` = signal in both examples). A `labels:` section in the event
description replaces this convention by its own list of class names in label order
([EventInfo.md](./EventInfo.md)).
* **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; the
Expand All @@ -80,6 +84,10 @@ A collection named `x` is read from `INPUTS/x`, matched case-insensitively, or f
`(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).
* **Flags.** Boolean columns `EVENT/<name>` named by `masked_classes` ([Options.md](./Options.md)) mark
the events whose listed classes are removed from the softmax in training. They are boolean, or
integers 0/1. No flagged event may carry one of the classes masked for its flag: `corenet-train`
and `corenet-validate` reject such a file and give the number of offending events per flag and class.
* **Event identifier.** `EVENT/event` is copied to the prediction files and is the input of the
`squares(event) % n_folds` rule.

Expand Down
11 changes: 11 additions & 0 deletions docs/EventInfo.md
Original file line number Diff line number Diff line change
Expand Up @@ -12,6 +12,7 @@ hypotheses: # the decay chains (required)
attention: # which candidates are compared with which (optional)
relations: # pairs of objects the classifier looks at (optional)
outputs: # the classes (required)
labels: # labels to train on, in label order (optional)
combine: # the hypotheses the classifier is built from (required)
training: # network settings (optional, see Options.md)
trainer: # training settings (optional, see Options.md)
Expand Down Expand Up @@ -162,6 +163,16 @@ first output is the main one: the classifier gives the probability of every clas
hypotheses in `combine`. Every further output also gets its own score from its hypothesis alone
(`heads/<output>` in the prediction files). Every hypothesis must appear in `combine` or in `outputs`.

```yaml
labels: [multijet, HH, ttbar] # labels to train on, in label order (0, 1, 2, ...); optional
```

`labels` (optional) names the labels to train on, in label order: label `0` is the first name, `1` the
second, and so on (at least two, all different). Without it the classes are "rest" plus the outputs, as
above. With it the classes are exactly these names, every output name must be one of them, and the main
score is the probability of the class of the first output; auxiliary heads are still built for the
further outputs only, so a network can have any number of classes without auxiliary heads.

## `training` and `trainer`

```yaml
Expand Down
17 changes: 16 additions & 1 deletion docs/Options.md
Original file line number Diff line number Diff line change
Expand Up @@ -35,11 +35,26 @@ Changing one of these gives a different network: validate the file with `corenet
| `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 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 |
| `finetune_reset_optimizer` | `--finetune-reset-optimizer` / `--no-finetune-reset-optimizer` | off | at freeze_epoch, start a new optimizer and learning-rate schedule over the trainable parameters (a fresh fine-tuning stage) instead of continuing the main stage's optimizer |
| `masked_classes` | `--masked-classes FLAG=CLASS[,CLASS]` | none | classes removed from the softmax for the events flagged by `EVENT/FLAG`; the flagged events still train the other classes; the file must hold no flagged event of an excluded class |
| `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. 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 |
| `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 the main class (the class of the first output; class 1 without `labels:`) 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`) |

`masked_classes` serves a training with a blinded region. Example: a classifier of the classes
`d3`, `d4` and `ttbar` is trained with the 4-tag data of the signal region left out of the file. The
3-tag data and the tt̄ events of the signal region are kept and flagged by `EVENT/SR`; with

```yaml
trainer:
masked_classes:
SR: [d4] # for events with EVENT/SR true, the d4 class is removed from the softmax
```

these events train the network to tell `d3` from `ttbar` only, and no event of the signal region
pulls the `d4` score. `corenet-evaluate` and the prediction files always use all classes.

Write floating-point numbers with a decimal point (`0.005` or `5.0e-3`): YAML reads `5e-3` as a string,
which the validation rejects.

Expand Down
4 changes: 2 additions & 2 deletions docs/TTH.md
Original file line number Diff line number Diff line change
Expand Up @@ -75,7 +75,7 @@ training:
attention_gate: true
kv_projection: true
phase_symmetric: true
reflect_eta: false
reflect_eta: true # use the forward-backward symmetry of the detector
```

### `objects`
Expand Down Expand Up @@ -116,7 +116,7 @@ One output, `signal: ttH`, hence two classes: 0 = rest (semileptonic tt̄), 1 =

### `training`

All network settings at their defaults except `reflect_eta: false`. [Options.md](./Options.md)
All network settings at their defaults. [Options.md](./Options.md)
describes every setting.

## Training, evaluation and export
Expand Down
2 changes: 1 addition & 1 deletion examples/bbww/bbww.yaml
Original file line number Diff line number Diff line change
Expand Up @@ -38,4 +38,4 @@ training:
attention_gate: true
kv_projection: true
phase_symmetric: true
reflect_eta: false
reflect_eta: true # use the forward-backward symmetry of the detector
10 changes: 6 additions & 4 deletions examples/bbww/bbww_hyperparameters.yaml
Original file line number Diff line number Diff line change
@@ -1,6 +1,6 @@
# The HH -> bbWW network of bbww.yaml with EVERY tunable option written out at its default value
# (except reflect_eta, which this example switches off). Training with this file gives the same
# result as with bbww.yaml. Copy it and edit the values. Reference: docs/Options.md.
# The HH -> bbWW network of bbww.yaml with EVERY tunable option written out at its default value.
# Training with this file gives the same result as with bbww.yaml. Copy it and edit the values.
# Reference: docs/Options.md.
objects:
jets: {features: [pt, eta, phi, mass], max: 12}
b: jets btag 2
Expand Down Expand Up @@ -41,7 +41,7 @@ training:
attention_gate: true # gated comparison of candidates
kv_projection: true # reduced-size projections when candidates are compared
phase_symmetric: true # phase-symmetric layers
reflect_eta: false # (default true) use the forward-backward symmetry of the detector
reflect_eta: true # use the forward-backward symmetry of the detector
head_weights: {ttbar: 1.0} # loss weight of the extra ttbar score (default 1.0)

# ---- training settings (read by corenet-train; a command-line flag overrides the value here)
Expand All @@ -52,6 +52,8 @@ trainer:
lr_gamma: 0.25
batch_size_init: 1024 # epoch-0 batch size; doubled at epochs 1, 3, 6 and 10 (fixed schedule)
freeze_epoch: 15 # from this epoch on only the output layers are trained
finetune_reset_optimizer: false # true: new optimizer and lr schedule at freeze_epoch
class_norm: true # normalise the event weights of every class to 1 over the training set
seed: 42 # random seed; the seed of fold k is seed + k
rest_order: pt # order of the jets taken by a `rest` line: pt | selector
masked_classes: {} # flag -> classes removed from the softmax for the flagged events, e.g. {SR: [d4]}
2 changes: 2 additions & 0 deletions examples/hh4b/hh4b_hyperparameters.yaml
Original file line number Diff line number Diff line change
Expand Up @@ -36,6 +36,8 @@ trainer:
lr_gamma: 0.25
batch_size_init: 1024 # epoch-0 batch size; doubled at epochs 1, 3, 6 and 10 (fixed schedule)
freeze_epoch: 15 # from this epoch on only the output layers are trained
finetune_reset_optimizer: false # true: new optimizer and lr schedule at freeze_epoch
class_norm: true # normalise the event weights of every class to 1 over the training set
seed: 42 # random seed; the seed of fold k is seed + k
rest_order: pt # order of the jets taken by a `rest` line: pt | selector
masked_classes: {} # flag -> classes removed from the softmax for the flagged events, e.g. {SR: [d4]}
2 changes: 1 addition & 1 deletion examples/tth/tth.yaml
Original file line number Diff line number Diff line change
Expand Up @@ -37,4 +37,4 @@ training:
attention_gate: true
kv_projection: true
phase_symmetric: true
reflect_eta: false
reflect_eta: true # use the forward-backward symmetry of the detector
2 changes: 1 addition & 1 deletion pyproject.toml
Original file line number Diff line number Diff line change
Expand Up @@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"

[project]
name = "CoReNet"
version = "1.0.0"
version = "1.1.0"
description = "CoReNet (Combinatorial Residual Network): a decay-chain-configurable neural network for event classification in collider physics"
readme = "README.md"
license = "MIT"
Expand Down
Loading
Loading