How google-deepmind/torax works
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