Metadata-Version: 2.5
Name: constellaration
Version: 0.3.0
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 :: 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==0.17.1
Requires-Dist: interpax==0.3.14
Requires-Dist: ipykernel
Requires-Dist: ipython
Requires-Dist: jax<=0.10.0
Requires-Dist: jaxtyping
Requires-Dist: kaleido
Requires-Dist: matplotlib==3.9.2
Requires-Dist: nbformat
Requires-Dist: nevergrad
Requires-Dist: numpy<2.3,>=2.1.3
Requires-Dist: orjson==3.10.16
Requires-Dist: pandas==2.2.3
Requires-Dist: plotly<7.0.0
Requires-Dist: pybind11<3.0.0
Requires-Dist: pydantic
Requires-Dist: pymoo==0.6.1.5
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.5.4
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 benchmarks, 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.

## Reproducibility and benchmark versions

This repository is under active development: new metrics, problems and dependency updates (e.g. [VMEC++](https://github.com/proximafusion/vmecpp)) can change the values computed by the forward model and the scoring functions.
To keep results comparable, the benchmark of [Cadena et al., NeurIPS 2025](https://openreview.net/forum?id=NQSbGKlCpx) is frozen to a tagged release.

| Use case | Version |
| --- | --- |
| [ConStellaration leaderboard](https://huggingface.co/spaces/proxima-fusion/constellaration-bench) (geometrical, simple-to-build QI, MHD-stable QI problems) | [`v0.3.0`](https://github.com/proximafusion/constellaration/releases/tag/v0.3.0) |
| Original NeurIPS 2025 paper experiments | [`0.2.1`](https://pypi.org/project/constellaration/0.2.1/) |
| Latest development | `main` |

If you are working on the challenge or comparing against the leaderboard, install the pinned benchmark release:

```bash
pip install constellaration==0.3.0
```

or, from source:

```bash
git clone --branch v0.3.0 https://github.com/proximafusion/constellaration.git
cd constellaration
pip install .
```

The leaderboard evaluates every submission with exactly this version, so scores computed locally with `constellaration==0.3.0` match the leaderboard.
Releases newer than `v0.3.0` may produce different metrics and scores and are not used by the leaderboard until explicitly announced here.
The PyPI version always equals the git tag of the release it was built from (`constellaration==X.Y.Z` ⇔ tag `vX.Y.Z`).

Differences of `v0.3.0` with respect to `0.2.1` (used for the original paper experiments) that can affect the benchmark scores:
- The rotational transform constraint uses the absolute value of the edge rotational transform, i.e. boundaries with negative iota are no longer penalized.
- Newer versions of VMEC++ and of other numerical dependencies (`booz-xform`, `jax`, `desc-opt`) are used, which can cause small numerical differences.

To reproduce the exact numbers of the paper, use `pip install constellaration==0.2.1` (this version is no longer maintained and may require pinning older versions of its unpinned dependencies).

## 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 system dependencies
   1. **On Ubuntu**: `sudo apt-get update && sudo apt-get install -y libnetcdf-dev`
   2. **On macOS**: `brew install netcdf`

3. Install the required Python dependencies:

  ```bash
  pip install .
  ```

  **Note for macOS:** building `booz-xform` from source calls `python` from the `PATH`. If `python` does not resolve to the interpreter you are installing into (e.g. with a pyenv `system` global, where only `python3` exists), the build fails with `Could not find a package configuration file provided by "pybind11"`. Install into an activated virtual environment so that `python` points to it:

  ```bash
  python3 -m venv .venv
  source .venv/bin/activate
  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

```
@inproceedings{
cadena2025constellaration,
title={ConStellaration: A dataset of {QI}-like stellarator plasma boundaries and optimization benchmarks},
author={Santiago A Cadena and Andrea Merlo and Emanuel Laude and Alexander Bauer and Atul Agrawal and Maria Pascu and Marija Savtchouk and Lukas Bonauer and Enrico Guiraud and Stuart R. Hudson and Markus Kaiser},
booktitle={The Thirty-ninth Annual Conference on Neural Information Processing Systems Datasets and Benchmarks Track},
year={2025},
url={https://openreview.net/forum?id=NQSbGKlCpx}
}
```
