# google-deepmind/torax architecture

> Architecture diagram of the GitHub repository google-deepmind/torax, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-05-12). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/google-deepmind/torax
- Repository: https://github.com/google-deepmind/torax

## Overview

##### Project Type and Purpose
- TORAX is a command-line driven, Python-based scientific simulation library—not a web app. It exposes a CLI (`run_torax`) and Python API to run differentiable tokamak transport simulations built with JAX.
- Its core is a modular, domain-driven architecture: configuration → initialization → time-stepping loop → physics & numerical solvers → output.

##### Main Components
a. CLI / Entrypoint
- `run_simulation_main.py`, `simulation_app.py`, `sim.py`, console script `run_torax`
b. Configuration & Validation
- `torax/config/*`: argument parsing, runtime_params, numerics, plasma composition, profile conditions, uses Pydantic models
c. Data & Geometry
- `torax/data/third_party/geo/*`: equilibrium files (EQDSK, MAT)
- `torax/geometry/*`: loaders, providers, pydantic models
d. Core Simulation Orchestration
- `torax/orchestration/*`: build initial state, run_simulation loop, step_function
- `torax/state.py`: representation of simulation state
e. Time-Stepping
- `torax/stepper/*`: `linear_theta`, `predictor_corrector`, `nonlinear` methods, runtime_params, pydantic models
- `torax/time_step_calculator/*`: calculates dt (fixed, chi-based)
f. Numerical Solver & FVM
- `torax/fvm/*`: finite-volume operators, discrete system, solver blocks (Newton, optimizer)
- `torax/jax_utils.py`: JAX wrappers, auto-jit, vmap
g. Physics & Models
- `torax/physics/*`: collisional formulas, charge states, psi calculations, scaling laws
- `torax/neoclassical/*`, `torax/mhd/*`, `torax/sources/*`, `torax/transport_model/*`, `torax/pedestal_model/*`
h. Output & Post-Processing
- `torax/output_tools/*`: write netCDF (`state_history.nc`), post-processing fits
- `torax/plotting/*`: plotruns, config templates
i. Examples & Tutorials
- `torax/examples/*`, `torax/tutorials/*`

##### Relationships & Data Flow
- **Startup**: CLI invokes `run_simulation_main` → loads config → `config_loader` → Pydantic validation → runtime parameters
- **Initialization**: geometry & profile loaders populate initial `State` object
- **Time Loop**: `run_simulation` calls `step_function` repeatedly
└─ `step_function` uses `time_step_calculator` to pick dt
└─ invokes `stepper` (e.g. predictor-corrector)
└─ inside stepper: calls FVM solver, physics models, sources, transport models
└─ JAX `jit`/`grad` wrap all compute kernels for speed & differentiability
- **Output**: each step appends to in-memory history, final writes to netCDF via `output_tools`
- **Post**: optional live plotting via `plotting/plotruns` or offline analysis

##### Architectural Patterns & Principles
- **Modularity**: clear separation of concerns—config, geometry, physics, solver, orchestration, I/O
- **Domain-Driven Design**: each physics domain in its own subpackage
- **Dependency Injection**: config determines which model implementations to wire into orchestrator
- **Auto-Diff & JIT**: all compute kernels designed for JAX’s `jit` and `grad` to enable fast runs and differentiability

