Skip to content

Correct q and COCOS statements in sign conventions reference - #268

Merged
logan-nc merged 3 commits into
PrincetonUniversity:developfrom
itpplasma:sign-conventions-q-fix
Jun 12, 2026
Merged

Correct q and COCOS statements in sign conventions reference#268
logan-nc merged 3 commits into
PrincetonUniversity:developfrom
itpplasma:sign-conventions-q-fix

Conversation

@krystophny

Copy link
Copy Markdown
Collaborator

Fixes #267. Follows up on @logan-nc's review comment on #253: the sign conventions reference merged in #266 claims q is read directly from the EFIT g-file without sign manipulation. For g-file input, q is recomputed by field-line integration in direct_run (equil/direct.f) and always comes out positive; the file's q profile is read but unused.

Changes to docs/sign_conventions.rst:

  • Safety Factor section: q is recomputed, not read; always positive for g-file input; inverse equilibria keep the input q profile including its sign; negative newq0 remains the one override.
  • "Why Positive m Is Always Resonant": q > 0 is now stated as guaranteed for direct equilibria rather than "standard tokamak".
  • COCOS Compatibility: sign choices in the g-file are normalized away on read (psi flip + ABS(F) + recomputed q), so only the per-radian flux units (Wb/rad) are required, not one specific sign convention.
  • Quick Reference table and Source Code References updated to match.
  • Two LaTeX-style em-dashes in the helicity section replaced.

Same correction applied to the q bullet in CLAUDE.md.

Verification

Documentation claims tested against develop (375ee8f) built with gfortran 16.1.1.

Failing before (doc claim "read directly from the EFIT g-file without sign manipulation" is falsified by the code): DCON run on the DIII-D ideal example g-file versus a copy with all signed quantities negated (psirz, simag, sibry, cpasma, ffprim, pprime, qpsi; the file's q profile becomes -1.06 to -8.03):

baseline: q0 =  1.062E+00, qmin =  1.062E+00, qmax =  5.320E+00, q95 =  4.228E+00
flipped:  q0 =  1.062E+00, qmin =  1.062E+00, qmax =  5.320E+00, q95 =  4.228E+00

$ cmp baseline/euler.bin flipped/euler.bin && echo IDENTICAL
IDENTICAL
$ cmp baseline/crit.bin flipped/crit.bin && echo IDENTICAL
IDENTICAL
$ diff baseline/dcon.out flipped/dcon.out
<  Total cpu time =  4.397E+00 seconds
<  Total wall time =  4.481E+00 seconds
>  Total cpu time =  4.468E+00 seconds
>  Total wall time =  4.525E+00 seconds

The g-file q sign has no effect and the recomputed q is positive in both runs, matching the corrected text. The unmodified example file already has fpol < 0, so the ABS(F) branch is exercised in the baseline; the flipped file has psio < 0 and exercises the psi flip branch.

Passing after: the revised rst parses cleanly (docutils; the pre-existing Sphinx-only :doc: role is unchanged).

krystophny and others added 3 commits June 10, 2026 14:24
… g-file

The sign conventions reference claimed q is read directly from the EFIT
g-file without sign manipulation. In the direct path the g-file q profile
is read but unused: direct_run rebuilds q from a field-line integration
using the sign-normalized psi map and |F|, so q is always positive for
g-file input. Verified by running DCON on a DIII-D g-file and on a copy
with all signed quantities negated: outputs (euler.bin, crit.bin, dcon.out,
netcdf) are identical except timestamps.

Also clarifies the COCOS section: sign conventions of the g-file are
normalized away on read, only the per-radian flux units are required.
Inverse equilibria keep the input q profile, including its sign.
@logan-nc

Copy link
Copy Markdown
Contributor

Superseded by #269, which carries these commits plus review corrections: the inverse-equilibrium q statement here was inaccurate (the main inverse path inverse_run recomputes q like direct_run rather than keeping the input file's q), and #269 also adds positive-q enforcement (guards newq0 < 0 and a chease4 q check) and removes the dead newq0==-1 sign-flip code. Opened on a PrincetonUniversity/GPEC branch because the maintainers can't push to this fork. This PR can be closed in favor of #269.

logan-nc added a commit that referenced this pull request Jun 12, 2026
…ositive

Correct q sign-convention docs and enforce positive q (replaces #268)
@logan-nc
logan-nc merged commit fe61b4f into PrincetonUniversity:develop Jun 12, 2026
8 of 10 checks passed
@krystophny

Copy link
Copy Markdown
Collaborator Author

Great, thanks Nik!

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.

sign_conventions doc: q is recomputed by field-line integration, not read from the g-file

2 participants