# DisruptionPy
#### An open-source physics-based Scientific Framework for Disruption Analysis of Fusion Plasmas for AI/ML applications
[](https://github.com/MIT-PSFC/disruption-py/actions/workflows/lint.yml)
[](https://github.com/MIT-PSFC/disruption-py/actions/workflows/tests.yml)
[](https://github.com/MIT-PSFC/disruption-py/actions/workflows/build.yml)
[](https://github.com/MIT-PSFC/disruption-py/actions/workflows/docs.yml)
[](https://github.com/MIT-PSFC/disruption-py/actions/workflows/dependabot/dependabot-updates)
[](https://github.com/MIT-PSFC/disruption-py/actions/workflows/stale.yml)
[](https://github.com/psf/black)
[](https://github.com/pylint-dev/pylint)
[](https://github.com/astral-sh/ruff)
[](https://github.com/koalaman/shellcheck)
[](https://github.com/adrienverge/yamllint)
[](https://github.com/pylint-dev/pylint-pytest)
[](https://github.com/MIT-PSFC/disruption-py/blob/main/pyproject.toml)
[](https://pepy.tech/project/disruption-py)
[](https://pypi.org/project/disruption-py/)
[](https://doi.org/10.5281/zenodo.13935223)
[](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.
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](https://en.wikipedia.org/wiki/Alcator_C-Mod) and [DIII-D](https://en.wikipedia.org/wiki/DIII-D_(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 [[1](https://doi.org/10.1080/15361055.2023.2229675)].
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](https://doi.org/10.1088/1741-4326/ab28bf), [3](https://doi.org/10.1088/1741-4326/abf74d)] 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](https://www.mdsplus.org/) 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.
<img src="docs/workflow.png" alt="Schematic flowchart of a typical DisruptionPy workflow. By Y Wei (2024)" width="400" onerror="this.onerror=null;this.src='workflow.png';" />
_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](https://doi.org/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](https://doi.org/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](https://doi.org/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](https://meetings.aps.org/Meeting/DPP24/Session/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](https://meetings.aps.org/Meeting/DPP24/Session/PP12.9).
6. Y Wei, et al. (2024), _"Physics validation of parameter methods in DisruptionPy"_, 66th APS Division of Plasma Physics Meeting, [PP12.10](https://meetings.aps.org/Meeting/DPP24/Session/PP12.10).
7. C Rea, et al. (2023), _"Open and FAIR Fusion for Machine Learning Applications"_, [Project website](https://crea-psfc.github.io/open-fair-fusion/).
## Repository layout
Notable branches:
- `main`, the [stable branch](https://github.com/MIT-PSFC/disruption-py/tree/main),
- `dev`, the [development branch](https://github.com/MIT-PSFC/disruption-py/tree/dev),
- `matlab`, the [historical branch](https://github.com/MIT-PSFC/disruption-py/tree/matlab).
## 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](https://pypi.org/project/disruption-py/)!
For standard installations, please follow the usual way:
```bash
# 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](docs/INSTALL.md).
## Getting Started
Please see the [project quickstart](https://mit-psfc.github.io/disruption-py/quickstart/usage_quickstart/).
## Contributing
> [!IMPORTANT]
> Make sure you refer to 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).
Raw data
{
"_id": null,
"home_page": "https://disruptions.mit.edu/",
"name": "disruption-py",
"maintainer": "Gregorio L. Trevisan",
"docs_url": null,
"requires_python": "<4.0,>=3.10",
"maintainer_email": "gtrevisan@psfc.mit.edu",
"keywords": "plasma physics, nuclear fusion, tokamak, disruptions",
"author": "Cristina Rea",
"author_email": "crea@psfc.mit.edu",
"download_url": "https://files.pythonhosted.org/packages/b3/2d/65da507ecded106f31e56b69ac7a7a23141c5d90523f915a53b6918c7431/disruption_py-0.9.0.tar.gz",
"platform": null,
"description": "\n# DisruptionPy\n\n#### An open-source physics-based Scientific Framework for Disruption Analysis of Fusion Plasmas for AI/ML applications\n\n[](https://github.com/MIT-PSFC/disruption-py/actions/workflows/lint.yml)\n[](https://github.com/MIT-PSFC/disruption-py/actions/workflows/tests.yml)\n[](https://github.com/MIT-PSFC/disruption-py/actions/workflows/build.yml)\n[](https://github.com/MIT-PSFC/disruption-py/actions/workflows/docs.yml)\n[](https://github.com/MIT-PSFC/disruption-py/actions/workflows/dependabot/dependabot-updates)\n[](https://github.com/MIT-PSFC/disruption-py/actions/workflows/stale.yml)\n\n[](https://github.com/psf/black)\n[](https://github.com/pylint-dev/pylint)\n[](https://github.com/astral-sh/ruff)\n[](https://github.com/koalaman/shellcheck)\n[](https://github.com/adrienverge/yamllint)\n[](https://github.com/pylint-dev/pylint-pytest)\n\n[](https://github.com/MIT-PSFC/disruption-py/blob/main/pyproject.toml)\n[](https://pepy.tech/project/disruption-py)\n[](https://pypi.org/project/disruption-py/)\n[](https://doi.org/10.5281/zenodo.13935223)\n[](https://github.com/MIT-PSFC/disruption-py/blob/main/LICENSE)\n\n## Concept\n\nDisruptionPy is an open-source Scientific Python package for fast retrieval of experimental Fusion data from [MDSplus](https://www.mdsplus.org/) servers.\nThe library allows an efficient database preparation for downstream analysis and/or ML model development for disruption studies.\nAt present, the main supported machines are [Alcator C-Mod](https://en.wikipedia.org/wiki/Alcator_C-Mod) and [DIII-D](https://en.wikipedia.org/wiki/DIII-D_(tokamak)).\n\n\n## Overview\n\n### Background\n\nA key element to ensure steady state operations in magnetically confined tokamak devices is the prediction and avoidance of disruptions.\nThese 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.\nThe 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](https://doi.org/10.1080/15361055.2023.2229675)].\nDisruptions 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.\nFusion science currently lacks first-principle, theoretical solutions to fully predict and avoid disruptions.\nHowever, previous work [[2](https://doi.org/10.1088/1741-4326/ab28bf), [3](https://doi.org/10.1088/1741-4326/abf74d)] 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.\nDisruptionPy provides a standardized analysis pipeline across different fusion devices to build ML-ready datasets.\n\n### Workflow\n\nDisruptionPy makes it easy to retrieve experimental data from [MDSplus](https://www.mdsplus.org/) fusion repositories efficiently.\nUsers 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.\nThese 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.\n\n<img src=\"docs/workflow.png\" alt=\"Schematic flowchart of a typical DisruptionPy workflow. By Y Wei (2024)\" width=\"400\" onerror=\"this.onerror=null;this.src='workflow.png';\" />\n\n_Figure: Schematic flowchart of a typical DisruptionPy workflow. By Y Wei (2024) [6]._\n\n### Acknowledgments\n\nThe 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].\n\n### References\n\n1. 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](https://doi.org/10.1080/15361055.2023.2229675).\n\n2. 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](https://doi.org/10.1088/1741-4326/ab28bf).\n\n3. 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](https://doi.org/10.1088/1741-4326/abf74d).\n\n4. C Rea, et al. (2024), _\"Open and FAIR Fusion for Machine Learning Applications\"_, 66th APS Division of Plasma Physics Meeting, [PP12.27](https://meetings.aps.org/Meeting/DPP24/Session/PP12.27).\n\n5. 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](https://meetings.aps.org/Meeting/DPP24/Session/PP12.9).\n\n6. Y Wei, et al. (2024), _\"Physics validation of parameter methods in DisruptionPy\"_, 66th APS Division of Plasma Physics Meeting, [PP12.10](https://meetings.aps.org/Meeting/DPP24/Session/PP12.10).\n\n7. C Rea, et al. (2023), _\"Open and FAIR Fusion for Machine Learning Applications\"_, [Project website](https://crea-psfc.github.io/open-fair-fusion/).\n\n\n## Repository layout\n\nNotable branches:\n\n- `main`, the [stable branch](https://github.com/MIT-PSFC/disruption-py/tree/main),\n- `dev`, the [development branch](https://github.com/MIT-PSFC/disruption-py/tree/dev),\n- `matlab`, the [historical branch](https://github.com/MIT-PSFC/disruption-py/tree/matlab).\n\n\n## Project layout\n\nBrief description of the folders in our project:\n\n- `disruption_py/`, package source code,\n- `docs/`, documentation sources,\n- `drafts/`, experimental scripts,\n- `examples/`, example workflows,\n- `scripts/`, miscellaneous scripts,\n- `tests/`, testing workflows.\n\n\n## Installation\n\nDisruptionPy is now open-source and [available at PyPI](https://pypi.org/project/disruption-py/)!\n\nFor standard installations, please follow the usual way:\n\n```bash\n# if you use poetry:\npoetry add disruption-py\n\n# if you use pip:\npip install disruption-py\n```\n\nFor custom installations, please refer to our [Installation guide](docs/INSTALL.md).\n\n\n## Getting Started\n\nPlease see the [project quickstart](https://mit-psfc.github.io/disruption-py/quickstart/usage_quickstart/).\n\n\n## Contributing\n\n> [!IMPORTANT]\n> Make sure you refer to the latest version of our [development branch](https://github.com/MIT-PSFC/disruption-py/tree/dev)!\n\n- If you encounter any problems, please [create a new issue](https://github.com/MIT-PSFC/disruption-py/issues/new).\n- If you would like to contribute, please [submit a pull request](https://github.com/MIT-PSFC/disruption-py/compare/dev...).\n- If you have general questions, please [start a new discussion](https://github.com/MIT-PSFC/disruption-py/discussions/new?category=q-a).\n",
"bugtrack_url": null,
"license": "MIT",
"summary": "An open-source physics-based Scientific Framework for Disruption Analysis of Fusion Plasmas for AI/ML applications",
"version": "0.9.0",
"project_urls": {
"Documentation": "https://mit-psfc.github.io/disruption-py/",
"Homepage": "https://disruptions.mit.edu/",
"Repository": "https://github.com/MIT-PSFC/disruption-py/"
},
"split_keywords": [
"plasma physics",
" nuclear fusion",
" tokamak",
" disruptions"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "9d83bfde0ec1b7a827648b0070849fd5ba016edf9f5ec94f79154ed5d9bbd9e5",
"md5": "8e1fd5a7c8d65569fff10a5357e222a9",
"sha256": "b0d0c5a94720343a1a942246c53881717c1e5bb228b98c0fb50907bd81bd34ba"
},
"downloads": -1,
"filename": "disruption_py-0.9.0-py3-none-any.whl",
"has_sig": false,
"md5_digest": "8e1fd5a7c8d65569fff10a5357e222a9",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": "<4.0,>=3.10",
"size": 111393,
"upload_time": "2025-01-16T21:26:33",
"upload_time_iso_8601": "2025-01-16T21:26:33.712458Z",
"url": "https://files.pythonhosted.org/packages/9d/83/bfde0ec1b7a827648b0070849fd5ba016edf9f5ec94f79154ed5d9bbd9e5/disruption_py-0.9.0-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "b32d65da507ecded106f31e56b69ac7a7a23141c5d90523f915a53b6918c7431",
"md5": "d8b45acc8bb1a167aa866b742eb6e85e",
"sha256": "e8ca576475069370e6b80c02cd827daaaa2f0fd35086af017373e576621e5e1a"
},
"downloads": -1,
"filename": "disruption_py-0.9.0.tar.gz",
"has_sig": false,
"md5_digest": "d8b45acc8bb1a167aa866b742eb6e85e",
"packagetype": "sdist",
"python_version": "source",
"requires_python": "<4.0,>=3.10",
"size": 96142,
"upload_time": "2025-01-16T21:26:35",
"upload_time_iso_8601": "2025-01-16T21:26:35.226732Z",
"url": "https://files.pythonhosted.org/packages/b3/2d/65da507ecded106f31e56b69ac7a7a23141c5d90523f915a53b6918c7431/disruption_py-0.9.0.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2025-01-16 21:26:35",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "MIT-PSFC",
"github_project": "disruption-py",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"lcname": "disruption-py"
}
JSON
