DOCS - correct the PENTRC rotation and harmonic sign statements - #282
Open
krystophny wants to merge 1 commit into
Open
DOCS - correct the PENTRC rotation and harmonic sign statements#282krystophny wants to merge 1 commit into
krystophny wants to merge 1 commit into
Conversation
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 PrincetonUniversity#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 PrincetonUniversity#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 PrincetonUniversity#268, which established that inverse_run recomputes q by flux-surface integration, and the current text is left as PrincetonUniversity#268 has it.
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Five corrections to
docs/sign_conventions.rst, each verified against the executables rather than against the surrounding prose. Documentation only, no source changes.Split out of #280, where they did not belong. Bundling them was worse than untidy: that text predated #269, so merging it would have reverted #269's correction that
inverse_runrecomputesqby flux-surface integration. This PR is written against currentdevelopand carries only the additive parts; the safety-factor section is left exactly as #269 has it.The corrections
1. The native chart does not fix physical handedness. The coordinate section opened by asserting GPEC "uses right-handed magnetic coordinates". DCON's chart and its
exp[2 pi i(m theta - n zeta)]decomposition are defined independently of the machine embedding, which is applied separately viahelicity. Readers were inferring physical handedness from an abstract chart.2. The machine embedding is now written down.
phi_CCW = -h(2*pi*zeta + dphi)withh = helicity, fromcoil/field.F. Without this a reader cannot map a native toroidal quantity into the laboratory frame without reading the coil module.3. "Positive
omega_Eis co-current for RH plasmas" was under-specified. In the CCW frame positive nativeomega_Ehas sign-h; relative to the plasma current its sign is(-h)/ipd = -btd. So it is co-current exactly whenbt_direction="negative"— a statement about the absolute field direction, which cannot be recovered fromhelicityalone sincehelicityis only the product. For(ip_direction, bt_direction) = (positive, positive), positive nativeomega_Eis clockwise and counter-current. Filed as #276.4. The effective bounce harmonic sign was wrong. Printed as
ell_eff = ell - sigma*n*q; every executable path usesell + sigma*n*q(pentrc/pitch.f90:244,pentrc/torque.F90:605).5. Added the zero-rotation caveat.
read_kinreplaces exactly-zeroomega_Eknots by1e-9 rad/sbefore applyingwpfac, sowefac=0, wpfac=1is not an exact zero control. Linked to #275. Plus a source reference for the native-to-machine toroidal map.Verification
An independent review checked items 3 and 4 against the source and confirmed both:
ell + n*qat the two cited lines, andphi_CCW = -h(2*pi*zeta + dphi)withh = ipd*btdatcoil/field.F:190andcoil/coil.F:163, giving the stated-btdrelative sign.