desc.objectives.EffectiveRipple

class desc.objectives.EffectiveRipple(eq, *, target=None, bounds=None, weight=1, normalize=True, normalize_target=True, loss_function=None, deriv_mode='auto', name='Effective ripple', grid=None, X=32, Y=32, Y_B=None, alpha=None, num_field_periods=20, num_well=None, num_quad=32, num_pitch=51, pitch_batch_size=None, surf_batch_size=1, nufft_eps=1e-06, spline=True, shard_input_data=False, **kwargs)Source

Proxy for neoclassical transport in the banana regime.

A 3D stellarator magnetic field admits ripple wells that lead to enhanced radial drift of trapped particles. In the banana regime, neoclassical (thermal) transport from ripple wells can become the dominant transport channel. The effective ripple (ε) proxy estimates the neoclassical transport coefficients in the banana regime. To ensure low neoclassical transport, a stellarator is typically optimized so that ε < 10⁻².

The objective is presented in [1], [2], and the computation is presented in [2].

References

Notes

Developer notes: Performance will improve significantly by resolving GitHub issues:

  • 1206 Upsample data above midplane to full grid assuming stellarator symmetry

  • 1034 Optimizers/objectives with auxiliary output

  • 2171 Single cotangent pullback through compute pipeline.

Parameters:

  • eq (Equilibrium) – Equilibrium to be optimized.

  • 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. Default grid samples the boundary surface at ρ=1.

  • X (int) – Poloidal Fourier grid resolution to interpolate the angle. Preferably rounded down to power of 2. Default is 32.

  • Y (int) – Toroidal Chebyshev grid resolution over a single field period to interpolate the angle. Preferably rounded down to power of 2. Default is 32.

  • 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 alpha, ). Starting field line poloidal labels. 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.

  • num_well (int) –

    Maximum number of wells to detect for each pitch and field line. Giving -1 will detect all wells but due to current limitations in JAX this will have worse performance. Specifying a number that tightly upper bounds the number of wells will increase performance. In general, an upper bound on the number of wells per toroidal transit is Aι+C where A, C are the poloidal and toroidal Fourier resolution of B, respectively, in straight-field line PEST coordinates, and ι is the rotational transform normalized by 2π. A tighter upper bound than num_well=(Aι+C)*num_transit is preferable. The check_points or plot methods in desc.integrals.Bounce2D are useful to select a reasonable value.

    This is the most important parameter to specify for performance.

  • num_quad (int) – Resolution for quadrature of bounce integrals. Default is 32.

  • num_pitch (int) – Resolution for quadrature over velocity coordinate.

  • pitch_batch_size (int) – Number of pitch values with which to compute simultaneously. If given None, then pitch_batch_size is num_pitch. Default is num_pitch.

  • surf_batch_size (int) – Number of flux surfaces with which to compute simultaneously. If given None, then surf_batch_size is grid.num_rho. Default is 1. Only consider increasing if pitch_batch_size is None.

  • shard_input_data (bool) – Whether to shard batched input data across devices before applying chunked batching. Default is False.

  • 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.

  • target ({float, ndarray}, optional) – Target value(s) of the objective. Only used if bounds is None. Must be broadcastable to Objective.dim_f. Defaults to target=0.

  • bounds (tuple of {float, ndarray}, optional) – Lower and upper bounds on the objective. Overrides target. Both bounds must be broadcastable to Objective.dim_f. Defaults to target=0.

  • weight ({float, ndarray}, optional) – Weighting to apply to the Objective, relative to other Objectives. Must be broadcastable to Objective.dim_f.

  • normalize (bool, optional) – Whether to compute the error in physical units or non-dimensionalize. Note: Has no effect for this objective.

  • normalize_target (bool, optional) – Whether target and bounds should be normalized before comparing to computed values. If normalize is True and the target is in physical units, this should also be set to True. Note: Has no effect for this objective.

  • loss_function ({None, 'mean', 'min', 'max','sum'}, optional) – Loss function to apply to the objective values once computed. This loss function is called on the raw compute value, before any shifting, scaling, or normalization.

  • deriv_mode ({"auto", "fwd", "rev"}) – Specify how to compute Jacobian matrix, either forward mode or reverse mode AD. auto selects forward or reverse mode based on the size of the input and output of the objective. Has no effect on self.grad or self.hess which always use reverse mode and forward over reverse mode respectively.

  • name (str, optional) – Name of the objective.

Methods

build([use_jit, verbose])

Build constant arrays.

compute(params[, constants])

Compute the effective ripple.

compute_scalar(*args, **kwargs)

Compute the scalar form of the objective.

compute_scaled(*args, **kwargs)

Compute and apply weighting and normalization.

compute_scaled_error(*args, **kwargs)

Compute and apply the target/bounds, weighting, and normalization.

compute_unscaled(*args, **kwargs)

Compute the raw value of the objective.

copy([deepcopy])

Return a (deep)copy of this object.

equiv(other)

Compare equivalence between DESC objects.

grad(*args, **kwargs)

Compute gradient vector of self.compute_scalar wrt x.

hess(*args, **kwargs)

Compute Hessian matrix of self.compute_scalar wrt x.

jac_scaled(*args, **kwargs)

Compute Jacobian matrix of self.compute_scaled wrt x.

jac_scaled_error(*args, **kwargs)

Compute Jacobian matrix of self.compute_scaled_error wrt x.

jac_unscaled(*args, **kwargs)

Compute Jacobian matrix of self.compute_unscaled wrt x.

jvp_scaled(v, x[, constants])

Compute Jacobian-vector product of self.compute_scaled.

jvp_scaled_error(v, x[, constants])

Compute Jacobian-vector product of self.compute_scaled_error.

jvp_unscaled(v, x[, constants])

Compute Jacobian-vector product of self.compute_unscaled.

load(load_from[, file_format])

Initialize from file.

print_value(args[, args0, fse, f0se])

Print the value of the objective and return a dict of values.

save(file_name[, file_format, file_mode])

Save the object.

xs(*things)

Return a tuple of args required by this objective from optimizable things.

Attributes

bounds

Lower and upper bounds of the objective.

built

Whether the transforms have been precomputed (or not).

constants

Constant parameters such as transforms and profiles.

dim_f

Number of objective equations.

fixed

Whether the objective fixes individual parameters (or linear combo).

linear

Whether the objective is a linear function (or nonlinear).

name

Name of objective (str).

normalization

normalizing scale factor.

scalar

Whether default "compute" method is a scalar or vector.

target

Target value(s) of the objective.

things

Optimizable things that this objective is tied to.

weight

Weighting to apply to the Objective, relative to other Objectives.