Sign reference disagrees with PENTRC passing harmonic and co-current map

[krystophny]

The current sign-conventions reference at aaf720d475df6616935a56ea5914a68df10575d0 disagrees with executable source in two sign-sensitive places.

1. It documents the passing-particle effective harmonic as ell_eff = ell - sigma*n*q:

GPEC/docs/sign_conventions.rst

Lines 272 to 286 in aaf720d

	Energy Integral Resonance
	-------------------------
	In the PENTRC energy integral (``xintgrnd`` in ``pentrc/energy.f90``), the
	resonance denominator involves:
	.. math::
	n \omega_E + \ell_{\mathrm{eff}} \omega_b \sqrt{x} + n \omega_D x
	where :math:`\omega_b` is the bounce frequency divided by :math:`x`,
	:math:`\omega_D` is the magnetic precession frequency,
	:math:`\ell_{\mathrm{eff}} = \ell - \sigma n q` is the effective bounce harmonic,
	and :math:`x = E/T` is the normalized energy. The sign of :math:`\omega_E`
	determines the direction of resonance in velocity space.

All three executable paths use the plus sign:

• pitch.f90:

  GPEC/pentrc/pitch.f90

  Lines 239 to 247 in aaf720d

  	if(lmda>bobmax)then
  	nueff = nuk/(2*epsr)
  	lnq = real(ell,r8)
  	else
  	nueff = nuk
  	lnq = ell+n*q
  	endif
  	! note: currently ignores -wb case for trapped
  	xint = xintgrl_lsode(wn,wt,we,wd,wb,nueff,ell,lnq,n,psi,lmda,method,record_this)

• pitch.f90 runtime integrand:

  GPEC/pentrc/pitch.f90

  Lines 357 to 369 in aaf720d

  	! energy integration of resonance operator
  	if(x<=pitch_bobmax)then ! circulating particles
  	nueff = pitch_nuk
  	lnq = pitch_ell+pitch_n*pitch_q
  	xint = xintgrl_lsode(pitch_wn,pitch_wt,pitch_we,wd,wb,nueff,pitch_ell,lnq,pitch_n,&
  	pitch_psi,real(x,r8),pitch_method,op_record=.false.)
  	xint = xint + xintgrl_lsode(pitch_wn,pitch_wt,pitch_we,wd,-wb,nueff,pitch_ell,lnq,pitch_n,&
  	pitch_psi,real(x,r8),pitch_method,op_record=.false.)
  	else ! trapped particles
  	nueff = pitch_nuk/(2*pitch_epsr) ! effective collisionality
  	lnq = real(pitch_ell,r8)
  	xint = xintgrl_lsode(pitch_wn,pitch_wt,pitch_we,wd,wb,nueff,pitch_ell,lnq,pitch_n,&
  	pitch_psi,real(x,r8),pitch_method,op_record=.false.)

• torque.F90:

  GPEC/pentrc/torque.F90

  Lines 591 to 597 in aaf720d

  	if(lmda>(bo/bmax)) then
  	sigma = 0 !trapped
  	else
  	sigma = 1 !passing
  	endif
  	lnq = l+sigma*n*q

So the maintained source implements ell_eff = ell + sigma*n*q.

2. The page says positive native omega_E is co-current for right-handed plasmas and counter-current for left-handed plasmas:

GPEC/docs/sign_conventions.rst

Lines 221 to 233 in aaf720d

	Rotation Velocity Conventions (PENTRC)
	======================================
	:math:`\omega_E` (E x B Rotation)
	----------------------------------
	- Column 6 of the PENTRC kinetic profile file: :math:`\omega_E` in rad/s.
	- Read by the ``read_kin`` subroutine in ``pentrc/inputs.f90``.
	- **Sign convention**: positive :math:`\omega_E` means rotation in the
	direction of the toroidal coordinate :math:`\zeta`.
	- Since :math:`\phi` direction depends on helicity, positive :math:`\omega_E`
	is effectively **co-current for RH plasmas** and **counter-current for
	LH plasmas**.

But the physical toroidal map in the coil field path is

phi_CCW = -helicity * (2*pi*zeta + delta_phi)

GPEC/coil/field.F

