constellaration 0.2.6__tar.gz → 0.3.0__tar.gz

{constellaration-0.2.6 → constellaration-0.3.0}/.gitignore

@@ -172,3 +172,9 @@ cython_debug/
 
 # PyPI configuration file
 .pypirc
+
+# Presentation visualizations
+presentations/
+
+# Generated by hatch-vcs at build time from the git tag
+src/constellaration/__about__.py

{constellaration-0.2.6 → constellaration-0.3.0}/LICENSE

@@ -1,6 +1,6 @@
 MIT License
 
-Copyright (c) 2025-present Proxima Fusion Gmbh <info@proximafusion.com>
+Copyright (c) 2025-present Proxima Fusion GmbH <info@proximafusion.com>
 
 Permission is hereby granted, free of charge, to any person obtaining a copy
 of this software and associated documentation files (the "Software"), to deal

{constellaration-0.2.6 → constellaration-0.3.0}/PKG-INFO

@@ -1,6 +1,6 @@
-Metadata-Version: 2.4
+Metadata-Version: 2.5
 Name: constellaration
-Version: 0.2.6
+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
@@ -18,17 +18,17 @@ 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==0.3.8
+Requires-Dist: desc-opt==0.17.1
+Requires-Dist: interpax==0.3.14
 Requires-Dist: ipykernel
 Requires-Dist: ipython
-Requires-Dist: jax<=0.6.0
+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.1.3
+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
@@ -43,7 +43,7 @@ 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.11
+Requires-Dist: vmecpp==0.5.4
 Provides-Extra: lint
 Requires-Dist: pre-commit; extra == 'lint'
 Provides-Extra: test
@@ -58,10 +58,45 @@ Description-Content-Type: text/markdown
 
 # 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.
+[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.
@@ -92,7 +127,7 @@ pip install constellaration
 
 2. Install the required system dependencies
    1. **On Ubuntu**: `sudo apt-get update && sudo apt-get install -y libnetcdf-dev`
-   2. **On MAC-OS**: `brew install netcdf`
+   2. **On macOS**: `brew install netcdf`
 
 3. Install the required Python dependencies:
 
@@ -100,6 +135,14 @@ pip install constellaration
   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.
@@ -135,7 +178,7 @@ pip install -e ".[test,lint]"
 
 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):
+Install the hook (once per clone):
 ```bash
 pip install pre-commit
 pre-commit install

{constellaration-0.2.6 → constellaration-0.3.0}/README.md

@@ -6,10 +6,45 @@
 
 # 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.
+[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.
@@ -40,7 +75,7 @@ pip install constellaration
 
 2. Install the required system dependencies
    1. **On Ubuntu**: `sudo apt-get update && sudo apt-get install -y libnetcdf-dev`
-   2. **On MAC-OS**: `brew install netcdf`
+   2. **On macOS**: `brew install netcdf`
 
 3. Install the required Python dependencies:
 
@@ -48,6 +83,14 @@ pip install constellaration
   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.
@@ -83,7 +126,7 @@ pip install -e ".[test,lint]"
 
 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):
+Install the hook (once per clone):
 ```bash
 pip install pre-commit
 pre-commit install

constellaration-0.3.0/constellaration/__about__.py

@@ -0,0 +1,24 @@
+# file generated by vcs-versioning
+# don't change, don't track in version control
+from __future__ import annotations
+
+__all__ = [
+    "__version__",
+    "__version_tuple__",
+    "version",
+    "version_tuple",
+    "__commit_id__",
+    "commit_id",
+]
+
+version: str
+__version__: str
+__version_tuple__: tuple[int | str, ...]
+version_tuple: tuple[int | str, ...]
+commit_id: str | None
+__commit_id__: str | None
+
+__version__ = version = '0.3.0'
+__version_tuple__ = version_tuple = (0, 3, 0)
+
+__commit_id__ = commit_id = None

{constellaration-0.2.6 → constellaration-0.3.0}/constellaration/boozer/boozer.py

@@ -41,7 +41,7 @@ class BoozerOutput(pydantic.BaseModel, arbitrary_types_allowed=True):
     """The number of Boozer poloidal modes."""
 
     max_boozer_toroidal_mode: int
-    """The number of Boozer toroidal modes."""
+    """The maximum Boozer toroidal mode number."""
 
     n_poloidal_modes: int
     """The number of poloidal modes."""
