| Name | essos JSON |
| Version |
0.16
JSON |
| download |
| home_page | None |
| Summary | ESSOS: e-Stellarator Simulation and Optimization Suite |
| upload_time | 2025-08-23 12:45:22 |
| maintainer | None |
| docs_url | None |
| author | None |
| requires_python | >=3.10 |
| license | MIT License
Copyright (c) 2024 uwplasma
Permission is hereby granted, free of charge, to any person obtaining a copy
of this software and associated documentation files (the "Software"), to deal
in the Software without restriction, including without limitation the rights
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
copies of the Software, and to permit persons to whom the Software is
furnished to do so, subject to the following conditions:
The above copyright notice and this permission notice shall be included in all
copies or substantial portions of the Software.
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
SOFTWARE.
|
| keywords |
plasma
physics
simulation
jax
|
| VCS |
 |
| bugtrack_url |
|
| requirements |
jax
jaxlib
tqdm
matplotlib
diffrax
optax
scipy
jaxkd
netcdf4
f90nml
pyevtk
optuna
pandas
|
| Travis-CI |
No Travis.
|
| coveralls test coverage |
No coveralls.
|
<p align="center">
<img src="https://raw.githubusercontent.com/uwplasma/ESSOS/refs/heads/main/docs/ESSOS_logo.png" align="center" width="30%">
</p>
<p align="center">
<em><code>❯ ESSOS: e-Stellarator Simulation and Optimization Suite</code></em>
</p>
<p align="center">
<img src="https://img.shields.io/github/license/uwplasma/ESSOS?style=default&logo=opensourceinitiative&logoColor=white&color=0080ff" alt="license">
<img src="https://img.shields.io/github/last-commit/uwplasma/ESSOS?style=default&logo=git&logoColor=white&color=0080ff" alt="last-commit">
<img src="https://img.shields.io/github/languages/top/uwplasma/ESSOS?style=default&color=0080ff" alt="repo-top-language">
<a href="https://github.com/uwplasma/ESSOS/actions/workflows/build_test.yml">
<img src="https://github.com/uwplasma/ESSOS/actions/workflows/build_test.yml/badge.svg" alt="Build Status">
</a>
<a href="https://codecov.io/gh/uwplasma/ESSOS">
<img src="https://codecov.io/gh/uwplasma/ESSOS/branch/main/graph/badge.svg" alt="Coverage">
</a>
<a href="https://essos.readthedocs.io/en/latest/?badge=latest">
<img src="https://readthedocs.org/projects/essos/badge/?version=latest" alt="Documentation Status">
</a>
</p>
## Table of Contents
- [Overview](#overview)
- [Features](#features)
- [Project Structure](#project-structure)
- [Getting Started](#getting-started)
- [Prerequisites](#prerequisites)
- [Installation](#installation)
- [From PyPI](#from-pypi)
- [From Source](#from-source)
- [Usage](#usage)
- [Testing](#testing)
- [Project Roadmap](#project-roadmap)
- [Contributing](#contributing)
- [License](#license)
- [Acknowledgments](#acknowledgments)
## Overview
ESSOS is an open-source project in Python that uses JAX to optimize stellarator coils. Optimization can be applied to several objectives, such as alpha particle confinement, plasma boundaries and magnetic field equilibria (including near-axis expansions). It leverages automatic differentiation and efficient numerical methods to streamline optimization efforts, creating a specialized and fast numerical tool for optimizing force-free stellarator equilibria. It is parallelized using JAX's sharding tools. It can be imported in a Python script using the **essos** package, or run directly in the command line as `essos`. To install it, use
```sh
pip install essos
```
Alternatively, you can download it and run the example scripts in the repository after downloading it as
```sh
git clone https://github.com/uwplasma/ESSOS
cd ESSOS
pip install .
python examples/trace_particles_from_coils.py
```
The project can be downloaded in its [GitHub repository](https://github.com/uwplasma/ESSOS).
## Features
- **JAX Integration**: Utilizes JAX for automatic differentiation and efficient numerical computations.
- **Optimization**: Implements optimization routines for stellarator coil design.
- **Particle Tracing**: Traces alpha particles in magnetic fields generated by coils.
- **Fieldline Tracing**: Traces magnetic field lines.
- **Coils and Near-Axis Fields**: Models and optimizes electromagnetic coils and near-axis magnetic fields.
## Project Structure
```
ESSOS/
├── essos/
│ ├── __init__.py
│ ├── __main__.py
│ ├── coils.py
│ ├── constants.py
│ ├── dynamics.py
│ ├── fields.py
│ ├── objective_functions.py
│ ├── optimization.py
│ ├── plot.py
│ └── surfaces.py
├── examples/
│ ├── create_stellarator_coils.py
│ ├── optimize_coils_and_nearaxis.py
│ ├── optimize_coils_for_nearaxis.py
│ ├── optimize_coils_particle_confinement_fullorbit.py
│ ├── optimize_coils_particle_confinement_guidingcenter.py
│ ├── optimize_coils_vmec_surface.py
│ ├── trace_fieldlines_coils.py
│ ├── trace_particles_coils_fullorbit.py
│ ├── trace_particles_coils_guidingcenter.py
│ ├── trace_particles_vmec.py
│ └── comparisons_SIMSOPT/
│ └── inputs/
│ ├── ESSOS_bio_savart_LandremanPaulQA.json
│ ├── SIMSOPT_bio_savart_LandremanPaulQA.json
│ ├── wout_n3are_R7.75B5.7.nc
│ └── wout_LandremanPaul2021_QA_reactorScale_lowres.nc
├── tests/
│ ├── test_coils.py
│ ├── test_constants.py
│ ├── test_dynamics.py
│ ├── test_fields.py
├── README.md
├── LICENSE.md
├── CODE_OF_CONDUCT.md
├── CONTRIBUTING.md
├── setup.py
├── pyproject.toml
└── requirements.txt
```
## Getting Started
### Prerequisites
- Python 3.8 or higher
### Installation
#### From PyPI
To install ESSOS from PyPI, run:
```sh
pip install essos
```
#### From Source
To install ESSOS from source, clone the repository and install the package:
```sh
git clone https://github.com/uwplasma/ESSOS
cd ESSOS
pip install .
```
## Usage
ESSOS can be run directly in the command line as `essos`, or by following one of the examples in the `examples` folder. For example, to trace particles in a magnetic field generated from coils, run:
```sh
python examples/trace_particles_coils_guidingcenter.py
```
## Testing
To run the tests, use `pytest`:
```sh
pytest .
```
## Project Roadmap
- [ ] Allow several optimization algorithms
- [ ] Allow plotly and/or Mayavi visualization
- [ ] Add DESC and SPEC equilibria for tracing
- [ ] Add beam injection examples
- [ ] Add plotting for near-axis expansion
- [ ] Add particle collisions
## Contributing
Contributions are welcome! Please fork the repository and submit a pull request. For major changes, please open an issue first to discuss what you would like to change.
- **💬 [Join the Discussions](https://github.com/uwplasma/ESSOS/discussions)**: Share your insights, provide feedback, or ask questions.
- **🐛 [Report Issues](https://github.com/uwplasma/ESSOS/issues)**: Submit bugs found or log feature requests for the `ESSOS` project.
- **💡 [Submit Pull Requests](https://github.com/uwplasma/ESSOS/blob/main/CONTRIBUTING.md)**: Review open PRs, and submit your own PRs.
<details closed>
<summary>Contributing Guidelines</summary>
1. **Fork the Repository**: Start by forking the project repository to your github account.
2. **Clone Locally**: Clone the forked repository to your local machine using a git client.
```sh
git clone https://github.com/uwplasma/ESSOS
```
3. **Create a New Branch**: Always work on a new branch, giving it a descriptive name.
```sh
git checkout -b new-feature-x
```
4. **Make Your Changes**: Develop and test your changes locally.
5. **Commit Your Changes**: Commit with a clear message describing your updates.
```sh
git commit -m 'Implemented new feature x.'
```
6. **Push to github**: Push the changes to your forked repository.
```sh
git push origin new-feature-x
```
7. **Submit a Pull Request**: Create a PR against the original project repository. Clearly describe the changes and their motivations.
8. **Review**: Once your PR is reviewed and approved, it will be merged into the main branch. Congratulations on your contribution!
</details>
<details closed>
<summary>Contributor Graph</summary>
<br>
<p align="left">
<a href="https://github.com{/uwplasma/ESSOS/}graphs/contributors">
<img src="https://contrib.rocks/image?repo=uwplasma/ESSOS">
</a>
</p>
</details>
---
## License
This project is protected under the MIT License. For more details, refer to the [LICENSE](LICENSE) file.
---
## Acknowledgments
- This project was developed as part of the New Talents in Physics Fellowship, awarded by the [Calouste Gulbenkian Foundation](https://gulbenkian.pt/en/).
- We acknowledge the help of the whole [UWPlasma](https://rogerio.physics.wisc.edu/) plasma group.
---
Raw data
{
"_id": null,
"home_page": null,
"name": "essos",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.10",
"maintainer_email": null,
"keywords": "Plasma, Physics, Simulation, JAX",
"author": null,
"author_email": "\"UWPlasma, UW-Madison group\" <rogerio.jorge@wisc.edu>",
"download_url": "https://files.pythonhosted.org/packages/f8/b6/97403f898b96922c72fa8f41580d057e6a5766ee5314738b9bed241d8aa9/essos-0.16.tar.gz",
"platform": null,
"description": "<p align=\"center\">\n <img src=\"https://raw.githubusercontent.com/uwplasma/ESSOS/refs/heads/main/docs/ESSOS_logo.png\" align=\"center\" width=\"30%\">\n</p>\n<p align=\"center\">\n <em><code>\u276f ESSOS: e-Stellarator Simulation and Optimization Suite</code></em>\n</p>\n<p align=\"center\">\n <img src=\"https://img.shields.io/github/license/uwplasma/ESSOS?style=default&logo=opensourceinitiative&logoColor=white&color=0080ff\" alt=\"license\">\n <img src=\"https://img.shields.io/github/last-commit/uwplasma/ESSOS?style=default&logo=git&logoColor=white&color=0080ff\" alt=\"last-commit\">\n <img src=\"https://img.shields.io/github/languages/top/uwplasma/ESSOS?style=default&color=0080ff\" alt=\"repo-top-language\">\n <a href=\"https://github.com/uwplasma/ESSOS/actions/workflows/build_test.yml\">\n <img src=\"https://github.com/uwplasma/ESSOS/actions/workflows/build_test.yml/badge.svg\" alt=\"Build Status\">\n </a>\n <a href=\"https://codecov.io/gh/uwplasma/ESSOS\">\n <img src=\"https://codecov.io/gh/uwplasma/ESSOS/branch/main/graph/badge.svg\" alt=\"Coverage\">\n </a>\n <a href=\"https://essos.readthedocs.io/en/latest/?badge=latest\">\n <img src=\"https://readthedocs.org/projects/essos/badge/?version=latest\" alt=\"Documentation Status\">\n </a>\n</p>\n\n## Table of Contents\n- [Overview](#overview)\n- [Features](#features)\n- [Project Structure](#project-structure)\n- [Getting Started](#getting-started)\n - [Prerequisites](#prerequisites)\n - [Installation](#installation)\n - [From PyPI](#from-pypi)\n - [From Source](#from-source)\n- [Usage](#usage)\n- [Testing](#testing)\n- [Project Roadmap](#project-roadmap)\n- [Contributing](#contributing)\n- [License](#license)\n- [Acknowledgments](#acknowledgments)\n\n## Overview\nESSOS is an open-source project in Python that uses JAX to optimize stellarator coils. Optimization can be applied to several objectives, such as alpha particle confinement, plasma boundaries and magnetic field equilibria (including near-axis expansions). It leverages automatic differentiation and efficient numerical methods to streamline optimization efforts, creating a specialized and fast numerical tool for optimizing force-free stellarator equilibria. It is parallelized using JAX's sharding tools. It can be imported in a Python script using the **essos** package, or run directly in the command line as `essos`. To install it, use\n\n ```sh\n pip install essos\n ```\n\nAlternatively, you can download it and run the example scripts in the repository after downloading it as\n\n ```sh\n git clone https://github.com/uwplasma/ESSOS\n cd ESSOS\n pip install .\n python examples/trace_particles_from_coils.py\n ```\n\nThe project can be downloaded in its [GitHub repository](https://github.com/uwplasma/ESSOS).\n\n## Features\n- **JAX Integration**: Utilizes JAX for automatic differentiation and efficient numerical computations.\n- **Optimization**: Implements optimization routines for stellarator coil design.\n- **Particle Tracing**: Traces alpha particles in magnetic fields generated by coils.\n- **Fieldline Tracing**: Traces magnetic field lines.\n- **Coils and Near-Axis Fields**: Models and optimizes electromagnetic coils and near-axis magnetic fields.\n\n## Project Structure\n```\nESSOS/\n\u251c\u2500\u2500 essos/\n\u2502 \u251c\u2500\u2500 __init__.py\n\u2502 \u251c\u2500\u2500 __main__.py\n\u2502 \u251c\u2500\u2500 coils.py\n\u2502 \u251c\u2500\u2500 constants.py\n\u2502 \u251c\u2500\u2500 dynamics.py\n\u2502 \u251c\u2500\u2500 fields.py\n\u2502 \u251c\u2500\u2500 objective_functions.py\n\u2502 \u251c\u2500\u2500 optimization.py\n\u2502 \u251c\u2500\u2500 plot.py\n\u2502 \u2514\u2500\u2500 surfaces.py\n\u251c\u2500\u2500 examples/\n\u2502 \u251c\u2500\u2500 create_stellarator_coils.py\n\u2502 \u251c\u2500\u2500 optimize_coils_and_nearaxis.py\n\u2502 \u251c\u2500\u2500 optimize_coils_for_nearaxis.py\n\u2502 \u251c\u2500\u2500 optimize_coils_particle_confinement_fullorbit.py\n\u2502 \u251c\u2500\u2500 optimize_coils_particle_confinement_guidingcenter.py\n\u2502 \u251c\u2500\u2500 optimize_coils_vmec_surface.py\n\u2502 \u251c\u2500\u2500 trace_fieldlines_coils.py\n\u2502 \u251c\u2500\u2500 trace_particles_coils_fullorbit.py\n\u2502 \u251c\u2500\u2500 trace_particles_coils_guidingcenter.py\n\u2502 \u251c\u2500\u2500 trace_particles_vmec.py\n\u2502 \u2514\u2500\u2500 comparisons_SIMSOPT/\n\u2502 \u2514\u2500\u2500 inputs/\n\u2502 \u251c\u2500\u2500 ESSOS_bio_savart_LandremanPaulQA.json\n\u2502 \u251c\u2500\u2500 SIMSOPT_bio_savart_LandremanPaulQA.json\n\u2502 \u251c\u2500\u2500 wout_n3are_R7.75B5.7.nc\n\u2502 \u2514\u2500\u2500 wout_LandremanPaul2021_QA_reactorScale_lowres.nc\n\u251c\u2500\u2500 tests/\n\u2502 \u251c\u2500\u2500 test_coils.py\n\u2502 \u251c\u2500\u2500 test_constants.py\n\u2502 \u251c\u2500\u2500 test_dynamics.py\n\u2502 \u251c\u2500\u2500 test_fields.py\n\u251c\u2500\u2500 README.md\n\u251c\u2500\u2500 LICENSE.md\n\u251c\u2500\u2500 CODE_OF_CONDUCT.md\n\u251c\u2500\u2500 CONTRIBUTING.md\n\u251c\u2500\u2500 setup.py\n\u251c\u2500\u2500 pyproject.toml\n\u2514\u2500\u2500 requirements.txt\n```\n\n## Getting Started\n\n### Prerequisites\n- Python 3.8 or higher\n\n### Installation\n\n#### From PyPI\nTo install ESSOS from PyPI, run:\n```sh\npip install essos\n```\n\n#### From Source\nTo install ESSOS from source, clone the repository and install the package:\n```sh\ngit clone https://github.com/uwplasma/ESSOS\ncd ESSOS\npip install .\n```\n\n## Usage\nESSOS can be run directly in the command line as `essos`, or by following one of the examples in the `examples` folder. For example, to trace particles in a magnetic field generated from coils, run:\n```sh\npython examples/trace_particles_coils_guidingcenter.py\n```\n\n## Testing\nTo run the tests, use `pytest`:\n```sh\npytest .\n```\n\n## Project Roadmap\n- [ ] Allow several optimization algorithms\n- [ ] Allow plotly and/or Mayavi visualization\n- [ ] Add DESC and SPEC equilibria for tracing\n- [ ] Add beam injection examples\n- [ ] Add plotting for near-axis expansion\n- [ ] Add particle collisions\n\n## Contributing\nContributions are welcome! Please fork the repository and submit a pull request. For major changes, please open an issue first to discuss what you would like to change.\n\n- **\ud83d\udcac [Join the Discussions](https://github.com/uwplasma/ESSOS/discussions)**: Share your insights, provide feedback, or ask questions.\n- **\ud83d\udc1b [Report Issues](https://github.com/uwplasma/ESSOS/issues)**: Submit bugs found or log feature requests for the `ESSOS` project.\n- **\ud83d\udca1 [Submit Pull Requests](https://github.com/uwplasma/ESSOS/blob/main/CONTRIBUTING.md)**: Review open PRs, and submit your own PRs.\n\n<details closed>\n<summary>Contributing Guidelines</summary>\n\n1. **Fork the Repository**: Start by forking the project repository to your github account.\n2. **Clone Locally**: Clone the forked repository to your local machine using a git client.\n ```sh\n git clone https://github.com/uwplasma/ESSOS\n ```\n3. **Create a New Branch**: Always work on a new branch, giving it a descriptive name.\n ```sh\n git checkout -b new-feature-x\n ```\n4. **Make Your Changes**: Develop and test your changes locally.\n5. **Commit Your Changes**: Commit with a clear message describing your updates.\n ```sh\n git commit -m 'Implemented new feature x.'\n ```\n6. **Push to github**: Push the changes to your forked repository.\n ```sh\n git push origin new-feature-x\n ```\n7. **Submit a Pull Request**: Create a PR against the original project repository. Clearly describe the changes and their motivations.\n8. **Review**: Once your PR is reviewed and approved, it will be merged into the main branch. Congratulations on your contribution!\n</details>\n\n<details closed>\n<summary>Contributor Graph</summary>\n<br>\n<p align=\"left\">\n <a href=\"https://github.com{/uwplasma/ESSOS/}graphs/contributors\">\n <img src=\"https://contrib.rocks/image?repo=uwplasma/ESSOS\">\n </a>\n</p>\n</details>\n\n---\n\n## License\n\nThis project is protected under the MIT License. For more details, refer to the [LICENSE](LICENSE) file.\n\n---\n\n## Acknowledgments\n\n- This project was developed as part of the New Talents in Physics Fellowship, awarded by the [Calouste Gulbenkian Foundation](https://gulbenkian.pt/en/).\n- We acknowledge the help of the whole [UWPlasma](https://rogerio.physics.wisc.edu/) plasma group.\n\n---\n\n",
"bugtrack_url": null,
"license": "MIT License\n \n Copyright (c) 2024 uwplasma\n \n Permission is hereby granted, free of charge, to any person obtaining a copy\n of this software and associated documentation files (the \"Software\"), to deal\n in the Software without restriction, including without limitation the rights\n to use, copy, modify, merge, publish, distribute, sublicense, and/or sell\n copies of the Software, and to permit persons to whom the Software is\n furnished to do so, subject to the following conditions:\n \n The above copyright notice and this permission notice shall be included in all\n copies or substantial portions of the Software.\n \n THE SOFTWARE IS PROVIDED \"AS IS\", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR\n IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,\n FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE\n AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER\n LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,\n OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE\n SOFTWARE.\n ",
"summary": "ESSOS: e-Stellarator Simulation and Optimization Suite",
"version": "0.16",
"project_urls": {
"Homepage": "https://github.com/uwplasma/ESSOS"
},
"split_keywords": [
"plasma",
" physics",
" simulation",
" jax"
],
"urls": [
{
"comment_text": null,
"digests": {
"blake2b_256": "b9d711c4e345defc4d1e21f81b7994030b6820dddef89c8b819edb3a171b5219",
"md5": "e4486c05dbf55fbea1302cfd7f64313f",
"sha256": "be81c40c215ef8fb5e1a9ed8e283a9a63fe82d71f5badd1fc4955f28718c6920"
},
"downloads": -1,
"filename": "essos-0.16-py3-none-any.whl",
"has_sig": false,
"md5_digest": "e4486c05dbf55fbea1302cfd7f64313f",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.10",
"size": 50330,
"upload_time": "2025-08-23T12:45:20",
"upload_time_iso_8601": "2025-08-23T12:45:20.431488Z",
"url": "https://files.pythonhosted.org/packages/b9/d7/11c4e345defc4d1e21f81b7994030b6820dddef89c8b819edb3a171b5219/essos-0.16-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": null,
"digests": {
"blake2b_256": "f8b697403f898b96922c72fa8f41580d057e6a5766ee5314738b9bed241d8aa9",
"md5": "959543d0a630340b74331a51e5fbeaee",
"sha256": "172bfc4b4d1d8f45ebeb43022fb6a955cf5030e9957cc4d01c024c52f9101a75"
},
"downloads": -1,
"filename": "essos-0.16.tar.gz",
"has_sig": false,
"md5_digest": "959543d0a630340b74331a51e5fbeaee",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.10",
"size": 7135700,
"upload_time": "2025-08-23T12:45:22",
"upload_time_iso_8601": "2025-08-23T12:45:22.046414Z",
"url": "https://files.pythonhosted.org/packages/f8/b6/97403f898b96922c72fa8f41580d057e6a5766ee5314738b9bed241d8aa9/essos-0.16.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2025-08-23 12:45:22",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "uwplasma",
"github_project": "ESSOS",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"requirements": [
{
"name": "jax",
"specs": []
},
{
"name": "jaxlib",
"specs": []
},
{
"name": "tqdm",
"specs": []
},
{
"name": "matplotlib",
"specs": []
},
{
"name": "diffrax",
"specs": []
},
{
"name": "optax",
"specs": []
},
{
"name": "scipy",
"specs": []
},
{
"name": "jaxkd",
"specs": []
},
{
"name": "netcdf4",
"specs": []
},
{
"name": "f90nml",
"specs": []
},
{
"name": "pyevtk",
"specs": []
},
{
"name": "optuna",
"specs": []
},
{
"name": "pandas",
"specs": []
}
],
"lcname": "essos"
}
