# heidelberg-hepml/lorentz-gatr architecture

> Architecture diagram of the GitHub repository heidelberg-hepml/lorentz-gatr, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-10-06). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/heidelberg-hepml/lorentz-gatr
- Repository: https://github.com/heidelberg-hepml/lorentz-gatr

## Overview

L-GATr is a Lorentz-equivariant geometric-algebra transformer library, accompanied by high-energy-physics experiments for amplitude regression, jet tagging, and event generation. The user workflow is to configure and launch an experiment, prepare its task-specific data, train or evaluate a model, and inspect logged results; the README also describes using the network and geometric-object interfaces directly. The graph includes the principal model-building layers and the documented experiment branches. Some subsystem links rely on the README or SOURCE INDEX references because their implementations were not excerpted.

Main entry points: [`experiments/base_experiment.py`](https://github.com/heidelberg-hepml/lorentz-gatr/blob/main/experiments/base_experiment.py) (Experiment runtime), [`gatr/layers/gatr_block.py`](https://github.com/heidelberg-hepml/lorentz-gatr/blob/main/gatr/layers/gatr_block.py) (Transformer block), [`run.py`](https://github.com/heidelberg-hepml/lorentz-gatr/blob/main/run.py) (Experiment launcher), [`experiments/tagging/experiment.py`](https://github.com/heidelberg-hepml/lorentz-gatr/blob/main/experiments/tagging/experiment.py) (Jet tagging)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_entry["Experiment entry"]
  node_launcher["Experiment launcher<br/>[run.py]"]
end

subgraph group_tasks["Physics experiments"]
  node_amplitudes["Amplitude regression<br/>[experiment.py]"]
  node_amplitude_data["Amplitude data<br/>[dataset.py]"]
  node_tagging["Jet tagging<br/>[experiment.py]"]
  node_tag_data["Tagging data<br/>[dataset.py]"]
  node_tag_embedding["Jet embedding<br/>[embedding.py]"]
  node_miniweaver["MiniWeaver ingestion<br/>[dataset.py]"]
  node_eventgen["Event generation<br/>[experiment.py]"]
  node_event_data["Event data<br/>[dataset.py]"]
  node_event_transforms["Event transforms<br/>[transforms.py]"]
end

subgraph group_representation["Geometric representation"]
  node_interfaces["GA interfaces<br/>[vector.py]"]
  node_spurions["Symmetry references<br/>[spurions.py]"]
end

subgraph group_network["Equivariant network"]
  node_gatr["GATr network<br/>[gatr.py]"]
  node_axial_gatr["Axial GATr<br/>[axial_gatr.py]"]
  node_gatr_block["Transformer block<br/>[gatr_block.py]"]
  node_attention_config["Attention configuration<br/>[config.py]"]
  node_attention_primitives["Attention primitives<br/>[attention.py]"]
  node_geo_mlp["Geometric MLP<br/>[mlp.py]"]
  node_geo_bilinears["Geometric bilinears"]
  node_equi_linear["Equivariant linear layers<br/>[linear.py]"]
  node_linear_primitives["Linear primitives<br/>[linear.py]"]
  node_tensor_utils["Tensor utilities<br/>[einsum.py]"]
end

subgraph group_runtime["Training and tracking"]
  node_base_experiment["Experiment runtime<br/>[base_experiment.py]"]
  node_logger["Logging<br/>[logger.py]"]
  node_mlflow["Run tracking<br/>[mlflow.py]"]
end

node_researcher(("Researcher"))
node_dataset_host(("Dataset host"))
node_tracking_store[("Tracking store")]

node_researcher -->|"launches"| node_launcher
node_launcher -->|"dispatches"| node_amplitudes
node_launcher -->|"dispatches"| node_tagging
node_launcher -->|"dispatches"| node_eventgen
node_dataset_host -->|"provides data"| node_amplitude_data
node_dataset_host -->|"provides data"| node_tag_data
node_dataset_host -->|"provides data"| node_event_data
node_amplitudes -->|"loads"| node_amplitude_data
node_tagging -->|"uses"| node_tag_data
node_tagging -->|"uses"| node_tag_embedding
node_tag_embedding -->|"imports from"| node_tag_data
node_miniweaver -.->|"supports ingestion"| node_tag_data
node_eventgen -->|"loads"| node_event_data
node_eventgen -.->|"uses"| node_event_transforms
node_amplitudes -->|"extends"| node_base_experiment
node_tagging -->|"extends"| node_base_experiment
node_eventgen -->|"extends"| node_base_experiment
node_base_experiment -->|"logs through"| node_logger
node_base_experiment -->|"tracks runs"| node_mlflow
node_mlflow -->|"uses"| node_logger
node_mlflow -->|"persists to"| node_tracking_store
node_tag_embedding -->|"embeds vectors"| node_interfaces
node_tag_embedding -->|"embeds references"| node_spurions
node_interfaces -->|"provides exports"| node_spurions
node_gatr -->|"builds from"| node_gatr_block
node_axial_gatr -->|"builds from"| node_gatr_block
node_gatr_block -->|"configures"| node_attention_config
node_gatr_block -->|"uses"| node_geo_mlp
node_geo_mlp -->|"uses"| node_geo_bilinears
node_geo_mlp -->|"uses"| node_equi_linear
node_equi_linear -->|"calls"| node_linear_primitives
node_linear_primitives -->|"uses"| node_tensor_utils
node_gatr_block -.->|"attention operations"| node_attention_primitives
node_base_experiment -.->|"instantiates configured model"| node_gatr

click node_launcher "https://github.com/heidelberg-hepml/lorentz-gatr/blob/main/run.py"
click node_amplitudes "https://github.com/heidelberg-hepml/lorentz-gatr/blob/main/experiments/amplitudes/experiment.py"
click node_amplitude_data "https://github.com/heidelberg-hepml/lorentz-gatr/blob/main/experiments/amplitudes/dataset.py"
click node_tagging "https://github.com/heidelberg-hepml/lorentz-gatr/blob/main/experiments/tagging/experiment.py"
click node_tag_data "https://github.com/heidelberg-hepml/lorentz-gatr/blob/main/experiments/tagging/dataset.py"
click node_tag_embedding "https://github.com/heidelberg-hepml/lorentz-gatr/blob/main/experiments/tagging/embedding.py"
click node_miniweaver "https://github.com/heidelberg-hepml/lorentz-gatr/blob/main/experiments/tagging/miniweaver/dataset.py"
click node_eventgen "https://github.com/heidelberg-hepml/lorentz-gatr/blob/main/experiments/eventgen/experiment.py"
click node_event_data "https://github.com/heidelberg-hepml/lorentz-gatr/blob/main/experiments/eventgen/dataset.py"
click node_event_transforms "https://github.com/heidelberg-hepml/lorentz-gatr/blob/main/experiments/eventgen/transforms.py"
click node_base_experiment "https://github.com/heidelberg-hepml/lorentz-gatr/blob/main/experiments/base_experiment.py"
click node_logger "https://github.com/heidelberg-hepml/lorentz-gatr/blob/main/experiments/logger.py"
click node_mlflow "https://github.com/heidelberg-hepml/lorentz-gatr/blob/main/experiments/mlflow.py"
click node_interfaces "https://github.com/heidelberg-hepml/lorentz-gatr/blob/main/gatr/interface/vector.py"
click node_spurions "https://github.com/heidelberg-hepml/lorentz-gatr/blob/main/gatr/interface/spurions.py"
click node_gatr "https://github.com/heidelberg-hepml/lorentz-gatr/blob/main/gatr/nets/gatr.py"
click node_axial_gatr "https://github.com/heidelberg-hepml/lorentz-gatr/blob/main/gatr/nets/axial_gatr.py"
click node_gatr_block "https://github.com/heidelberg-hepml/lorentz-gatr/blob/main/gatr/layers/gatr_block.py"
click node_attention_config "https://github.com/heidelberg-hepml/lorentz-gatr/blob/main/gatr/layers/attention/config.py"
click node_attention_primitives "https://github.com/heidelberg-hepml/lorentz-gatr/blob/main/gatr/primitives/attention.py"
click node_geo_mlp "https://github.com/heidelberg-hepml/lorentz-gatr/blob/main/gatr/layers/mlp/mlp.py"
click node_geo_bilinears "https://github.com/heidelberg-hepml/lorentz-gatr/blob/main/gatr/layers/mlp/geometric_bilinears.py"
click node_equi_linear "https://github.com/heidelberg-hepml/lorentz-gatr/blob/main/gatr/layers/linear.py"
click node_linear_primitives "https://github.com/heidelberg-hepml/lorentz-gatr/blob/main/gatr/primitives/linear.py"
click node_tensor_utils "https://github.com/heidelberg-hepml/lorentz-gatr/blob/main/gatr/utils/einsum.py"

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_launcher toneBlue
class node_amplitudes,node_amplitude_data,node_tagging,node_tag_data,node_tag_embedding,node_miniweaver,node_eventgen,node_event_data,node_event_transforms,node_tracking_store toneAmber
class node_interfaces,node_spurions toneMint
class node_gatr,node_axial_gatr,node_gatr_block,node_attention_config,node_attention_primitives,node_geo_mlp,node_geo_bilinears,node_equi_linear,node_linear_primitives,node_tensor_utils toneRose
class node_base_experiment,node_logger,node_mlflow,node_researcher,node_dataset_host toneIndigo
```

## Components

### Experiment entry

- [Experiment launcher](https://github.com/heidelberg-hepml/lorentz-gatr/blob/main/run.py): `run.py`

### Physics experiments

- [Amplitude regression](https://github.com/heidelberg-hepml/lorentz-gatr/blob/main/experiments/amplitudes/experiment.py): `experiments/amplitudes/experiment.py`
- [Amplitude data](https://github.com/heidelberg-hepml/lorentz-gatr/blob/main/experiments/amplitudes/dataset.py): `experiments/amplitudes/dataset.py`
- [Jet tagging](https://github.com/heidelberg-hepml/lorentz-gatr/blob/main/experiments/tagging/experiment.py): `experiments/tagging/experiment.py`
- [Tagging data](https://github.com/heidelberg-hepml/lorentz-gatr/blob/main/experiments/tagging/dataset.py): `experiments/tagging/dataset.py`
- [Jet embedding](https://github.com/heidelberg-hepml/lorentz-gatr/blob/main/experiments/tagging/embedding.py): `experiments/tagging/embedding.py`
- [MiniWeaver ingestion](https://github.com/heidelberg-hepml/lorentz-gatr/blob/main/experiments/tagging/miniweaver/dataset.py): `experiments/tagging/miniweaver/dataset.py`
- [Event generation](https://github.com/heidelberg-hepml/lorentz-gatr/blob/main/experiments/eventgen/experiment.py): `experiments/eventgen/experiment.py`
- [Event data](https://github.com/heidelberg-hepml/lorentz-gatr/blob/main/experiments/eventgen/dataset.py): `experiments/eventgen/dataset.py`
- [Event transforms](https://github.com/heidelberg-hepml/lorentz-gatr/blob/main/experiments/eventgen/transforms.py): `experiments/eventgen/transforms.py`

### Geometric representation

- [GA interfaces](https://github.com/heidelberg-hepml/lorentz-gatr/blob/main/gatr/interface/vector.py): `gatr/interface/vector.py`
- [Symmetry references](https://github.com/heidelberg-hepml/lorentz-gatr/blob/main/gatr/interface/spurions.py): `gatr/interface/spurions.py`

### Equivariant network

- [GATr network](https://github.com/heidelberg-hepml/lorentz-gatr/blob/main/gatr/nets/gatr.py): `gatr/nets/gatr.py`
- [Axial GATr](https://github.com/heidelberg-hepml/lorentz-gatr/blob/main/gatr/nets/axial_gatr.py): `gatr/nets/axial_gatr.py`
- [Transformer block](https://github.com/heidelberg-hepml/lorentz-gatr/blob/main/gatr/layers/gatr_block.py): `gatr/layers/gatr_block.py`
- [Attention configuration](https://github.com/heidelberg-hepml/lorentz-gatr/blob/main/gatr/layers/attention/config.py): `gatr/layers/attention/config.py`
- [Attention primitives](https://github.com/heidelberg-hepml/lorentz-gatr/blob/main/gatr/primitives/attention.py): `gatr/primitives/attention.py`
- [Geometric MLP](https://github.com/heidelberg-hepml/lorentz-gatr/blob/main/gatr/layers/mlp/mlp.py): `gatr/layers/mlp/mlp.py`
- [Geometric bilinears](https://github.com/heidelberg-hepml/lorentz-gatr/blob/main/gatr/layers/mlp/geometric_bilinears.py): `gatr/layers/mlp/geometric_bilinears.py`
- [Equivariant linear layers](https://github.com/heidelberg-hepml/lorentz-gatr/blob/main/gatr/layers/linear.py): `gatr/layers/linear.py`
- [Linear primitives](https://github.com/heidelberg-hepml/lorentz-gatr/blob/main/gatr/primitives/linear.py): `gatr/primitives/linear.py`
- [Tensor utilities](https://github.com/heidelberg-hepml/lorentz-gatr/blob/main/gatr/utils/einsum.py): `gatr/utils/einsum.py`

### Training and tracking

- [Experiment runtime](https://github.com/heidelberg-hepml/lorentz-gatr/blob/main/experiments/base_experiment.py): `experiments/base_experiment.py`
- [Logging](https://github.com/heidelberg-hepml/lorentz-gatr/blob/main/experiments/logger.py): `experiments/logger.py`
- [Run tracking](https://github.com/heidelberg-hepml/lorentz-gatr/blob/main/experiments/mlflow.py): `experiments/mlflow.py`

### Other components

- **Researcher**
- **Dataset host**
- **Tracking store**

## Connections

- Researcher → Experiment launcher: launches (evidence: `README.md`)
- Experiment launcher → Amplitude regression: dispatches (evidence: `run.py`)
- Experiment launcher → Jet tagging: dispatches (evidence: `run.py`)
- Experiment launcher → Event generation: dispatches (evidence: `run.py`)
- Dataset host → Amplitude data: provides data (evidence: `README.md`)
- Dataset host → Tagging data: provides data (evidence: `README.md`)
- Dataset host → Event data: provides data (evidence: `README.md`)
- Amplitude regression → Amplitude data: loads (evidence: `experiments/amplitudes/experiment.py`)
- Jet tagging → Tagging data: uses (evidence: `experiments/tagging/experiment.py`)
- Jet tagging → Jet embedding: uses (evidence: `experiments/tagging/experiment.py`)
- Jet embedding → Tagging data: imports from (evidence: `experiments/tagging/embedding.py`)
- MiniWeaver ingestion → Tagging data: supports ingestion
- Event generation → Event data: loads (evidence: `experiments/eventgen/experiment.py`)
- Event generation → Event transforms: uses
- Amplitude regression → Experiment runtime: extends (evidence: `experiments/amplitudes/experiment.py`)
- Jet tagging → Experiment runtime: extends (evidence: `experiments/tagging/experiment.py`)
- Event generation → Experiment runtime: extends (evidence: `experiments/eventgen/experiment.py`)
- Experiment runtime → Logging: logs through (evidence: `experiments/base_experiment.py`)
- Experiment runtime → Run tracking: tracks runs (evidence: `experiments/base_experiment.py`)
- Run tracking → Logging: uses (evidence: `experiments/mlflow.py`)
- Run tracking → Tracking store: persists to (evidence: `README.md`)
- Jet embedding → GA interfaces: embeds vectors (evidence: `experiments/tagging/embedding.py`)
- Jet embedding → Symmetry references: embeds references (evidence: `experiments/tagging/embedding.py`)
- GA interfaces → Symmetry references: provides exports (evidence: `gatr/interface/__init__.py`)
- GATr network → Transformer block: builds from (evidence: `gatr/nets/gatr.py`)
- Axial GATr → Transformer block: builds from (evidence: `gatr/nets/axial_gatr.py`)
- Transformer block → Attention configuration: configures (evidence: `gatr/layers/gatr_block.py`)
- Transformer block → Geometric MLP: uses (evidence: `gatr/layers/gatr_block.py`)
- Geometric MLP → Geometric bilinears: uses (evidence: `gatr/layers/mlp/mlp.py`)
- Geometric MLP → Equivariant linear layers: uses (evidence: `gatr/layers/mlp/mlp.py`)
- Equivariant linear layers → Linear primitives: calls (evidence: `gatr/layers/linear.py`)
- Linear primitives → Tensor utilities: uses (evidence: `gatr/primitives/linear.py`)
- Transformer block → Attention primitives: attention operations
- Experiment runtime → GATr network: instantiates configured model
