DKX 2.8.0

A converged kinetic bootstrap row compiled as one program, a momentum-conserving
correction for pitch-angle-scattering solves, refined ambipolar roots, and the
options vmex --neoclassical uses.

Documentation and repository

• Documentation rebuilt (#292): getting started, user guide (every case field,
  outputs, CLI, Python API), tutorials, how DKX works, physics, numerics,
  benchmarks, examples, features and design decisions. The README defines the
  case schema before using it.
• Historical development files removed (#293, #298); dead doc citations
  repointed; dkx run --out help, the dkx.run method docstring and the
  analytic tokamak wording corrected; [output].plots wired.
• Ambipolar root stability is classified from the outward current (#301); the
  optional Boozer backend is declared as the booz extra (#302).

Bootstrap objective

• KineticBootstrapMismatch defaults to Nxi = 48 (was 16). Pitch-angle
  convergence study (plan.md 16.7): on the VMEX QA beta = 2.5% deck with its
  published profiles, <j.B> at Nxi = 48 is within 1.1% of Nxi = 96-128
  for |E_r| >= 5 kV/m and within 3% at |E_r| <= 1 kV/m; Nxi = 16 was 16-44%
  low. A realistic E_r does not converge at far lower Nxi (one step of the
  ladder at most), so the row keeps E_r = 0 by default. Rows built with an
  explicit resolution are unchanged.

• KineticBootstrapCurrent(ambipolar=True) refines its bracketed ion root
  with the same Brent refinement as the representative radial scan (at most
  4 more single-field solves) and reads <j.B> from the solve at the refined
  root instead of interpolating across the scan bracket.

Representative run

• The ambipolar root of each surface is refined after bracketing: Brent's
  method on the bracket, at most 4 more single-field solves, stopping at
  |J_r| <= 1e-6 max|J_r| or a 0.01 kV/m bracket. Moments are read at the
  refined root instead of interpolated across a 10-20 kV/m bracket. On the
  VMEX QA beta = 2.5% bootstrap deck with its published profiles (default
  grid) the roots move from -11.8, -25.8, -49.0, -39.8, -43.3 to -11.9, -26.1,
  -46.5, -43.4, -39.0 kV/m, and <j.B> at r/a = 0.55 from -4755 to -3192
  kA/m^2, for 18 extra solves (radial-scan wall time 59 s to 117 s). The
  outer roots stay non-monotone: there J_r is within 1-5% of zero over tens
  of kV/m and its crossings move by tens of kV/m on the full grid, so that
  spread is a resolution effect, not a bracket artifact.
• The ambipolarity panel spans its row; the two empty slots beside it are gone.
• run_representative accepts surfaces, er (ambipolar root or a
  prescribed kV/m), collision_operator (fp, pas,
  pas+momentum_correction), explicit profiles (ne_coeffs, Te_coeffs,
  Ti_coeffs polynomials in s, as VMEX's KineticProfiles; T_i may differ
  from T_e) and redl_jdotb, an external Redl curve drawn on the bootstrap
  panel. Defaults are unchanged.
• Fix: the radial scan solved every surface with the n, T and gradients of
  r/a = 0.5. Each surface now uses its own plasma. On the VMEX QA beta = 2.5%
  bootstrap deck this removes the r/a = 0.55 outlier (-46 kV/m between -31
  and -28). The Er profile is now monotone: -13, -27, -50, -60, -61 kV/m at
  r/a = 0.25 to 0.85. A dense scan confirmed that the root itself was a real
  crossing for the plasma it was given, not a root-pick or bracket error.
• The evaluated root is the most negative stable root under the
  outward-current rule of #301. The ambipolarity panel is now drawn for every
  surface, with each root labelled ion, unstable or electron.
• Fix: the caption no longer clips at the canvas edges. Long lines wrap, and
  the layout rect's height no longer runs past the top of the figure.

Physics

• Rewrite dkx.momentum_correction as the Sugama–Nishimura moment method on the
  structured pitch-angle solve (Phys. Plasmas 9, 4637 (2002); Maassberg, Beidler &
  Turkin, Phys. Plasmas 16, 072504 (2009)). The parallel particle flow, heat flow and
  next Sonine moment of every species are coupled through the full Fokker–Planck
  operator (friction l^ab_ij and field-particle restoration from DKX's own
  Rosenbluth-potential operator), the projection is weighted by nu_D so the model
  conserves total parallel momentum exactly, and <j.B>, flows and back-substituted
  radial fluxes are read off one corrected state. momentum_corrected_solve(pas, fp)
  is traceable and differentiable; friction_drives caches the velocity-space part.
  KineticBootstrapMismatch(collision_model="pas+momentum_correction") uses it as a
  VMEX objective row. Accuracy against full Fokker–Planck on the same grid is in
  docs/physics/reduced_models.md.

Removed

• The single-moment, database-based correction (ParallelViscosity,
  parallel_viscosity, parallel_friction_matrix, solve_corrected_flows and the
  database signature of momentum_corrected_bootstrap). It carried the parallel
  particle flow only, so the temperature-gradient bootstrap drive was lost, and closed
  the system with an ad hoc M0 V_unc drive. Accessing the old names raises an error
  that names the replacement; dkx.api.momentum_corrected_bootstrap now takes the
  pitch-angle operator and its Fokker–Planck twin.

Performance

• Retain the Fokker-Planck speed triangle in the sparse Krylov preconditioner
  (#303). solve(preconditioner="sparse_triangle") keeps the self-species
  upper speed triangle that "sparse" drops, reusing the same sparse LU
  factors by back-substitution over speed. The stalled-solve escalation now
  tries it in place of "sparse" on Fokker-Planck and Sugama decks; an
  explicit preconditioner="sparse" is unchanged. On the HSX Fokker-Planck
  DKES deck it cut GCROT iterations from 46-55 to 16-18 across a four-rung
  ladder (54,564 to 786,244 unknowns) and on the W7-X paper deck from 22-26
  to 10-11, with currents and fluxes equal to the solver tolerance.
• Compile the kinetic bootstrap-current row of a VMEX optimization as one
  program. KineticBootstrapMismatch traced one Boozer transform and one
  kinetic solve per surface as an unrolled loop, was dispatched op by op when
  VMEX evaluated it eagerly at set-up, and was differentiated forward through
  the kinetic solve once per boundary dof by VMEX's block Jacobian. The
  surfaces are now one batch axis of one compiled program, an eager call
  compiles once per runtime, and the forward derivative applies the
  reverse-mode Jacobian (one adjoint solve per surface) to every tangent
  (batched_with_reverse_jvp). The Boozer plan is also built under an outer
  jit, which used to raise. Values and Jacobian rows are unchanged to
  3e-14 and 1.4e-12 relative (8.6e-6 for the Fokker-Planck Krylov route,
  whose tangent solves become adjoint solves at the same tolerance). On a
  shared 36-core host (8 pinned cores, load 8-33), the row's added cost over
  the same VMEX problem without it fell from 92-122 s to 56-74 s for set-up
  plus one residual and one Jacobian (three surfaces, default grid); an eager evaluation from 68-80 s cold and
  6-7 s warm to 20-26 s and 0.6 s; the example's CI smoke pass from 358 s
  to 298 s.