Skip to content

rename custom-Jacobian TOML knobs to jac_custom_power_* #288

Description

@logan-nc

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):

  1. Rename jac_type = "other"jac_type = "custom" (clearer intent; we have no stable API yet, so no shim needed).
  2. Add user-facing inputs jac_custom_power_bp/b/r/rc to EquilibriumConfig (optional, default 0). These are read only at config construction.
  3. 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.
  4. Internal power_bp/power_b/power_r/power_rc are untouchedFieldLineDerivParams 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.

Activity

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Metadata

Metadata

Assignees

Labels

refactorBehavior-preserving restructuring

Type

No type

Projects

No projects

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions