Documentation needed for sign and/or COCOS conventions

[logan-nc]

The fortran GPEC repo recently added incredibly helpful documentation of the GPEC sign conventions: PrincetonUniversity/GPEC#266

The Julia repo should have something similar in our documentation.

As a reach goal, which perhaps should be separated out into a separate issue, we should consider updating the Julia GPEC conventions to conform to a true COCOS convention for more clarity and easier communication/interface with other codes in the field.

[logan-nc]

@matt-pharr, what do you think? Just copy over the sign convention rst into a md?

What about the COCOS task? Worth keeping as a bigger todo issue?

[logan-nc]

This is related to #239 but can safely be done separately

[logan-nc]

@jhalpern30 and @calin1989, digging into the claims in the fortran PR linked above and comapring to the COCOS paper [Sauter NF 2013] got me this:

Per Sauter-Medvedev Table 1, COCOS indices that differ only by the 2π flux factor are the pairs (1,11), (2,12), … — so the pure-÷2π partner of IMAS COCOS 11 is COCOS 1, not COCOS 2 (which differ additionally in σ_RφZ / toroidal handedness and in sign(q)). The Julia reader converts COCOS 11 → "internal COCOS 2" by dividing ψ by 2π only (ReadEquilibrium.jl:413-424), with no handedness/sign reinterpretation. So the code's COCOS-2 label cannot be taken as a certified COCOS index without a full first-principles check of σ_Bp, σ_RφZ, σ_ρθφ. This ambiguity is exactly why we fall back to documenting the practical input requirement rather than asserting a certified index (per user instruction).

Please double check your COCOS 2 claims from the IMAS integration.