docs: add Hugging Face model card based on paper (#9)

- docs: add Hugging Face model card (196e2e82ecc61b8fb16ce65877e43ec6126113b3)
- docs: reproduce paper in model card (76eff8f0d9f97c4952f8a8ad79ebf84c7f9b22b6)
- docs: preserve paper author affiliations (7f136d97ab4e8589ef03ffa8c9691875cbb3aa7c)

README_PROJECT.md

@@ -0,0 +1,282 @@
+# GNN4Colliders
+
+GNN4Colliders is a collider-machine-learning toolkit. The repository name
+reflects its first production model family, ROOT-GNN; the Python package is
+`gnn4colliders`, and the configuration identifier is `root_gnn`. Shared ROOT
+ingestion, collider features, metadata, tasks, training, inference, and
+distributed utilities are designed so that a future sequence model can reuse
+them without requiring every event to be a graph.
+
+```text
+ROOT files -> EventSample -> shared collider features
+                              ├── GraphSample -> ROOT-GNN
+                              └── future SequenceSample -> ROOT-Transformer
+```
+
+The new implementation lives under [`src/gnn4colliders`](src/gnn4colliders/).
+[`legacy/`](legacy/) is a frozen behavioral reference for parity work and
+historical checkpoint investigation, not a supported runtime backend.
+
+## Installation
+
+The supported development environment is Python 3.12 (`>=3.12,<3.13`). Core
+development is supported on macOS and Linux:
+
+```bash
+# macOS (Apple Silicon): CPU ROOT-GNN development and tests
+uv sync --dev --extra root-gnn
+
+# Linux x86_64 with an NVIDIA GPU: validated ROOT-GNN development
+uv sync --dev --extra root-gnn
+```
+
+The core package can be installed without DGL when only shared data or task
+code is needed. ROOT-GNN models, graph construction, and ROOT-GNN parity tests
+require the `root-gnn` extra. On Linux x86_64, it uses the validated CUDA 12.1
+wheels configured in `pyproject.toml`; a compatible NVIDIA driver is still
+required. On Apple Silicon macOS, it installs the CPU DGL wheel, supporting
+local graph/cache development. The default ROOT-GNN backend performs training
+with native PyTorch graph tensors, so it runs on Apple MPS, NVIDIA CUDA, and
+CPU; DGL remains a cache and legacy-compatibility adapter. Do not add
+site-specific CUDA, Slurm, or filesystem paths to model or task configuration.
+
+Use the MPS profile on an Apple Silicon Mac:
+
+```bash
+uv run gnn4colliders train environment=macos
+```
+
+## Data samples
+
+ROOT inputs are available from the
+[HWresearch/Delphes dataset](https://huggingface.co/datasets/HWresearch/Delphes).
+Download the 64-event smoke-test sample with the Hugging Face CLI:
+
+```bash
+hf download HWresearch/Delphes testing/ttH_NLO_64.root \
+  --repo-type dataset --local-dir data/raw
+```
+
+The sample is `data/raw/testing/ttH_NLO_64.root`, has tree name `output`, and
+is suitable for checking the prepare/train workflow. The dataset also provides
+larger process-specific ROOT samples under `samples/`, derived datasets under
+`derived/`, and analysis-specific ntuples under `analyses/`. These data are
+intentionally ignored by Git; inspect a selected ROOT file's tree and branches
+before writing its preparation configuration.
+
+## Quick start
+
+Prepare a graph cache from a ROOT tree. The feature specifications below are
+illustrative placeholders; replace them with the branches in the input tree.
+The full preparation interface is documented in
+[`docs/configuration.md`](docs/configuration.md).
+
+```bash
+uv run gnn4colliders prepare \
+  data.files=[data/events.root] \
+  data.tree_name=Events \
+  data.cache.path=cache/events.pt \
+  'data.feature_branches=[["jet_pt"],["jet_eta"],["jet_phi"],CALC_E,[1.0],[0.0],NODE_TYPE]' \
+  data.object_types=[vector] \
+  data.scales=[1,1,1,1,1,1,1]
+```
+
+Train, evaluate, and predict from that cache:
+
+```bash
+uv run gnn4colliders train \
+  data.cache.path=cache/events.pt \
+  trainer.max_epochs=1 \
+  environment.output_root=outputs/pretraining_multiclass
+
+uv run gnn4colliders evaluate \
+  data.cache.path=cache/events.pt \
+  inference.checkpoint=outputs/pretraining_multiclass/checkpoints/epoch_0000.pt
+
+uv run gnn4colliders predict \
+  data.cache.path=cache/events.pt \
+  inference.checkpoint=outputs/pretraining_multiclass/checkpoints/epoch_0000.pt \
+  inference.output=outputs/pretraining_multiclass/predictions.npz
+```
+
+For a dependency-complete, temporary-data version of this flow, run
+`uv run python scripts/dev/smoke_end_to_end.py`.
+
+## Core concepts
+
+`EventSample` is the architecture-neutral event boundary. It contains the
+selected `objects`, `label`, `global_features`, and named `EventMetadata`.
+Metadata includes `fold`, `weight`, and stable `sample_id`; callers should not
+interpret public `tracking[:, N]` columns. Legacy tracking mappings exist only
+at compatibility boundaries.
+
+The ROOT-GNN adapter converts shared features to a directed, fully connected
+graph with no self-loops: an event with `N` nodes has `N * (N - 1)` edges.
+Node columns are, in order, `pt`, `eta`, `phi`, `energy`, `btag`, `charge`,
+and `node_type`. Edge columns are `deta`, wrapped `dphi`, and `dR`.
+Object collections are concatenated in configured object-type order. The
+compatibility energy is `pt * cosh(eta)` before per-column scaling.
+
+`GraphSampleCache` stores processed graph samples and schema metadata. It is a
+Level-2 graph cache, not the universal event cache. Feature, graph, and cache
+schema versions are checked when loading; incompatible versions fail before
+training.
+
+## ROOT-GNN training and transfer
+
+`EdgeNetwork` encodes node, edge, and global features, performs iterative
+edge/node/global message passing, decodes a graph representation, and applies
+the classifier. Its output is raw logits; sigmoid or softmax is task-owned.
+
+Multiclass pretraining uses the semantic `model=root_gnn/edge_network` and
+`task=pretraining_multiclass` groups:
+
+```bash
+uv run gnn4colliders train \
+  data.cache.path=cache/events.pt \
+  model=root_gnn/edge_network task=pretraining_multiclass \
+  trainer.max_epochs=20 data.batch_size=64 \
+  environment.output_root=outputs/pretraining_multiclass
+```
+
+Fine-tuning is a separate workflow. It loads a pretrained backbone, replaces
+the classifier, and creates a new task/head optimizer:
+
+```bash
+uv run gnn4colliders train \
+  data.cache.path=cache/target.pt \
+  model=root_gnn/fine_tuned_edge_network \
+  task=binary_classification \
+  checkpoint.pretrained=/path/to/pretrained.pt \
+  model.freeze_backbone=true \
+  trainer.max_epochs=10
+```
+
+Set `model.freeze_backbone=false` to train the reused backbone as well.
+Transfer learning is not resume training:
+
+| Workflow | Meaning | Restored state |
+| --- | --- | --- |
+| Resume | Continue the same task/run | model, optimizer, scheduler, trainer, early stopping, and RNG state when present |
+| Transfer | Start a new task from a pretrained backbone | model weights only; new classifier and optimizer |
+
+Resume example:
+
+```bash
+uv run gnn4colliders train \
+  data.cache.path=cache/events.pt \
+  checkpoint.resume=outputs/pretraining_multiclass/checkpoints/epoch_0000.pt \
+  trainer.max_epochs=20
+```
+
+Validation is evaluated each epoch and drives scheduling/early stopping;
+`test` remains held out. Evaluation computes task metrics over the complete
+selected split, including weighted ROC AUC where defined:
+
+```bash
+uv run gnn4colliders evaluate \
+  data.cache.path=cache/events.pt \
+  inference.split=test \
+  inference.checkpoint=/path/to/checkpoint.pt
+```
+
+Prediction writes a named compressed NPZ. Labeled data includes `labels`;
+`fold` and `weight` are included when available. Every result includes
+`sample_id`, `logits`, `scores`, and `predictions`:
+
+```bash
+uv run gnn4colliders predict \
+  data.cache.path=cache/events.pt \
+  inference.checkpoint=/path/to/checkpoint.pt \
+  inference.output=outputs/predictions.npz
+```
+
+Optional Python-level ROOT writing is provided by
+`gnn4colliders.inference.write_root_scores`. It clones the selected tree,
+adds `score` (or `score_class_N`), and writes `selection_pass`; IDs ending in
+`:<entry>` preserve alignment and unselected entries receive NaN scores. The
+CLI currently exposes NPZ output only.
+
+The supported legacy checkpoint, metadata, and output boundary is documented
+in [`docs/compatibility.md`](docs/compatibility.md). New code should use named
+metadata fields; positional tracking is accepted only by the explicit
+compatibility adapter.
+
+### ONNX export
+
+Install the optional export dependencies and export a prepared graph-cache
+checkpoint with numerical ONNX validation:
+
+```bash
+uv sync --extra root-gnn --extra onnx
+uv run gnn4colliders export \
+  export.checkpoint=/path/to/checkpoint.pt \
+  export.output=model.onnx \
+  data.cache.path=/path/to/graph-cache.pt
+```
+
+The model accepts processed graph tensors and returns raw logits. See
+[`docs/export.md`](docs/export.md) for the tensor contract and limitations.
+
+## Configuration and environments
+
+Hydra groups are `data`, `model`, `task`, `trainer`, `checkpoint`,
+`inference`, `environment`, and `distributed`. Use configuration for a new
+experiment and Python for new behavior. Examples:
+
+```bash
+uv run gnn4colliders train trainer.max_epochs=50 data.batch_size=64
+uv run gnn4colliders train environment=perlmutter environment.device=cuda
+uv run gnn4colliders train distributed=ddp environment=perlmutter
+```
+
+Each run writes a resolved configuration to
+`<environment.output_root>/resolved_config.yaml`. See
+[`docs/configuration.md`](docs/configuration.md) for the group reference and
+[`docs/perlmutter.md`](docs/perlmutter.md) for launch examples.
+
+## Distributed execution and reproducibility
+
+Launch DDP with `torchrun` or the provided Slurm wrappers. `data.batch_size`
+and `data.num_workers` are per process, so the ordinary effective batch size
+is `batch_size * world_size`. Training shards may be padded for equal steps;
+validation and prediction are unpadded. Rank 0 writes shared checkpoints,
+configs, and predictions, and metrics/results are gathered across ranks.
+
+The configured seed controls initialization and deterministic local loader
+ordering; distributed process seeds are rank-offset and samplers use
+`set_epoch`. CPU runs are reproducible for fixed inputs and environment. GPU
+kernels, DGL, and distributed scheduling can remain nondeterministic, so the
+project does not promise bitwise GPU reproducibility.
+
+## Development and validation
+
+```bash
+uv run pytest
+uv run pytest tests/unit
+GNN4COLLIDERS_REQUIRE_ROOT_GNN=1 uv run pytest tests/parity -v
+uv run ruff check .
+uv run ruff format --check .
+uv run python benchmarks/benchmark_preprocessing.py
+uv run python benchmarks/benchmark_training.py --device cpu
+```
+
+Unit tests cover isolated components, integration tests cover small workflows,
+and parity tests compare deterministic behavior with the frozen legacy
+reference. Performance guidance and measured caveats are in
+[`docs/performance.md`](docs/performance.md) and
+[`benchmarks/README.md`](benchmarks/README.md).
+See [`docs/testing.md`](docs/testing.md) for test layers, optional dependency
+markers, and package smoke validation.
+
+## Architecture and migration status
+
+See [`docs/architecture.md`](docs/architecture.md) for responsibility
+boundaries and the future sequence-model extension point. See
+[`docs/migration.md`](docs/migration.md) for the migration matrix,
+intentional redesigns, compatibility limits, and deferred work.
+
+ROOT-GNN v1 covers ROOT preparation, validated feature/graph/model/task
+behavior, training, fine-tuning, checkpoint resume, evaluation, prediction,
+single-process/DDP execution, and validated ONNX export. Streaming distributed
+output, legacy cleanup, and ROOT-Transformer remain follow-up work.

paper.tar.gz

@@ -0,0 +1,3 @@
+version https://git-lfs.github.com/spec/v1
+oid sha256:9587a5b67b73dfc0f88b2a641b98410623a592d47cedd8fc71b35d28e9e1dfbc
+size 142839