An open-source physics-based Scientific Framework for Disruption Analysis of Fusion Plasmas for AI/ML applications
DisruptionPy is an open-source Scientific Python package for fast retrieval of experimental Fusion data from MDSplus servers. The library allows an efficient database preparation for downstream analysis and/or ML model development for disruption studies. Currently supported devices are:
A key element to ensure steady state operations in magnetically-confined tokamak devices is the prediction and avoidance of disruptions. These are sudden losses of the thermal and magnetic energy stored within the plasma, which can occur when tokamaks operate near stability boundaries or because of hardware anomalies. The energy stored in the plasma and released during disruptions over milliseconds can cause severe damage to plasma-facing components, limiting experimental operations and the device's lifespan [FST2023]. Disruptions still pose a serious challenge to next-generation fusion devices such as ITER or SPARC, which will have to operate near some of the limits of plasma stability to achieve intended performance and will do so at for long and frequent intervals. Fusion science currently lacks first-principle, theoretical solutions to fully predict and avoid disruptions. However, previous work [NF2019, NF2021] has shown the usefulness of machine-learning (ML) algorithms for disruption prevention for both DIII-D and EAST operations. DisruptionPy provides a standardized analysis pipeline across different fusion devices to build ML-ready datasets.
DisruptionPy makes it easy to retrieve experimental data from MDSplus fusion repositories efficiently. Users can create their own routines and/or use built-in ones that retrieve and derive a variety of important signals from experimental data for disruption analysis. These routines are then interpolated on a requested timebase across the specified set of plasma discharges (or shots) to assemble a dataset and save it under a variety of available formats.
Figure: Schematic flowchart of a typical DisruptionPy workflow (by: Y Wei).
The most recent revamp of DisruptionPy was partially supported by DOE FES under Award DE-SC0024368, "Open and FAIR Fusion for Machine Learning Applications".
DisruptionPy supports data extraction workflows on several fusion devices.
Each device hosts experimental data separately and may require authorization for access.
DisruptionPy itself does not provide access to any of the underlying servers.
To obtain access, please contact your host at the desired institution.
Most machines require both MDSplus and SQL database access for full functionality.
| Device | Institution | Data | Metadata | Access |
|---|---|---|---|---|
| Alcator C-Mod | MIT PSFC | MDSplus | SQL | 🟡 |
| DIII-D | GA | MDSplus | SQL | 🟡 |
| EAST | ASIPP | MDSplus | SQL | 🔴 |
| HBT-EP | Columbia | MDSplus | - | 🟡 |
| MAST | UKAEA | S3 | - | 🟢 |
DisruptionPy is open-source on Github and available at PyPI!
Depending on the target device, DisruptionPy may need non-Python software to be installed as a pre-requisite. For more details, please refer to the Devices section above and our Installation guide.
DisruptionPy follows best practices for project metadata (eg: pyproject.toml and dependency groups) and can therefore be installed with all its dependencies through any standard Python package manager.
We recommend using either Poetry or uv for a user-friendly virtual environment experience.
We suggest to install DisruptionPy:
- from the stable branch,
main, for production workflows; - from the development branch,
dev, for development workflows; - from any other branch, only for testing workflows.
If executing on a supported server, installation might not be necessary at all!
Several public installations are currently maintained automatically, as outlined in our Installation guide.
Most users will want to use DisruptionPy as a standalone application.
DisruptionPy can easily be installed in its own virtual environment without first creating a dummy project.
# if you use uv
uv tool install disruption-py
# if you use pipx
pipx install disruption-pyIf you use uv, you can also execute DisruptionPy on the fly without a persistent virtual environment, either from PyPI or from any branch on Github:
# if you use uv, from PyPI
uvx disruption-py
# or from Github
uvx --from git+https://github.com/MIT-PSFC/disruption-py@"${DISPY_BRANCH:-dev}" disruption-pySome users will want to use DisruptionPy as a dependency within their own project.
In order to install DisruptionPy, please choose the appropriate snippet:
# if you use poetry
poetry add disruption-py
# if you use uv
uv add disruption-py
# if you use pip
pip install disruption-pyMost developers will want to install DisruptionPy from source, in order to be able to modify the codebase as needed.
As a quick reference, DisruptionPy can be cloned and installed as follows:
git clone https://github.com/MIT-PSFC/disruption-py -b dev
cd disruption-py
# if you use poetry
poetry install
# if you use uv
uv sync
# if you use venv/pip
python -m venv .venv
source .venv/bin/activate
pip install -e .For custom development installations, please refer to our Installation guide.
Depending on the target device, DisruptionPy may benefit from SQL access. For more details, please refer to the Devices section above.
While we honor the legacy sybase_login file credential format for database connections, we recommend using the following configuration snippet for maximum flexibility:
# ~/.config/disruption-py/user.toml
[cmod.inout.sql]
db_user = ""
db_pass = ""
[d3d.inout.sql]
db_user = ""
db_pass = ""
[east.inout.sql]
db_user = ""
db_pass = ""The above configuration file may be used to further override any framework configuration parameter.
When installed, a simple command-line entry point is available as disruption-py.
The command-line arguments, which are subject to change, are documented in the help message:
# show help message
disruption-py --helpusage: disruption-py [-h] [-t TOKAMAK] [-m METHODS] [-e EFIT_TREE] [-b TIME_BASE]
[-o OUTPUT_FILE] [-p PROCESSES] [-l LOG_LEVEL]
[shots ...]
positional arguments:
shots
options:
-h, --help show this help message and exit
-t TOKAMAK, --tokamak TOKAMAK
-m METHODS, --methods METHODS
-e EFIT_TREE, --efit-tree EFIT_TREE
-b TIME_BASE, --time-base TIME_BASE
-o OUTPUT_FILE, --output-file OUTPUT_FILE
-p PROCESSES, --processes PROCESSES
-l LOG_LEVEL, --log-level LOG_LEVEL
A parameter-less command-line invocation allows to compute all physics methods for a given device on a few prototypical shots. If unspecified, the device is inferred from the local environment.
# default workflow
disruption-pyFor simplified workflows, a flattened invocation of our data pipeline is available from Python, as well:
from disruption_py.workflow import run
out = run(*args)For more complicated workflows requiring the configuration of all the settings according to the specific user needs, a full-fledged disruption script might be necessary.
Please refer to our examples/defaults.py script for a quickstart workflow with explicit default arguments.
Make sure you refer to the latest version of our development branch!
- If you encounter any problems, please create a new issue.
- If you would like to contribute, please submit a pull request.
- If you have general questions, please start a new discussion.
The ancestor MATLAB code was authored by several contributors at MIT PSFC before 2021:
- Robert Granetz, Principal Research Scientist,
- Cristina Rea, then Research Scientist,
- Kevin Montes, then Graduate Research Assistant,
- Alex Tinguely, then Graduate Research Assistant,
- Jinxiang Zhu, then Graduate Research Assistant.
The initial porting of the code to Python, under the supervision of Dr. Cristina Rea, was tackled by:
- Herbert Turner, then Master's Student.
The subsequent heavy development and maintenance of the code within the newly-established MIT PSFC Disruption Studies Group, was funded under the 3-year DOE FES Grant "Open and FAIR Fusion for Machine Learning Applications" (2024-2026).
Several contributors have been involved in the development of the code since then, most notably:
- Gregorio L. Trevisan, Research Scientist,
- Josh Lorincz, Undergraduate Student,
- Amos Decker, Undergraduate Student,
- William Wei, PostDoctoral Associate.
For a complete list of contributors, please refer to the Contributors page.
DisruptionPy can be cited as follows:
- GL Trevisan, et al. (2025), "DisruptionPy: An open-source physics-based scientific framework for disruption analysis of fusion plasmas", JOSS, under review
- GL Trevisan, et al. (2024), "DisruptionPy: An open-source physics-based scientific framework for disruption analysis of fusion plasmas", Zenodo, DOI: 10.5281/zenodo.13935223
A list of works derived from DisruptionPy can be found in REFERENCES.md.