From 235df13923f04f8db3ac84dec0d702a8b7b381da Mon Sep 17 00:00:00 2001 From: Christopher Albert Date: Sat, 25 Jul 2026 14:39:28 +0200 Subject: [PATCH] DOCS - correct the PENTRC rotation and harmonic sign statements Five corrections to docs/sign_conventions.rst, all verified against the executables rather than against the surrounding prose: - The coordinate section presented the native DCON chart as though it fixed physical handedness. It does not: the chart and its exp[2 pi i(m theta - n zeta)] decomposition are defined independently of the machine embedding, which is applied separately via helicity. - The machine embedding is now stated explicitly as phi_CCW = -h(2 pi zeta + dphi) with h = helicity, from coil/field.F, so readers can map a native toroidal quantity to the laboratory frame without reading the coil module. - 'Positive omega_E is co-current for RH plasmas' was under-specified. In the CCW frame positive native omega_E has sign -h, and relative to the plasma current its sign is (-h)/ipd = -btd. So it is co-current exactly when bt_direction='negative', which is a statement about the absolute field direction and cannot be recovered from helicity alone. Filed as issue #276. - The effective bounce harmonic was printed as ell - sigma*n*q. Every executable path uses ell + sigma*n*q (pentrc/pitch.f90:244, pentrc/torque.F90:605). - Added a note that read_kin replaces exactly-zero omega_E knots by 1e-9 rad/s, so wefac=0 with wpfac=1 is not an exact zero control (issue #275), and a source reference for the native-to-machine toroidal map. Split out of the PENTRC numerical fixes, which these were previously bundled with. An earlier draft of this change also rewrote the safety-factor section to say that the inverse path inherits q from the input file; that is superseded by #268, which established that inverse_run recomputes q by flux-surface integration, and the current text is left as #268 has it. --- docs/sign_conventions.rst | 30 ++++++++++++++++++++++++------ 1 file changed, 24 insertions(+), 6 deletions(-) diff --git a/docs/sign_conventions.rst b/docs/sign_conventions.rst index 3754c615e..40dfccb45 100644 --- a/docs/sign_conventions.rst +++ b/docs/sign_conventions.rst @@ -17,8 +17,11 @@ setting up kinetic calculations. Coordinate System ================= -GPEC uses right-handed magnetic coordinates :math:`(\psi, \theta, \zeta)` with -Fourier decomposition :math:`\exp(im\theta - in\phi)`. +DCON defines its native magnetic chart :math:`(\psi, \theta, \zeta)` and +Fourier decomposition :math:`\exp[2\pi i(m\theta-n\zeta)]` independently of +the physical machine embedding. Do not infer physical handedness from this +abstract chart alone: GPEC maps its native toroidal coordinate to the +counter-clockwise machine angle using ``helicity``, as described below. Poloidal Flux :math:`\psi` -------------------------- @@ -46,6 +49,10 @@ Toroidal Coordinate :math:`\zeta` and :math:`\phi` - :math:`\phi` is effectively **CCW** (counter-clockwise from above) for left-handed (LH) configurations, but **CW** (clockwise) for right-handed (RH) configurations. +- In the laboratory convention where :math:`\phi_{\rm CCW}` increases + counter-clockwise viewed from above, the implemented machine embedding is + :math:`\phi_{\rm CCW}=-h(2\pi\zeta+\delta\phi)`, with + :math:`h=\mathrm{helicity}` (``coil/field.F``). Working Coordinate Options -------------------------- @@ -229,9 +236,13 @@ Rotation Velocity Conventions (PENTRC) - 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**. +- In the CCW laboratory frame, positive native :math:`\omega_E` has sign + :math:`-h`. Relative to plasma current its sign is + :math:`(-h)/s_I=-s_B`, where :math:`s_I=\mathtt{ipd}` and + :math:`s_B=\mathtt{btd}`. It is therefore co-current exactly when + ``bt_direction="negative"`` (clockwise), not according to helicity alone. + For ``(ip_direction,bt_direction)=(positive,positive)``, positive native + :math:`\omega_E` is clockwise and counter-current. Diamagnetic Frequencies ----------------------- @@ -270,6 +281,12 @@ Rotation Scaling Parameters - ``wpfac``: scales the total rotation :math:`\omega_\phi = \omega_E + \omega_{*n} + \omega_{*T}` by indirectly adjusting :math:`\omega_E`. +At the current revision, ``read_kin`` replaces every exactly zero +:math:`\omega_E` knot by :math:`10^{-9}\,\mathrm{rad/s}` before applying +``wpfac``. Consequently ``wefac=0,wpfac=1`` is not an exact zero control. +This behavior is tracked in `issue 275 +`_. + Energy Integral Resonance ------------------------- @@ -282,7 +299,7 @@ resonance denominator involves: 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, +: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. @@ -362,6 +379,7 @@ Source Code References - **Resonant surface finder**: ``sing_find`` in ``dcon/sing.f`` - **Output sign flips**: ``gpec/gpout.f`` (many locations, search ``helicity``) - **omega_E input**: ``read_kin`` in ``pentrc/inputs.f90`` +- **native-to-machine toroidal map**: ``field_bs_psi`` in ``coil/field.F`` - **Diamagnetic frequencies**: ``tpsi`` in ``pentrc/torque.F90`` - **Energy integral**: ``xintgrnd`` in ``pentrc/energy.f90`` - **SURFMN interface**: ``docs/outputs.rst``