@@ -100,10 +100,10 @@ class BoozerOutput(pydantic.BaseModel, arbitrary_types_allowed=True):
     """The magnetic field strength sine Fourier coefficients in Boozer coordinates."""
 
     gmnc_b: FOURIER_COEFFICIENTS
-    """The equilibrium jacobian cosine Fourier coefficients in Boozer coordinates."""
+    """The equilibrium Jacobian cosine Fourier coefficients in Boozer coordinates."""
 
     gmns_b: FOURIER_COEFFICIENTS
-    """The equilibrium jacobian sine Fourier coefficients in Boozer coordinates."""
+    """The equilibrium Jacobian sine Fourier coefficients in Boozer coordinates."""
 
     rmnc_b: FOURIER_COEFFICIENTS
     """The equilibrium flux surfaces R coordinate cosine Fourier coefficients in Boozer
@@ -216,7 +216,7 @@ class BoozerSettings(pydantic.BaseModel):
     """
 
     verbose: bool = False
-    """If True, running booz_xform in verbose mode."""
+    """If True, runs booz_xform in verbose mode."""
 
 
 class BoozerPresetSettings(pydantic.BaseModel):
@@ -230,7 +230,7 @@ class BoozerPresetSettings(pydantic.BaseModel):
     """
 
     verbose: bool = False
-    """If True, running booz_xform in verbose mode."""
+    """If True, runs booz_xform in verbose mode."""
 
 
 def run_boozer(
@@ -305,10 +305,10 @@ def create_boozer_settings_from_equilibrium_resolution(
     mhd_equilibrium: vmec_utils.VmecppWOut,
     settings: BoozerPresetSettings,
 ) -> BoozerSettings:
-    """Derives Boozer transformation settings from the resolution of the equilibriumn
-    according to the given boozer settings preset.
+    """Derives Boozer transformation settings from the resolution of the equilibrium
+    according to the given Boozer settings preset.
 
-    See the wrapped function boozer.boozer_settings_from_equilibrium_resolution   for
+    See the wrapped function boozer.boozer_settings_from_equilibrium_resolution for
     more details.
     """
     return boozer_settings_from_equilibrium_resolution(
@@ -333,7 +333,7 @@ def boozer_settings_from_equilibrium_resolution(
         normalized_toroidal_flux: The normalized toroidal flux values at which the
             transformation to Boozer coordinates is performed. If None, the
             transformation to Boozer coordinates will be run on all flux surfaces.
-        verbose: If True, running booz_xform in verbose mode.
+        verbose: If True, runs booz_xform in verbose mode.
     """
     mpol = max(6 * mhd_equilibrium.mpol, 2)
     ntor = max(2 * mhd_equilibrium.ntor - 1, 0)

{constellaration-0.2.6 → constellaration-0.3.0}/constellaration/data_generation/vmec_optimization.py

@@ -273,7 +273,7 @@ def _compute_omnigenous_field_residuals(
     modB: jt.Float[np.ndarray, " n_collocation_points"],
     target_modB: jt.Float[np.ndarray, " n_collocation_points"],
 ) -> jt.Float[np.ndarray, " n_collocation_points"]:
-    # Scale both magnetic field strength such that the average is ~1T.
+    # Scale both magnetic field strengths such that the average is ~1T.
     scaled_modB = modB / np.mean(modB)
     scaled_target_modB = target_modB / np.mean(target_modB)
     return (scaled_modB - scaled_target_modB) / scaled_target_modB

{constellaration-0.2.6 → constellaration-0.3.0}/constellaration/data_generation/vmec_optimization_settings.py

@@ -12,7 +12,8 @@ class OmnigenousFieldVmecOptimizationSettings(pydantic.BaseModel):
     """The maximum toroidal mode number of the resulting configuration."""
 
     n_inner_optimizations: int = 1
-    """The number of inner optimization to perform to obtain the final configuration."""
+    """The number of inner optimizations to perform to obtain the final
+    configuration."""
 
     gradient_free_budget_per_design_variable: int = 100
     """The budget for the gradient free optimization per design variable.

{constellaration-0.2.6 → constellaration-0.3.0}/constellaration/generative_model/bootstrap_dataset.py

@@ -19,10 +19,10 @@ ANY_PROBLEM = problems.GeometricalProblem | problems.SimpleToBuildQIStellarator
 
 
 def load_source_datasets_with_no_errors() -> pd.DataFrame:
-    """Load and concatenate source datasets from HugginFace dataset.
+    """Load and concatenate source datasets from the Hugging Face dataset.
 
     Includes all ids, unfolded targets and unfolded metrics but not the contents of the
-    mhd  equilibria.
+    MHD equilibria.
     """
     dframe = datasets.load_dataset("proxima-fusion/constellaration", "default")[  # type: ignore
         "train"
@@ -213,7 +213,7 @@ def _to_Y_constraints(
     dframe: pd.DataFrame,
     problem: ANY_PROBLEM,
 ) -> np.ndarray:
-    """Extracts the constraint metrics from the DataFrame from the given problem."""
+    """Extracts the constraint metrics from the DataFrame for the given problem."""
     if isinstance(problem, problems.GeometricalProblem):
         targets = np.array(
             [
@@ -264,7 +264,7 @@ def _to_Y_objective(
     dframe: pd.DataFrame,
     problem: ANY_PROBLEM,
 ) -> np.ndarray:
-    """Extracts the objective metrics from the DataFrame from the given problem."""
+    """Extracts the objective metrics from the DataFrame for the given problem."""
     if isinstance(problem, problems.GeometricalProblem):
         return dframe["max_elongation"].to_numpy()
     elif isinstance(problem, problems.SimpleToBuildQIStellarator):

{constellaration-0.2.6 → constellaration-0.3.0}/constellaration/generative_model/mcmc_algo.py

@@ -108,9 +108,9 @@ class RandomWalkMetropolis:
     def _tune_scale_covariance(
         self, proposal_scale: float, accept_rate: float
     ) -> float:
-        r"""Tune the acceptance rate according to the last tuning interval. If higher
-        acceptance rate , means you need to expand your search field or increase
-        variance(its too small currently)
+        r"""Tune the acceptance rate according to the last tuning interval. If the
+        acceptance rate is higher, you need to expand your search field or increase
+        the variance (it's too small currently).
 
         The goal is an acceptance rate within 20\% - 50\%.
         The (acceptance) rate is adapted according to the following rule:

{constellaration-0.2.6 → constellaration-0.3.0}/constellaration/generative_model/optimize_with_mcmc.py

@@ -30,7 +30,8 @@ def optimize_with_mcmc(
     initial_stepsize: np.ndarray | None = None,
     **kwargs,
 ) -> np.ndarray:
-    """Optimizes a function using MCMC sampling."
+    """Optimizes a function using MCMC sampling.
+
     Args:
         function: For a given design variable, a function to compute a tuple of
             objectives and constraints. Constraint negative is considered as
@@ -68,13 +69,13 @@ def optimize_with_mcmc(
         # for the objective, quasi-likelihood
         beta = settings.beta  # can be a hyperparameter too. e.g. 1.0
         num_objectives = objectives.shape[0]
-        # The is just a basic form to deal with multi-objective optimization
+        # This is just a basic form to deal with multi-objective optimization
         w = 1 / num_objectives
         quasi_likelihood_obj = np.exp(-beta * np.sum(w * objectives))
 
         # for the constraints, indicator function
         if settings.smooth_constraints:
-            k = settings.k  # more the k, more steep the sigmoid. default 3
+            k = settings.k  # the larger k, the steeper the sigmoid. default 3
             sigma = (
                 settings.sigma
             )  # controls the degree of constraint violation allowed, def 0.01
@@ -83,7 +84,7 @@ def optimize_with_mcmc(
                 # sigmoid function
                 quasi_likelihood_cons_tmp = 1.0 / (
                     1.0 + np.exp(k * con)
-                )  # 1/(1+exp(-k(-x))) -x as we want 1 when constraoints satisfied
+                )  # 1/(1+exp(-k(-x))) -x as we want 1 when constraints satisfied
                 # else 0
                 # gaussian
                 quasi_likelihood_cons *= np.exp(
@@ -106,7 +107,7 @@ def optimize_with_mcmc(
 
     # Initialize the MCMC algorithm
     print(
-        "Running MCMC (Adaptive Random Walk Metrolopis Hastings)"
+        "Running MCMC (Adaptive Random Walk Metropolis-Hastings) "
         f"with {settings.num_samples} samples"
     )
     mcmc = mcmc_algo.RandomWalkMetropolis(target_logprob=_log_target)