v0.17.2

New Features

• Adds desc.objectives.DeflationOperator, a new objective class which can be used to apply deflation techniques to equilibrium and optimization problems to find multiple local minima or multiple solutions from a single initial point, either by wrapping an existing desc.objectives._Objective object or by including as an additional penalty or constraint. Also adds a tutorial showing this functionality.
• Sub-objectives of an ObjectiveFunction can now have different use_jit values than the ObjectiveFunction. These objectives have to be built before building the ObjectiveFunction.
• Adds num_neighbors parameter to CoilSetMinDistance that limits the pairwise distance computation to the nearest neighbors per coil, reducing memory useage for large coilsets.
• Method to plot frequency spectrum of inverse stream map in field line coordinates Bounce2D.plot_angle_spectrum.
• Method to compute bounce integrals in batches is now added to the public API Bounce2D.batch.
• Initiated deprecation of Bounce2D.compute_fieldline_length in favor of eq.compute("V_psi").
• The quadrature resolution in Bounce2D.compute_fieldline_length now corresponds to the resolution over a single field period instead of the resolution over a toroidal transit.
• Adds an optional attribute ion_density to the Equilibrium class, to allow the ion density profile to be set independently of the electron density and effective atomic number. Also adds compute functions for "ni_rr" and "Zeff_rr".
• Modernizes dependencies to use nvidia-ml-py in place of nvgpu.

Important

If you are updating an existing software environment uninstall pynvml first and then reinstall the dependencies to correctly get nvidia-ml-py.

Bug Fixes

• Fixes SyntaxError thrown when loading hdf5 data from file-like objects.
• Fixes a bug in OmnigenousField.change_resolution when changing L_B.
• Scaling a ScaledProfile or taking power of a PowerProfile now only updates the scale/power attributes instead of nesting the ScaledProfile/PowerProfiles.
• jax.Arrays in _static_attrs will be automatically converted to np.ndarray to prevent stalling code. In general, jax arrays should be omitted in _static_attrs.
• Fixes a bug in desc.magnetic_fields.fieldline_integrate when calling with an integer bs_chunk_size.

Performance Improvements

• Reduces import time of desc modules.
  • Now, desc.compute._build_data_index uses depth-first search algorithm to construct the dependency tree.
  • Some of the default value computations at import time are removed (i.e. desc.integrals.bounce_integral.default_quad)
