Coordinates and field representation¶
This page derives the coordinate constructions that make the guiding-centre
Lagrangian canonical (Guiding-centre model, Eq. (2)) and states
what is splined for each integ_coords choice.
Usage: Field sources and coordinates.
All constructions produce coordinates \((r,\vartheta,\varphi)\) with
\(A_r = h_r = 0\) and splines of the five functions \(A_\vartheta, A_\varphi, h_\vartheta,
h_\varphi, B\) with first and second derivatives (field_can_t in
src/field/field_can_base.f90). The integrators use nothing else.
Implementation details and the libneo interfaces are in
DOC/coordinates-and-fields.md (Design notes).
Reference and integration coordinates¶
Reference coordinates \(u\) describe inputs and outputs: VMEC
\((s,\vartheta,\varphi)\) with the geometric toroidal angle
\(\varphi\), or chartmap \((\rho,\vartheta,\zeta)\) defined by a table
of Cartesian positions \(\mathbf x(u)\). Integration coordinates are
the canonical coordinates selected by integ_coords. ref_to_integ and
integ_to_ref (src/field_can.f90) convert start points, end points,
orbit samples and wall-hit points.
Canonical flux coordinates (integ_coords = 0)¶
VMEC provides straight-field-line flux coordinates \((s,\vartheta, \varphi)\) with \(\vartheta = \theta + \lambda_\text{V}\) and
but \(B_s \neq 0\). SIMPLE shifts both angles along the field line by a generating function \(G_c(s,\vartheta_c,\varphi_c)\):
The shift keeps field lines straight. It changes the one-form \(A_\vartheta d\vartheta + A_\varphi d\varphi\) only by \(d\bigl((\iota\psi_\text{tor} - \psi_\text{pol})G_c\bigr)\), because \((\iota\psi_\text{tor}-\psi_\text{pol})' = \iota'\psi_\text{tor}\); this gauge term is dropped, so \(A_\vartheta\) and \(A_\varphi\) are unchanged. The radial covariant field component becomes \(B_s^c = B_s + \iota' G_c B_\vartheta + (\iota B_\vartheta + B_\varphi) \partial_s G_c\), and \(B_s^c = 0\) gives a linear ODE along \(s\) at fixed \((\vartheta_c,\varphi_c)\):
It is integrated outward from the axis, starting from \(G_c = 10^{-8}\),
on a grid uniform in \(\sqrt s\) (rhs_cancoord in
src/get_canonical_coordinates.F90), with the VMEC fields evaluated at
\((\vartheta,\varphi)\) from the equations above. The new components are
with angular derivatives from finite-difference stencils. The integration
radius is \(r = s\), with \(A_\vartheta = \psi_\text{tor}^\text{edge}\,s\)
(field_can_flux.f90). The derivation from VMEC data is in
DOC/canonical_and_boozer_flux_coords_via_VMEC.tex.
Boozer coordinates (integ_coords = 2)¶
Boozer coordinates are flux coordinates with
SIMPLE builds them from VMEC by an angle shift computed in libneo
(boozer_converter.F90) or reads them from a Boozer chartmap
(Boozer chartmap format). The radial covariant component
\(B_s\) is not computed and not used: the Boozer Lagrangian sets
\(h_s = 0\). \(A_\vartheta\) and \(A_\varphi\) are then
one-dimensional, and \(h_k = B_k/B\) vary on a surface only through
\(B\); a field evaluation needs a three-dimensional spline of \(B\)
and one-dimensional splines of \(A_\varphi\), \(B_\vartheta\) and
\(B_\varphi\) (\(A_\vartheta\) is linear in \(s\)). The integration radius is
\(r = s\); a chartmap stores \(\rho = \sqrt s\)
(field_can_boozer.f90).
Meiss coordinates (integ_coords = 3)¶
Meiss and Hazeltine (1990) remove \(h_r\) and \(A_r\) in any coordinates with \(h_\varphi \neq 0\), without nested flux surfaces. Starting from reference coordinates \((r,\vartheta,\varphi)\) (VMEC with \(r=\sqrt s\), a chartmap with \(r=\rho\), a coil field splined on such a grid, or a SPECTRE volume), SIMPLE changes the toroidal angle and the gauge,
The radial components in \((r,\vartheta,\varphi_c)\) are \(h_r + h_\varphi\partial_r\lambda\) and \(A_r + A_\varphi\partial_r\lambda - \partial_r\chi\). Setting both to zero gives two ODEs in \(r\) at fixed \((\vartheta,\varphi_c)\),
evaluated at \(\varphi = \varphi_c + \lambda\) and integrated outward
from \(r_\text{min} = 10^{-6}\) with \(\lambda = \chi = 0\)
(rh_can in src/field/field_can_meiss.f90; adaptive RK with relative
tolerance canonical_ode_relerr; identity where \(|h_r| < 10^{-9}\)
along the slice). The new angular components,
and \(B\) are tabulated on a grid of canonical_grid_nr \(\times\)
canonical_grid_ntheta \(\times\) canonical_grid_nphi points over one
field period and splined in three dimensions (init_canonical_field_components).
All five functions depend on all three coordinates, so a field evaluation
costs one batched three-dimensional spline of five components.
Albert coordinates (integ_coords = 4)¶
The Newton solves of the integrators find \(r\) from \(p_\vartheta\) (Integrators). Albert coordinates replace the Meiss radius by
with the sign of \(A'_\vartheta\) at the outer boundary, so that
\(A_\vartheta = A_{\vartheta,\text{norm}}\,\psi\) is linear and
\(\partial_\psi A_\vartheta\) constant. The other four functions are
regridded from \(r\) to a uniform \(\psi\) grid covered by every
\((\vartheta,\varphi_c)\) line (src/field/field_can_albert.f90).
Field sources¶
VMEC \(R\), \(Z\), \(\lambda_\text{V}\) are splined in \(s\)
(order ns_s) and the angles (order ns_tp, multharm points per
highest harmonic), with near-axis harmonics continued by axis_healing.
Coil fields (Biot–Savart, src/field/field_coils.f90) are splined on a
reference grid before the Meiss or Albert construction. A chartmap
tabulates \(\mathbf x(\rho,\vartheta,\zeta)\) (and \(B\),
\(B_\vartheta\), \(B_\varphi\), \(A_\varphi\) for Boozer
chartmaps) and may extend beyond the LCFS. Each SPECTRE volume has its own
Meiss chart on \(\rho_g \in [k-1, k]\) (Full orbit, SPECTRE and GPU objective).
References¶
J. D. Meiss and R. D. Hazeltine, Canonical coordinates for guiding center particles, Phys. Fluids B 2, 2563 (1990), https://doi.org/10.1063/1.859380
C. G. Albert, G. S. Grassler, S. V. Kasilov, M. Markl, J. Schatzlmayr, Symplectic integration of guiding-center equations in canonical coordinates for general toroidal fields, arXiv:2503.15278 (2025), https://arxiv.org/abs/2503.15278