fusion-surrogates 0.1.0

Transport surrogate models for Tokamak fusion.

Fusion surrogates

A library of surrogate models for tokamak fusion.

This library provides both inference code and model weights and metadata. It is designed to provide surrogate models for TORAX, but the models should be usable by other fusion simulators.

QLKNN_7_11

Currently, this library only holds the QLKNN_7_11 model. This model is a surrogate of Qualikiz, a quasilinear gyrokinetic code for turbulent transport in tokamaks.

It is based on the original QLKNN10D model by Van de Plassche et al. PoP 2020 (also available on arxiv). It was trained by combining data for the QLKNN11D dataset and QLKNN7D-edge dataset. A paper describing the details of the model is in the works and should be published soon.

The model takes as input:

• Normalized logarithmic heat and density gradients for electrons and main ions ($$R/L_{Te}$$, $$R/L_{Ti}$$, $$R/L_{ne}$$, $$R/L_{ni}$$)
• Safety factor ($$q$$)
• Magnetic shear ($$\hat{s}$$)
• Local inverse aspect ratio ($$r/R_{maj}$$)
• ion-electron temperature ratio ($$T_i/T_e$$)
• Logarithmic ion-electron normalized collisionality ($$\mathrm{log}(\nu^*)$$)
• Normalized density ($$n_i/n_e$$)

It outputs ion and electron heat and particle fluxes for each transport mode (Ion Temperature Gradient [ITG], Electron Temperature Gradient [ETG], Trapped Electron Modes [TEM]), as well as the the maximum growth rate on ion gyroradius scales. Specifically, we output the leading flux for that mode (ion heat flux for ITG, electron heat flux for TEM and ETG), and ratios of the relevant secondary fluxes to the leading flux of that mode.

More details on the inputs and outputs mentioned above can be found in the Qualikiz documentation.

Installation instructions

Install virtualenv (if not already installed):

pip install --upgrade pip

pip install virtualenv

Create a code directory where you will install the virtual env and other fusion_surrogates dependencies.

mkdir /path/to/fusion_surrogates_dir && cd "$_"

Where /path/to/fusion_surrogates_dir should be replaced by a path of your choice.

Create a fusion_surrogates virtual env:

python3 -m venv fusion_surrogates_venv

Activate the virtual env:

source fusion_surrogates_venv/bin/activate

Download and install the library via http:

git clone https://github.com/google-deepmind/fusion_surrogates.git

or ssh (ensure that you have the appropriate SSH key uploaded to github).

git clone [e-mail]:google-deepmind/fusion_surrogates.git

Enter the fusion_surrogates directory

cd fusion_surrogates

Install the library:

pip install -e .

If you want to run unit tests, install with the testing option:

pip install -e .[testing]
pytest

Disclaimer

Copyright 2025 Google LLC

All software is licensed under the Apache License, Version 2.0 (Apache 2.0); you may not use this file except in compliance with the Apache 2.0 license. You may obtain a copy of the Apache 2.0 license at: https://www.apache.org/licenses/LICENSE-2.0

All other materials are licensed under the Creative Commons Attribution 4.0 International License (CC-BY). You may obtain a copy of the CC-BY license at: https://creativecommons.org/licenses/by/4.0/legalcode

Unless required by applicable law or agreed to in writing, all software and materials distributed here under the Apache 2.0 or CC-BY licenses are distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the licenses for the specific language governing permissions and limitations under those licenses.

This is not an official Google product.