##### Elements
- **Annotations**: note “JAX jit/grad” and “Pydantic validation” on relevant modules

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% CLI & Config Layer
    subgraph "CLI & Config" 
        direction TB
        CLI["run_torax CLI"]:::entry
        RunMain["run_simulation_main.py"]:::entry
        SimApp["simulation_app.py"]:::entry
        Sim["sim.py"]:::entry
        CLI --> RunMain
        RunMain --> SimApp
        SimApp --> Sim
        ConfigLoader["Config Loader (Pydantic)"]:::entry
        Sim --> ConfigLoader
    end

    %% Initialization Layer
    subgraph "Initialization" 
        direction TB
        GeometryLoader["geometry_loader.py"]:::io
        GeometryProvider["geometry_provider.py"]:::io
        DataStore["EQDSK/MAT Files"]:::io
        ConfigLoader --> GeometryLoader
        GeometryLoader --> GeometryProvider
        DataStore --> GeometryLoader
        GeometryProvider --> InitialState["Initial State"]:::orchestration
    end

    %% Core Simulation Loop
    subgraph "Core Simulation Loop"
        direction TB
        Orchestrator["run_simulation (Orchestrator)"]:::orchestration
        StepFunc["step_function"]:::orchestration
        TimeCalc["Time-Step Calculator"]:::numerical
        Stepper["Stepper"]:::numerical
        FVM["FVM Solver"]:::numerical
        Physics["Physics Models"]:::physics
        Sources["Sources & Transport Models"]:::physics
        JAXNote["Note: JAX jit/grad"]:::annotation
        InitialState --> Orchestrator
        Orchestrator --> StepFunc
        StepFunc --> TimeCalc
        StepFunc --> Stepper
        Stepper --> FVM
        FVM --> Physics
        FVM --> Sources
        Physics --> FVM
        Sources --> FVM
        Physics --- JAXNote
        FVM --- JAXNote
    end

    %% Output & Plotting Layer
    subgraph "Output & Visualization"
        direction TB
        OutputTools["output_tools"]:::output
        Plotting["plotting"]:::output
        Orchestrator --> OutputTools
        OutputTools --> Plotting
    end

    %% Click Events
    click RunMain "https://github.com/google-deepmind/torax/blob/main/torax/run_simulation_main.py"
    click SimApp "https://github.com/google-deepmind/torax/blob/main/torax/simulation_app.py"
    click Sim "https://github.com/google-deepmind/torax/blob/main/torax/sim.py"
    click ConfigLoader "https://github.com/google-deepmind/torax/blob/main/torax/config/config_loader.py"
    click GeometryLoader "https://github.com/google-deepmind/torax/blob/main/torax/geometry/geometry_loader.py"
    click GeometryProvider "https://github.com/google-deepmind/torax/blob/main/torax/geometry/geometry_provider.py"
    click DataStore "https://github.com/google-deepmind/torax/tree/main/torax/data/third_party/geo/"
    click InitialState "https://github.com/google-deepmind/torax/blob/main/torax/orchestration/initial_state.py"
    click Orchestrator "https://github.com/google-deepmind/torax/blob/main/torax/orchestration/run_simulation.py"
    click StepFunc "https://github.com/google-deepmind/torax/blob/main/torax/orchestration/step_function.py"
    click TimeCalc "https://github.com/google-deepmind/torax/blob/main/torax/time_step_calculator/time_step_calculator.py"
    click Stepper "https://github.com/google-deepmind/torax/blob/main/torax/stepper/stepper.py"
    click FVM "https://github.com/google-deepmind/torax/blob/main/torax/fvm/discrete_system.py"
    click Physics "https://github.com/google-deepmind/torax/blob/main/torax/physics/formulas.py"
    click Sources "https://github.com/google-deepmind/torax/tree/main/torax/sources/"
    click OutputTools "https://github.com/google-deepmind/torax/blob/main/torax/output_tools/output.py"
    click Plotting "https://github.com/google-deepmind/torax/blob/main/torax/plotting/plotruns.py"

    %% Styles
    classDef entry fill:#a8f0a5,stroke:#333,stroke-width:1px
    classDef io fill:#a0d8f0,stroke:#333,stroke-width:1px
    classDef orchestration fill:#f9d6a5,stroke:#333,stroke-width:1px
    classDef numerical fill:#f5a5a5,stroke:#333,stroke-width:1px
    classDef physics fill:#d6a5f9,stroke:#333,stroke-width:1px
    classDef output fill:#cccccc,stroke:#333,stroke-width:1px
    classDef annotation fill:#ffffff,stroke-dasharray: 2 2,stroke:#666,stroke-width:1px,font-style:italic
```
