
# DisruptionPy

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

[![Workflow: Lint](https://github.com/MIT-PSFC/disruption-py/actions/workflows/lint.yml/badge.svg)](https://github.com/MIT-PSFC/disruption-py/actions/workflows/lint.yml)
[![Workflow: Tests](https://github.com/MIT-PSFC/disruption-py/actions/workflows/tests.yml/badge.svg)](https://github.com/MIT-PSFC/disruption-py/actions/workflows/tests.yml)
[![Workflow: Build](https://github.com/MIT-PSFC/disruption-py/actions/workflows/build.yml/badge.svg)](https://github.com/MIT-PSFC/disruption-py/actions/workflows/build.yml)
[![Workflow: Docs](https://github.com/MIT-PSFC/disruption-py/actions/workflows/docs.yml/badge.svg)](https://github.com/MIT-PSFC/disruption-py/actions/workflows/docs.yml)
[![Workflow: Dependabot](https://img.shields.io/badge/Dependabot-enabled-34d058?logo=github)](https://github.com/MIT-PSFC/disruption-py/actions/workflows/dependabot/dependabot-updates)
[![Workflow: Stale](https://img.shields.io/badge/Stale%20bot-enabled-34d058?logo=github)](https://github.com/MIT-PSFC/disruption-py/actions/workflows/stale.yml)

[![Code style: black](https://img.shields.io/badge/code%20style-black-000000.svg)](https://github.com/psf/black)
[![Linting: pylint](https://img.shields.io/badge/linting-pylint-yellowgreen)](https://github.com/pylint-dev/pylint)
[![Linting: ruff](https://img.shields.io/badge/linting-ruff-purple)](https://github.com/astral-sh/ruff)
[![Linting: shellcheck](https://img.shields.io/badge/linting-shellcheck-lightgreen)](https://github.com/koalaman/shellcheck)
[![Linting: yamllint](https://img.shields.io/badge/linting-yamllint-lightblue)](https://github.com/adrienverge/yamllint)
[![Testing: pytest](https://img.shields.io/badge/testing-pytest-red)](https://github.com/pylint-dev/pylint-pytest)

[![Supported versions](https://img.shields.io/pypi/pyversions/disruption-py)](https://github.com/MIT-PSFC/disruption-py/blob/main/pyproject.toml)
[![Stats: downloads](https://static.pepy.tech/badge/disruption-py)](https://pepy.tech/project/disruption-py)
[![Available: PyPI](https://img.shields.io/pypi/v/disruption-py.svg)](https://pypi.org/project/disruption-py/)
[![Paper: JOSS](https://joss.theoj.org/papers/e98dd4586a1383f120c5005b539ca6f8/status.svg)](https://joss.theoj.org/papers/e98dd4586a1383f120c5005b539ca6f8)
[![Available: Zenodo](https://zenodo.org/badge/DOI/10.5281/zenodo.13935223.svg)](https://doi.org/10.5281/zenodo.13935223)
[![License: MIT](https://img.shields.io/pypi/l/disruption-py?color=750014)](https://github.com/MIT-PSFC/disruption-py/blob/main/LICENSE)


## Concept

DisruptionPy is an open-source Scientific Python package for fast retrieval of experimental Fusion data from [MDSplus](https://www.mdsplus.org/) servers or [Xarray](https://xarray.dev/) stores.
The library allows an efficient database preparation for downstream analysis and/or ML model development for disruption studies.
Currently supported devices are:

- [Alcator C-Mod](https://en.wikipedia.org/wiki/Alcator_C-Mod)
- [DIII-D](https://en.wikipedia.org/wiki/DIII-D_(tokamak))
- [EAST](https://en.wikipedia.org/wiki/Experimental_Advanced_Superconducting_Tokamak)
- [HBT-EP](https://fusion.columbia.edu/facilities/hbt-ep-tokamak)
- [MAST](https://en.wikipedia.org/wiki/Mega_Ampere_Spherical_Tokamak)


## 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 [[FST2023](https://doi.org/10.1080/15361055.2023.2229675)].
Disruptions still pose a serious challenge to next-generation fusion devices such as [ITER](https://en.wikipedia.org/wiki/ITER) or [SPARC](https://en.wikipedia.org/wiki/SPARC_(tokamak)), 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](https://doi.org/10.1088/1741-4326/ab28bf), [NF2021](https://doi.org/10.1088/1741-4326/abf74d)] has shown the usefulness of machine-learning (ML) algorithms for disruption prevention for both [DIII-D](https://en.wikipedia.org/wiki/DIII-D_(tokamak)) and [EAST](https://en.wikipedia.org/wiki/Experimental_Advanced_Superconducting_Tokamak) operations.
DisruptionPy provides a standardized analysis pipeline across different fusion devices to build ML-ready datasets.

### Workflow

DisruptionPy makes it easy to efficiently retrieve experimental data from [MDSplus](https://www.mdsplus.org/) fusion repositories or [Xarray](https://xarray.dev/) stores.
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.

<p align="center">
<img src="docs/workflow.png" alt="Schematic flowchart of a typical DisruptionPy workflow (by: Y Wei)" width="75%" onerror="this.onerror=null;this.src='workflow.png';" />
</p>

_Figure: Schematic flowchart of a typical DisruptionPy workflow (by: Y Wei)._

### Acknowledgments

The most recent revamp of DisruptionPy was partially supported by DOE FES under Award DE-SC0024368, ["Open and FAIR Fusion for Machine Learning Applications"](https://crea-psfc.github.io/open-fair-fusion/).


## Devices

DisruptionPy supports data extraction workflows on several fusion devices.

### Access

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.

### Data sources

Workflows targeting the only open-access device, MAST, do not require additional software.
Other machines require MDSplus support, and possibly SQL database access for full functionality.

| Device        | Institution | Data    | Metadata | Access           |
|---------------|-------------|---------|----------|------------------|
| Alcator C-Mod | MIT PSFC    | MDSplus | SQL      | :yellow_circle:  |
| DIII-D        | GA          | MDSplus | SQL      | :yellow_circle:  |
| EAST          | ASIPP       | MDSplus | SQL      | :red_circle:     |
| HBT-EP        | Columbia    | MDSplus | -        | :yellow_circle:  |
| MAST          | UKAEA       | S3      | -        | :green_circle:   |

## Installation

DisruptionPy is [open-source on Github](https://github.com/MIT-PSFC/disruption-py/) and [available at PyPI](https://pypi.org/project/disruption-py/)!

### Pre-requisites

Depending on the target device, DisruptionPy may need non-Python software to be installed as a pre-requisite.
Please install pre-requisites, namely either MDSplus or SQL drivers, _only if required_.
For more details, please refer to the Devices section above and our [Installation guide](INSTALL.md).

Note: [MDSplus might not yet support Apple Silicon chips](https://www.mdsplus.org/index.php/Latest_Macintosh_Distributions).

### Dependencies

DisruptionPy follows best practices for project metadata (eg: [pyproject.toml](https://peps.python.org/pep-0621/) and [dependency groups](https://peps.python.org/pep-0735/)) and can therefore be installed with all its dependencies through any standard Python package manager.

We recommend using either [Poetry](https://python-poetry.org/) or [uv](https://docs.astral.sh/uv/) for a user-friendly virtual environment experience.

### Branches

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.

### A) Run pre-installed

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](INSTALL.md).

### B) Install as an application

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.

```bash
# if you use uv
uv tool install disruption-py

# if you use pipx
pipx install disruption-py
```

If 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:

```bash
# 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-py
```

### C) Install as a dependency

Some users will want to use DisruptionPy as a dependency within their own project.

In order to install DisruptionPy, please choose the appropriate snippet:

```bash
# if you use poetry
poetry add disruption-py

# if you use uv
uv add disruption-py

# if you use pip
pip install disruption-py
```

### D) Install from source

Most 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:

```bash
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](INSTALL.md).

### Configuration

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:

```toml
# ~/.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.


## Getting Started

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:

```bash
# show help message
disruption-py --help
```
```
usage: 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.

```bash
# default workflow
disruption-py
```

For simplified workflows, a flattened invocation of our data pipeline is available from Python, as well:

```python
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.


## Contributing

Make sure you branch off the latest version of our [development branch](https://github.com/MIT-PSFC/disruption-py/tree/dev)!

- If you encounter any problems, please [create a new issue](https://github.com/MIT-PSFC/disruption-py/issues/new).
- If you would like to contribute, please [submit a pull request](https://github.com/MIT-PSFC/disruption-py/compare/dev...).
- If you have general questions, please [start a new discussion](https://github.com/MIT-PSFC/disruption-py/discussions/new?category=q-a).

#### Testing

In order to validate your code and test your workflows, please:

1. Install the necessary `dev`elopment dependencies:

```bash
# if you use poetry
poetry install --with dev

# if you use uv
uv sync --group dev
```

2. Verify that the code satisfies our linting rules:

```bash
# if you use poetry
make check
```

3. Verify that the workflows pass our test suite:

```bash
# if you use poetry
poetry run pytest

# if you use uv
uv run pytest
```


## Credits

#### before 2021

The ancestor MATLAB code was authored by several contributors at [MIT PSFC](https://www.psfc.mit.edu/) 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.

#### 2022 - 2023

The initial porting of the code to Python, under the supervision of Dr. Cristina Rea, was tackled by:

- Herbert Turner, then Master's Student.

#### 2024 - present

The subsequent heavy development and maintenance of the code within the newly-established [MIT PSFC Disruption Studies Group](https://disruptions.mit.edu/), was funded under the 3-year DOE FES Grant ["Open and FAIR Fusion for Machine Learning Applications"](https://crea-psfc.github.io/open-fair-fusion/) (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](https://github.com/MIT-PSFC/disruption-py/graphs/contributors) page.


## Citation

DisruptionPy can be cited as follows:

- GL Trevisan, _et al._ (2026), _"DisruptionPy: An open-source physics-based scientific framework for disruption analysis of fusion plasmas"_, Journal of Open Source Software, [accepted](https://joss.theoj.org/papers/e98dd4586a1383f120c5005b539ca6f8)
- 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](https://doi.org/10.5281/zenodo.13935223)

A list of works derived from DisruptionPy can be found in [REFERENCES.md](REFERENCES.md).
