# joker383627/for_hep architecture

> Architecture diagram of the GitHub repository joker383627/for_hep, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-09-26). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/joker383627/for_hep
- Repository: https://github.com/joker383627/for_hep

## Overview

This repository contains a particle-physics analysis notebook collection and a PyTorch top-versus-QCD jet classifier. The classifier workflow reads ROOT jet data, prepares padded and standardized particle inputs, trains a particle-attention model, and evaluates classification performance. The model internals and training/evaluation behavior are supported by sampled source; notebook roles are inferred only from their filenames because their contents and the README were not provided.

Main entry points: [`top_tagger/models.py`](https://github.com/joker383627/for_hep/blob/main/top_tagger/models.py) (Class logits), [`top_tagger/train.py`](https://github.com/joker383627/for_hep/blob/main/top_tagger/train.py) (Evaluation metrics), [`top_tagger/preprocess.py`](https://github.com/joker383627/for_hep/blob/main/top_tagger/preprocess.py) (Feature preparation), [`top_tagger/top_tagger.ipynb`](https://github.com/joker383627/for_hep/blob/main/top_tagger/top_tagger.ipynb) (Tagger workflow)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_data["Jet data preparation"]
  node_prepare["Feature preparation<br/>[preprocess.py]"]
  node_dataset["Jet dataset<br/>[preprocess.py]"]
  node_loaders["Data loaders<br/>[preprocess.py]"]
end

subgraph group_model["Classifier model"]
  node_transformer["Particle transformer<br/>[models.py]"]
  node_pairwise["Pairwise features<br/>[models.py]"]
  node_particle_attention["Particle attention<br/>[models.py]"]
  node_class_attention["Class attention<br/>[models.py]"]
  node_classifier["Class logits<br/>[models.py]"]
end

subgraph group_training["Training and evaluation"]
  node_trainer["Training loop<br/>[train.py]"]
  node_evaluation["Evaluation metrics<br/>[train.py]"]
  node_rejection["Background rejection<br/>[train.py]"]
end

subgraph group_analysis["Physics analysis"]
  node_tagger_notebook["Tagger workflow<br/>[top_tagger.ipynb]"]
  node_mining_notebook["Data mining<br/>[data_mining.ipynb]"]
  node_smeft_notebook["SM vs SMEFT<br/>[sm_vs_smeft.ipynb]"]
end

node_analyst(("Analyst"))
node_root[("ROOT jet data")]

node_root -->|"reads ROOT"| node_prepare
node_prepare -->|"builds tensors"| node_dataset
node_dataset -->|"splits batches"| node_loaders
node_trainer -->|"consumes batches"| node_loaders
node_trainer -->|"trains model"| node_classifier
node_trainer -->|"evaluates model"| node_evaluation
node_evaluation -->|"scores batches"| node_classifier
node_evaluation -->|"provides scores"| node_rejection
node_classifier -->|"computes interactions"| node_pairwise
node_classifier -->|"dispatches embeddings"| node_particle_attention
node_classifier -->|"dispatches embeddings"| node_class_attention
node_classifier -->|"returns logits"| node_evaluation
node_analyst -->|"uses"| node_tagger_notebook
node_analyst -->|"uses"| node_mining_notebook
node_analyst -->|"uses"| node_smeft_notebook

click node_prepare "https://github.com/joker383627/for_hep/blob/main/top_tagger/preprocess.py"
click node_dataset "https://github.com/joker383627/for_hep/blob/main/top_tagger/preprocess.py"
click node_loaders "https://github.com/joker383627/for_hep/blob/main/top_tagger/preprocess.py"
click node_transformer "https://github.com/joker383627/for_hep/blob/main/top_tagger/models.py"
click node_pairwise "https://github.com/joker383627/for_hep/blob/main/top_tagger/models.py"
click node_particle_attention "https://github.com/joker383627/for_hep/blob/main/top_tagger/models.py"
click node_class_attention "https://github.com/joker383627/for_hep/blob/main/top_tagger/models.py"
click node_classifier "https://github.com/joker383627/for_hep/blob/main/top_tagger/models.py"
click node_trainer "https://github.com/joker383627/for_hep/blob/main/top_tagger/train.py"
click node_evaluation "https://github.com/joker383627/for_hep/blob/main/top_tagger/train.py"
click node_rejection "https://github.com/joker383627/for_hep/blob/main/top_tagger/train.py"
click node_tagger_notebook "https://github.com/joker383627/for_hep/blob/main/top_tagger/top_tagger.ipynb"
click node_mining_notebook "https://github.com/joker383627/for_hep/blob/main/data_analysis/data_mining.ipynb"
click node_smeft_notebook "https://github.com/joker383627/for_hep/blob/main/data_analysis/sm_vs_smeft.ipynb"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_prepare,node_dataset,node_loaders toneBlue
class node_transformer,node_pairwise,node_particle_attention,node_class_attention,node_classifier,node_root toneAmber
class node_trainer,node_evaluation,node_rejection toneMint
class node_tagger_notebook,node_mining_notebook,node_smeft_notebook toneRose
class node_analyst toneIndigo
```

## Components

### Jet data preparation

- [Feature preparation](https://github.com/joker383627/for_hep/blob/main/top_tagger/preprocess.py): `top_tagger/preprocess.py`
- [Jet dataset](https://github.com/joker383627/for_hep/blob/main/top_tagger/preprocess.py): `top_tagger/preprocess.py`
- [Data loaders](https://github.com/joker383627/for_hep/blob/main/top_tagger/preprocess.py): `top_tagger/preprocess.py`

### Classifier model

- [Particle transformer](https://github.com/joker383627/for_hep/blob/main/top_tagger/models.py): `top_tagger/models.py`
- [Pairwise features](https://github.com/joker383627/for_hep/blob/main/top_tagger/models.py): `top_tagger/models.py`
- [Particle attention](https://github.com/joker383627/for_hep/blob/main/top_tagger/models.py): `top_tagger/models.py`
- [Class attention](https://github.com/joker383627/for_hep/blob/main/top_tagger/models.py): `top_tagger/models.py`
- [Class logits](https://github.com/joker383627/for_hep/blob/main/top_tagger/models.py): `top_tagger/models.py`

### Training and evaluation

- [Training loop](https://github.com/joker383627/for_hep/blob/main/top_tagger/train.py): `top_tagger/train.py`
- [Evaluation metrics](https://github.com/joker383627/for_hep/blob/main/top_tagger/train.py): `top_tagger/train.py`
- [Background rejection](https://github.com/joker383627/for_hep/blob/main/top_tagger/train.py): `top_tagger/train.py`

### Physics analysis

- [Tagger workflow](https://github.com/joker383627/for_hep/blob/main/top_tagger/top_tagger.ipynb): `top_tagger/top_tagger.ipynb`
- [Data mining](https://github.com/joker383627/for_hep/blob/main/data_analysis/data_mining.ipynb): `data_analysis/data_mining.ipynb`
- [SM vs SMEFT](https://github.com/joker383627/for_hep/blob/main/data_analysis/sm_vs_smeft.ipynb): `data_analysis/sm_vs_smeft.ipynb`

### Other components

- **Analyst**
- **ROOT jet data**

## Connections

- ROOT jet data → Feature preparation: reads ROOT
- Feature preparation → Jet dataset: builds tensors
- Jet dataset → Data loaders: splits batches
- Training loop → Data loaders: consumes batches
- Training loop → Class logits: trains model
- Training loop → Evaluation metrics: evaluates model
- Evaluation metrics → Class logits: scores batches
- Evaluation metrics → Background rejection: provides scores
- Class logits → Pairwise features: computes interactions
- Class logits → Particle attention: dispatches embeddings
- Class logits → Class attention: dispatches embeddings
- Class logits → Evaluation metrics: returns logits
- Analyst → Tagger workflow: uses
- Analyst → Data mining: uses
- Analyst → SM vs SMEFT: uses