Metadata-Version: 2.4
Name: constellaration
Version: 0.2.3
Summary: Code for analyzing and evaluating stellarator plasma shapes
Project-URL: Documentation, https://github.com/proximafusion/constellaration#readme
Project-URL: Issues, https://github.com/proximafusion/constellaration/issues
Project-URL: Source, https://github.com/proximafusion/constellaration
Author-email: Maria Pascu <mariap@proximafusion.com>
License-Expression: MIT
License-File: LICENSE
Classifier: Development Status :: 4 - Beta
Classifier: Programming Language :: Python
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Programming Language :: Python :: Implementation :: CPython
Classifier: Programming Language :: Python :: Implementation :: PyPy
Requires-Python: >=3.10
Requires-Dist: booz-xform==0.0.9
Requires-Dist: datasets==3.5.1
Requires-Dist: desc-opt
Requires-Dist: interpax
Requires-Dist: ipykernel
Requires-Dist: ipython
Requires-Dist: jaxtyping
Requires-Dist: kaleido==0.2.1
Requires-Dist: matplotlib==3.9.2
Requires-Dist: nbformat
Requires-Dist: nevergrad
Requires-Dist: numpy==2.1.3
Requires-Dist: orjson==3.10.16
Requires-Dist: pandas==2.2.3
Requires-Dist: plotly==6.0.1
Requires-Dist: pybind11<3.0.0
Requires-Dist: pydantic
Requires-Dist: pymoo==0.6.1.5.dev0
Requires-Dist: qicna==0.3.4
Requires-Dist: scikit-activeml==0.5.2
Requires-Dist: scikit-build-core==0.10
Requires-Dist: scikit-learn==1.5.2
Requires-Dist: scipy
Requires-Dist: seaborn==0.13.2
Requires-Dist: simsopt==1.8.1; python_version < '3.13'
Requires-Dist: simsopt==1.9.0; python_version >= '3.13'
Requires-Dist: vmecpp==0.4.7
Provides-Extra: lint
Requires-Dist: pre-commit; extra == 'lint'
Provides-Extra: test
Requires-Dist: pytest; extra == 'test'
Description-Content-Type: text/markdown

<picture>
  <source media="(prefers-color-scheme: dark)" srcset="https://github.com/user-attachments/assets/978b76bc-cd9b-4af8-b1f3-18efde7c079f">
  <source media="(prefers-color-scheme: light)" srcset="https://github.com/user-attachments/assets/ec4e391a-9044-44ae-93f0-9dd8bed70001">
  <img alt="A dark Proxima logo in light color mode and a light one in dark color mode." src="https://github.com/user-attachments/assets/ec4e391a-9044-44ae-93f0-9dd8bed70001" width=400px>
</picture>

# ConStellaration: A dataset of QI-like stellarator plasma boundaries and optimization benchmarks

[ConStellaration](https://arxiv.org/abs/2506.19583) is a dataset of diverse QI-like stellarator plasma boundary shapes and optimization benchmakrs, paired with their ideal-MHD equilibria and performance metrics.
The dataset is available on [Hugging Face](https://huggingface.co/datasets/proxima-fusion/constellaration).
The repository contains a suite of tools and notebooks for exploring the dataset, including a forward model for plasma simulation, scoring functions for optimization evaluation and data-driven generative modeling.

## Installation

The following instructions have been tested on **Ubuntu 22.04** and **Ubuntu 24.04**. Other platforms may require additional steps and have not been validated.

The system dependency `libnetcdf-dev` is required for running the forward model. On Ubuntu, please ensure it is installed before proceeding, by running:

  ```bash
  sudo apt-get update
  sudo apt-get install build-essential cmake libnetcdf-dev
  ```

### Install from PyPI

The package can be installed directly from PyPI:

```bash
pip install constellaration
```

### Install by cloning the repository

1. Clone the repository:

  ```bash
  git clone https://github.com/proximafusion/constellaration.git
  cd constellaration
  ```

2. Install the required Python dependencies:

  ```bash
  pip install .
  ```

### Running with Docker

If you prefer not to install system dependencies, you can use the provided Dockerfile to build a Docker image and run your scripts in a container.

1. Build the Docker image:

  ```bash
  docker build -t constellaration .
  ```

2. Run your scripts by mounting a volume to the container:

  ```bash
  docker run --rm -v $(pwd):/workspace constellaration python relative/path/to/your_script.py
  ```

Replace `your_script.py` with the path to your script. The `$(pwd)` command mounts the current directory to `/workspace` inside the container.

## Explanation Notebook

You can explore the functionalities of the repo through the [Boundary Explorer Notebook](https://github.com/proximafusion/constellaration/blob/main/notebooks/boundary_explorer.ipynb).

## Contributing

To be able to run unit tests, please install the test and lint environment:

```bash
pip install -e ".[test,lint]"
```

**Note:** The development and test environment currently supports **Python 3.10** only. Other Python versions are not guaranteed to work.
### Linting

We use **pre-commit** to automatically lint and format code before each commit. Linting is static code analysis that catches style issues and potential errors. If any **hook** fails, the commit will be blocked until you fix the reported issues and re-stage your changes.

 Install the hook (once per clone):
```bash
pip install pre-commit
pre-commit install
```

You can run all pre-commit hooks against all files like this:
```bash
pre-commit run --all-files
```
### Unit tests

To locally run all unit tests (while in the top directory of the repo)

```bash
pytest .
```

## Optimization baseline

The optimization baseline can be executed by running the individual files within the folder `optimization_examples`.

## Citation

```
@article{cadena2025constellaration,
  title={ConStellaration: A dataset of QI-like stellarator plasma boundaries and optimization benchmarks},
  author={Cadena, Santiago A and Merlo, Andrea and Laude, Emanuel and Bauer, Alexander and Agrawal, Atul and Pascu, Maria and Savtchouk, Marija and Guiraud, Enrico and Bonauer, Lukas and Hudson, Stuart and others},
  journal={arXiv preprint arXiv:2506.19583},
  year={2025}
}
```
