# Evaluate a stellarator boundary

The evaluator of Proxima Fusion's ConStellaration benchmarks, constellaration
0.2.6, as the leaderboard on Hugging Face runs it, wrapped in functions that
other notebooks can call.

| File                             | What it holds                                                                                 |
| -------------------------------- | --------------------------------------------------------------------------------------------- |
| `data/reference-boundary.json`   | Proxima's example boundary for the single-objective problems, upstream `inputs/boundary.json` |
| `data/reference-boundaries.json` | Proxima's two-boundary example for the MHD-stable problem, upstream `inputs/boundaries.json`  |
| `data/leading-front.json`        | The 688 feasible (L∇B, A) points of the leading MHD-stable submission                         |

- **Source:** https://github.com/proximafusion/constellaration, tag v0.2.6,
  `hugging_face_competition/inputs/`. `flux_compression_both_weights`
  adapts `compute_flux_compression_in_regions_of_bad_curvature` from
  `constellaration/mhd/turbulent_transport.py`. MIT licence, Copyright (c)
  2025-present Proxima Fusion GmbH; the notice is in `UPSTREAM-LICENSE`.
- **Leading front:** written by `build_data.py` of the leaderboard
  notebook from the leaderboard's results dataset as recorded on 25 October
  2026 (submission of Eppy@EP-Hard, 23 October 2026, score 249.14).
  Recorded objectives only, no boundary.
- **Needs:** Python 3.10 to 3.13. The geometrical problem fits a 1.5 GiB
  ScienceHub kernel for boundaries of the dataset's size; the two QI
  problems need about 3 GiB, more than ScienceHub compute offers, so run
  them on your own machine. With the booz-xform override in the notebook's
  header no dependency needs a compiler on Linux x86-64 or on macOS 14
  or later.
- **Call it:** `evaluate`, `evaluate_many`, `compute_metrics`,
  `constraint_report`, `added_hypervolume`, `leader_front`,
  `feasible_points` and `rotating_ellipse`; the notebook documents each and
  shows how to load them on your own machine or copy them into a ScienceHub
  notebook.

## The booz-xform override

The notebook pins `constellaration==0.2.6` and overrides one dependency:
booz-xform 0.1.0 instead of 0.0.9. Release 0.0.9 publishes no wheels, and
building it needs a C++ compiler, CMake and libnetcdf, which ScienceHub's
kernel image does not have. With the override no package needs a compiler;
two pure-Python packages (pylatexenc, nvgpu) come as source archives. On
Python 3.13 the kernel image installs everything in 18 s.

The override does not change any number. The reference boundary and the
paper's baselines for all three problems (eight forward-model runs) give
bit-identical metrics, QI residual included, in two environments:

| Environment             | Python | booz-xform               | simsopt | jax   | scipy  |
| ----------------------- | ------ | ------------------------ | ------- | ----- | ------ |
| ScienceHub kernel image | 3.13   | 0.1.0                    | 1.9.0   | 0.5.3 | 1.17.1 |
| Leaderboard Space       | 3.10   | 0.0.9, built from source | 1.8.1   | 0.6.0 | 1.15.3 |

The 16 runs are rows of `data/rescored.parquet` in the leaderboard notebook
of this project, with `run` "kernel image" or "leaderboard environment".
That notebook pairs them by boundary and reports the largest difference
over their 110 metric values: 0.

## Cost of one evaluation

Measured on Hetzner CPX42 servers (AMD EPYC), one core per evaluation,
with VMEC++ single-threaded as upstream sets it. The kernel-image rows ran
one process per evaluation on one CPU, so their memory belongs to that
evaluation. Rows from the leaderboard environment ran on Python 3.10, where
worker processes are reused, so their memory is an upper bound.

| Problem               | Boundary                      | Environment  | Time                     | Peak memory |
| --------------------- | ----------------------------- | ------------ | ------------------------ | ----------- |
| Geometrical           | reference, 5 × 9 modes        | kernel image | 72 s                     | 1.0 GiB     |
| Geometrical           | paper baseline                | kernel image | 35 s                     | 1.0 GiB     |
| Geometrical           | top 3 entries, 13 × 25 modes  | leaderboard  | 117–146 s                | ≤ 1.72 GiB  |
| Simple-to-build       | reference and paper baseline  | kernel image | 76–77 s                  | 2.7 GiB     |
| MHD-stable            | paper baseline, per point     | kernel image | 70–120 s                 | 2.7 GiB     |
| MHD-stable            | leading front, 24 points      | leaderboard  | 54–127 s                 | ≤ 3.1 GiB   |
| Flux compression only | two leading fronts, per point | leaderboard  | median 67 s, up to 252 s | ≤ 1.45 GiB  |

The memory of the two QI problems comes from one line of the QI residual
(`omnigeneity/qi.py`, the `angle` array): |B| is evaluated for every Boozer
mode on a 601 × 75 grid at once, about 2,300 × 45,075 doubles per array.
The largest peak, 3,136 MiB for an MHD-stable point in the leaderboard
environment, sets the 3.1 GiB below which the notebook refuses the QI
problems.

A ScienceHub kernel has 1.5 GiB of memory. It fits a geometrical
evaluation of a boundary of the dataset's size; the largest leaderboard
entries, measured at up to 1.72 GiB, may not fit.