Applicability

Machine-independent.

Limitations

A GEQDSK is identified as a two-dimensional grid by the presence of its characteristic keys, so a mapping that happens to carry them is treated as one. Only the requested time slice and profile grid are read; everything else in a multi-slice source is discarded.

Provenance

1. The per-source adapters below preserve each format’s own layout conventions; see vaft.process.cocos.identify_convention for how the convention is inferred when the caller does not assert one.

Applicability

Machine-independent.

Limitations

Midpoint rule on the given points, so a coarsely sampled contour underweights regions of high curvature. Takes the field magnitudes as given and cannot check they were computed in a consistent convention.

Provenance

1. The definition used with shafranov_integrals and calculate_diamagnetism as their reference field.

Applicability

Machine-independent.

Limitations

The same per-cell boundary mask as volume_average, so the boundary is resolved only to the grid. The vacuum field is a single boundary value rather than a profile.

Provenance

1. The volume-integral definition of diamagnetism; the surface-integral form is calculate_reconstructed_diamagnetic_flux, and the two should agree for a consistent equilibrium.

Processing steps

1. Validate grid dimensions and identify the flux conversion factor from cocos.
2. Normalize or deduce psi_axis and psi_boundary, converting to Wb/rad if necessary.
3. Evaluate and interpolate f_profile onto the requested levels_norm.
4. Call flux_surface_quantities to trace contours and compute geometric averages.
5. Apply on-axis quadratic extrapolation in radius (linear in normalized flux $\psi_N$) to resolve $q_0$.
6. Attach the COCOS sign factor $\sigma_q$ and package the output.

Defaults

levels_norm defaults to 65 points from 0 to 1 (numerical convenience). cocos=11 matches the IMAS standard data dictionary convention.

Applicability

Machine-independent. Works for any 2D tokamak poloidal flux map.

Provenance

1. O. Sauter and S. Yu. Medvedev, Comput. Phys. Commun. 184 (2013) 293, Eq. (17) and Table I for COCOS relations and safety factor definitions.
2. J. Wesson, Tokamaks, 4th ed., Oxford University Press (2011), Sec. 3.4.

Processing steps

1. Map the poloidal current profile onto the grid through psi_to_rz.
2. Form the plasma and vacuum toroidal fields as that function over the major radius.
3. Integrate their difference over the cross-section inside the boundary.

Applicability

Machine-independent.

Limitations

A cross-sectional integral on the grid, so the boundary is resolved only to the cell. The vacuum field is taken as a single boundary value rather than a profile, which is exact only where the poloidal current is flat outside the plasma.

Provenance

1. The definition of diamagnetic flux as the toroidal-field deficit integrated over the plasma cross-section, in the form the EFIT-style workflow this package reproduces uses.

Applicability

Machine-independent.

Limitations

required_for is a free string; an unrecognized value applies the general requirements rather than being rejected. A clean report says the fields are present and shaped correctly, not that their values are physical.

Provenance

1. Issue #337 for the split between a precondition and a scientific verdict, and #253 for the validation layer that owns the latter.

Applicability

Machine-independent.

Limitations

A separation is not a correspondence: two contours can be close everywhere and still differ in where along the curve a feature sits. Time grows as the product of the two point counts; memory is bounded by working through the vertices in blocks.

Provenance

1. Point-to-segment distance and the symmetric Hausdorff distance are standard computational geometry.

Applicability

Machine-independent.

Limitations

Takes the flux as given and cannot check that it was computed against the same reference radius and field used here.

Provenance

1. The EFIT xmui definition, evaluated through vaft.formula.equilibrium.virial_muihat_from_Bt_R0_dphi.

Processing steps

1. Drop the seeds that are already outside the limiting polygon; they have no connection length and are reported as nan.
2. Step every surviving line together by fourth-order Runge-Kutta in the toroidal angle, once forward and once backward, retiring a line as it leaves the polygon or reaches max_length_m.
3. Add the two branches. A line retired on length contributes max_length_m and is flagged rather than being read as a wall hit.

Defaults

The two-degree step is a numerical convenience, chosen by convergence against a half-degree trace on VEST’s vacuum field: the median length moves by 7e-5 and the 95th percentile by 4e-3 of itself. The 150 m limit is an assumed value, long enough that a Lloyd threshold evaluated on it has already saturated and short enough that a line circulating near a null terminates.

Applicability

Machine-independent. The wall polygon and the field are both the caller’s.

Limitations

