Skip to content

Write dimensional helical response output#142

Open
krystophny wants to merge 20 commits into
mainfrom
feat/flux-pumping/resolved-current-output
Open

Write dimensional helical response output#142
krystophny wants to merge 20 commits into
mainfrom
feat/flux-pumping/resolved-current-output

Conversation

@krystophny

Copy link
Copy Markdown
Member

Closes #141.

Parent stack head: feat/flux-pumping/local-helical-drive at 47343f3 (PR #140). This cumulative PR targets main and remains unmerged with the rest of the feature stack.

Write helical_current_response.h5 for single-species mode-1 helical-source runs. The contract records the input quadrature, Fourier phase, mode, surface, species, solver switches, source amplitudes, normalized current channels, dimensional D31/D32 coefficients, and whether a separate off reference is required. It does not label a flux-surface moment as local or geometric toroidal current.

Correct the existing multispecies HDF5 unit metadata to match the normative NEO-2 output document: D13/D23/D31/D32 use cm^2 G/s; D33 uses cm^2 G^2/s.

Numerical and physics invariants:

  • D_3k = gamma_3k v_T rho B_ref = gamma_3k 2 T c/(z e).
  • Solver order and final-output mapping remain current row 3, A1/A2 columns 1/2.
  • Fourier phase remains exp(+i(m_theta theta + m_phi phi)).
  • The real/imaginary reconstruction is H=(R-R0)-i(I-R0); source-only fileless runs use the existing exact-zero guard as R0=0.
  • The kinetic operator, collision moments, discretization, convergence criteria, transfer algebra, ABI, and memory layout are unchanged.
  • The output is a harmonic response coefficient. Pointwise parallel current and geometric toroidal current require a later distribution/coordinate reconstruction.

Verification

Failing before:

helical_current_response.h5: absent
D31/D32 HDF5 unit attribute: cm^2/s

Passing after:

$ fo
Static: OK (340 modules, 340 changed, 340 affected)
Build: OK
Tests: OK
Lint: OK
All stages passed

The focused normalization/reconstruction, shared-source, and output-geometry tests pass 3/3. A three-case HELCORE integration completed every 24 x 24 final join in 3:24.90 with peak RSS 541996 KiB and no IEEE, NaN, signal, or runtime marker. The runner validated every HDF5 field, unit, phase, switch, species, finite value, and the agreement with fulltransp at relative tolerance 1e-13.

Reconstructed (m_theta,m_phi)=(1,-1) response:

D31 = 1.4677305578740989e12 - 5.42208046219255e11 i cm^2 G/s
D32 = 4.18887130153984e12 - 6.277850811343069e11 i cm^2 G/s

The exact-zero source guard supplies the baseline for this fileless source-only case.

isw_qflux_NA=1 with in_file_pert='none' assembles an identically zero
non-axisymmetric source. That zero vector is the Arnoldi seed, so its
normalization divides by zero (0/0 -> NaN) and zhseqr then fails to
converge at every step, spinning without qflux output. Reject the
configuration in check() with a clear message instead.
Add an optional right-hand side to the non-axisymmetric solve: the
drive of a single-helicity perturbation given by a radial corrugation
field (delta B^s/B_0^phi)_mn and an electrostatic potential harmonic
Phi_mn. The vpar corrugation piece enters the A1/A2 force channels
with velocity weights a3m and x^2 (sigma-odd), the ExB piece with
weights x^-1 and a1m (sigma-even); the two new velocity moments are
computed in compute_sources. Input via new &ntv_input variables
(isw_hel_drive, m_theta_hel, hel_brad_re/im, hel_phim_re/im), default
off. Band profiles, moments and dimensional prefactors follow a
CAS-checked derivation (see issue #118).

Off by default: golden-record QL summary.h5 is reproduced to 1e-15
against a main build.
Review findings on the drive commit: fold the x^(3k-4) weight into a
single power so the x=0 quadrature node stays finite; skip the moment
quadrature on the precomputed-matrix-element path and reject
isw_hel_drive at run time when the moments are unavailable; reject the
unvalidated relativistic branch, reconstruction mode and unset species
data; deallocate asource_hel in collop_unload.
The zero-source guard added upstream rejects isw_qflux_NA=1 with
in_file_pert='none'. With the misalignment drive, that configuration is
valid: the drive supplies the non-axisymmetric source. Relax the guard
so it fires only when the drive is off or all its amplitudes are zero.
@krystophny

Copy link
Copy Markdown
Member Author

Added slice: pointwise helical parallel-current profile (commit 6439ac9)

Extends the resolved-current output with a per-field-line-point current profile
for the mode-1 local (axi) solver.

What it does. After the transport contraction
qflux(2,k) = sum_col flux_vector(2,col)*source_vector(col,k), the new
pointwise_current_mod decomposes that current channel into its per-point
contributions. flux_vector's columns partition into disjoint per-step blocks,
so the block dot products sum back to qflux(2,k) exactly. The routine reuses
the already-verified current row: the counter-passing block carries the explicit
minus sign (parallel current is odd under sigma -> -sigma) and the phi-quadrature
weight is baked in, so no new sign, weight, or normalization is introduced.

Invariant preserved. The solver writes current_profile.dat only when the
helical drive is active (isw_hel_drive /= 0), so runs without it are bitwise
unchanged. A hard self-check aborts the run if the field-line sum does not
reproduce qflux(2,k).

Verification.

  • ctest TEST suite: 17/17 pass; new pointwise_current_test added.
  • Red/green: breaking the block partition (dropping the npassing+1 factor)
    aborts with ERROR STOP FAIL: per-point contributions do not sum to the qflux current channel; restored -> Passed.
  • Single-surface l=1 helical-core benchmark, three drive quadratures: the
    harmonic current response reproduces the reference to ~1e-11, and each
    current_profile.dat reconstructs qflux(2,k) to ~1e-15 relative over 961
    finite points.

Parent slice: dimensional helical response contract (this PR's earlier commits).
No merge requested; review only under the integration freeze.

@krystophny krystophny force-pushed the feat/flux-pumping/resolved-current-output branch from 6439ac9 to 36d2cde Compare July 11, 2026 16:39
@krystophny

Copy link
Copy Markdown
Member Author

Correction: the pointwise current-profile slice was moved to its own stacked PR #151 (top of the stack, on the source-conjugacy branch) to keep this PR focused on the dimensional response contract and to avoid rebasing the intervening open PRs. Please disregard the previous comment's commit reference; the pointwise work is reviewed in #151.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

Write a dimensional helical current-response contract

1 participant