desc.integrals.Bounce2D

class desc.integrals.Bounce2D(grid, data, angle, Y_B=None, alpha=None, num_field_periods=20, quad=None, *, automorphism=None, nufft_eps=1e-06, spline=True, check=False, vander=None, **kwargs)Source

Computes bounce integrals using pseudo-spectral methods.

The bounce integral is defined as ∫ f(ρ,α,λ,ℓ) dℓ where

• dℓ parametrizes the distance along the field line in meters.

• f(ρ,α,λ,ℓ) is the quantity to integrate along the field line.

• The boundaries of the integral are bounce points ℓ₁, ℓ₂ s.t. λB(ρ,α,ℓᵢ) = 1.

• λ is a constant defining the integral proportional to the magnetic moment over energy.

• B is the norm of the magnetic field.

For a particle with fixed λ, bounce points are defined to be the location on the field line such that the particle’s velocity parallel to the magnetic field is zero. The bounce integral is defined up to a sign. We choose the sign that corresponds to the particle’s guiding center trajectory traveling in the direction of increasing field-line-following coordinate ζ.

The computation is breifly presented in [1].

References

[1]

K. Unalmis et al., “Spectrally accurate, reverse-mode differentiable bounce-averaging algorithm and its applications,” J. Plasma Physics. 2026;92(3):E72. https://arxiv.org/pdf/2412.01724.

Examples

• desc/compute/_fast_ion.py

• desc/compute/_neoclassical.py

• desc/compute/_turbulence.py

• tests/test_integrals.py::TestBounce2D::test_bounce2d_checks

See also

Bounce1D

Some comments comparing Bounce1D to Bounce2D are given below. Bounce1D uses lower order accurate, one-dimensional splines. Bounce2D is superior for optimization objectives in DESC as it solves the moving grid interpolation problem, avoids recomputing 3D Fourier-Zernike series on a time-dependent grid, and is able to compute the derivative matrix relevant to optimization with a compact sparse pullback.

Parameters:

• grid (Grid) – Tensor-product grid in (ρ, θ, ζ) with uniformly spaced nodes (θ, ζ) ∈ [0, 2π) × [0, 2π/NFP). Number of poloidal and toroidal nodes preferably rounded down to powers of two. Determines the flux surfaces to compute on and resolution of FFTs.

• data (dict[str, jnp.ndarray]) – Data evaluated on grid. Must include names in Bounce2D.required_names. If the input is not a real-valued array, then it is assumed that the Fourier transform as returned by Bounce2D.fourier was given instead.

• angle (jnp.ndarray) – Shape (num ρ, X, Y). Angle returned by Bounce2D.angle.

• Y_B (int) –

  Desired resolution for algorithm to compute bounce points. A reference value is (grid.num_theta+grid.num_zeta)//2.

  If the option spline is True, the bounce points are found with 𝒪(Y_B⁻¹²) error. In this case, the final error will be of order 𝒪(Y_B⁻¹⁸) in bounce integrals with (v_∥)¹ and 𝒪(Y_B⁻⁶) in bounce integrals with (v_∥)⁻¹.

  If the option spline is False, the bounce points are found such that the bounce integrals have exponential accuracy in this parameter.

• alpha (jnp.ndarray) – Shape (num α, ). Starting field line poloidal labels. Default is single field line. On irrational magnetic surfaces, it is sufficient to integrate along a single field line. On a rational or near-rational surface in non-axisymmetric configurations, it is necessary to integrate along multiple field lines until the surface is covered sufficiently.

• num_field_periods (int) – Number of field periods to follow field line. In axisymmetric configurations, integration along the field line for a single poloidal transit between two global maxima of B is sufficient for convergence. For a 3D configuration, the magnetic surface should be covered sufficiently.

• quad (tuple[jnp.ndarray]) – Quadrature points xₖ and weights wₖ for the approximation of an integral ∫₋₁¹ g(x) dx = ∑ₖ wₖ g(xₖ). Default is 32 points.

• automorphism (tuple[Callable] or None) – The first callable should be an automorphism of the real interval [-1, 1]. The second callable should be the derivative of the first. This map defines a change of variable for the bounce integral. The choice made for the automorphism will affect the performance of the quadrature.

• nufft_eps (float) – Precision requested for interpolation with non-uniform fast Fourier transform (NUFFT). If less than 1e-14 then NUFFT will not be used.

• spline (bool) – Whether to use cubic splines to compute initial guess for bounce points instead of Chebyshev series. Default is True. It can be preferable to set to False on equilibria with high NFP, (such cases make smaller Y_B feasible), or on GPUs where eigenvalue solves are fast.

• check (bool) – Flag for debugging. Must be false for JAX transformations.

Methods

angle(eq[, X, Y, rho, iota, params, ...])	Return the angle for mapping boundary coordinates to field line coordinates.
batch(fun, data, grid, *, angle[, names, ...])	Compute function fun batched over flux surfaces.
check_points(points, pitch_inv, *[, plot])	Check that bounce points are computed correctly.
compute_fieldline_length([quad])	Compute the (mean) proper length of the field line ∫ dℓ / B.
compute_theta(eq[, X, Y, rho, iota, params, ...])	Method has been deprecated in favor of Bounce2D.angle.
fourier(f)	Transform to DESC spectral domain.
integrate(integrand, pitch_inv[, data, ...])	Bounce integrate ∫ f(ρ,α,λ,ℓ) dℓ.
interp_to_argmin(f, points, *[, nufft_eps])	Interpolate f to the deepest point in magnetic well w.
pitch_quad(min_B, max_B, num_pitch, **kwargs)	Return 1/λ values and weights for quadrature between min_B and max_B.
plot(l, m[, pitch_inv])	Plot B and bounce points on the specified field line.
plot_angle_spectrum(angle, l, *[, norm, ...])	Plot frequency spectrum of the given inverse stream map.
plot_theta(l, m, **kwargs)	Plot θ on the specified field line.
points(pitch_inv[, num_well])	Compute bounce points.
reshape(grid, f)	Reshape arrays for acceptable input to integrate.

Attributes

required_names

Required keys in the data dictionary given to the __init__ method.