README.md

DisruptionPy

An open-source physics-based Scientific Framework for Disruption Analysis of Fusion Plasmas for AI/ML applications

Concept

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. At present, the main supported machines are Alcator C-Mod and DIII-D.

Overview

Background

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 [1]. 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 [2, 3] has shown the usefulness of machine-learning (ML) algorithms for disruption prevention for both DIII-D and EAST -- the Experimental Advanced Superconducting Tokamak in China -- operations. DisruptionPy provides a standardized analysis pipeline across different fusion devices to build ML-ready datasets.

Workflow

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 (2024) [6].

Acknowledgments

The most recent revamp of DisruptionPy [4, 5, 6] was partially supported by DOE FES under Award DE-SC0024368, "Open and FAIR Fusion for Machine Learning Applications" [7].

References

1. AD Maris, A Wang, C Rea, RS Granetz, E Marmar (2023), "The Impact of Disruptions on the Economics of a Tokamak Power Plant", Fusion Science and Technology 80(5) 636-652, DOI:10.1080/15361055.2023.2229675.

2. C Rea, KJ Montes, KG Erickson, RS Granetz & RA Tinguely (2019), "A real-time machine learning-based disruption predictor in DIII-D", Nuclear Fusion 59 096016, DOI:10.1088/1741-4326/ab28bf.

3. WH Hu, C Rea, et al. (2021), "Real-time prediction of high-density EAST disruptions using random forest", Nuclear Fusion 61 066034, DOI:10.1088/1741-4326/abf74d.

4. C Rea, et al. (2024), "Open and FAIR Fusion for Machine Learning Applications", 66th APS Division of Plasma Physics Meeting, PP12.27.

5. GL Trevisan, et al. (2024), "Functional Improvements and Technical Developments of a Community-driven and Physics-informed Numerical Library for Disruption Studies", 66th APS Division of Plasma Physics Meeting, PP12.9.

6. Y Wei, et al. (2024), "Physics validation of parameter methods in DisruptionPy", 66th APS Division of Plasma Physics Meeting, PP12.10.

7. C Rea, et al. (2023), "Open and FAIR Fusion for Machine Learning Applications", Project website.

Repository layout

Notable branches:

• main, the stable branch,
• dev, the development branch,
• matlab, the historical branch.

Project layout

Brief description of the folders in our project:

• disruption_py/, package source code,
• docs/, documentation sources,
• drafts/, experimental scripts,
• examples/, example workflows,
• scripts/, miscellaneous scripts,
• tests/, testing workflows.

Installation

DisruptionPy is now open-source and available at PyPI!

For standard installations, please follow the usual way:

# if you use poetry:
poetry add disruption-py

# if you use pip:
pip install disruption-py

For custom installations, please refer to our Installation guide.

Getting Started

Please see the project quickstart.

Contributing

Important

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.