D0FUS
Top: plasma geometry (Miller surfaces), kinetic profiles, safety factor, radiative cooling, and fusion reactivity. Bottom: radial build, superconductor critical current, TF and CS coil cross-sections, CICC conductors, and a multi-machine comparison. Right: the full poloidal radial build, from plasma out to the TF coil.
D0FUS (Design 0-dimensional for Fusion Systems) is a Python tokamak systems code for fast 0D/1D design-space exploration, covering plasma physics, superconducting magnet engineering, and techno-economic assessment. It is developed at CEA-IRFM.
About 39 000 lines of pure Python: a core library of seven modules and over 500 functions, plus five execution modes. The code is fully documented in the PhD thesis of T. Auclair (2026), whose Appendix D serves as the reference manual; release v2.7.0 is the version archived with the thesis.
Documentation: d0fus.readthedocs.io. Installation, user guide, the models with their derivations, the verification benchmarks, and an API reference generated from the code at every release.
Highlights
- Pure Python, NumPy/SciPy only. No compilation, runs in Spyder, Jupyter or as a batch job.
- Two fidelity levels (Academic and Refined), with a per-model selector in
GlobalConfigfor any mixed combination, andpreset_academic()/preset_refined()factories for coherent sets. - Five execution modes (RUN, SCAN, OPTIMIZATION, POPCON, UNCERTAINTY), auto-detected from the input file syntax.
- Library mode: every function is callable in isolation, outside the solver loop.
- Distinctive engineering scope: radially graded TF coils, REBCO Jc scalings, three TF mechanical configurations (wedging, bucking, plug), quench-protection sizing.
Installation
Option A — Spyder standalone (recommended, no Python knowledge required)
- Install Spyder from spyder-ide.org (bundled Python included).
- Get the code:
git clone https://github.com/IRFM/D0FUS.git, or Code → Download ZIP on github.com/IRFM/D0FUS and extract. - In Spyder, File → Open…
D0FUS.py. The working directory is set toD0FUS/automatically. - In the IPython console:
%pip install -r requirements.txt(falls back to!pip install -r requirements.txtif%pipfails). - Press F5 and select
D0FUS_INPUTS/1_run_ITER.txtin the file picker. Results print to the console, figures open automatically.
Option B — Miniforge (conda users)
conda create -n d0fus python=3.11 && conda activate d0fus
conda install pip spyder
git clone https://github.com/IRFM/D0FUS.git && cd D0FUS
pip install -r requirements.txt
python D0FUS.py D0FUS_INPUTS/1_run_ITER.txt
Option C — pip (headless / library use)
pip install d0fus
Deck-driven run from a script or terminal:
from D0FUS_EXE import D0FUS_run
D0FUS_run.main("D0FUS_INPUTS/1_run_ITER.txt") # full run + report files + figures
Programmatic single point, no files involved:
from dataclasses import replace
from D0FUS_BIB.D0FUS_parameterization import DEFAULT_CONFIG
from D0FUS_EXE import D0FUS_run
cfg = replace(DEFAULT_CONFIG, R0=8.0, Bmax_TF=13.0, Supra_choice="REBCO")
results = D0FUS_run.run(cfg) # tuple of 165 outputs (np.nan if no solution)
Input decks (
D0FUS_INPUTS/) are not shipped in the PyPI package: clone the repository to get them.
Project structure
D0FUS/
├── D0FUS_BIB/ # Core library
│ ├── D0FUS_import.py # Centralised imports
│ ├── D0FUS_parameterization.py # Physical constants, GlobalConfig dataclass
│ ├── D0FUS_physical_functions.py # Plasma physics (profiles, limits, currents, exhaust, RE)
│ ├── D0FUS_radial_build_functions.py # Magnets (TF/CS, CICC, quench, ripple)
│ ├── D0FUS_cost_functions.py # Techno-economics (Sheffield, Whyte)
│ ├── D0FUS_cost_data.py # Reference cost data
│ ├── D0FUS_power_flow.py # Plant power-balance Sankey diagrams
│ └── D0FUS_figures.py # Figure catalogue
├── D0FUS_EXE/ # Execution modes
│ ├── D0FUS_run.py # Single design point
│ ├── D0FUS_scan.py # 2D parameter scan
│ ├── D0FUS_genetic.py # Genetic optimisation
│ ├── D0FUS_popcon.py # POPCON operating-space map
│ └── D0FUS_uncertainty.py # Monte-Carlo uncertainty propagation
├── D0FUS_INPUTS/ # Example decks, 1_run_ITER.txt … 5_popcon_ITER.txt
├── D0FUS_OUTPUTS/ # Auto-created, timestamped result folders
├── tests/ # pytest suite, run by GitHub Actions (.github/workflows)
├── D0FUS.py # Entry point (mode auto-detection)
├── pyproject.toml · requirements.txt · CITATION.cff
└── README.md
Execution modes
The mode is detected from the content of the input file. Text after # is a comment, and section titles such as [POPCON] are optional.
| Mode | Purpose | Trigger in the deck |
|---|---|---|
| RUN | Single design point, 165 outputs, report files, 16 figures | Fixed values only (R0 = 9) |
| SCAN | 2D feasibility map, 108 registered output quantities | Exactly 2 entries [min, max, n_points], other than the POPCON pair |
| OPTIMIZATION | Genetic cost minimisation (DEAP) | 2+ entries [min, max] |
| POPCON | Operating map (n̄, T̄) at fixed machine | nbar_line and Tbar written [min, max, n_points] |
| UNCERTAINTY | Monte-Carlo propagation of input uncertainties | At least one tri(), norm(), unif() or envelope() entry |
RUN solves the coupled design point: in pulsed mode a scalar root-finding on the helium ash fraction (Brent), in steady-state a 2D solve on (f_α, Q) (Powell). An outer loop updates the q(ρ) profile of the bootstrap model and solves again, usually once. Post-convergence: TF/CS sizing, flux budget, divertor loads, L-H margin, costs, runaway-electron indicators.
SCAN evaluates an independent grid in parallel (joblib/loky), overlaying the operational limits (Greenwald, Troyon, kink) and the radial-build closure on any registered output.
OPTIMIZATION minimises COE (default), C_invest, volume or R0, maximises P_elec, or minimises an expression of the inputs and outputs written in the deck (custom). Feasibility follows the RUN rule and comes first in the ranking: any feasible design beats any infeasible one, and infeasible designs are ranked by their violation of the limits. An optional capital-cost ceiling adds a soft penalty.
POPCON freezes the deck's converged machine and sweeps (n̄_line, T̄), returning Q, powers and the H-mode access margin at every node, bounded by the Greenwald, Troyon and L-H limits (logic of the open-source cfspopcon, reusing the D0FUS physics chain).
UNCERTAINTY assigns distributions (norm(), tri(), unif()) to any inputs and discrete model switches with envelope(A | B), draws Latin-Hypercube samples, and returns output distributions and one feasible share with its 95 % Wilson confidence interval, the no-solution draws being counted as failures.
Command-line options
python D0FUS.py DECK [--output-dir DIR] [--no-figures] [--no-3d] [--seed N]
| Option | Effect |
|---|---|
--output-dir DIR |
Parent folder of the result folders, instead of D0FUS_OUTPUTS |
--no-figures |
Reports and data files only |
--no-3d |
RUN: skips the 3D machine view (PyVista), the slowest figure |
--seed N |
Random seed of OPTIMIZATION and UNCERTAINTY, overriding the deck |
-h |
Help, with the deck syntax of each mode |
Without a deck, D0FUS.py lists the files of D0FUS_INPUTS with their detected mode.
Execution time (14-core laptop)
| Mode | Configuration | Wall time |
|---|---|---|
| RUN | single point | ~200 ms |
| SCAN | 50 × 50 grid | ~25 s |
| OPTIMIZATION | 50 × 10 generations | ~2 min 30 |
| POPCON / UNCERTAINTY | N nodes or samples | ~N × 200 ms / n_cores |
Two fidelity levels
Each model carries its own selector in GlobalConfig; the factories preset_academic() and preset_refined() set a coherent bundle. Both levels share the same interface and solver, with comparable run times.
| Model | Academic | Refined |
|---|---|---|
| Plasma geometry | Elliptical torus | Miller flux surfaces, κ(ρ), δ(ρ) |
| Volume element | V′ = 4π²R₀a²κρ | Numerical Miller Jacobian |
| Bootstrap current | Segal-Cerfon-Freidberg fit | Sauter (1999/2002) refitted by Redl (2021) |
| q(ρ) profile | Parametric j(ρ) ∝ (1−ρ²)^αJ | Self-consistent Picard on j_Ω + j_CD + j_bs |
| Resistivity | Spitzer | Sauter/Redl neoclassical |
| TF stress model | Thin-cylinder, two-layer | Thick-cylinder, composite CICC (or CIRCE0D) |
| CS stress model | Hoop only | Hoop + axial fringe-field |
Inputs
All parameters live in one typed dataclass, GlobalConfig (165 fields), each with a physically motivated default. A deck overrides only what it names; everything else keeps its default, so a complete machine fits in a few lines:
R0 = 7
Bmax_TF = 14
Supra_choice = REBCO
Key parameters and their actual defaults:
| Parameter | Description | Default | Options |
|---|---|---|---|
P_fus / R0 / a / b |
Fusion power [MW], radii [m], blanket+shield [m] | 2000 / 9.0 / 3.0 / 1.2 | |
Bmax_TF / Bmax_CS_adm |
Peak field on TF / admissible on CS [T] | 12.0 / 25.0 | |
Supra_choice |
Superconductor | Nb3Sn |
NbTi, Nb3Sn, REBCO |
Supra_choice_CS / J_wost_Manual_CS |
CS superconductor / CS current density when Manual [A/m²] |
same / None |
same, NbTi, Nb3Sn, REBCO, Manual |
Choice_Buck_Wedg |
TF mechanical configuration | Wedging |
Wedging, Bucking, Plug |
Chosen_Steel_TF / Chosen_Steel_CS |
TF structural steel / CS jacket steel | 316L / 316L |
316L, N50H, Manual |
Scaling_Law |
Confinement scaling | ITPA20 |
IPB98(y,2), ITPA20-IL, DS03, L-mode, L-mode OK, ITER89-P |
Option_Kappa |
Elongation model | Blend |
Wenninger, Stambaugh, Freidberg, Manual |
Option_q95 |
q₉₅ formula | ITER_1989 |
Sauter |
density_limit_model |
Density limit | greenwald |
zanca, giacomin |
Plasma_profiles |
Profile preset | H |
L, Advanced, EU-DEMO, NT, Manual |
Bootstrap_choice |
Bootstrap model | Sauter-Redl |
Segal |
Operation_mode |
Scenario | Pulsed (3600 s, 50 MW) |
Steady-State |
CD_source |
Current-drive model | Academic (γ_CD 0.20, η_WP 0.40) |
LHCD, ECCD, NBCD, Multi |
Zeff |
Effective charge | computed from the impurity inventory | or fixed value |
rho_rad_core |
Core/edge radiation boundary | 0.6 | 1.0 = conservative preset |
cost_model |
Cost model | Sheffield |
Whyte, None |
The complete field list, with units, defaults and provenance comments, is in D0FUS_parameterization.py and on the GlobalConfig fields page of the documentation; every run also writes it to output_detailed.txt.
Deck syntax by mode
# RUN: fixed values # SCAN: exactly two brackets
R0 = 9 R0 = [3, 9, 25]
Bmax_TF = 13 a = [1, 3, 25]
# OPTIMIZATION: 2+ ranges # POPCON: full RUN deck, then
R0 = [3, 9] [POPCON]
Bmax_TF = [10, 16] nbar_line = [0.35, 1.45, 45]
fitness_objective = COE Tbar = [3.5, 24.0, 36]
# UNCERTAINTY: full RUN deck, then
[UNCERTAINTY]
H = norm(0.75, 1.50) # truncated normal around the deck value
Scaling_Law = envelope(IPB98(y,2) | ITPA20) # model switch (pipe-separated)
[CONTROLS]
n_samples = 1500
Continuous distributions: norm(sigma), norm(lo, hi), norm(lo, centre, hi), tri(...), unif(lo, hi). One worked example per mode ships in D0FUS_INPUTS/.
Outputs
Every mode writes a folder named after the mode and the time, to the second, under D0FUS_OUTPUTS/<mode>/. From a clone, D0FUS_OUTPUTS is at the root of the repository, whatever the working directory. For an installed package, it is in the working directory. A RUN produces input_parameters.txt (the deck), output_highlight.txt (key results), output_detailed.txt (every input including defaults, every output), and 18 figures (cross-section, Miller surfaces, profiles, q(ρ), radiation, divertor two-point, radial build, coil and CICC drawings, cost breakdown, temperature and density maps, pulse and dwell power-balance Sankey diagrams, PyVista 3D view skipped with --no-3d). A design without a solution gives NaN in the reports and figures. SCAN writes the 2D map, OPTIMIZATION the convergence plot, optimization_summary.json (settings, seed, Hall of Fame), a copy of the deck and the reports of the best design, POPCON the operating-contour map, UNCERTAINTY a summary with the feasible share and its confidence interval, the per-output distributions and figures.
Models in brief
Plasma geometry follows the Miller parameterisation (Miller 1998) with on-axis regularity enforced (Ball & Parra 2015). The three first-order plasma limits are Greenwald, Troyon and the kink limit on q₉₅, with the density-limit model selectable (Greenwald, Zanca 2019, Giacomin 2022 near-separatrix). Impurity radiation uses the Mavrin (2018) cooling rates; the divertor is characterised by an Eich attached estimate or a two-point model with a Lengyel seeding closure on non-coronal OpenADAS curves. The L-H threshold offers Martin (2008) and the two ITPA TC-26 metal-wall scalings (Delabie 2026). Current drive follows the METIS efficiency models; the NBCD efficiency agrees with the IPDG89 formula used by PROCESS within 4 %. Runaway-electron indicators combine a hot-tail seed (Smith 2008) and avalanche amplification (Breizman 2019), for comparative ranking only.
The TF inboard leg is a Princeton-D (File, Mills & Sheffield 1971); conductors are CICC-like with a helium-fraction hierarchy; critical currents use ITER parameterisations (NbTi, Nb₃Sn) and REBCO datasets (Senatore 2024, Fujikura 2019); quench protection is sized on the Maddock hot-spot criterion; the winding pack can be radially graded. Costing follows Sheffield & Milora (2016), with a surface-proportional Whyte (2024) model for cross-checks; costs never feed back into the physics.
Full derivations, validity domains and references: Models section of the documentation, adapted from the thesis (Chapter 1 and Appendices B-C).
Version and citation
To cite D0FUS, use CITATION.cff (GitHub's Cite this repository button) or cite the thesis:
T. Auclair, Apport des supraconducteurs à haute température critique au dimensionnement de machines de fusion nucléaire par confinement magnétique, PhD thesis, Aix-Marseille Université / CEA-IRFM, 2026.
Contributing
Contributions and questions are welcome: timothe.auclair@proton.me
Tests: pip install -e ".[dev]", then python -m pytest from the repository root. GitHub Actions runs the suite on Python 3.10 to 3.13 at every push and pull request.
License
CeCILL-C, a French free software license compatible with the GNU LGPL. See LICENSE.
© 2025-2026 CEA/IRFM
Metadata
Release files for d0fus 3.3.0
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Source distribution (sdist)
| File | Size | Uploaded | Provenance | Actions |
|---|---|---|---|---|
| d0fus-3.3.0.tar.gz | 574.3 kB | Without provenance | Details for d0fus-3.3.0.tar.gz |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Actions Reset |
|---|---|---|---|---|
| d0fus-3.3.0-py3-none-any.whl | Python 3 | none | any | Details for d0fus-3.3.0-py3-none-any.whl |
Total release size: 1.2 MB
Release files / d0fus-3.3.0.tar.gz
| Download URL | d0fus-3.3.0.tar.gz |
|---|---|
| Size | 574.3 kB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
469fe35d4d1a013af166fe9088f7c4124297994e64d8cbafac88606088359d5f
|
|
BLAKE2b-256 checksum How to use checksums |
cd25b29e40a863f8b826638473291c92c28c84145bc7ee5f8f2eb82ea9c285c7
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
twine/7.0.0 CPython/3.11.18
|
Release files / d0fus-3.3.0-py3-none-any.whl
| Download URL | d0fus-3.3.0-py3-none-any.whl |
|---|---|
| Size | 576.5 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
6817da34b1520cdf953b1efefd3d296523c52236a5c433f9a28f15c9f8d98ca1
|
|
BLAKE2b-256 checksum How to use checksums |
1297c3cb2f876e6f869b7887c425b81e83b88535986b660ad43e9d8e9be4c7e3
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
twine/7.0.0 CPython/3.11.18
|
Security for d0fus 3.3.0
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
No provenance found
None of the files in this release were uploaded with provenance metadata.
A note on package security
PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.
To learn more about protecting yourself from malicious actors, visit our package security documentation.