# christy62/llm-g-2 architecture

> Architecture diagram of the GitHub repository christy62/llm-g-2, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-11-19). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/christy62/llm-g-2
- Repository: https://github.com/christy62/llm-g-2

## Overview

This repository is a research prototype for reconstructing positron tracks by translating detector-hit sequences into decay-vertex and momentum parameters. Its visible workflow spans simulated decay generation, helix propagation to detector hits, optional strip digitization, conversion of event data into training examples, and LLM fine-tuning. Separate conversion scripts cover alternate hit formats. The README describes model-generated forward predictions and track-match results, but places inference in an external Colab notebook. Some data handoffs and the inference implementation are not established by the sampled source, so those connections are omitted.

Main entry points: [`generate_hits.py`](https://github.com/christy62/llm-g-2/blob/main/generate_hits.py) (Hit propagation), [`fine_tune_llm.py`](https://github.com/christy62/llm-g-2/blob/main/fine_tune_llm.py) (LLM fine-tuning), [`generate_decay_details.py`](https://github.com/christy62/llm-g-2/blob/main/generate_decay_details.py) (Decay generation), [`plot_helix.py`](https://github.com/christy62/llm-g-2/blob/main/plot_helix.py) (Track plotting)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_simulation["Event simulation"]
  node_decay["Decay generation"]
  node_hitgen["Hit propagation<br/>[generate_hits.py]"]
  node_mcs["Scattering propagation<br/>[hit_details_mcs.py]"]
end

subgraph group_encoding["Hit encoding"]
  node_stripid["Strip mapping<br/>[strip_id.py]"]
  node_vane["Strip tokenization"]
  node_csvjson["MCS dataset conversion<br/>[csv_to_json.py]"]
  node_newjson["Random-hit conversion<br/>[new_json.py]"]
  node_g4json["Geant4 conversion<br/>[g4_json.py]"]
end

subgraph group_learning["LLM training"]
  node_training["LLM fine-tuning<br/>[fine_tune_llm.py]"]
  node_model["Trained model<br/>[fine_tune_llm.py]"]
end

subgraph group_analysis["Validation and results"]
  node_eventformat["Forward event format<br/>[gen_event.py]"]
  node_plot["Track plotting<br/>[plot_helix.py]"]
end

node_researcher(("Researcher"))
node_colab["Inference notebook"]

node_researcher -->|"generates events"| node_decay
node_researcher -->|"generates hits"| node_hitgen
node_researcher -->|"trains model"| node_training
node_training -->|"produces"| node_model
node_model -.->|"inference available"| node_colab
node_hitgen -.->|"visualizes tracks"| node_plot

click node_decay "https://github.com/christy62/llm-g-2/blob/main/generate_decay_details.py"
click node_hitgen "https://github.com/christy62/llm-g-2/blob/main/generate_hits.py"
click node_mcs "https://github.com/christy62/llm-g-2/blob/main/hit_details_mcs.py"
click node_stripid "https://github.com/christy62/llm-g-2/blob/main/strip_id.py"
click node_vane "https://github.com/christy62/llm-g-2/blob/main/vane_sensor_strip.py"
click node_csvjson "https://github.com/christy62/llm-g-2/blob/main/csv_to_json.py"
click node_newjson "https://github.com/christy62/llm-g-2/blob/main/new_json.py"
click node_g4json "https://github.com/christy62/llm-g-2/blob/main/g4_json.py"
click node_training "https://github.com/christy62/llm-g-2/blob/main/fine_tune_llm.py"
click node_eventformat "https://github.com/christy62/llm-g-2/blob/main/gen_event.py"
click node_plot "https://github.com/christy62/llm-g-2/blob/main/plot_helix.py"
click node_model "https://github.com/christy62/llm-g-2/blob/main/fine_tune_llm.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_decay,node_hitgen,node_mcs toneBlue
class node_stripid,node_vane,node_csvjson,node_newjson,node_g4json toneAmber
class node_training,node_model toneMint
class node_eventformat,node_plot toneRose
class node_researcher,node_colab toneIndigo
```

## Components

### Event simulation

- [Decay generation](https://github.com/christy62/llm-g-2/blob/main/generate_decay_details.py): `generate_decay_details.py`
- [Hit propagation](https://github.com/christy62/llm-g-2/blob/main/generate_hits.py): `generate_hits.py`
- [Scattering propagation](https://github.com/christy62/llm-g-2/blob/main/hit_details_mcs.py): `hit_details_mcs.py`

### Hit encoding

- [Strip mapping](https://github.com/christy62/llm-g-2/blob/main/strip_id.py): `strip_id.py`
- [Strip tokenization](https://github.com/christy62/llm-g-2/blob/main/vane_sensor_strip.py): `vane_sensor_strip.py`
- [MCS dataset conversion](https://github.com/christy62/llm-g-2/blob/main/csv_to_json.py): `csv_to_json.py`
- [Random-hit conversion](https://github.com/christy62/llm-g-2/blob/main/new_json.py): `new_json.py`
- [Geant4 conversion](https://github.com/christy62/llm-g-2/blob/main/g4_json.py): `g4_json.py`

### LLM training

- [LLM fine-tuning](https://github.com/christy62/llm-g-2/blob/main/fine_tune_llm.py): `fine_tune_llm.py`
- [Trained model](https://github.com/christy62/llm-g-2/blob/main/fine_tune_llm.py): `fine_tune_llm.py`

### Validation and results

- [Forward event format](https://github.com/christy62/llm-g-2/blob/main/gen_event.py): `gen_event.py`
- [Track plotting](https://github.com/christy62/llm-g-2/blob/main/plot_helix.py): `plot_helix.py`

### Other components

- **Researcher**
- **Inference notebook**

## Connections

- Researcher → Decay generation: generates events (evidence: `README.md`)
- Researcher → Hit propagation: generates hits (evidence: `README.md`)
- Researcher → LLM fine-tuning: trains model (evidence: `README.md`)
- LLM fine-tuning → Trained model: produces (evidence: `fine_tune_llm.py`)
- Trained model → Inference notebook: inference available (evidence: `README.md`)
- Hit propagation → Track plotting: visualizes tracks
