Correct false VMEC toroidal-angle explanation in Boozer field comments

[krystophny]

Goal

Correct the VMEC handedness explanation in src/field/field_can_boozer.f90 without changing runtime behavior.

At b7badf8, the comment above eval_field_booz says VMEC is left-handed because phi_v = -cylindrical angle, and uses that statement to explain torflux=-phi_vmec/(2*pi). The first statement is false for a standard VMEC wout: VMEC zeta is the physical geometric cylindrical azimuth. The usual signgs=-1 describes the orientation of the complete (s,theta,zeta) chart; it does not imply a hidden toroidal-angle reversal.

Evidence

The native VMEC/booz_xform relations are

zeta_B = zeta_VMEC + p
theta_B = theta_VMEC + lambda_VMEC + iota*p

booz_xform writes pmn=-p=zeta_VMEC-zeta_B, so the Cartesian azimuth reconstructed from its output is

phi_cyl = zeta_VMEC = zeta_B + pmn.

A pointwise native reconstruction from a standard wout and freshly generated booz_xform output agrees to 2.8e-9 m in Cartesian position. Interpreting the stored pmn with the opposite sign misses by at least 7.7e-2 m. A compiled SIMPLE chartmap probe then agrees with the same direct booz_xform reconstruction to 3.2e-5 cm in position and 7.8e-5 relative in Cartesian B. Its oriented coordinate determinants are negative, while the metric API returns their absolute values.

The differential-form reason for the flux sign is independent of a toroidal reversal. For coordinates (s,theta,zeta) and oriented Jacobian J<0,

B^zeta = (partial_s A_theta - partial_theta A_s)/J.

In the usual gauge A_s=0, the sign of A_theta must account for the signed Jacobian. This is the relevant explanation for A_theta=-Phi_tor/(2*pi) on the ordinary VMEC path.

Requested change

Update only the sign-convention comment in src/field/field_can_boozer.f90:

• state that VMEC zeta is the physical cylindrical azimuth;
• state that signgs=-1 belongs to the full flux-coordinate chart;
• explain A_theta=-Phi_tor/(2*pi) using the oriented curl/Jacobian identity;
• retain A_phi=-chi and iota=-dA_phi/dA_theta as written.

A candidate comment-only change is already available on branch agent/coordinate-contract, commit 10ac7e7.

Positive and negative cases

• Positive: on the standard signgs=-1 VMEC fixture, phi_cyl=zeta_VMEC=zeta_B+pmn reconstructs the native Cartesian geometry.
• Negative: phi_cyl=-zeta_VMEC or phi_cyl=zeta_B-pmn must fail the Cartesian position gate.
• Non-goal: this issue does not define behavior for a positive-Jacobian signgs=+1 file; that requires a separate native fixture and must not be inferred from the documentation correction.
• Non-goal: do not change torflux, A_theta, orbit equations, chartmap data, or any executable output in this issue.

Verification

fo
fo lint src/field/field_can_boozer.f90
ctest --test-dir build --output-on-failure -R 'test_boozer_chartmap|test_chartmap_aphi_abscissa|test_boozer_chartmap_roundtrip|test_e2e_boozer_chartmap|test_jacobian_conventions_vmec'

References

• VMEC wout Fourier geometry uses the m*theta-n*zeta kernel; VMEC/booz_xform source routines vcoords, harfun, and boozer provide the executable angle and pmn definitions.
• S. P. Hirshman and J. C. Whitson, Phys. Fluids 26, 3553 (1983), for the VMEC flux-coordinate formulation.
• A. H. Boozer, Phys. Fluids 24, 1999 (1981), for the Boozer-coordinate representation.

Exact source revisions, paths, and line anchors should be recorded in the merged documentation because line numbers will move with this edit.