Lines 166 to 193 in aaf720d

	! Loop over every theta, zeta point on the flux surface
	DO itheta=1,cmtheta
	CALL bicube_eval_external(crzphi,psi,ctheta(itheta),1,
	$ spline_ipsi,spline_itheta,
	$ crzphi_f,crzphi_fx,crzphi_fy)
	rfac=SQRT(crzphi_f(1))
	eta=twopi*(ctheta(itheta)+crzphi_f(2))
	rr=cro+rfac*COS(eta)
	zz=czo+rfac*SIN(eta)
	jac=crzphi_f(4)
	w11=(1+crzphi_fy(2))*twopi**2*rfac*rr/jac
	w12=-crzphi_fy(1)*pi*rr/(rfac*jac)
	delpsi=SQRT(w11**2+w12**2)
	IF(wegt/=0)THEN
	aspl_f_arr(itheta)=jac*delpsi
	ELSE
	aspl_f_arr(itheta)=1.0
	ENDIF
	w11=w11/delpsi
	w12=w12/delpsi
	DO izeta=1,cmzeta
	phi=-helicity*(twopi*czeta(izeta)+crzphi_f(3))
	xobs(itheta,izeta)=rr*COS(phi)
	yobs(itheta,izeta)=rr*SIN(phi)
	zobs(itheta,izeta)=zz

with helicity = ipd*btd and positive direction strings defined as CCW from above. Therefore the native +zeta sign relative to plasma current is

(-helicity) / ipd = -btd

(equivalently multiplication by ipd, since signs square to one). Co/counter-current depends on the absolute bt_direction, not helicity alone. For (ipd,btd,helicity)=(+1,+1,+1), positive native omega_E is clockwise and counter-current, contrary to the page.

These are documentation corrections only; this issue does not assert that the executable resonance or coordinate transforms should change.

[krystophny]

Documentation-only correction is pushed on fork branch agent/coordinate-sign-audit at commit 19b4352: krystophny@19b43523 . It separates the abstract native chart from the physical machine embedding, corrects the co/counter-current rule, and changes the documented passing harmonic to the executed plus sign. No production physics source is changed.

[krystophny]

Rechecked against freshly fetched upstream develop at 81927f167c0996bb12e49b4e6b8af8d17ac743fb (2026-07-23). Both discrepancies remain:

• docs/sign_conventions.rst still states ell_eff = ell - sigma*n*q and the helicity-only co/counter-current rule.
• the executable still constructs ell + n*q in both pentrc/pitch.f90 paths and in pentrc/torque.F90.

I also audited all fetched branches and all PENTRC-touching commits since 2025. No unmerged frequency/torque sign patch is present. Relative to the audited aaf720d4 checkout, current upstream changes PENTRC physics source only by adding omega_p=wphi NetCDF serialization in pentrc/torque.F90; the other PENTRC diffs are whitespace. The July 23 commits touch only gpec/gpout.f and do not alter PENTRC.

This remains a documentation defect; I still do not infer an executable sign change from curve agreement.

[krystophny]

Campaign update (2026-07-26): the documentation correction is isolated in ready-for-review PR #282 and the charge-verified PENTRC rerun uses the executable ell+n*q behavior. The TC24 audit retains PENTRC native signs but keeps GPEC-fed publication magnitude-only; neither this issue nor #282 is being used to promote a physical sign before the manufactured nonzero complex-mode helicity/torque/power gate closes.

[krystophny]

Fresh source/CAS/data audit confirms both documentation corrections and sharpens the cross-code consequence. For PENTRC versus NEO-RT, with q_P=-q_N, ell_P=-ell_N, omega_b,P=omega_b,N, and omega_D,P=-omega_D,N, the complete resonance denominator closes up to one harmless global minus only when omega_E,P=-omega_E,N. Preserving the electric term leaves the exact residual 2*n*omega_E; flipping n leaves a harmonic-dependent residual and cannot repair it.

The independent 16-lane TC24 matrix agrees: aggregate relative L2 against phase-matched PENTRC is (-M_t,+n)=0.296, then (-M_t,-n)=0.938, (+M_t,-n)=1.207, (+M_t,+n)=3.747. Here the accepted post-fix GPEC tuple implies n=+3. This selects the relative electric-frequency bridge; it is not a torque-output sign flip and does not by itself locate the mismatch in PENTRC versus the NEO serializer.