Skip to content

GKX 2.0.0

Choose a tag to compare

@rogeriojorge rogeriojorge released this 02 Sep 19:51
· 1311 commits to main since this release
46b178e

GKX 2.0.0

A major release. 105 commits since 1.8.2, and the version is 2.0.0 because
imports break: ten module paths were removed, and the Diffrax integrator is
gone from the base product along with its configuration surface.

Named imports are almost entirely unaffected: gkx.api still resolves 346
exports, and from gkx.api import integrate_linear works exactly as before.
Ten names left the public surface and ten joined it.

Gone: integrate_linear_diffrax, integrate_linear_diffrax_streaming,
integrate_nonlinear_diffrax, booz_xform_flux_tube_mapping_from_inputs,
booz_xform_flux_tube_sensitivity_report, vmex_flux_tube_sensitivity_report,
vmex_flux_tube_array_parity_report, vmex_metric_tensor_sensitivity_report,
vmex_field_line_tensor_sensitivity_report,
vmex_boozer_flux_tube_sensitivity_report.

New: load, solve, scan, plot, prepare, and the result types Case,
PreparedSimulation, LinearResult, NonlinearResult, ScanResult. These
are the advertised entry points, and gkx.api.__all__ is now those 15 names
rather than all 346. That changes from gkx.api import *, which previously
bound 346 names and now binds 15; every one of the 346 remains importable by
name.

Breaking: module paths

Container directories that held a single implementation file were removed and
their contents fused into the module that owned them. These import paths no
longer exist:

gkx.solvers.linear                       -> gkx.solvers_linear
gkx.solvers.linear.parallel              -> gkx.solvers_linear_parallel
gkx.solvers.nonlinear                    -> gkx.solvers_nonlinear
gkx.benchmarking.shared                  -> gkx.benchmarking_shared
gkx.diagnostics.moments                  -> gkx.operators.moments
gkx.workflows.runtime.config             -> gkx.config
gkx.diagnostics.growth_series            -> removed
gkx.geometry.vmec_boundary_collection    -> removed
gkx.objectives.stellarator_residuals     -> fused into gkx.objectives.stellarator
gkx.objectives.qa_low_turbulence_*       -> fused into gkx.objectives.stellarator

Names re-exported from a package still resolve: from gkx.diagnostics import total_energy works, import gkx.diagnostics.moments does not.

The moment kernels moved to the operators layer because they were never
diagnostics in the first place -- they run inside the traced step, under jit
and psum, where computing them outside the timed route costs up to 118x.

Breaking: Diffrax removed from the base product

No shipped deck or example selected it, and no test used it as a live oracle.
On an RTX A4000, at matched fitted-mode accuracy on the maintained
kinetic-electron stress case, the native explicit owner ran 25.16/14.59 s
cold/warm against Diffrax's 47.85/37.87 -- about 2.6x faster warm -- with a
17.5 MB device peak against 69.1 MB. Diffrax's 20,000-step ceiling fails
before its time path reaches the declared t=40 horizon that native completes.

Removed with it: six TimeConfig selector fields, three public exports, every
[time] deck key that named it, the benchmark oracle flags, and the dead
save_mode, mode_method, save_field and density_species_index kwargs on
integrate_linear_from_config.

Physics and geometry

  • The synthetic Boozer closure is removed. It was a stand-in, and results that
    depended on it were not measurements of the coordinate system they named.
  • End damping no longer depends on the step size.
  • A canonical VMEX WOUT geometry adapter, plus VMEX state and mirror adapters.
  • The parity and sensitivity report builders are evicted.

Re-run anything whose numbers came from the synthetic closure or from a
step-size-dependent damping tail.

Performance

Cold start on a nonlinear CPU run is the headline. Measured on one workstation
(jax 0.10.2, CPU, Cyclone nonlinear, Nl=4 Nm=8, 5 steps), alternating refs
across three repetitions:

  • the seed diagnostic is compiled once instead of once per primitive:
    23.7 s -> 19.1 s cold, 336 -> 231 XLA compilations, every array bitwise
    identical including a value_and_grad
  • the linear cache is built on the host when its inputs are concrete:
    68 fewer compilations, 2175 ms -> 1340 ms, bitwise identical
  • the streaming reversal avoids two gathers: 13.0 ms -> 9.6 ms

Tests, examples and docs

The suite was consolidated from about a hundred files to 76 with the node-ID
set preserved, not the pass count. Sixteen of the 36 shipped examples now
execute in CI at smoke resolution, up from four; the remaining sixteen are
registered against the specific thing that blocks them rather than silently
absent. Running them for the first time found two bugs: the parallelization
deck never ran at all, because a scan-level parallel strategy was forwarded
into each per-ky worker and the inner solve rejected it.

A fresh user's first run is now executed in CI from the installed wheel, and
the documentation's external links are checked nightly. That check found three
citations whose DOIs were never registered -- Frei et al. 2021, Stephens et
al. 2021 and Xanthopoulos et al. 2009 -- all corrected.

Corrections to the published record

Three numbers this project had published turned out not to be reproducible, and
all three are fixed rather than annotated.

The closed VMEX mirror case was built on the solver's seeded initial guess and
never solved. Its normalized force residual was 0.61. Everything published for
that case was a property of an initial guess, so the builder now solves before
it measures and the numbers are republished from the converged state:

force residual rms   0.61150  ->  0.0048389
bmag max/min         1.77849  ->  1.03801
gamma                0.13907  ->  0.07959
Q_QL                 0.99785  ->  0.21721

A documented physical claim went with it. The docs stated that this field
strength ratio is the cross-section elongation squared. That identity held
only on the seed. On solved equilibria it is 1.03801 against an elongation
squared of 1.77778, and two configurations sharing an elongation squared of
4.00000 give 1.11730 and 1.09976 -- so it is not a function of elongation at
all. A gate now refuses to write an uncertifiable record, so a seed cannot ship
as an equilibrium again.

vmex_mirror_gkx_performance.json was presented as a generated artifact and
never had a generator, on any branch, in the history of this repository. It
stamped no commit, no version and no date, and its central quantity cannot be
regenerated on a solved equilibrium at all. It is deleted, together with the
claims that rested on it; the CPU/GPU parity claim it carried has a real,
generator-backed home elsewhere.

Three cited DOIs were never registered and are corrected: Frei et al. 2021,
Stephens et al. 2021, Xanthopoulos et al. 2009.

Known issue

The w7x_itg linear comparison fixture under tools/ reaches |field| ~ 5.75e75
late in a run at its own pinned settings. It is a development comparison input,
not a shipped example, and no shipped deck is over its stability bound. Tracked
as issue #192, where what is ruled out is recorded: the geometry is bit-identical
to the earlier campaign's, and the case runs clean when truncated.

Install

pip install gkx==2.0.0