The wall test is applied once per step, so a line ends at the last point inside the polygon rather than at the true crossing – of order $R\,\mathrm{d}\varphi$, millimetres against the tens of metres the length itself runs to. Fixed step, so accuracy is set by the step alone and there is no error control. A field line that closes on itself never strikes the wall, and this returns max_length_m for it, flagged; distinguishing a closed line from a merely long one is not attempted.

Provenance

1. The field-line equations in toroidal-angle form, as in trace_field_line, stepped over many seeds at once.
2. B. Lloyd et al., Nucl. Fusion 31 (1991) 2031, Sec. 2, for the role the connection length plays in the breakdown threshold this feeds.

Applicability

Machine-independent.

Limitations

Assumes one simple closed contour; a self-intersecting or open segment gives a signed area that does not mean what the formulas take it to mean. Every quantity is only as accurate as the contour’s sampling.

Provenance

1. IMAS data dictionary definitions for the boundary’s geometric axis and triangularity, which fix the centre these are measured against.
2. The exact revolution volume is vaft.formula.equilibrium.exact_volume_from_RZ_contour.

Applicability

Machine-independent.

Limitations

The 1e-3 concavity threshold sits above the chord error of a smooth contour sampled with about a hundred points; a coarser contour can read a small spurious depth. Outboard concavity is not reported.

Provenance

1. The observables proposed in #942, section 7, kept separate from the coefficients of any one parameterization.

Processing steps

1. Resolve the source convention from the declared index, or from a single surviving identification candidate.
2. Take the per-quantity factors for the pair from OMAS.
3. Scale the flux quantities, the poloidal current, the safety factor, the two source gradients, the plasma current and the vacuum field, each by its own factor.
4. Record the target index on the returned convention.

Applicability

Machine-independent.

Limitations

Refuses rather than guesses when the source convention is ambiguous, which is the common case for a file that declares nothing and whose flux exponent could not be identified. The identified-candidate list carried on the result is shifted on the assumption that every candidate shares the source’s storage family, which is not guaranteed and can produce an out-of-range index; tracked in #601.

Provenance

1. Sauter and Medvedev (2013) for the conventions; the per-quantity factors are omas.cocos_transform.

Applicability

Machine-independent.

Provenance

1. Definition of the current moments; see issue #943.

Applicability

Machine-independent.

Provenance

1. Definition of the current moments; see issue #943.

Applicability

Machine-independent.

Provenance

1. Definition of the current moments; see issue #943.

Defaults

