jax_sbgeom.distance module

Minimum distance between smooth objects: a coil and a flux surface (minimum_distance), or two coils (minimum_distance_between_curves).

Method: sample both objects coarsely, take the n_starts samples of the first object that are closest to the second, polish each by a Newton root-find on the gradient of 0.5 d^2 (optimistix) and return the smallest distance. Derivatives use optimistix’ implicit adjoint: exact (first and higher order) and nothing is differentiated through the sampling or the iterations (at first order: the envelope theorem).

Limits, stated plainly:

  • The sampling only has to put the wanted minimum in the basin of a start. If two minima are nearly equally deep the polished value can still come from the wrong one, by at most the sampling error (O(h^2 curvature)); refine n_curve / n_theta / n_phi or raise n_starts if that matters.

  • converged reports whether Newton converged for the returned minimum. If it is False the value is still an upper bound on the distance (any pair of points is at least as far apart as the minimum), but derivatives are not valid.

  • A continuum of minima (e.g. a ring coaxial with an axisymmetric surface) makes the Hessian singular; the result is NaN with converged=False.

  • The result is piecewise smooth; smoothing across several coils (a soft minimum) is the caller’s job.

  • Warm start: pass x0 (e.g. the previous result.x) to skip the sampling.

Curve parameters are in radians, t = 2 pi s with s in [0, 1) the coil parametrisation. The curve must be smooth (FourierCoil, a spline coil); a piecewise-linear DiscreteCoil is not suitable.

class MinimumDistance(distance: Array, x: Array, converged: Array)[source]

Bases: NamedTuple

distance: Array

Alias for field number 0

x: Array

Alias for field number 1

converged: Array

Alias for field number 2

minimum_distance(curve, surface, *, s: float = 1.0, n_curve: int = 256, n_theta: int = 60, n_phi: int = 100, n_starts: int = 2, x0: Optional[Array] = None, tol: float = 1e-10, max_steps: int = 12)[source]

Minimum distance between a coil and the flux surface at label s (full torus: theta, phi in [0, 2 pi)).

Parameters:

  • curve (Coil (smooth, e.g. FourierCoil))

  • surface (FluxSurface)

  • s (float)

  • n_curve (int)

  • n_theta (int)

  • n_phi (int)

  • n_starts (int)

  • x0 (Optional[Array])

  • tol (float)

  • max_steps (int)

Return type:

MinimumDistance

minimum_distance_between_curves(curve_a, curve_b, *, n_curve: int = 256, n_starts: int = 2, x0: Optional[Array] = None, tol: float = 1e-10, max_steps: int = 12)[source]

Minimum distance between two different closed curves; x = (t_a, t_b) [rad]. Arguments as for minimum_distance. Do not pass a curve with itself (the minimum is the trivial zero).

Return type:

MinimumDistance