• Significantly improves convergence of inverse stream maps (#1919).
• Check-pointing to bounce integrals to improve speed and reduce memory of reverse mode differentiation.
• Resolves a JAX memory regression in bounce integrals by avoiding materialization of a large tensor in memory. Previously, we had closed the issue by adding nuffts as a workaround. This update actually solves the issue for the case when a user specifies to not use nuffts as well.
• ObjectiveFunction.print_value can now use the previously computed compute_scaled_error values to print. For bounded objectives, we fall back to computing compute_unscaled. Additionally, compute_scaled_error and array splitting are used in other parts of the code to prevent recompilation for one-time tasks, which makes initialization faster.

Deprecations

• constants argument of compute, jvp, jac, grad and hess methods (including all of their variants) to all objective classes (including ObjectiveFunction and wrappers) is deprecated and will be removed in a future release. This argument was not necessary, and the code will still work if user doesn't pass it. Users should update their custom objectives for this change. In addition, constants property of the ObjectiveFunction and all sub-classes of _Objective is deprecated.

New Contributors

• @andycthea made their first contribution in #2123
• @TElder-thea made their first contribution in #2140
• @matthewfeickert made their first contribution in #2163

Full Changelog: v0.17.1...v0.17.2

v0.17.1

This patch release updates package dependencies to resolve critical incompatibilities between jax-related libraries. DESC versions 0.16.0 and 0.17.0 contain a known bug when used alongside jax-finufft v1.3.0, and we recommend that users upgrade to DESC version 0.17.1 to ensure environment stability.

If an immediate upgrade is not feasible, the issue can be mitigated by manually downgrading jax-finufft to version 1.2.0.

Minor Changes

• Fixes incorrect units in the documentation of some curvature variables.

Full Changelog: v0.17.0...v0.17.1

v0.17.0

New Features

• Adds particle tracing capabilities in desc.particles module.
  • Particle tracing is done via desc.particles.trace_particles function.
  • Particles can be initialized in couple different ways:
    • ManualParticleInitializerLab : Initializes particles at given positions in lab coordinates.
    • ManualParticleInitializerFlux : Initializes particles at given positions in flux coordinates.
    • CurveParticleInitializer : Initializes N particles on a given curve.
    • SurfaceParticleInitializer : Initializes N particles on a given surface.
  • Implemented particle trajectory models are:
    • VacuumGuidingCenterTrajectory : Integrates the particle motion by vacuum guiding center ODEs, conserving energy and mu.
  • Particle trajectories can be plotted with desc.plotting.plot_particle_trajectories function.
• Adds new option for loss_function, "sum", which changes an objective to target the sum of the values computed.
• Adds utility functions desc.external.paraview.export_surface_to_paraview, desc.external.paraview.export_volume_to_paraview and desc.external.paraview.export_coils_to_paraview to export Paraview files for surfaces, volume and coils. These functions use an optional dependency pyvista which is not automatically installed.
• The x_scale option for eq.optimize and related functions can now be given as a dictionary mapping individual parameter names to their relevant scales,
  or if multiple things are being optimized, x_scale can be a list of dict, one for each optimizable thing.
• Adds new option x_scale='ess' to use exponential spectral scaling from (Jang 2025) which has been shown to improve performance and robustness as an alternative to fourier continuation methods.
• Adds x_scale='ess' option for the OmigenousField class.
• Adds "scipy-l-bfgs-b" optimizer option as a wrapper to scipy's "l-bfgs-b" method.
• The x_scale parameter can now be used with stochastic gradient descent type optimizers.
• Adds wrappers for optax optimizers. They can be used by prepending 'optax-' to the name of the optimizer (i.e. optax-adam). Additional arguments to the optimizer such as learning_rate can be pass via options = {'optax-options': {'learning_rate': 0.01}}. Even a custom optax optimizer can be used by specifying the method as 'optax-custom' and passing the optax optimizer via the 'update-rule' key of optax-options in the options dictionary. See the docstring of the optax-custom for details.
• Adds check_intersection flag to desc.magnetic_fields.FourierCurrentPotentialField.to_Coilset, to allow the choice of checking the resulting coilset for intersections or not.
• Changes the import paths for desc.external to require reference to the sub-modules.
• Adds a differentiable utility for finding constant offset toroidal surfaces inside of optimizations. See PR for more details.
• Add support for Python 3.14
• Adds support for optimization targeting individual coils in a coilset.
  • Coil objectives accept pytree inputs for target, bounds, and weight.
  • Able to set weights to zero, excluding certain coils from the objective.

Bug Fixes

• No longer uses the full Hessian to compute the scale when x_scale="auto" and using a scipy optimizer that approximates the hessian (e.g. if using "scipy-bfgs", no longer attempts the Hessian computation to get the x_scale).
• SplineMagneticField.from_field() correctly uses the NFP input when given. Also adds this as a similar input option to MagneticField.save_mgrid().
• Fixes some bugs that hampered robustness of desc.geometry.FourierRZToroidalSurface.constant_offset_surface, particularly when the given grid had stellarator symmetry or when NFP=1.
• Fixes possible bug in computing normalizations when both kinetic and pressure profiles are assigned. Also adds warnings whenever an pressure is added to a kinetic-constrained equilibrium and vice-versa to alert user to ambiguous equilibrium setups.
• Adds error in MercierStability to guard against situation where if a grid with a point at rho=0 were used, NaN would be computed, asMercierStability is undefined on-axis.

Performance Improvements

• ProximalProjection.grad uses a single VJP on the objective instead of multiple JVP followed by a manual VJP. This should be more efficient for expensive objectives.

Deprecations

• sgd optimizer is deprecated in favor of optax-sgd, and will be removed in a future release. To achieve the same behavior with optimizer = Optimizer('sgd') and options={'alpha': ..., 'beta': ...} when the optimizer is removed, one can use optimizer = Optimizer('optax-sgd') and options={'optax-options': {'learning_rate': alpha, 'momentum': beta, 'nesterov': True}}.
• Removes FiniteDiffDerivative from the public API. This class was no longer actually usable with the current versions of DESC's optimization framework, as JAX is now required for running any equilibrium or optimization solves.

New Contributors

• @byoungj made their first contribution in #1736

Full Changelog: v0.16.0...v0.17.0

v0.16.0

New Features

• New basis vector and metric elements derivatives in PEST coordinates and quantities useful for a global MHD stability solver.
• Adds desc.external.TERPSICHORE objective for computing linear ideal MHD stability growth rates. This objective subclasses from ExternalObjective and requires access to the TERPSICHORE code, which is not included with DESC or its dependencies.
• Adds docs/dev_guids/external_objectives.rst as a tutorial for how to use external objectives, with TERPSICHORE as an example using parallel processing.
• Adds keyword argument normalize to plot_1d, plot_3d. normalize is a string to use for normalization.
• Adds new linear objective ShareParameters which can enforce that the chosen parameters of two or more objects of the same type remain identical during an optimization. Potentially useful for flexible stellarator optimization, where one has two coilsets with the same geometry but differing currents, and attempts to optimize for two different stellarator equilibria.
• Changes related to field_line_integrate, see #1839:
  • field_line_integrate now returns diffrax.diffeqsolve.stats and diffrax.diffeqsolve.result if the flag return_aux is set to True.
  • Renames maxsteps argument of field_line_integrate to max_steps. Now the argument has a consistent meaning with the diffrax package and specifies the maximum number of steps allowed for whole integration. Previously, it was used as maximum number of iterations between integration steps.
  • field_line_integrate function doesn't accept additional keyword-arguments related to diffrax, if it is necessary, they must be given through options dictionary.
  • poincare_plot and plot_field_lines functions can now plot partial results if the integration failed. Previously, user had to pass throw=False or change the integration parameters. Users can ignore the warnings that are caused by hitting the bounds (i.e. Terminating differential equation solve because an event occurred.).
  • chunk_size argument is now used for chunking the number of field lines. For the chunking of Biot-Savart integration for the magnetic field, users can use bs_chunk_size instead.

Bug Fixes

• Fixes straight field line equilibrium conversion, see #1880
• desc.compat.rescale will now return ScaledProfile instances for most of its profiles, to fix a bug where improper scaling could occur for certain profile types.
• Now always use sym=False in the default grid for plot_fsa to ensure correct averages
• Fixes bug that could lead extra compilation of jit-compiled functions that include field_line_integrate.
• Fixes inaccurate normalizations scales that could be computed for certain equilibria which had m=1 n=0 R and m=-1 n=0 Z components much smaller than their actual average minor radius, see #1954
• Fix bug in PlasmaCoilSetMinDistance that occured using a FourierRZToroidalSurface object without passing in an the evaluation grid, see #2013
• Equilibrium profile assignments are now guaranteed to be consistent with the equilibrium resolution—automatically increasing lower-resolution profiles to match the equilibrium (while keeping higher-resolution profiles untouched)—meaning users who relied on lower-resolution profiles to implicitly restrict optimization must now explicitly use the FixParameters constraint.
• Allow desc.vmec.VMECIO.load to load wout files that lack lrfp__logical__, like those outputted by VMEC++. This change assumes that those output files don't have poloidal flux label.
• Fixes a bug that had prevented passing the legend kwarg to desc.plotting.plot_surfaces.

Backend

• When using any of the "proximal-" optimization methods, the equilbrium is now always solved before beginning optimization to the specified tolerance (as determined, for example, by options={"solve_options":{"ftol"...}} passed to the desc.optimize.Optimizer.optimize call). This ensures the assumptions of the proximal projection method are enforced starting from the first step of the optimization.
• desc.continuation.solve_continuation_automatic now falls back to performing shape perturbations first and then pressure if the default pressure-then-shaping path fails, increasing robustness in arriving at the final equilibrium. To go directly to the path of applying shaping then pressure, pass the flag shaping_first=True.
• desc.equilibrium.Equilibrium.set_initial_guess now sets lambda to zero for most use cases, and the docstring has been updated to be more explicit on what is done in each case.
• Minimum JAX version bumped up to 0.5.0

Performance Improvements

• Coordinate mapping uses partial summation, see #1826
• Non-uniform FFTs (NUFFTS) are now used by default for computing bounce integrals, see #1834. NUFFT functionality is added through jax-finufft package. If the GPU installation fails, users can fall back to the older (much slower) implementation by setting nufft_eps=0 in the computation of the related quantities.

New Contributors

• @singh-jaydeep made their first contribution in #1905

Full Changelog: v0.15.0...v0.16.0

v0.15.0

New Features

• Adds new desc.geometry.FourierXYCurve and desc.coils.FourierXYCoil classes, which are a form of planar curve and coil class which describe the curve in terms of cartesian x and y in the plane (as opposed to using polar radius like FourierPlanarCurve and FourierPlanarCoil), which can make describing certain shapes (such as ellipses) easier. See #1504 for more information.
• Adds desc.objectives.PlasmaCoilSetMaxDistance objective, which allows setting a maximum distance the coils are allowed to be from the equilibrium, useful, for example, when trying to balance the need for space for a blanket while also ensuring the cryostat is not too large. See #1722
• Add meshgrid_flatten utility for flattening 3d data to a 1d array in the correct order, essentially the opposite of meshgrid_reshape.
• Adds ability to get top k eigenfunctions the corresponding eigenvalues from the ideal ballooning solver.
• Adds desc.plotting.plot_field_lines function which can take in an input desc.magnetic_fields.MagneticField object and plot a field line trajectory starting from some initial point in cylindrical coordinates.
• Addsgamma_c compute quantity which is the integrand of Gamma_c. User can also plot gamma_c using the desc.plotting.plot_gammac function. (Note this function uses more memory than expected due to a performance regression in an upstream library. This is resolved in the next release).

Performance Improvements

• Use integration on the boundary (as opposed to volume integration) for more quantities where this is applicable (through use of Stoke's theorem), see #1094
• Minor memory improvements from a slight refactoring of desc.equilibrium.Equilibrium.from_near_axis method
• Improve performance of desc.magnetic_fields.field_line_integrate for fields with large stored attributes (such as desc.magnetic_fields.SplineMagneticField (#1830)
• Performance improvements for desc.objectives.BallooningStability objective (#1763, #1826)
• Performance improvements for objectives which rely on coordinate mapping #1826

Minor Changes

• Adds source_grid kwarg to from_field for SplineMagneticField , to allow for specifying the grid used to discretize the magnetic field the splined field is being created from.
• Change default constraints for eq.optimize to just be ForceBalance, so now no other constraints are included by default, see #1725
• Allows safenormalize to work on multiple vectors.
• Updates to docs
  • Notes on role of eq.Psi in vacuum free boundary in free boundary tutorial and coil optimization tutorial
  • Updates Adding new objective functions tutorial
  • Adds example uses of GenericObjective and ObjectiveFromUser to advanced optimization tutorial
  • updates installation docs for della and adds new uv install method

Bug Fixes

• ensures surfaces only compute things that make sense for their parametrizations, see #1724
• fixes bugs in VMEC I/O
  • bug in desc.vmec.write_vmec_input for spline profiles (see #1740)
  • fixes error when reading VMEC input files with PMASS_TYPE defined which could result in converted DESC input files lacking a pressure profile
• Ensures the stochastic optimizer sgd prints an iteration even if the first step satisfies the termination criterion
• Fix nan in reverse mode gradient caused by rotation_matrix
• Fix some outstanding bugs with desc.io.write_ascii function
• Fixes bug in desc.geometry.FourierRZCurve from_values when a numpy array. See #1828
• Ensures user supplied linear constraint x_scale passed to desc.optimize.Optimizer.optimize is not overwritten by the default dynamically updated x_scale

Deprecations

• desc.io.write_ascii method for equilibrium I/O is deprecated and not recommended for use. Users are recommended instead to use the hdf5 files as the primary method of I/O with DESC objects.
• Deprecates norm_F and norm_name kwargs from desc.plotting functions (plot_fsa, plot_section, plot_2d) in favor of the new compute quantity |F|_normalized, which is the magnitude of the force error normalized by the volume-averaged magnetic pressure gradient.
• renames linecolor to color in the desc.plotting module functions

Breaking Changes

• Significant changes to how DESC handles static attributes during JIT compilation. Going forward if any class/object has attributes that should be treated as static by jax.jit, these should be declared at the class level like _static_attrs = ["foo", "bar"]. Generally, non-arraylike attributes such as functions, strings etc should be marked static, as well as any attributes used for control flow. Previously this was done automatically, but in a way that caused a lot of performance bugs and unnecessary recompilation. These changes have been implemented for all classes in the desc repository, but if you have custom objectives or other local objects that subclass from desc you may need to add this yourself. JAX error messages usually do a good job of alerting you to things that need to be static, and feel free to open an issue with desc if you have any questions.

New Contributors

• @gretahibbard made their first contribution in #1529

Full Changelog: v0.14.2...v0.15.0

v0.14.2

New Features

• Updates Equilibrium initial guess to use geometric center as the axis. This will allow non-convex cross-sections to be initialized without having to solve to achieve nested surfaces.
• Adds new regularization options to desc.objectives.SurfaceCurrentRegularization.
• Adds a new utility function desc.compat.contract_equilibrium which takes in an Equilibrium object and an argument inner_rho, and returns a new Equilibrium with original Equilibrium's inner_rho flux surface as its boundary.
  Optionally can also contract the profiles of the original Equilibrium so that the new Equilibrium's profiles match the original's in real space.
• Adds second-order NAE constraints, accessible by passing order=2 to desc.objectives.get_NAE_constraints.
• result dictionary returned by Optimizer.optimize or eq.optimize now includes sub-dictionary "Objective values" containing summary info of objective values before and after optimization, the same info that is printed to the terminal by default.
• Adds error for incorrect grids in desc.objectives.BootstrapRedlConsistency and when computing current Redl and <J*B> Redl compute quantities
• Allows Redl compute quantities to use SplineProfile and updates Redl bootstrap current consistency tutorial to include a SplineProfile optimization
• Adds automatically generated header file showing date the input file was created with desc.vmec.VMECIO.write_vmec_input
• Adds source_grid argument to desc.magnetic_fields._MagneticField.save_mgrid function to allow user to control the discretization of the magnetic field object being used to construct the mgrid output.
• Allows x_scale to be passed to factorize_linear_constraints in Optimizer.optimize through the new "linear_constraint_options".

Performance Improvements

• ProximalProjection uses jvp's for the derivative of the ForceBalance part instead of manually taking the matrix products. This reduces the jacobian time on CPU.
• Improves memory management to reduce the base memory used during optimization while using lsq-exact, lsq-auglag and fmin-auglag optimizers as well as their proximal- versions.

Bug Fixes

• Fixes issue in desc.geometry.curve.FourierPlanarCurve.from_values where the orientation of the fitted curve can be the reverse of the original curve, which can be problematic for coils (the current is not negated, so the resulting fitted coil would have field opposite of the initial).
• Fixes bug where ObjectiveFunction was incorrectly using deriv_mode="batched" and the heuristic-set jac_chunk_size when jac_chunk_size is given to a sub-objective, where it should have instead defaulted to deriv_mode="blocked". See #1687
• Fixes bug where ProximalProjection was using wrong jac_chunk_size internally and using more memory than one would expect given the jac_chunk_size. This fix gives separate blocked and batched methods to ProximalProjection.

New Contributors

• @cfe316 made their first contribution in #1674
• @ryanwu4 made their first contribution in #1708

Full Changelog: v0.14.1...v0.14.2

v0.14.1

What's Changed

• Fixes bug in desc.vmec.VMECIO.write_vmec_input for current-constrained equilibria, where DESC was incorrectly writing the $s^0$ mode, where VMEC actually assumes it is zero and starts at the $s^1$ (which is different than the usual convention VMEC uses for its current profile when it uses the current derivative, where it starts with the $s^0$ mode).

Full Changelog: v0.14.0...v0.14.1

v0.14.0

What's Changed

• Updates default parameters for partition support size in the singular surface integrals.
• Enables tracking multiple field lines in Bounce2D.
• Adds desc.objectives.LinkingCurrentConsistency for ensuring that coils in a stage 2 or single stage optimization provide the required linking current for a given equilibrium.
• desc.objectives.Omnigenity is now vectorized and able to optimize multiple surfaces at the same time. Previously it was required to use a different objective for each surface.
• Adds a new objective desc.objectives.MirrorRatio for targeting a particular mirror ratio on each flux surface, for either an Equilibrium or OmnigenousField.
• Adds the output quantities wb and wp to VMECIO.save.
• Changes implementation of Dommaschk potentials to use recursive algorithm and symbolic integration, improving agreement of numerical results with the literature.
• eq.solve and eq.perturb now accept LinearConstraintProjection as objective. This option must be used without any constraints.
• Allows non-proximal optimizers to handle optimizing more than one Equilibrium object simultaneously.
• Renames compute quantity sqrt(g)_B to sqrt(g)_Boozer_DESC to more accurately reflect what the quantiy is (the jacobian from (rho,theta_B,zeta_B) to (rho,theta,zeta)), and adds a new function to compute sqrt(g)_Boozer which is the jacobian from (rho,theta_B,zeta_B) to (R,phi,Z).
• DESC/JAX version and device info is no longer printed by default, but can be accessed with the function desc.backend.print_backend_info().

New Features

• Adds Bounce integral methods with desc.integrals.Bounce2D.

• Adds Effective ripple desc.objectives.EffectiveRipple and Gamma_c desc.objectives.Gamma_c optimization objectives.

• Adds new compute quantities for partial derivatives in different coordinate systems.

• Adds a new profile class PowerProfile for raising profiles to a power.

• Adds an option scaled_termination (defaults to True) to all the desc optimizers to measure the norms for xtol and gtol in the scaled norm provided by x_scale (which defaults to using an adaptive scaling based on the Jacobian or Hessian). This should make things more robust when optimizing parameters with widely different magnitudes. The old behavior can be recovered by passing options={"scaled_termination": False}.

• Adds a new objective desc.objectives.CoilIntegratedCurvature for targeting convex coils.

• Adds the example "reactor_QA", which is similar to "precise_QA" but with self-consistent bootstrap current at finite beta.

• desc.objectives.CoilSetMinDistance and desc.objectives.PlasmaCoilSetMinDistance now include the option to use a softmin which can give smoother gradients.

• Adds a new function desc.coils.initialize_helical_coils for creating an initial guess for stage 2 helical coil optimization.

• Adds desc.vmec_utils.make_boozmn_output for writing boozmn.nc style output files
  for compatibility with other codes which expect such files from the Booz_Xform code.

• Adds a new objective desc.objectives.ExternalObjective for wrapping external codes with finite differences.

• Allows specification of Nyquist spectrum maximum modenumbers when using VMECIO.save to save a DESC .h5 file as a VMEC-format wout file

• Adds an option to VMECIO.save to specify the grid resolution in real space.

• Performance Improvements

• A number of minor improvements to basis function evaluation and spectral transforms to improve speed. These will also enable future improvements for larger gains.

• proximal- optimizers use a single LinearConstraintProjection and this makes the optimization faster for high resolution cases where taking the SVD (for null-space and inverse) of constraint matrix takes significant time.

• Chunking/batching can now be used in more places. Note that this might change the default behavior and you might get OOM (out of memory) errors.

  • Adds batching feature to parallelize singular integrals used in free boundary solves.
  • Adds chunk_size option to compute magnetic field methods to increase performance. Users may need to update their scripts to pass in bs_chunk_size=20 or some other reasonable number if out of memory occurs as the default attempts to perform the entire computation at once.
  • desc.objectives.CoilSetMinDistance and desc.objectives.PlasmaCoilSetMinDistance now have a dist_chunk_size option to break up the distance calculation into smaller pieces to save memory.
  • Changes hessian computation to use chunked jacfwd and jacrev, allowing jac_chunk_size to now reduce hessian memory usage as well.

Bug Fixes

• Small bug fix to use the correct normalization length a in the BallooningStability objective.
• Fixes I/O bug when saving/loading _Profile classes that do not have a _params attribute.
• Minor bugs described in #1323.
• Corrects basis vector computations made on surface objects #1175.
• Allows keyword arguments to be passed to GenericObjective and ObjectiveFromUser.
• Fixes bug where save_in_makegrid_format function did not correctly account for CoilSet objects with NFP>1 or sym=True attributes, and so would not save all the coils.
• Fixes issue with interpolator for singular integrals #1522 and additional checks 1519.
• Fixes the coil currents in desc.coils.initialize_modular_coils to now give the correct expected linking current.
• desc.objectives.PlasmaVesselDistance now correctly accounts for multiple field periods on both the equilibrium and the vessel surface. Previously it only considered distances within a single field period.
• Sets os.environ["JAX_PLATFORMS"] = "cpu" instead of os.environ["JAX_PLATFORM_NAME"] = "cpu" when doing set_device("cpu").
• Fixes bug in desc.input_reader.desc_output_to_input utility function for asymmetric equilibria profiles, where the full profile resolution was not being saved.
• Fixes bug when passing only sym into .change_resolution for FourierRZToroidalSurface, ZernikeRZToroidalSection and FourierRZCurve.
• Fixes bug that was setting ObjectiveFunction._things_per_objective_idx incorrectly. Now each _Objective can define a unique order that it expects to use parameters for multiple "things".
• Fixes bug that occurs when an NAE solution used with NAE constraints is asymmetric, but has a symmetric axis.
• Fixes bug in FourierCurrentPotentialField.change_Phi_resolution where N_Phi would be changed to M_Phi if N is not explicitly passed into the method.
• Fixes bug when setting current for a MixedCoilSet with an arbitrary tree structure.
• Corrects Cholesky factorized least-squares solve for wide matrices used in root finding.
• Fixes bug in the formula for computing "P_fusion".

Breaking Changes

• Adds support for Python 3.13 and removes support for 3.9 since new JAX versions require minimum Python 3.10.

Full Changelog: v0.13.0...v0.14.0

v0.13.0

New Features

• Adds function solve_regularized_surface_current to desc.magnetic_fields module that implements the REGCOIL algorithm (Landreman, (2017)) for surface current normal field optimization, which can run on both CPUs and GPUs.
  • Can specify the tuple current_helicity=(M_coil, N_coil) to determine if resulting contours correspond to helical topology (both (M_coil, N_coil) not equal to 0), modular (N_coil equal to 0 and M_coil nonzero) or windowpane/saddle (M_coil and N_coil both zero)
  • M_coil is the number of poloidal transits a coil makes before returning to itself, while N_coil is the number of toroidal transits a coil makes before returning to itself (this is sort of like the QS helicity)
  • if multiple values of the regularization parameter are input, will return a family of surface current fields (as a list) corresponding to the solution at each regularization value
• Adds method to_CoilSet to FourierCurrentPotentialField which implements a coil cutting algorithm to discretize the surface current into coils
  • works for both modular and helical coils
• Adds a new objective SurfaceCurrentRegularization (which minimizes w*|K|, the regularization term from surface current in the REGCOIL algorithm, with w being the objective weight which act as the regularization parameter)
  • use of both this and the QuadraticFlux objective allows for REGCOIL solutions to be obtained through the optimization framework, and combined with other objectives as well.
• Adds a new tutorial showing how to useREGCOIL features, as well as a new section in the stage two optimization notebook using REGCOIL to obtain an initial guess for filamentary coil optimization.
• Adds from_input_file method to Equilibrium class to generate an Equilibrium object with boundary, profiles, resolution and flux specified in a given DESC or VMEC input file
• Adds SurfaceQuadraticFlux objective which minimizes the quadratic magnetic flux through a FourierRZToroidalSurface object, allowing for optimizing for Quadratic flux minimizing (QFM) surfaces.
• Allows ToroidalFlux objective to accept FourierRZToroidalSurface so it can be used to specify the toroidal flux through a QFM surface.
• Adds eq_fixed flag to ToroidalFlux to allow for the equilibrium/QFM surface to vary during optimization, useful for single-stage optimizations.
• Adds tutorial notebook showcasing QFM surface capability.
• Adds rotate_zeta function to desc.compat to rotate an Equilibrium around Z axis.

Minor Changes

• Changes local area weighting of Bn in QuadraticFlux objective to be the square root of the local area element (Note that any existing optimizations using this objective may need different weights to achieve the same result now.)
• Adds an NFP attribute to ScalarPotentialField, VectorPotentialField and DommaschkPotentialField, to allow SplineMagneticField.from_field and MagneticField.save_mgrid to efficiently take advantage of the discrete toroidal symmetry of these fields, if present.
• Adds support for numpy version 2.0.0
• Various improvements to optimization algorithms for improving performance of equilibrium solving and optimization, especially on GPUs.

Bug Fixes

• Fixes bug that occurs when taking the gradient of root and root_scalar with newer versions of JAX (>=0.4.34) and unpins the JAX version.
• Changes FixLambdaGauge constraint to now enforce zero flux surface average for lambda, instead of enforcing lambda(rho,0,0)=0 as it was incorrectly doing before.
• Fixes bug in softmin/softmax implementation.
• Fixes bug that occurred when using ProximalProjection with a scalar optimization algorithm.
• Fixes bug where from desc.plotting import * would not import desc.plotting.poincare_plot

Full Changelog: v0.12.3...v0.13.0

v0.12.3

What's Changed

• Add jac_chunk_size keyword argument to ObjectiveFunction to reduce memory usage of forward mode Jacobian calculation , see docs for more details
• Add objective using for Ideal-Ballooning Stability, see related paper for more details.
• Make naming of grids kwargs among free boundary objectives more uniform
• Add kwarg options to plot 3d without any axis visible
• Pin jax version temporarily to avoid JAX-related bug

Bug Fixes

• Fix error that can occur when get_NAE_constraints is called for only fixing the axis
• bug fix for most_rational with negative arguments
• fix bug. in FixOmniBMax

New Contributors

• @lisamessier made their first contribution in #1269
• @missing-user made their first contribution in #1274
• @felicia22 made their first contribution in #1284

Full Changelog: v0.12.2...v0.12.3