This is a proposed toml change. If it is to be implemented, it should be done prior to v2.0.0.
Problem
In the [Equilibrium] section of gpec.toml, the Jacobian coordinate system is chosen with jac_type. For the named systems (hamada, pest, boozer, equal_arc, park) the constructor forces a fixed set of exponents. The raw exponents are exposed as top-level keys:
jac_type = "pest" # named type → exponents below are overwritten/ignored
power_bp = 0
power_b = 0
power_r = 0
This is misleading: power_bp/power_b/power_r/power_rc look like they apply to every run, but they only matter when jac_type = "other". For any named type they're silently overwritten by the EquilibriumConfig inner constructor, so listing them as 0 in every example is clutter that implies false relevance.
Proposed change
Make the user-facing knobs clearly scoped to the custom case, with no change to the bulk of the code (everything downstream keeps reading the internal power_* fields):
- Rename
jac_type = "other" → jac_type = "custom" (clearer intent; we have no stable API yet, so no shim needed).
- Add user-facing inputs
jac_custom_power_bp/b/r/rc to EquilibriumConfig (optional, default 0). These are read only at config construction.
- In the
EquilibriumConfig inner constructor, when jac_type = "custom", copy jac_custom_power_* → power_*; named types continue to force power_* and ignore the custom knobs. The existing "recognize a named type from the exponents" normalization is retained.
- Internal
power_bp/power_b/power_r/power_rc are untouched — FieldLineDerivParams and every Jacobian formula (DirectEquilibrium.jl, DirectEquilibriumArcLength.jl, InverseEquilibrium.jl) keep using them as the single source of truth.
This is contained to one source file (src/Equilibrium/EquilibriumTypes.jl). The TOML parser already filters on fieldnames, so the new fields are picked up automatically.
Example TOMLs
Per our annotation convention ("only active, meaningful variables in examples"):
- Add
custom to the jac_type option-list comment everywhere:
# Coordinate system (hamada, pest, boozer, equal_arc, custom)
- Remove the
power_* lines from files using a named jac_type (they're inactive there). This is safe — named types force the exponents regardless of file contents, so no numerical results change.
- Include
jac_custom_power_* lines only in files that actually set jac_type = "custom".
A custom config would then read:
jac_type = "custom" # non-standard Jacobian; exponents below define it
jac_custom_power_bp = 1 # poloidal-field exponent
jac_custom_power_b = 0 # total-field exponent
jac_custom_power_r = 0 # major-radius exponent
jac_custom_power_rc = 0 # minor-radius (rfac) exponent
Documentation
The EquilibriumConfig docstring is rendered on the docs website via the @autodocs block in docs/src/equilibrium.md, so it's the natural home for explaining custom. Update it to list "custom" (not "other") and document the four jac_custom_power_* fields with the Jacobian definition J = Bp^bp · B^b / (R^r · rfac^rc), noting they're ignored for any named jac_type.
This is a proposed toml change. If it is to be implemented, it should be done prior to v2.0.0.
Problem
In the
[Equilibrium]section ofgpec.toml, the Jacobian coordinate system is chosen withjac_type. For the named systems (hamada,pest,boozer,equal_arc,park) the constructor forces a fixed set of exponents. The raw exponents are exposed as top-level keys:This is misleading:
power_bp/power_b/power_r/power_rclook like they apply to every run, but they only matter whenjac_type = "other". For any named type they're silently overwritten by theEquilibriumConfiginner constructor, so listing them as0in every example is clutter that implies false relevance.Proposed change
Make the user-facing knobs clearly scoped to the custom case, with no change to the bulk of the code (everything downstream keeps reading the internal
power_*fields):jac_type = "other"→jac_type = "custom"(clearer intent; we have no stable API yet, so no shim needed).jac_custom_power_bp/b/r/rctoEquilibriumConfig(optional, default 0). These are read only at config construction.EquilibriumConfiginner constructor, whenjac_type = "custom", copyjac_custom_power_* → power_*; named types continue to forcepower_*and ignore the custom knobs. The existing "recognize a named type from the exponents" normalization is retained.power_bp/power_b/power_r/power_rcare untouched —FieldLineDerivParamsand every Jacobian formula (DirectEquilibrium.jl,DirectEquilibriumArcLength.jl,InverseEquilibrium.jl) keep using them as the single source of truth.This is contained to one source file (
src/Equilibrium/EquilibriumTypes.jl). The TOML parser already filters onfieldnames, so the new fields are picked up automatically.Example TOMLs
Per our annotation convention ("only active, meaningful variables in examples"):
customto thejac_typeoption-list comment everywhere:# Coordinate system (hamada, pest, boozer, equal_arc, custom)power_*lines from files using a namedjac_type(they're inactive there). This is safe — named types force the exponents regardless of file contents, so no numerical results change.jac_custom_power_*lines only in files that actually setjac_type = "custom".A custom config would then read:
Documentation
The
EquilibriumConfigdocstring is rendered on the docs website via the@autodocsblock indocs/src/equilibrium.md, so it's the natural home for explainingcustom. Update it to list"custom"(not"other") and document the fourjac_custom_power_*fields with the Jacobian definitionJ = Bp^bp · B^b / (R^r · rfac^rc), noting they're ignored for any namedjac_type.