Leaving flux_tolerance at None is the justified choice, and an override is a numerical convenience only: each saddle otherwise gets its own window from its Hessian curvature and the grid spacing, because psi is stationary there and a one-cell position error perturbs its flux only at second order. A single global tolerance cannot be right for saddles of different sharpness. fourier_modes = 16 is likewise a numerical convenience, enough harmonics to represent a tokamak boundary without fitting the contour’s own sampling. The coefficients are fit_fourier_surface’s, one convention for every contour (#945). Before #945 the phase origin was the sampled point of largest R; it is now the phase of R’s first harmonic, so individual cosine and sine values differ from older results while the per-harmonic amplitudes and the reconstruction error do not.

Applicability

Machine-independent. The gap directions are where a machine’s own geometry enters, and they are supplied by the caller.

Limitations

Topology needs a wall or limiter to distinguish limited from ambiguous; without one, a plasma with no X-point is ambiguous rather than limited. Strike points and gaps require the corresponding geometry and are simply absent otherwise. The Fourier fit assumes a single closed contour.

Provenance

1. The Hessian classification of stationary points of psi is the standard O-point and X-point test; the boundary-relevance condition is what distinguishes a physical X-point from a saddle elsewhere in the domain.

Processing steps

1. Take j_tor as given, or evaluate the Grad-Shafranov current J_phi = -sigma_Bp (2 pi)**e_Bp (R p'(psi) + FF'(psi)/(mu0 R)) from the record’s flux-function profiles in its declared COCOS.
2. Weight each cell by the fraction of it inside the LCFS.
3. Integrate the total current and the centroid, then every central moment with 2 <= p + q <= max_order.

Defaults

max_order = 4 is a numerical convenience: second order gives the widths and tilt, third the skewness and up-down asymmetry, fourth the first shape beyond them; higher orders grow more sensitive to the edge.

Applicability

Machine-independent.

Limitations

An ODS’s own profiles_2d.j_tor is not read automatically – as_equilibrium does not carry it – so pass it as j_tor; the derived density agrees with update_equilibrium_profiles_2d_j_tor to about 1e-10 inside the LCFS. NaN cells of a supplied j_tor that the fractional weights still count are filled from p'/FF' and the source label says how many. The integrated current is checked against the record’s ip, and a disagreement beyond five percent – typically a factor 2*pi or -1 from a wrongly declared convention – is warned about, not corrected. Current outside the LCFS, such as a halo or a vessel current, is excluded by the weighting. The Shafranov (magnetic) moments of #943 are a separate representation and are not computed here.

Provenance

1. Definition of the current moments; see issue #943.
2. O. Sauter and S. Yu. Medvedev, Tokamak coordinate conventions: COCOS, Comput. Phys. Commun. 184, 293 (2013), Eq. 12, for the sign and 2*pi of the Grad-Shafranov current.

Processing steps

1. Check preconditions for the global requirement set and keep the report.
2. Boundary geometry: major and minor radius, elongation, upper and lower triangularity, volume and surface area from the last closed flux surface.
3. Energy: integrate pressure over the plasma volume by grid quadrature for the pressure integral and the thermal energy.
4. Betas: toroidal from the volume-average pressure and the vacuum field, normalized from that and the current, poloidal from the boundary-average poloidal field.
5. Virial: the Shafranov boundary integrals and the internal inductance from the Lao closure.
6. Safety factor: on-axis, at 95 percent of the normalized flux, at the edge, the magnetic shear, and the radius of each requested rational surface.

Applicability

Machine-independent.

Limitations

Every quantity degrades independently: a missing pressure profile costs the energies and the betas but not the geometry. A failure inside the pressure integration is captured as a warning on the returned report rather than raised. The virial internal inductance is ill-conditioned as its coefficient approaches one.

Provenance

1. IMAS data dictionary definitions for the boundary geometric axis, triangularity, and the global quantities this mirrors.
2. Lao’s virial closure for the internal inductance from the Shafranov boundary integrals, evaluated by vaft.formula.equilibrium.virial_li_from_S_alpha_rt.
3. The boundary integrals themselves come from vaft.process.equilibrium.shafranov_integrals and vaft.process.equilibrium.efit_virial_volume_integrals, the EFIT-style weighted forms.

Processing steps

1. psi_n = (psi_1d - psi_axis)/(psi_boundary - psi_axis).
2. rho_pol_n = sqrt(psi_n), by definition of that coordinate.
3. rho_tor_n = sqrt(Phi/Phi_boundary) with Phi the cumulative trapezoidal integral of q over the normalized flux, returned only if q is finite, of matching length, and produces a monotonic result.

Applicability

Machine-independent.

Limitations

rho_tor_n is unavailable when q is missing, non-finite, of the wrong length, or gives a non-monotonic toroidal flux, and when psi_n is not strictly monotonic. The integral is trapezoidal on the stored grid, so a coarse or axis-clustered q limits its accuracy near the axis. The published definition string names dpsi where the integration variable is psi_n; the value is unaffected and the wording is tracked in #602.

Provenance

1. The toroidal flux definition Phi = int q dpsi and its normalized radius, as used by the IMAS data dictionary for rho_tor_norm.
2. vaft.process.profile.core_profiles consumes this to evaluate kinetic fits on the equilibrium grid, and refuses by name when the record here is unavailable (issue #420).

Applicability

Machine-independent.

Limitations

The reference radius is guarded against a near-singular denominator, so a degenerate geometry returns a finite but meaningless value rather than diverging. Every optional input governs one output: omit the pressure and the pressure-dependent terms are simply absent.

Provenance

1. EFIT’s weighted volume integrals, with the fractional cell weights standing in for its externally supplied weight map; see fractional_cell_weights_from_boundary.

Processing steps

1. Trace the line through $(R_S, 0)$ forward and backward against the wall, and label the branch that rises the upper one.
2. $R_{\mathrm{LIN}}$: the wall polygon’s midplane crossing nearest the start on its inboard side.
3. Mirror point of each branch: the smallest $R$ the branch reaches before it ends, excluding the seed – the strongest field an electron escaping that way has to pass. Record $|Z|$ and $R$ there.
4. Keep the weaker mirror: the branch whose mirror point sits at the larger $R$, so the smaller field rise. Its $|Z|$ is $Z_{\max}$ and its $R$ is $R_m$. If $R_m \ge R_S$ the line never dips inward.
5. $R_C = Z_{\max}^2 / \bigl(2(R_S - R_m)\bigr)$, the parabola through the start and the mirror point, then $\alpha$ and $F_3$ from vaft.formula.startup.ejiri_mirror_alpha_from_R_S_R_LIN_R_C_Z_max and vaft.formula.startup.ejiri_f3_from_alpha.
6. For comparison, fit $R - R_S = c_1 Z + c_2 Z^2$ over $|Z| \le$ z_fit and report $-1/(2c_2)$ as curvature_radius_local.

Defaults

The 150 m limit is a numerical convenience matching connection_length_map, and it is where the result converges on VEST: at the breakdown onset of the packaged shot, from the electron-cyclotron resonance, 50 m stops both branches short and gives $Z_{\max} = 0.13$ m and $F_3 = 0.38$, while 150, 500 and 1500 m all give $0.30$ m and $0.51$. The quarter-$Z_{\max}$ window and the one-degree step are numerical conveniences: at 2, 1, 0.5 and 0.25 degrees $F_3$ agrees to six figures and $R_C$ and $Z_{\max}$ to four.

Applicability

Machine-independent. The wall polygon and the field are both the caller’s, and so is r_start – normally the electron-cyclotron resonance, from vaft.formula.startup.electron_cyclotron_resonance_radius.

Limitations

An Ejiri-inspired geometric proxy, not the numerical orbit boundary: it says nothing about EC power, collisions or breakdown itself. A branch whose first step already leaves the wall is read as an immediate loss on that side, so a start point within one step of the wall reports no confinement – shorten dphi if that is not the answer wanted. A branch that stops on max_length_m sets saturated and raises a RuntimeWarning: that result is not converged and is not a bound, since a longer trace can move both the mirror point and the branch that binds.

Provenance

1. A. Ejiri and Y. Takase, Nucl. Fusion 47 (2007) 403, Sec. 3, for the orbit-boundary slope and the geometry factor.
2. The trace is trace_field_line, and the two relations are the vaft.formula.startup kernels named in the processing steps.

Applicability

Machine-independent.

Limitations

With neither cocos nor psi_per_radian known, from the arguments or the record, the flux is taken as weber per radian and a UserWarning says so (#1313); a weber flux then gives a field 2*pi too large. With the storage family but no index, the orientation is assumed (k < 0) and the warning says that instead; a record’s open candidates settle it when they agree, and leave it to the same announced assumption when they do not (the packaged g-file, open between COCOS 1 and 2, warns like its arrays do). Outside the confined region the poloidal current function clips to its nearest edge value, the clip-and-interpolate convention psi_to_rz uses, so the toroidal field there is that clipped function over the major radius rather than the true vacuum field. The spline extrapolates beyond the grid, where the field should not be read.

Provenance

1. Sauter and Medvedev (2013), Eq. 20, for the prefactor.
2. The point-wise twin make_equilibrium_field_interpolator in this module, which this routine is pinned to by test.

Applicability

Machine-independent.

Provenance

1. Truncated Fourier series of a closed curve; the arc-length angle and phase are VAFT’s convention (#945).

Applicability

Machine-independent.

Provenance

1. Guazzotto and Freidberg (2021), Eqs. (2.9), (3.2) and (A4); Part 2, Eqs. (5.12)-(5.14).

Applicability

Machine-independent.

Limitations

Up-down symmetric and single-valued in theta, so it cannot represent a separatrix, an X-point, or an asymmetric boundary at all. Triangularity is bounded by one because the arcsine of it must exist. Squareness is bounded by one half because d(theta + zeta*sin(2*theta))/dtheta = 1 + 2*zeta*cos(2*theta) changes sign beyond it: the parameterization then doubles back and the “surface” crosses itself, so a larger magnitude does not describe a squarer plasma but a curve that is not one. The indentation is bounded below for the same reason: at equal height the two sides are 2 r cos(theta) (cos(alpha sin(theta)) + b sin(theta)**2) apart, which stays positive for every theta exactly when b > -cos(alpha) = -sqrt(1 - delta**2).

Provenance

1. Miller, Chu, Greene, Lin-Liu and Waltz, Noncircular, finite aspect ratio, local equilibrium model, Phys. Plasmas 5, 973 (1998), which introduced this parameterization.
2. The squareness term follows the extended form used for shape comparison, e.g. Barr, Boyer, Humphreys et al., ShapeFIT, Nucl. Fusion 58, 076011 (2018), App. A.
3. The inboard-indentation term for bean-shaped plasmas (PBX/PBX-M) is VAFT’s, specified with its bean-onset criterion in issue #941.

Applicability

Machine-independent.

Provenance

1. H. Xie and Y. Li, arXiv:2601.02942 (2026), Eqs. (6)-(11).

Applicability

Machine-independent.

Limitations

Linear sources only, so it cannot represent a peaked pressure profile or a realistic current density. The poloidal current is recovered as a square root, clipped at zero, so a model whose flux excursion drives the square negative silently flattens rather than failing.

Provenance

1. Solov’ev, Hydromagnetic stability of closed plasma configurations (1968), for the linear-source closed form.
2. The five-term homogeneous basis and the particular integral follow the standard polynomial construction for that solution.
3. A. J. Cerfon and J. P. Freidberg, Phys. Plasmas 17, 032502 (2010), for the seven- and twelve-term bases of basis="cerfon_freidberg_even" and "cerfon_freidberg".

Applicability

Machine-independent.

Limitations

Marching squares on the grid, so a contour is resolved only to the cell and a surface smaller than a few cells is poorly represented. Contours are returned in the order the algorithm finds them, not sorted by size or by containment.

Provenance

1. The IMAS data dictionary layout for a two-dimensional flux profile, which fixes the axis order this assumes.

Processing steps

1. Drop non-finite samples.
2. For each integer m in range, find every bracket where q - m/n changes sign and interpolate the crossing linearly.
3. Sort the crossings outward.

Applicability

Machine-independent. Any monotonic radial coordinate; the name says psi_norm because that is what the perturbed-equilibrium codes report their rational surfaces on.

Limitations

Accuracy is that of linear interpolation, so the error scales with the square of the local grid spacing and with the curvature of q – which means it is worst exactly where q is steepest, at the edge. On the grid GPEC itself writes, which is refined around the rational surfaces (a spacing of 3.6e-06 at the outermost surface of the DIII-D example against 7.4e-03 in the core), the surfaces come back to 1.4e-09 in psi_norm. On a uniform grid of the kind an equilibrium reconstruction produces they do not: 6.5e-04 at 129 points and 4.0e-05 at 513, in both cases dominated by the outermost surface. Interpolate q onto a finer grid before asking, if the answer has to be better than that.

A reversed-shear q resonates twice on the same m, and both crossings are returned. A root that sits exactly on a grid point, or a q that is flat at m / n over an interval, is returned once – at the node and at the start of the flat region respectively – rather than once per sign change, which would double-count it.

Provenance

1. gpec_multimode_metrics.rational_surface_table derived the same surfaces from GPEC output; this takes them from the equilibrium, so they can be known before a run – at the accuracy the equilibrium’s own grid supports, which the Limitations quantify.

Applicability

Machine-independent.

Limitations

A saddle is only a candidate X-point: numerical saddles far from the plasma are common on reconstructed maps. Whether one bounds the plasma is decided by derive_boundary_representation. Searches start only from interior grid nodes and keep only roots strictly inside the grid, so a point in the outermost cell may be missed; two closer than half a cell are reported once.

Provenance

1. The Hessian classification of stationary points of psi is the standard O-point and X-point test.

Processing steps

1. Resample the contour to max(256, 8*modes) points uniform in arc length.
2. Orient it counter-clockwise and start at its largest R.
3. Solve the cosine and sine coefficients of R and Z by least squares.
4. Rotate the angle origin so the first harmonic of R is a pure cosine (r_sin[1] = 0, r_cos[1] > 0), which fixes the phase independently of the contour’s sampling and starting point.
5. Score the reconstruction geometrically: contour-to-model and model-to-contour nearest distances on a dense evaluation.

Defaults

modes = 6 and max_normalized_rms = 0.02 are numerical conveniences: six harmonics resolve the shaped surfaces of a tokamak to well under a percent, and the two-percent threshold is the one the Miller fit uses, so the two acceptances are comparable.

Applicability

Machine-independent.

Limitations

The phase origin is undefined only for a contour with no first harmonic in R, which no closed plasma surface is. max_error and hausdorff_distance are the same number, the larger of the two directed maxima, kept separately to parallel MillerFitResult. Arc length is not a flux-coordinate angle, so the coefficients describe shape, not straight-field-line harmonics.

Provenance

1. Least-squares Fourier series of a closed curve; the convention is VAFT’s (#945), shared with the LCFS representation.

Processing steps

1. Convert the levels to normalized poloidal flux when needed.
2. Trace the closed surface at each level; a level outside the coordinate’s range, or whose surface is open or missing, is recorded as skipped rather than dropped or clamped silently.
3. Fit each traced surface and sort the fits by radial value.

Applicability

Machine-independent.

Limitations

Near an X-point the arc-length series needs many harmonics to follow the corner, which the acceptance threshold reports rather than hides. Radial derivatives of the coefficients are not computed yet.

Provenance

1. See fit_fourier_surface; the surface tracing is the one fit_miller_sequence uses.

Processing steps

Convert the source profiles to COCOS 11, integrate toroidal plasma current inside fractional LCFS cells, and evaluate exact ring Green responses for the plasma and signed-turn PF rectangles. Assemble weighted boundary and saddle rows, then solve bounded, optionally regularized least squares.

Defaults

As a numerical convenience, omitted flux and field weights divide by the target flux span and peak plasma boundary field, and the current scale defaults to |Ip|/number of circuits. No hardware current limits are inferred from geometry.

Applicability

Machine-independent. Axisymmetric free-space coils and static equilibria.

Limitations

Passive currents, iron, surface-current sheets and toroidal flow are not modeled. Highly conditioned current vectors need hardware bounds and later free-boundary closure for a physical interpretation.

Provenance

1. Exact kernels in vaft.process.electromagnetics and the COCOS-aware source profiles in vaft.data.equilibrium.EquilibriumData.

Processing steps

1. Convert the requested levels into normalized poloidal flux when they are given in another coordinate.
2. Trace the contour at each level and keep the closed one containing the magnetic axis.
3. Fit each with fit_miller_surface, vetoing surfaces within five percent of a minor radius of an active X-point.
4. On the accepted surfaces sorted by minor radius, spline-differentiate the three shape parameters, then the safety factor for the magnetic shear, and the pressure for the ballooning parameter.

Defaults

The five percent X-point proximity is a numerical convenience marking where the surface stops being locally Miller-like; so is the requirement of four accepted surfaces for radial derivatives, which is the smallest set a cubic spline can use.

Applicability

Machine-independent.

Limitations

Rejected surfaces are returned with the rest, so a caller must filter on acceptance before using them. Derivatives are unavailable when fewer than four surfaces are accepted or when the fitted minor radii are not strictly increasing, and the reason says which. The shear and the ballooning term additionally need the safety factor, the pressure and the vacuum field, and are simply absent without them.

Provenance

1. Miller et al., Phys. Plasmas 5, 973 (1998); the radial derivatives are what makes the parameterization a local equilibrium model rather than a shape description.

Processing steps

1. Resample the contour to a uniform arc-length parameterization.
2. Seed the five parameters from the contour’s bounding box.
3. Solve a bounded least squares on point-to-surface distances, refining each point’s local angle by five Newton steps per evaluation so the residual is a true nearest-point distance rather than an index-matched one.
4. Score with a symmetric distance: contour-to-model and model-to-contour, giving a root-mean-square, a maximum, and a Hausdorff distance.
5. Reject, in order, a surface too near the boundary, a surface near an X-point, a fitted indentation that makes the surface cross itself, a residual over the threshold, or a solve that did not converge.

Defaults

max_normalized_rms = 0.02 is a validated-workflow threshold, not a physical constant: two percent of the minor radius is where a fitted surface stops being a useful stand-in for the traced one. The parameter bounds, elongation in 0.05 to 10 and triangularity within 0.999, are numerical conveniences that keep the solve inside the parameterization’s own domain; so is the indentation box of -0.95 to 2, whose delta-dependent lower limit is enforced after the solve instead.

Applicability

Machine-independent.

Limitations

Miller is up-down symmetric, so a genuinely asymmetric surface fits poorly by construction and is rejected rather than approximated. Without squareness a surface whose corners are squarer or rounder than a sine can express has nowhere to put that shape either: it goes into the residual, and past max_normalized_rms the fit is rejected as “not Miller-like enough to use” when what is true is “not five-parameter Miller-like” (#867). Surfaces at or beyond 95.5 percent of the normalized flux are rejected outright, because separatrix geometry is not locally Miller-like there. The X-point proximity has to be determined by the caller; this function only honours the flag. Unlike every other derived quantity in this module, the provenance recorded here carries no convention, tracked in #604.

Provenance

1. Miller et al., Phys. Plasmas 5, 973 (1998), for the parameterization being fitted.

Processing steps

1. Trace surfaces at rho from 0.15 to 0.97 and take the LCFS as rho = 1.
2. Extract each surface’s MXH parameters: centre and minor radius from its radial extent, elongation from its height, the geometric angle from Eq. (7), the distorted angle from Eq. (6), and their difference as a harmonic series (Eq. 8).
3. Fit every parameter’s radial profile as f_edge + sum_l f_l u_l(rho) with u_l of Eq. (10), the edge value fixed to the LCFS.
4. Evaluate the representation on a (rho, theta) grid and measure psi_N(R, Z) - rho**2 on the equilibrium’s own flux map.

Defaults

harmonics = 2 and radial_order = 4 give 9 x 5 = 45 parameters, inside the paper’s “fewer than 100” for high fidelity; tolerance = 0.01 matches its 1e-2 accuracy level and boundary_tolerance = 0.02 leaves room for a diverted corner. All are numerical conveniences.

Applicability

Machine-independent.

Limitations

Xie and Li use this basis as the unknown of a Grad-Shafranov solver; here it only represents an existing equilibrium, so no force balance is imposed and the source profiles are not fitted. A diverted LCFS has a corner an MXH shape of low order cannot follow; the boundary error says so. The profiles are anchored at rho = 1 only, so the axis position is an extrapolation, reported as a metric.

Provenance

1. H. Xie and Y. Li, What is the minimum number of parameters required to represent solutions of the Grad-Shafranov equation?, arXiv:2601.02942 (2026), Eqs. (4), (6)-(11).

Processing steps

1. Convert the flux to per radian and select the grid points inside the LCFS with psi_N <= psi_n_max.
2. Solve for the basis coefficients, p' and FF' by least squares on the flux there.
3. Evaluate the fitted model on the grid and measure the flux, field, axis, boundary and topology errors against the equilibrium.

Defaults

basis = "cerfon_freidberg" (twelve terms, up-down asymmetry allowed) and tolerance = 0.02 are numerical conveniences: two percent of the flux span is roughly where a Solov’ev stand-in stops being useful for shape and field studies.

Applicability

Machine-independent.

Limitations

A Solov’ev model has constant sources, so a reconstruction with peaked or hollow profiles fits only approximately, and the fitted p' and FF' are effective values, not the equilibrium’s. A poor fit is returned with status poor_fidelity, not rejected.

Provenance

1. Solov’ev (1968) and Cerfon and Freidberg, Phys. Plasmas 17, 032502 (2010), for the model; the fit is the linear inverse of #1166.

Processing steps

1. Trace the contour at each level, taking the confined segment when several are returned, and substituting the supplied outline at the boundary.
2. Form the averages and the shape parameters on each resolved contour.
3. Return NaN for a level whose contour is missing or below min_points, then fill those by interpolation against the square root of the normalized flux, the coordinate in which near-axis geometry is linear.
4. Set the on-axis level to its exact point limits.

Defaults

min_points is a numerical convenience tied to what a flux map can resolve; see MIN_FLUX_SURFACE_POINTS for the measurement behind its value.

Applicability

Machine-independent.

Limitations

The innermost one or two levels are the least accurate everywhere, because the flux gradient is small and varies fastest there. That is a property of the map, not of this routine: on the packaged OMFIT reference the stored dvolume_dpsi runs 8.53, 22.85, 29.59, 29.05, 28.85 from the axis out, a ramp that cannot be physical since the derivative approaches a finite limit, while the trace here gives a smooth 30.8, 29.3, 29.3. Compare against a reference only outside a normalized flux of about 0.05, and check the near-axis values against the integral of the derivative recovering the volume instead.

On axis the surface is a point: the volume, area and surface are exactly zero and the three geometric averages take their axis limits, but the shape parameters and the two derivatives are undefined there and are extrapolated from the innermost resolved surface.

Provenance

1. The flux-surface average as the IMAS data dictionary defines the gm family, and the same contour extraction extract_flux_surface_contours provides.

Defaults

samples_per_axis = 5 is a numerical convenience: twenty-five sub-samples per cell resolve the boundary to about a fifth of a cell, which is finer than the flux map that produced the boundary in the first place.

Applicability

Machine-independent.

Limitations

Sub-sampling, not exact polygon clipping, so a cell is resolved only to the sub-sample spacing and a boundary feature smaller than a cell is missed. Assumes a single closed polygon.

Provenance

1. Replaces EFIT’s externally provided cell-weight map; consumed by shafranov_integrals and efit_virial_volume_integrals.

Applicability

Machine-independent.

Limitations

Second-order central differences, one-sided at the edges, so the outermost two cells inherit that lower accuracy. A caller comparing against a source term should ignore that frame, as grad_shafranov_residual does.

Provenance

1. The Grad-Shafranov equation in its standard axisymmetric form.

Applicability

Machine-independent.

Limitations

The two source profiles are interpolated onto the grid through the flux itself, so the residual is meaningful only where they are the equilibrium’s own.

Pass the boundary. Outside the separatrix the flux is not monotonic; it folds back into the normalized range near the poloidal field coils, so a flux-value cutoff alone re-admits vacuum points where the two profiles are extrapolation and the operator is reading coil current. On a free-boundary grid that is a third of the points and two orders of magnitude of spurious residual, and it does not affect a fixed-boundary grid at all, so comparing the two without it is not comparing like with like.

Provenance

1. The Grad-Shafranov equation; the operator is grad_shafranov_operator and the source term is formed from the two profiles the equilibrium stores.

Processing steps

1. Evaluate G = Delta* psi - (-mu0 R^2 p' - FF') on the grid with grad_shafranov_residual, in per-radian flux.
2. Trace each requested surface and resample it uniformly in arc length from its outboard side, as fit_fourier_surface does.
3. Interpolate G onto the samples and take its discrete Fourier coefficients, then rotate them by the surface’s canonical phase.

Defaults

max_mode = 8 is a numerical convenience; the surface is sampled at max(256, 8*max_mode) points, at least four per wavelength of the highest harmonic, so the kept modes do not alias.

Applicability

Machine-independent.

Limitations

The angle is geometric (arc length), not a straight-field-line angle; a PEST projection waits on the flux-coordinate framework (#472). The residual is a finite-difference quantity, so near a sharp boundary or on a coarse grid its harmonics carry discretization error of the grid scale.

Provenance

1. The projection of a force-balance residual onto poloidal harmonics follows the moment step of variational-moment equilibrium methods (VMOMS); here it is a diagnostic of an existing equilibrium (#948).

Processing steps

1. Take beta0, or obtain it from q0 by Eq. (6.12) (Part 2, Eq. 6.1).
2. Integrate psi_J, psi_J**2 and their (1 + nu G)/(1 + eps_hat x) and (1 + G)/(1 + eps_hat x) weighted forms over the plasma in (x, y), where the volume element is uniform.
3. Iterate the exterior field ratio Delta_B until the surface current carries the bootstrap fraction (Part 2, Eqs. 3.9 and 6.3).
4. Evaluate Eqs. (6.4)-(6.10) (Part 2, 6.4-6.11), and q95 as the line integral F/(2 pi) closed_integral dl/(R**2 B_p) on the psi = 0.05 surface.

Defaults

q0 = 1 is the paper’s choice for Table 4, a conventional value. resolution = 500 is a numerical convenience giving about three significant figures, the precision the paper publishes.

Applicability

Machine-independent.

Limitations

Integrals are on a Cartesian grid masked by the surface, so they carry an error of order the cell size. Part 2’s Table 2 is reproduced to 0.5 % in beta_p and 1.1 % in q_star. The surface-current jump uses Eq. (3.9), whose toroidal-field term carries R0**2/R**2; Eq. (6.2) prints it without, a 0.2 % difference in q*.

Provenance

1. Guazzotto and Freidberg (2021), Section 6, Eqs. (6.3)-(6.12).
2. Guazzotto and Freidberg (2021), Part 2, doi:10.1017/S0022377821000118, Eqs. (3.6)-(3.10) and Section 6, Eqs. (6.1)-(6.12).

Processing steps

1. Fix beta0 and from it p0 (6.3), dB/B0 (6.4) and the axis flux Psi_0 (6.5).
2. Evaluate psi on an R-Z grid through x = (R**2/R0**2 - 1 - eps**2)/(2 eps).
3. Build p = p0 (f_P + (1 - f_P) psi**2 + A1 (psi - psi**2)) and F**2 = R0**2 B0**2 (1 + 2 (dB/B0) psi**2 + 2 A2 (psi - psi**2)) (Part 2, Eqs. 4.1, 4.3, 4.5; A1 = A2 = 0 without pedestals), their flux derivatives, and I_p from Ampere’s law on J_phi.
4. Store in COCOS 11 and convert when another convention is asked for.

Defaults

q0 = 1 as in the paper’s Table 4, a conventional value; resolution = 129 is a numerical convenience.

Applicability

Machine-independent.

Limitations

q is not filled; compute it with calculate_q_profile_from_psi or take q95 from guazzotto_freidberg_parameters. The surface currents of Part 2 are not on the grid: ip is the core current I and bt0 the interior B0; I_hat/I and B_hat0/B0 are in metadata["parameters"].

Provenance

1. Guazzotto and Freidberg (2021), Eqs. (2.2), (2.8), (6.3)-(6.8); Part 2, Eqs. (4.1)-(4.6) and (6.5)-(6.6).