From 6f01d37b97369e58835b0841bc2147e4595456bf Mon Sep 17 00:00:00 2001 From: Rogerio Jorge Date: Tue, 10 Nov 2026 12:32:15 -0600 Subject: [PATCH 1/6] Derive Tracing timestep and max_steps, tie atol to rtol, warn on unfinished orbits --- README.md | 5 +- essos/dynamics.py | 37 +- essos/objective_functions.py | 14 +- essos/objective_functions.py.bak | 566 +++++++++++++++++++++++++++++++ tests/test_dynamics.py | 29 +- 5 files changed, 634 insertions(+), 17 deletions(-) create mode 100644 essos/objective_functions.py.bak diff --git a/README.md b/README.md index 7a59d253..492080d7 100644 --- a/README.md +++ b/README.md @@ -268,8 +268,9 @@ the `wout` directly and DESC fits it. ± is the binomial standard error. - **Stopping coil-field traces.** Pass `stopping_criteria=LevelsetStoppingCriterion(...)` to end Cartesian traces once they leave a prescribed distance from a surface, and read the per-line mask from `tracing.boundary_hits`. -- **Step budget.** `max_steps` (default `1_000_000`) bounds every Diffrax solve, - so a trace that cannot finish returns instead of running unbounded. +- **Step budget and defaults.** `max_steps` (default 16 times the steps of a fixed-step solve) bounds every + Diffrax solve and a `RuntimeWarning` reports orbits that did not finish. `timestep` defaults to 1/400 of the + transit time `R0 / v`, `rtol` to `1e-8` and `atol` to `rtol`. - **Progress bars** are off by default; pass `progress=True` when interactive. With `particle_batch_size=n` particles are traced `n` at a time and the bar counts completed particles (batches are bypassed under `jax.jit`/`grad`). diff --git a/essos/dynamics.py b/essos/dynamics.py index 667afb9d..3eae72db 100644 --- a/essos/dynamics.py +++ b/essos/dynamics.py @@ -1,5 +1,6 @@ from pyexpat import model import os +import warnings import jax jax.config.update("jax_enable_x64", True) # Every Tracing compiles a new solve, since maxtime and the save times are constants of it: about 4 s on a CPU @@ -776,6 +777,16 @@ def wrapped(t, y, args): return wrapped +# Steps per transit time R0/speed of the default timestep: Dopri8 conserves energy to ~1e-6 (see tests). +_STEPS_PER_TRANSIT = 400 + + +def _warn_unfinished(count, max_steps): + if count: + warnings.warn(f"{count} orbit(s) did not finish: non-finite state or max_steps={max_steps} reached; " + "raise max_steps or the timestep", RuntimeWarning, stacklevel=3) + + # Outcome of each VMEC guiding center, ``Tracing.status``. VMEC_STATUS = { 0: "inside the LCFS at maxtime", @@ -899,10 +910,10 @@ def _wall_function(field, wall): class Tracing(): def __init__(self, trajectories_input=None, initial_conditions=None, times_to_trace=None, - field=None, electric_field=None,model=None, maxtime: float = 1e-7, timestep: int = 1.e-8, - rtol= 1.e-7, atol = 1e-7, particles=None, condition=None,species=None,tag_gc=1.,boundary=None,rejected_steps=None, + field=None, electric_field=None,model=None, maxtime: float = 1e-7, timestep=None, + rtol=1.e-8, atol=None, particles=None, condition=None,species=None,tag_gc=1.,boundary=None,rejected_steps=None, solver=None, stopping_criteria=None, progress=True, devices=None, - max_steps=1_000_000, exterior_field=None, wall=None, max_returns=16, reentry_depth=None, + max_steps=None, exterior_field=None, wall=None, max_returns=16, reentry_depth=None, particle_batch_size=None, adjoint=None): if condition is not None and stopping_criteria is not None: @@ -938,9 +949,16 @@ def __init__(self, trajectories_input=None, initial_conditions=None, times_to_tr self.initial_conditions = initial_conditions self.times_to_trace = times_to_trace self.maxtime = maxtime + # timestep=None: 1/_STEPS_PER_TRANSIT of the transit time R0/speed; maxtime/100 for a field line, or when + # the field or particles are being differentiated (traced values cannot size a step). + if timestep is None: + scales = [getattr(field, "r_axis", 1.0), jnp.max(particles.total_speed) if particles is not None else jnp.nan] + timestep = (maxtime / 100 if any(isinstance(x, jax.core.Tracer) for x in scales) or np.isnan(scales[1]) + else float(abs(scales[0]) / scales[1]) / _STEPS_PER_TRANSIT) self.timestep = timestep self.rtol = rtol - self.atol = atol + # An absolute tolerance above rtol floors the error, so atol follows rtol by default. + self.atol = rtol if atol is None else atol self._trajectories = trajectories_input self.particles = particles self.species=species @@ -970,7 +988,8 @@ def __init__(self, trajectories_input=None, initial_conditions=None, times_to_tr self.reentry_depth = reentry_depth # Diffrax's ceiling was effectively unbounded, so a trace that could not # finish ran until the process was killed rather than returning. - self.max_steps = max_steps + # max_steps=None: 16 times the steps of a fixed-step solve, enough for tolerances down to 1e-12. + self.max_steps = int(16 * np.ceil(maxtime / timestep)) + 16 if max_steps is None else max_steps # Reverse mode (jax.grad) by default; diffrax.ForwardMode() for jax.jvp and jax.jacfwd, which # diffrax's checkpointed adjoint cannot do. self.adjoint = diffrax.RecursiveCheckpointAdjoint() if adjoint is None else adjoint @@ -1081,7 +1100,10 @@ def condition_BioSavart(t, y, args, **kwargs): if self._vmec_default: - return self._set_vmec_outputs(self.trace()) + self._set_vmec_outputs(self.trace()) + if not isinstance(self.failed, jax.core.Tracer): + _warn_unfinished(int(np.sum(self.failed)), self.max_steps) + return trace_result = self.trace() if self.stopping_criteria is not None: trajectories, self.event_mask = trace_result @@ -1097,6 +1119,8 @@ def condition_BioSavart(t, y, args, **kwargs): self.axis_hits = jnp.zeros(len(self._trajectories), dtype=bool) self.boundary_hits = jnp.zeros(len(self._trajectories), dtype=bool) self.total_particles_unresolved = jnp.sum(self.axis_hits) + if not isinstance(self._trajectories, jax.core.Tracer): + _warn_unfinished(int(jnp.sum(~jnp.isfinite(self._trajectories[:, -1]).all(-1))), self.max_steps) trajectory_points = self.trajectories[:, :, :3] if hasattr(self.field, "toroidal_angle_batch"): @@ -1246,7 +1270,6 @@ def _terms(self, key, flag=False): def _solve(self, terms, solver, controller, t0, y0, args, event, throw=False): """diffeqsolve from t0 to maxtime, saving at self.times (clipped to t0) and at the end.""" - import warnings warnings.simplefilter("ignore", category=FutureWarning) # see https://github.com/patrick-kidger/diffrax/issues/445 return diffeqsolve(terms, solver, t0=t0, t1=self.maxtime, dt0=self.timestep, y0=y0, args=args, saveat=SaveAt(subs=[diffrax.SubSaveAt(ts=jnp.clip(self.times, t0, self.maxtime)), diff --git a/essos/objective_functions.py b/essos/objective_functions.py index 48b3166b..1ca43cf0 100644 --- a/essos/objective_functions.py +++ b/essos/objective_functions.py @@ -50,7 +50,7 @@ def loss_r0_near_axis(field_nearaxis, r0_target=1.0): ##############################Particle confinement losses ############################## -def loss_particle_radial_drift_fullorbit(field, particles, timestep=1.e-8, maxtime=1e-5, num_steps=300, trace_tolerance=1e-5, model='GuidingCenterAdaptative',boundary=None): +def loss_particle_radial_drift_fullorbit(field, particles, timestep=None, maxtime=1e-5, num_steps=300, trace_tolerance=1e-7, model='GuidingCenterAdaptative',boundary=None): particles.to_full_orbit(field) tracing = Tracing(field=field, model=model, particles=particles, maxtime=maxtime, timestep=timestep,times_to_trace=num_steps, atol=trace_tolerance,rtol=trace_tolerance,boundary=boundary) @@ -62,7 +62,7 @@ def loss_particle_radial_drift_fullorbit(field, particles, timestep=1.e-8, maxti v_r_cross=jnp.diff(r_cross,axis=1)#/tracing.times_to_trace*tracing.maxtime return (jnp.sum(jnp.square(jnp.average(v_r_cross,axis=1)))) -def loss_particle_radial_drift(field, particles, timestep=1.e-8, maxtime=1e-5, num_steps=300, trace_tolerance=1e-5, model='GuidingCenterAdaptative',boundary=None): +def loss_particle_radial_drift(field, particles, timestep=None, maxtime=1e-5, num_steps=300, trace_tolerance=1e-7, model='GuidingCenterAdaptative',boundary=None): tracing = Tracing(field=field, model=model, particles=particles, maxtime=maxtime, timestep=timestep,times_to_trace=num_steps, atol=trace_tolerance,rtol=trace_tolerance,boundary=boundary) xyz = tracing.trajectories[:,:, :3] @@ -74,7 +74,7 @@ def loss_particle_radial_drift(field, particles, timestep=1.e-8, maxtime=1e-5, n return (jnp.sum(jnp.square(jnp.average(v_r_cross,axis=1)))) -def loss_particle_alpha_drift(field, particles, timestep=1.e-8, maxtime=1e-5, num_steps=300, trace_tolerance=1e-5, model='GuidingCenterAdaptative',boundary=None): +def loss_particle_alpha_drift(field, particles, timestep=None, maxtime=1e-5, num_steps=300, trace_tolerance=1e-7, model='GuidingCenterAdaptative',boundary=None): tracing = Tracing(field=field, model=model, particles=particles, maxtime=maxtime, timestep=timestep,times_to_trace=num_steps, atol=trace_tolerance,rtol=trace_tolerance,boundary=boundary) xyz = tracing.trajectories[:,:, :3] @@ -95,7 +95,7 @@ def loss_particle_alpha_drift(field, particles, timestep=1.e-8, maxtime=1e-5, nu v_theta=jnp.diff(theta,axis=1)#/tracing.times_to_trace*tracing.maxtime return jnp.sum(jnp.square(jnp.average(v_theta,axis=1))) -def loss_particle_gammac(field, particles, timestep=1.e-8, maxtime=1e-5, num_steps=300, trace_tolerance=1e-5, model='GuidingCenterAdaptative',boundary=None): +def loss_particle_gammac(field, particles, timestep=None, maxtime=1e-5, num_steps=300, trace_tolerance=1e-7, model='GuidingCenterAdaptative',boundary=None): tracing = Tracing(field=field, model=model, particles=particles, maxtime=maxtime, timestep=timestep,times_to_trace=num_steps, atol=trace_tolerance,rtol=trace_tolerance,boundary=boundary) xyz = tracing.trajectories[:,:, :3] @@ -119,7 +119,7 @@ def loss_particle_gammac(field, particles, timestep=1.e-8, maxtime=1e-5, num_ste #return jnp.sum(jnp.square((2./jnp.pi*jnp.absolute(jnp.arctan2(jnp.average(v_r_cross,axis=1),jnp.average(v_theta,axis=1)))))) return jnp.max(2./jnp.pi*jnp.absolute(jnp.arctan2(jnp.average(v_r_cross,axis=1),jnp.average(v_theta,axis=1)))) -def loss_particle_rcross_final(field, particles, timestep=1.e-8, maxtime=1e-5, num_steps=300, trace_tolerance=1e-5, model='GuidingCenterAdaptative',boundary=None): +def loss_particle_rcross_final(field, particles, timestep=None, maxtime=1e-5, num_steps=300, trace_tolerance=1e-7, model='GuidingCenterAdaptative',boundary=None): tracing = Tracing(field=field, model=model, particles=particles, maxtime=maxtime, timestep=timestep,times_to_trace=num_steps, atol=trace_tolerance,rtol=trace_tolerance,boundary=boundary) xyz = tracing.trajectories[:,:, :3] @@ -130,7 +130,7 @@ def loss_particle_rcross_final(field, particles, timestep=1.e-8, maxtime=1e-5, n -def loss_particle_Br(field, particles, timestep=1.e-8, maxtime=1e-5, num_steps=300, trace_tolerance=1e-5, model='GuidingCenterAdaptative',boundary=None): +def loss_particle_Br(field, particles, timestep=None, maxtime=1e-5, num_steps=300, trace_tolerance=1e-7, model='GuidingCenterAdaptative',boundary=None): tracing = Tracing(field=field, model=model, particles=particles, maxtime=maxtime, timestep=timestep,times_to_trace=num_steps, atol=trace_tolerance,rtol=trace_tolerance,boundary=boundary) xyz = tracing.trajectories[:,:, :3] @@ -145,7 +145,7 @@ def loss_particle_Br(field, particles, timestep=1.e-8, maxtime=1e-5, num_steps=3 B_r=jnp.multiply(B_particle[:,:,0],dr_cross_dx)+jnp.multiply(B_particle[:,:,1],dr_cross_dy)+jnp.multiply(B_particle[:,:,2],dr_cross_dz) return jnp.sum(jnp.abs(B_r)) -def loss_particle_iota(field, particles, timestep=1.e-8, maxtime=1e-5, num_steps=300, trace_tolerance=1e-5, model='GuidingCenterAdaptative',boundary=None,target_iota=0.41): +def loss_particle_iota(field, particles, timestep=None, maxtime=1e-5, num_steps=300, trace_tolerance=1e-7, model='GuidingCenterAdaptative',boundary=None,target_iota=0.41): tracing = Tracing(field=field, model=model, particles=particles, maxtime=maxtime, timestep=timestep,times_to_trace=num_steps, atol=trace_tolerance,rtol=trace_tolerance,boundary=boundary) xyz = tracing.trajectories[:,:, :3] diff --git a/essos/objective_functions.py.bak b/essos/objective_functions.py.bak new file mode 100644 index 00000000..20853f09 --- /dev/null +++ b/essos/objective_functions.py.bak @@ -0,0 +1,566 @@ +import jax + +# from build.lib.essos import coils +jax.config.update("jax_enable_x64", True) +import jax.numpy as jnp +from jax import jit, vmap +from functools import partial +from essos.dynamics import Tracing +from essos.fields import BiotSavart,BiotSavart_from_gamma +from essos.surfaces import BdotN_over_B +from essos.coils import Curves, Coils +from essos.constants import mu_0 +from essos.coil_perturbation import perturb_curves, perturb_curves_systematic, perturb_curves_statistic + + + + + +########################## NEAR-AXIS FIELD LOSSES ########################## +def near_axis_field_quantities(field_nearaxis): + Raxis = field_nearaxis.R0 + Zaxis = field_nearaxis.Z0 + phi = field_nearaxis.phi + Xaxis = Raxis*jnp.cos(phi) + Yaxis = Raxis*jnp.sin(phi) + points = jnp.array([Xaxis, Yaxis, Zaxis]) + B_nearaxis = field_nearaxis.B_axis.T + gradB_nearaxis = field_nearaxis.grad_B_axis.T + return points, B_nearaxis, gradB_nearaxis + + + +def loss_B_difference_coils_near_axis(field, field_nearaxis): + points, B_nearaxis, _ = near_axis_field_quantities(field_nearaxis) + B_coils = vmap(field.B)(points.T) + B_difference_loss = jnp.sum(jnp.abs(jnp.array(B_coils)-jnp.array(B_nearaxis))) + return B_difference_loss + +def loss_gradB_difference_coils_near_axis(field, field_nearaxis): + points, _, gradB_nearaxis = near_axis_field_quantities(field_nearaxis) + gradB_coils = vmap(field.dB_by_dX)(points.T) + gradB_difference_loss = jnp.sum(jnp.abs(jnp.array(gradB_coils)-jnp.array(gradB_nearaxis))) + return gradB_difference_loss + +def loss_iota_near_axis(field_nearaxis,iota_target=0.41): + return jnp.abs((field_nearaxis.iota - iota_target)) + +def loss_r0_near_axis(field_nearaxis, r0_target=1.0): + return jnp.abs((field_nearaxis.R0[0] - r0_target)) + + +##############################Particle confinement losses ############################## +def loss_particle_radial_drift_fullorbit(field, particles, timestep=None, maxtime=1e-5, num_steps=300, trace_tolerance=1e-5, model='GuidingCenterAdaptative',boundary=None): + particles.to_full_orbit(field) + tracing = Tracing(field=field, model=model, particles=particles, maxtime=maxtime, + timestep=timestep,times_to_trace=num_steps, atol=trace_tolerance,rtol=trace_tolerance,boundary=boundary) + xyz = tracing.trajectories[:,:, :3] + R_axis=field.r_axis + Z_axis=field.z_axis + #Ideally here one would differentiate in time through diffrax !TODO + r_cross=jnp.sqrt(jnp.square(jnp.sqrt(jnp.square(xyz[:,:,0])+jnp.square(xyz[:,:,1]))-R_axis+1.e-12)+jnp.square(xyz[:,:,2]-Z_axis+1.e-12)) + v_r_cross=jnp.diff(r_cross,axis=1)#/tracing.times_to_trace*tracing.maxtime + return (jnp.sum(jnp.square(jnp.average(v_r_cross,axis=1)))) + +def loss_particle_radial_drift(field, particles, timestep=None, maxtime=1e-5, num_steps=300, trace_tolerance=1e-5, model='GuidingCenterAdaptative',boundary=None): + tracing = Tracing(field=field, model=model, particles=particles, maxtime=maxtime, + timestep=timestep,times_to_trace=num_steps, atol=trace_tolerance,rtol=trace_tolerance,boundary=boundary) + xyz = tracing.trajectories[:,:, :3] + R_axis=field.r_axis + Z_axis=field.z_axis + #Ideally here one would differentiate in time through diffrax !TODO + r_cross=jnp.sqrt(jnp.square(jnp.sqrt(jnp.square(xyz[:,:,0])+jnp.square(xyz[:,:,1]))-R_axis+1.e-12)+jnp.square(xyz[:,:,2]-Z_axis+1.e-12)) + v_r_cross=jnp.diff(r_cross,axis=1)#/tracing.times_to_trace*tracing.maxtime + return (jnp.sum(jnp.square(jnp.average(v_r_cross,axis=1)))) + + +def loss_particle_alpha_drift(field, particles, timestep=None, maxtime=1e-5, num_steps=300, trace_tolerance=1e-5, model='GuidingCenterAdaptative',boundary=None): + tracing = Tracing(field=field, model=model, particles=particles, maxtime=maxtime, + timestep=timestep,times_to_trace=num_steps, atol=trace_tolerance,rtol=trace_tolerance,boundary=boundary) + xyz = tracing.trajectories[:,:, :3] + R_axis=field.r_axis + Z_axis=field.z_axis + #def theta(x,R_axis=R_axis,Z_axis=Z_axis): + # return jnp.arctan2(x[2]-Z_axis+1.e-12, jnp.sqrt(x[0]**2+x[1]**2)-R_axis+1.e-12) + #def phi(x): + # return jnp.arctan2(x[1], x[0]) + ##AbsB = vmap(self.field.AbsB)(xyz) + ##B_contravariant=vmap(self.field.B_contravariant,in_axes=(0))(xyz) + #Ideally here one would differentiate in time through diffrax !TODO + #grad_theta=vmap(jax.jacfwd(theta,argnums=0),in_axes=0)(xyz) + #grad_phi=vmap(jax.jacfwd(phi,argnums=0),in_axes=0)(xyz) + #v_theta=jnp.tensordot(v_xyz,grad_theta,axes=(1,1)) + #v_alpha=v_theta-jnp.tensordot(B_contravariant,grad_theta,axes=(1,1))/jnp.tensordot(B_contravariant,grad_phi,axes=(1,1))*jnp.tensordot(v_xyz,grad_phi,axes=(1,1)) + theta=jnp.arctan2(xyz[:,:,2]-Z_axis+1.e-12, jnp.sqrt(xyz[:,:,0]**2+xyz[:,:,1]**2)-R_axis+1.e-12) + v_theta=jnp.diff(theta,axis=1)#/tracing.times_to_trace*tracing.maxtime + return jnp.sum(jnp.square(jnp.average(v_theta,axis=1))) + +def loss_particle_gammac(field, particles, timestep=None, maxtime=1e-5, num_steps=300, trace_tolerance=1e-5, model='GuidingCenterAdaptative',boundary=None): + tracing = Tracing(field=field, model=model, particles=particles, maxtime=maxtime, + timestep=timestep,times_to_trace=num_steps, atol=trace_tolerance,rtol=trace_tolerance,boundary=boundary) + xyz = tracing.trajectories[:,:, :3] + R_axis=field.r_axis + Z_axis=field.z_axis + #def theta(x,R_axis=R_axis,Z_axis=Z_axis): + # return jnp.arctan2(x[2]-Z_axis+1.e-12, jnp.sqrt(x[0]**2+x[1]**2)-R_axis+1.e-12) + #def phi(x): + # return jnp.arctan2(x[1], x[0]) + ##AbsB = vmap(self.field.AbsB)(xyz) + ##B_contravariant=vmap(self.field.B_contravariant,in_axes=(0))(xyz) + #Ideally here one would differentiate in time through diffrax !TODO + #grad_theta=vmap(jax.jacfwd(theta,argnums=0),in_axes=0)(xyz) + #grad_phi=vmap(jax.jacfwd(phi,argnums=0),in_axes=0)(xyz) + #v_theta=jnp.tensordot(v_xyz,grad_theta,axes=(1,1)) + #v_alpha=v_theta-jnp.tensordot(B_contravariant,grad_theta,axes=(1,1))/jnp.tensordot(B_contravariant,grad_phi,axes=(1,1))*jnp.tensordot(v_xyz,grad_phi,axes=(1,1)) + r_cross=jnp.sqrt(jnp.square(jnp.sqrt(jnp.square(xyz[:,:,0])+jnp.square(xyz[:,:,1]))-R_axis+1.e-12)+jnp.square(xyz[:,:,2]-Z_axis+1.e-12)) + v_r_cross=jnp.diff(r_cross,axis=1)#/tracing.times_to_trace*tracing.maxtime + theta=jnp.arctan2(xyz[:,:,2]-Z_axis+1.e-12, jnp.sqrt(xyz[:,:,0]**2+xyz[:,:,1]**2)-R_axis+1.e-12) + v_theta=jnp.diff(theta,axis=1)#/tracing.times_to_trace*tracing.maxtime + #return jnp.sum(jnp.square((2./jnp.pi*jnp.absolute(jnp.arctan2(jnp.average(v_r_cross,axis=1),jnp.average(v_theta,axis=1)))))) + return jnp.max(2./jnp.pi*jnp.absolute(jnp.arctan2(jnp.average(v_r_cross,axis=1),jnp.average(v_theta,axis=1)))) + +def loss_particle_rcross_final(field, particles, timestep=None, maxtime=1e-5, num_steps=300, trace_tolerance=1e-5, model='GuidingCenterAdaptative',boundary=None): + tracing = Tracing(field=field, model=model, particles=particles, maxtime=maxtime, + timestep=timestep,times_to_trace=num_steps, atol=trace_tolerance,rtol=trace_tolerance,boundary=boundary) + xyz = tracing.trajectories[:,:, :3] + R_axis=field.r_axis + Z_axis=field.z_axis + r_cross=jnp.sqrt(jnp.square(jnp.sqrt(jnp.square(xyz[:,:,0])+jnp.square(xyz[:,:,1]))-R_axis+1.e-12)+jnp.square(xyz[:,:,2]-Z_axis+1.e-12)) + return jnp.linalg.norm((jnp.average(r_cross,axis=1))) + + + +def loss_particle_Br(field, particles, timestep=None, maxtime=1e-5, num_steps=300, trace_tolerance=1e-5, model='GuidingCenterAdaptative',boundary=None): + tracing = Tracing(field=field, model=model, particles=particles, maxtime=maxtime, + timestep=timestep,times_to_trace=num_steps, atol=trace_tolerance,rtol=trace_tolerance,boundary=boundary) + xyz = tracing.trajectories[:,:, :3] + R_axis=tracing.field.r_axis + Z_axis=tracing.field.z_axis + fac_xy=jnp.sqrt(jnp.square(xyz[:,:,0])+jnp.square(xyz[:,:,1])) + r_cross=jnp.sqrt(jnp.square(fac_xy-R_axis+1.e-12)+jnp.square(xyz[:,:,2]-Z_axis+1.e-12)) + dr_cross_dx=(fac_xy-R_axis+1.e-12)*xyz[:,:,0]/(r_cross*fac_xy+1.e-12) + dr_cross_dy=(fac_xy-R_axis+1.e-12)*xyz[:,:,1]/(r_cross*fac_xy+1.e-12) + dr_cross_dz=(xyz[:,:,2]-Z_axis+1.e-12)/(r_cross+1.e-12) + B_particle=jax.vmap(jax.vmap(field.B_covariant,in_axes=0),in_axes=0)(xyz) + B_r=jnp.multiply(B_particle[:,:,0],dr_cross_dx)+jnp.multiply(B_particle[:,:,1],dr_cross_dy)+jnp.multiply(B_particle[:,:,2],dr_cross_dz) + return jnp.sum(jnp.abs(B_r)) + +def loss_particle_iota(field, particles, timestep=None, maxtime=1e-5, num_steps=300, trace_tolerance=1e-5, model='GuidingCenterAdaptative',boundary=None,target_iota=0.41): + tracing = Tracing(field=field, model=model, particles=particles, maxtime=maxtime, + timestep=timestep,times_to_trace=num_steps, atol=trace_tolerance,rtol=trace_tolerance,boundary=boundary) + xyz = tracing.trajectories[:,:, :3] + R_axis=tracing.field.r_axis + Z_axis=tracing.field.z_axis + #theta=jnp.arctan2(xyz[:,:,2]-Z_axis+1.e-12, jnp.sqrt(xyz[:,:,0]**2+xyz[:,:,1]**2)-R_axis+1.e-12) + fac_xy=jnp.sqrt(jnp.square(xyz[:,:,0])+jnp.square(xyz[:,:,1])) + dtheta_dx=-(xyz[:,:,2]-Z_axis+1.e-12)*xyz[:,:,0]/(fac_xy+1.e-12)/(jnp.square(fac_xy-R_axis+1.e-12)+jnp.square(xyz[:,:,2]-Z_axis+1.e-12)+1.e-12) + dtheta_dy=-(xyz[:,:,2]-Z_axis+1.e-12)*xyz[:,:,1]/(fac_xy+1.e-12)/(jnp.square(fac_xy-R_axis+1.e-12)+jnp.square(xyz[:,:,2]-Z_axis+1.e-12)+1.e-12) + dtheta_dz=(fac_xy-R_axis+1.e-12)/(jnp.square(fac_xy-R_axis+1.e-12)+jnp.square(xyz[:,:,2]-Z_axis+1.e-12)+1.e-12) + dphi_dx=-(xyz[:,:,1])/(fac_xy**2+1.e-12) + dphi_dy=xyz[:,:,0]/(fac_xy**2+1.e-12) + B_particle=jax.vmap(jax.vmap(tracing.field.B_covariant,in_axes=0),in_axes=0)(xyz) + B_theta=jnp.multiply(B_particle[:,:,0],dtheta_dx)+jnp.multiply(B_particle[:,:,1],dtheta_dy)+jnp.multiply(B_particle[:,:,2],dtheta_dz) + B_phi=jnp.multiply(B_particle[:,:,0],dphi_dx)+jnp.multiply(B_particle[:,:,1],dphi_dy) + return jnp.sum(jnp.maximum(target_iota-B_theta/B_phi,0.0)) + + + + + + + + +################### B ON SURAFCE LOSSES ########################## +@partial(jit, static_argnames=['npoints']) +def normB_axis(field, npoints=15): + R_axis=field.r_axis + phi_array = jnp.linspace(0, 2 * jnp.pi, npoints) + B_axis = vmap(lambda phi: field.AbsB(jnp.array([R_axis * jnp.cos(phi), R_axis * jnp.sin(phi), 0])))(phi_array) + return B_axis + +@partial(jit, static_argnames=['npoints', 'target_B']) +def loss_normB_axis_average(field,npoints=15, target_B=5.7): + B_axis = normB_axis(field, npoints) + return jnp.abs(jnp.average(B_axis)-target_B) + + +def loss_BdotN(field,surface): + return jnp.sum(jnp.abs(BdotN_over_B(surface, field))) + +def _sqrt_sum_positive(u): + """sqrt(sum(max(u, 0))) with a zero (not NaN) gradient where the constraint is met.""" + total = jnp.sum(jnp.maximum(u, 0.0)) + return jnp.where(total > 0, jnp.sqrt(jnp.where(total > 0, total, 1.0)), 0.0) + +@partial(jit, static_argnames=['target_tol']) +def loss_BdotN_constraint(field,surface,target_tol=1.e-6): + bdotn_over_b = BdotN_over_B(surface, field) + return _sqrt_sum_positive(jnp.square(bdotn_over_b)-target_tol) + + +########################### B ON SURAFCE LOSSES FOR STOCHASTIC OPTIMIZATION ########################## +def copy_coils_from_field(field): + return field.coils.copy() + +@partial(jit, static_argnames=['sampler']) +def perturbed_field_from_field(field, key, sampler): + coils = copy_coils_from_field(field) + base_key = jax.random.key(key) + split_keys = jax.random.split(base_key, 2) + coils = perturb_curves_systematic(coils, sampler, key=split_keys[0]) + coils = perturb_curves_statistic(coils, sampler, key=split_keys[1]) + return BiotSavart(coils) + + +@partial(jit, static_argnames=['sampler']) +def loss_bdotn_stochastic(field, surface, sampler, keys): + def perturbed_loss(key): + perturbed_field = perturbed_field_from_field(field, key, sampler) + bdotn_over_b = BdotN_over_B(surface, perturbed_field) + return jnp.sum(jnp.abs(bdotn_over_b)) + + return jnp.mean(jax.vmap(perturbed_loss)(keys)) + + +@partial(jit, static_argnames=['sampler', 'target_tol']) +def constraint_bdotn_stochastic(field, surface, sampler, keys, target_tol=1.0e-6): + def perturbed_square(key): + perturbed_field = perturbed_field_from_field(field, key, sampler) + return jnp.square(BdotN_over_B(surface, perturbed_field)) + + expected_square = jnp.mean(jax.vmap(perturbed_square)(keys), axis=0) + return _sqrt_sum_positive(expected_square - target_tol) + + + + +######################### COIL GEOMETRY LOSSES ################################# + +@partial(jit, static_argnames=['max_coil_length']) +def loss_coil_length(coils, max_coil_length=0): + return jnp.square(coils.length/max_coil_length - 1) + +@partial(jit, static_argnames=['max_coil_curvature']) +def loss_coil_curvature(coils, max_coil_curvature=0): + pointwise_curvature_loss = jnp.square(jnp.maximum(coils.curvature-max_coil_curvature, 0)) + return jnp.mean(pointwise_curvature_loss*jnp.linalg.norm(coils.gamma_dash, axis=-1), axis=1) + +def compute_candidates(coils, min_separation): + centers = coils.curves.curves[:, :, 0] + a_n = coils.curves.curves[:, :, 2 : 2*coils.order+1 : 2] + b_n = coils.curves.curves[:, :, 1 : 2*coils.order : 2] + radii = jnp.sum(jnp.linalg.norm(a_n, axis=1)+jnp.linalg.norm(b_n, axis=1), axis=1) + + i_vals, j_vals = jnp.triu_indices(len(coils), k=1) + centers_dists = jnp.linalg.norm(centers[i_vals] - centers[j_vals], axis=1) + mask = centers_dists <= min_separation + radii[i_vals] + radii[j_vals] + + return i_vals[mask], j_vals[mask] + + +# Blockwise, memory-efficient coil separation loss +@partial(jit, static_argnames=["min_separation", "block_size"]) +def loss_coil_separation(coils, min_separation, candidates=None, block_size=None): + """ + Memory-efficient coil separation loss using blockwise vmap. + Args: + coils: Coils object + min_separation: Minimum allowed separation + candidates: Optional tuple of (i, j) coil index arrays + block_size: Block size for memory efficiency. If None, uses full vmap (no chunking) + Returns: + Scalar loss (sum over all coil pairs) + """ + if candidates is None: + candidates = jnp.triu_indices(len(coils), k=1) + + def pair_loss(i, j): + gamma_i = coils.gamma[i] + gamma_dash_i = jnp.linalg.norm(coils.gamma_dash[i], axis=-1) + gamma_j = coils.gamma[j] + gamma_dash_j = jnp.linalg.norm(coils.gamma_dash[j], axis=-1) + n_points = gamma_i.shape[0] + + # If block_size is None, use full vmap (no chunking) + use_block_size = min(n_points, n_points if block_size is None else block_size) + n_blocks = (n_points + use_block_size - 1) // use_block_size + padded_points = n_blocks * use_block_size + pad_width = padded_points - n_points + + gamma_j_blocks = jnp.pad(gamma_j, ((0, pad_width), (0, 0))).reshape(n_blocks, use_block_size, 3) + gamma_dash_j_blocks = jnp.pad(gamma_dash_j, (0, pad_width)).reshape(n_blocks, use_block_size) + valid_blocks = (jnp.arange(padded_points) < n_points).reshape(n_blocks, use_block_size) + + def block_sum(block_gamma_j, block_gamma_dash_j, block_valid): + dists_block = jnp.linalg.norm(gamma_i[:, None, :] - block_gamma_j[None, :, :], axis=2) + penalty_block = jnp.maximum(0, min_separation - dists_block) + weighted_penalty = ( + jnp.square(penalty_block) + * gamma_dash_i[:, None] + * block_gamma_dash_j[None, :] + * block_valid[None, :] + ) + return jnp.sum(weighted_penalty) + + total = jnp.sum(jax.vmap(block_sum)(gamma_j_blocks, gamma_dash_j_blocks, valid_blocks)) + norm = gamma_i.shape[0] * gamma_j.shape[0] + return total / norm + + losses = jax.vmap(pair_loss)(*candidates) + return jnp.sum(losses) + +# Blockwise, memory-efficient coil-surface distance loss +@partial(jit, static_argnames=["min_distance", "block_size"]) +def loss_coil_surface_distance(coils, surface, min_distance, block_size=None): + """ + Memory-efficient coil-surface distance loss using blockwise vmap and symmetry reduction. + Args: + coils: Coils object + surface: Surface object (with gamma, unitnormal) + min_distance: Minimum allowed coil-surface distance + block_size: Block size for memory efficiency. If None, uses full vmap (no chunking) + nfp: Number of field periods + stellsym: Whether stellarator symmetry is present + Returns: + Scalar loss (sum over all relevant coil-surface pairs) + """ + n_coils = coils.gamma.shape[0] + n_points_coil = coils.gamma.shape[1] + surface_points = surface.gamma.reshape(-1, 3) + n_points_surface = surface_points.shape[0] + + # Only check unique coils for symmetry + if coils.stellsym: + n_unique_coils = n_coils // (2 * coils.nfp) + else: + n_unique_coils = n_coils // coils.nfp + n_unique_coils = max(1, n_unique_coils) + unique_coil_indices = jnp.arange(n_unique_coils) + + def single_coil_loss(idx): + gamma_i = coils.gamma[idx] + gamma_dash_i = coils.gamma_dash[idx] + gamma_dash_norm = jnp.linalg.norm(gamma_dash_i, axis=1) + n_points = gamma_i.shape[0] + + # If block_size is None, use full vmap (no chunking) + use_block_size = min(n_points_surface, n_points_surface if block_size is None else block_size) + n_blocks = (n_points_surface + use_block_size - 1) // use_block_size + padded_points = n_blocks * use_block_size + pad_width = padded_points - n_points_surface + + surface_point_blocks = jnp.pad(surface_points, ((0, pad_width), (0, 0))).reshape(n_blocks, use_block_size, 3) + valid_blocks = (jnp.arange(padded_points) < n_points_surface).reshape(n_blocks, use_block_size) + + def block_sum(block_surface_points, block_valid): + dists_block = jnp.linalg.norm(gamma_i[:, None, :] - block_surface_points[None, :, :], axis=2) + penalty_block = jnp.maximum(0, min_distance - dists_block) + weighted_penalty = jnp.square(penalty_block) * gamma_dash_norm[:, None] * block_valid[None, :] + return jnp.sum(weighted_penalty) + + total = jnp.sum(jax.vmap(block_sum)(surface_point_blocks, valid_blocks)) + norm = gamma_i.shape[0] * n_points_surface + return total / norm + + losses = jax.vmap(single_coil_loss)(unique_coil_indices) + return jnp.sum(losses) + + +# Blockwise vmap linking number loss (memory efficient, fully differentiable) +@partial(jit, static_argnames=["block_size"]) +def loss_linkingnumber(coils, candidates=None, block_size=None): + if candidates is None: + candidates = jnp.triu_indices(len(coils), k=1) + dphi = coils.curves.quadpoints[1] - coils.curves.quadpoints[0] + + def pair_linking(i, j): + gamma_i = coils.gamma[i] + gamma_dash_i = coils.gamma_dash[i] + gamma_j = coils.gamma[j] + gamma_dash_j = coils.gamma_dash[j] + n_points = gamma_j.shape[0] + + # If block_size is None, use full vmap (no chunking) + use_block_size = min(n_points, n_points if block_size is None else block_size) + n_blocks = (n_points + use_block_size - 1) // use_block_size + padded_points = n_blocks * use_block_size + pad_width = padded_points - n_points + + gamma_j_blocks = jnp.pad(gamma_j, ((0, pad_width), (0, 0))).reshape(n_blocks, use_block_size, 3) + gamma_dash_j_blocks = jnp.pad(gamma_dash_j, ((0, pad_width), (0, 0))).reshape(n_blocks, use_block_size, 3) + valid_blocks = (jnp.arange(padded_points) < n_points).reshape(n_blocks, use_block_size) + + def block_sum(block_gamma_j, block_gamma_dash_j, block_valid): + def integrand(r2, dr2): + diff = gamma_i - r2 + cross = jnp.cross(gamma_dash_i, dr2) + norm = jnp.linalg.norm(diff, axis=1) + return jnp.sum(diff * cross, axis=1) / (norm**3 + 1e-12) + + block_vals = jax.vmap(integrand, in_axes=(0, 0))(block_gamma_j, block_gamma_dash_j) + return jnp.sum(block_vals * block_valid[:, None]) + + total = jnp.sum(jax.vmap(block_sum)(gamma_j_blocks, gamma_dash_j_blocks, valid_blocks)) + linking = total * (dphi ** 2) / (4 * jnp.pi) + return jnp.abs(linking) + + losses = jax.vmap(pair_linking)(*candidates) + return jnp.sum(losses) + + + + +# Lorentz force loss: accepts Coils object, keyword args, JAX-friendly +@partial(jit, static_argnames=["p", "threshold", "block_size"]) +def loss_lorentz_force_coils(coils, p=1, threshold=0.5e6, block_size=None, conductor_radius=None): + """ + Loss function penalizing Lorentz force on coils using Landreman-Hurwitz method. + + Matches SIMSOPT's ``LpCurveForce``:: + + J = (1/p) sum_i (1/L_i) int max(|dF_i/dl| - F_0, 0)^p dl_i + + so it is independent of the quadrature resolution. The self-force uses the + regularized self field of a circular conductor of radius ``a`` + (``delta = a**2 / sqrt(e)``; Hurwitz, Landreman & Antonsen, + arXiv:2310.09313). + + Args: + coils: Coils object (with gamma, gamma_dash, gamma_dashdash, currents, quadpoints) + p: Power for penalty (default 1) + threshold: Force threshold F_0 in N/m (default 0.5e6) + block_size: Block size for memory efficiency. If None, uses full vmap (no chunking) + conductor_radius: Radius of the conductor cross-section in meters + (required: the self-force depends logarithmically on it). + Returns: + Scalar loss (sum over all coils) + """ + if conductor_radius is None: + raise ValueError("loss_lorentz_force_coils needs conductor_radius (the coil cross-section radius in m)") + n_coils = coils.gamma.shape[0] + indices = jnp.arange(n_coils) + other_indices = jnp.array([ + [j for j in range(n_coils) if j != i] + for i in range(n_coils) + ], dtype=jnp.int32) + + def single_coil_loss(idx): + gamma_i = coils.gamma[idx] + gamma_dash_i = coils.gamma_dash[idx] + gamma_dashdash_i = coils.gamma_dashdash[idx] + current_i = coils.currents[idx] + quadpoints = coils.curves.quadpoints + regularization = regularization_circ(conductor_radius) + other_idx = other_indices[idx] + gamma_others = coils.gamma[other_idx] + gamma_dash_others = coils.gamma_dash[other_idx] + gamma_dashdash_others = coils.gamma_dashdash[other_idx] + currents_others = coils.currents[other_idx] + biot_savart = BiotSavart_from_gamma(gamma_others, gamma_dash_others, gamma_dashdash_others, currents_others) + n_points = gamma_i.shape[0] + use_block_size = min(n_points, n_points if block_size is None else block_size) + n_blocks = (n_points + use_block_size - 1) // use_block_size + padded_points = n_blocks * use_block_size + pad_width = padded_points - n_points + + gamma_i_blocks = jnp.pad(gamma_i, ((0, pad_width), (0, 0))).reshape(n_blocks, use_block_size, 3) + valid_blocks = (jnp.arange(padded_points) < n_points).reshape(n_blocks, use_block_size) + + def block_field(block_gamma_i, block_valid): + block_B = jax.vmap(biot_savart.B)(block_gamma_i) + return block_B * block_valid[:, None] + + block_B_mutual = jax.vmap(block_field)(gamma_i_blocks, valid_blocks).reshape(padded_points, 3)[:n_points] + block_gammadash_norm = jnp.linalg.norm(gamma_dash_i, axis=1) + block_tangent = gamma_dash_i / block_gammadash_norm[:, None] + block_B_self = B_regularized_pure( + gamma_i, gamma_dash_i, gamma_dashdash_i, + quadpoints, current_i, regularization + ) + block_force = jnp.cross(current_i * block_tangent, block_B_self + block_B_mutual) + block_force_norm = jnp.linalg.norm(block_force, axis=1) + # Uniform quadrature on [0, 1): int f dl = mean(f |gamma'|), L = mean(|gamma'|). + integral = jnp.mean(jnp.maximum(block_force_norm - threshold, 0) ** p * block_gammadash_norm) + return integral / jnp.mean(block_gammadash_norm) / p + + penalties = jax.vmap(single_coil_loss)(indices) + return jnp.sum(penalties) + + + + + + +def B_regularized_singularity_term(rc_prime, rc_prime_prime, regularization): + """The term in the regularized Biot-Savart law in which the near-singularity + has been integrated analytically. + + regularization corresponds to delta * a * b for rectangular x-section, or to + a²/√e for circular x-section. + + A prefactor of μ₀ I / (4π) is not included. + + The derivatives rc_prime, rc_prime_prime refer to an angle that goes up to + 2π, not up to 1. + """ + norm_rc_prime = jnp.linalg.norm(rc_prime, axis=1) + return jnp.cross(rc_prime, rc_prime_prime) * (0.5 * (-2 + jnp.log(64 * norm_rc_prime * norm_rc_prime / regularization)) / (norm_rc_prime**3))[:, None] + + +def B_regularized_pure(gamma, gammadash, gammadashdash, quadpoints, current, regularization): + # The factors of 2π in the next few lines come from the fact that simsopt + # uses a curve parameter that goes up to 1 rather than 2π. + phi = quadpoints * 2 * jnp.pi + rc = gamma + rc_prime = gammadash / 2 / jnp.pi + rc_prime_prime = gammadashdash / 4 / jnp.pi**2 + n_quad = phi.shape[0] + dphi = 2 * jnp.pi / n_quad + analytic_term = B_regularized_singularity_term(rc_prime, rc_prime_prime, regularization) + dr = rc[:, None] - rc[None, :] + first_term = jnp.cross(rc_prime[None, :], dr) / ((jnp.sum(dr * dr, axis=2) + regularization) ** 1.5)[:, :, None] + cos_fac = 2 - 2 * jnp.cos(phi[None, :] - phi[:, None]) + denominator2 = cos_fac * jnp.sum(rc_prime * rc_prime, axis=1)[:, None] + regularization + factor2 = 0.5 * cos_fac / denominator2**1.5 + second_term = jnp.cross(rc_prime_prime, rc_prime)[:, None, :] * factor2[:, :, None] + integral_term = dphi * jnp.sum(first_term + second_term, 1) + return current * mu_0 / (4 * jnp.pi) * (analytic_term + integral_term) + + + +def regularization_circ(a): + """Regularization for a circular conductor""" + return a**2 / jnp.sqrt(jnp.e) + + +def regularization_rect(a, b): + """Regularization for a rectangular conductor""" + return a * b * rectangular_xsection_delta(a, b) + +def rectangular_xsection_k(a, b): + """Auxiliary function for field in rectangular conductor""" + return (4 * b) / (3 * a) * jnp.arctan(a/b) + (4*a)/(3*b)*jnp.arctan(b/a)+ (b**2)/(6*a**2)*jnp.log(b/a) + (a**2)/(6*b**2)*jnp.log(a/b) - (a**4 - 6*a**2*b**2 + b**4)/(6*a**2*b**2)*jnp.log(a/b+b/a) + + +def rectangular_xsection_delta(a, b): + """Auxiliary function for field in rectangular conductor""" + return jnp.exp(-25/6 + rectangular_xsection_k(a, b)) + + +#def loss_BdotN_only_with_perturbation(x, vmec, dofs_curves, currents_scale, nfp,n_segments=60, stellsym=True, N_stells=10): +# """ +# Compute the loss function for BdotN with a perturbation applied to the BdotN value.): +# field=field_from_dofs(x,dofs_curves, currents_scale, nfp,n_segments, stellsym) +# +# bdotn_over_b = BdotN_over_B(vmec.surface, field) +# +# # Apply perturbation to the BdotN value +# bdotn_over_b += perturbation +# +# bdotn_over_b_loss = jnp.sum(jnp.abs(bdotn_over_b)) + +# return bdotn_over_b_loss + + + +####################### SURFACE GEOMETRY LOSSES ########################## diff --git a/tests/test_dynamics.py b/tests/test_dynamics.py index c5c48a61..20d80fb4 100644 --- a/tests/test_dynamics.py +++ b/tests/test_dynamics.py @@ -585,7 +585,7 @@ def test_tracing_max_steps_is_configurable_and_bounded(): from essos.dynamics import Tracing default = inspect.signature(Tracing).parameters["max_steps"].default - assert default == 1_000_000 + assert default is None # derived from maxtime and timestep source = inspect.getsource(Tracing) assert "max_steps=10000000000" not in source @@ -1229,3 +1229,30 @@ def test_mu_collision_models_accept_coils_as_the_field(monkeypatch): B = BiotSavart(coils).AbsB(particles.initial_xyz[0]) mu = particles.initial_vperpendicular[0]**2 / (2 * B * SPEED_OF_LIGHT**2) np.testing.assert_allclose(trace.initial_conditions[0, 4], mu, rtol=1e-6) + + +@pytest.fixture(scope="module") +def qa_coil_alphas(): + from essos.coils import Coils + from essos.fields import BiotSavart + path = Path(__file__).resolve().parents[1] / "examples" / "input_files" / "ESSOS_biot_savart_LandremanPaulQA.json" + R0 = jnp.array([1.23, 1.27]) + particles = Particles(initial_xyz=jnp.stack([R0, 0 * R0, 0 * R0], axis=1), initial_vparallel_over_v=jnp.array([0.3, -0.5]), + energy=4000 * 1.602176634e-19) + return BiotSavart(Coils.from_json(str(path))), particles + + +@pytest.mark.parametrize("model, options, bound", [ + ("GuidingCenterAdaptative", {}, 1e-6), # default tolerance + ("GuidingCenter", {}, 1e-6), # default timestep +]) +def test_default_tracing_conserves_energy(qa_coil_alphas, model, options, bound): + field, particles = qa_coil_alphas + tracing = Tracing(field=field, model=model, particles=particles, maxtime=1e-4, times_to_trace=20, **options) + assert float(jnp.max(jnp.abs(tracing.energy() / particles.energy - 1))) < bound + + +def test_truncated_tracing_warns(qa_coil_alphas): + field, particles = qa_coil_alphas + with pytest.warns(RuntimeWarning, match="did not finish"): + Tracing(field=field, model="GuidingCenterAdaptative", particles=particles, maxtime=1e-5, max_steps=20) From 27db86e3a0bd9df94c692c2af60a93a0aca6ca4e Mon Sep 17 00:00:00 2001 From: Rogerio Jorge Date: Tue, 10 Nov 2026 12:32:42 -0600 Subject: [PATCH 2/6] Remove stray backup file --- essos/objective_functions.py.bak | 566 ------------------------------- 1 file changed, 566 deletions(-) delete mode 100644 essos/objective_functions.py.bak diff --git a/essos/objective_functions.py.bak b/essos/objective_functions.py.bak deleted file mode 100644 index 20853f09..00000000 --- a/essos/objective_functions.py.bak +++ /dev/null @@ -1,566 +0,0 @@ -import jax - -# from build.lib.essos import coils -jax.config.update("jax_enable_x64", True) -import jax.numpy as jnp -from jax import jit, vmap -from functools import partial -from essos.dynamics import Tracing -from essos.fields import BiotSavart,BiotSavart_from_gamma -from essos.surfaces import BdotN_over_B -from essos.coils import Curves, Coils -from essos.constants import mu_0 -from essos.coil_perturbation import perturb_curves, perturb_curves_systematic, perturb_curves_statistic - - - - - -########################## NEAR-AXIS FIELD LOSSES ########################## -def near_axis_field_quantities(field_nearaxis): - Raxis = field_nearaxis.R0 - Zaxis = field_nearaxis.Z0 - phi = field_nearaxis.phi - Xaxis = Raxis*jnp.cos(phi) - Yaxis = Raxis*jnp.sin(phi) - points = jnp.array([Xaxis, Yaxis, Zaxis]) - B_nearaxis = field_nearaxis.B_axis.T - gradB_nearaxis = field_nearaxis.grad_B_axis.T - return points, B_nearaxis, gradB_nearaxis - - - -def loss_B_difference_coils_near_axis(field, field_nearaxis): - points, B_nearaxis, _ = near_axis_field_quantities(field_nearaxis) - B_coils = vmap(field.B)(points.T) - B_difference_loss = jnp.sum(jnp.abs(jnp.array(B_coils)-jnp.array(B_nearaxis))) - return B_difference_loss - -def loss_gradB_difference_coils_near_axis(field, field_nearaxis): - points, _, gradB_nearaxis = near_axis_field_quantities(field_nearaxis) - gradB_coils = vmap(field.dB_by_dX)(points.T) - gradB_difference_loss = jnp.sum(jnp.abs(jnp.array(gradB_coils)-jnp.array(gradB_nearaxis))) - return gradB_difference_loss - -def loss_iota_near_axis(field_nearaxis,iota_target=0.41): - return jnp.abs((field_nearaxis.iota - iota_target)) - -def loss_r0_near_axis(field_nearaxis, r0_target=1.0): - return jnp.abs((field_nearaxis.R0[0] - r0_target)) - - -##############################Particle confinement losses ############################## -def loss_particle_radial_drift_fullorbit(field, particles, timestep=None, maxtime=1e-5, num_steps=300, trace_tolerance=1e-5, model='GuidingCenterAdaptative',boundary=None): - particles.to_full_orbit(field) - tracing = Tracing(field=field, model=model, particles=particles, maxtime=maxtime, - timestep=timestep,times_to_trace=num_steps, atol=trace_tolerance,rtol=trace_tolerance,boundary=boundary) - xyz = tracing.trajectories[:,:, :3] - R_axis=field.r_axis - Z_axis=field.z_axis - #Ideally here one would differentiate in time through diffrax !TODO - r_cross=jnp.sqrt(jnp.square(jnp.sqrt(jnp.square(xyz[:,:,0])+jnp.square(xyz[:,:,1]))-R_axis+1.e-12)+jnp.square(xyz[:,:,2]-Z_axis+1.e-12)) - v_r_cross=jnp.diff(r_cross,axis=1)#/tracing.times_to_trace*tracing.maxtime - return (jnp.sum(jnp.square(jnp.average(v_r_cross,axis=1)))) - -def loss_particle_radial_drift(field, particles, timestep=None, maxtime=1e-5, num_steps=300, trace_tolerance=1e-5, model='GuidingCenterAdaptative',boundary=None): - tracing = Tracing(field=field, model=model, particles=particles, maxtime=maxtime, - timestep=timestep,times_to_trace=num_steps, atol=trace_tolerance,rtol=trace_tolerance,boundary=boundary) - xyz = tracing.trajectories[:,:, :3] - R_axis=field.r_axis - Z_axis=field.z_axis - #Ideally here one would differentiate in time through diffrax !TODO - r_cross=jnp.sqrt(jnp.square(jnp.sqrt(jnp.square(xyz[:,:,0])+jnp.square(xyz[:,:,1]))-R_axis+1.e-12)+jnp.square(xyz[:,:,2]-Z_axis+1.e-12)) - v_r_cross=jnp.diff(r_cross,axis=1)#/tracing.times_to_trace*tracing.maxtime - return (jnp.sum(jnp.square(jnp.average(v_r_cross,axis=1)))) - - -def loss_particle_alpha_drift(field, particles, timestep=None, maxtime=1e-5, num_steps=300, trace_tolerance=1e-5, model='GuidingCenterAdaptative',boundary=None): - tracing = Tracing(field=field, model=model, particles=particles, maxtime=maxtime, - timestep=timestep,times_to_trace=num_steps, atol=trace_tolerance,rtol=trace_tolerance,boundary=boundary) - xyz = tracing.trajectories[:,:, :3] - R_axis=field.r_axis - Z_axis=field.z_axis - #def theta(x,R_axis=R_axis,Z_axis=Z_axis): - # return jnp.arctan2(x[2]-Z_axis+1.e-12, jnp.sqrt(x[0]**2+x[1]**2)-R_axis+1.e-12) - #def phi(x): - # return jnp.arctan2(x[1], x[0]) - ##AbsB = vmap(self.field.AbsB)(xyz) - ##B_contravariant=vmap(self.field.B_contravariant,in_axes=(0))(xyz) - #Ideally here one would differentiate in time through diffrax !TODO - #grad_theta=vmap(jax.jacfwd(theta,argnums=0),in_axes=0)(xyz) - #grad_phi=vmap(jax.jacfwd(phi,argnums=0),in_axes=0)(xyz) - #v_theta=jnp.tensordot(v_xyz,grad_theta,axes=(1,1)) - #v_alpha=v_theta-jnp.tensordot(B_contravariant,grad_theta,axes=(1,1))/jnp.tensordot(B_contravariant,grad_phi,axes=(1,1))*jnp.tensordot(v_xyz,grad_phi,axes=(1,1)) - theta=jnp.arctan2(xyz[:,:,2]-Z_axis+1.e-12, jnp.sqrt(xyz[:,:,0]**2+xyz[:,:,1]**2)-R_axis+1.e-12) - v_theta=jnp.diff(theta,axis=1)#/tracing.times_to_trace*tracing.maxtime - return jnp.sum(jnp.square(jnp.average(v_theta,axis=1))) - -def loss_particle_gammac(field, particles, timestep=None, maxtime=1e-5, num_steps=300, trace_tolerance=1e-5, model='GuidingCenterAdaptative',boundary=None): - tracing = Tracing(field=field, model=model, particles=particles, maxtime=maxtime, - timestep=timestep,times_to_trace=num_steps, atol=trace_tolerance,rtol=trace_tolerance,boundary=boundary) - xyz = tracing.trajectories[:,:, :3] - R_axis=field.r_axis - Z_axis=field.z_axis - #def theta(x,R_axis=R_axis,Z_axis=Z_axis): - # return jnp.arctan2(x[2]-Z_axis+1.e-12, jnp.sqrt(x[0]**2+x[1]**2)-R_axis+1.e-12) - #def phi(x): - # return jnp.arctan2(x[1], x[0]) - ##AbsB = vmap(self.field.AbsB)(xyz) - ##B_contravariant=vmap(self.field.B_contravariant,in_axes=(0))(xyz) - #Ideally here one would differentiate in time through diffrax !TODO - #grad_theta=vmap(jax.jacfwd(theta,argnums=0),in_axes=0)(xyz) - #grad_phi=vmap(jax.jacfwd(phi,argnums=0),in_axes=0)(xyz) - #v_theta=jnp.tensordot(v_xyz,grad_theta,axes=(1,1)) - #v_alpha=v_theta-jnp.tensordot(B_contravariant,grad_theta,axes=(1,1))/jnp.tensordot(B_contravariant,grad_phi,axes=(1,1))*jnp.tensordot(v_xyz,grad_phi,axes=(1,1)) - r_cross=jnp.sqrt(jnp.square(jnp.sqrt(jnp.square(xyz[:,:,0])+jnp.square(xyz[:,:,1]))-R_axis+1.e-12)+jnp.square(xyz[:,:,2]-Z_axis+1.e-12)) - v_r_cross=jnp.diff(r_cross,axis=1)#/tracing.times_to_trace*tracing.maxtime - theta=jnp.arctan2(xyz[:,:,2]-Z_axis+1.e-12, jnp.sqrt(xyz[:,:,0]**2+xyz[:,:,1]**2)-R_axis+1.e-12) - v_theta=jnp.diff(theta,axis=1)#/tracing.times_to_trace*tracing.maxtime - #return jnp.sum(jnp.square((2./jnp.pi*jnp.absolute(jnp.arctan2(jnp.average(v_r_cross,axis=1),jnp.average(v_theta,axis=1)))))) - return jnp.max(2./jnp.pi*jnp.absolute(jnp.arctan2(jnp.average(v_r_cross,axis=1),jnp.average(v_theta,axis=1)))) - -def loss_particle_rcross_final(field, particles, timestep=None, maxtime=1e-5, num_steps=300, trace_tolerance=1e-5, model='GuidingCenterAdaptative',boundary=None): - tracing = Tracing(field=field, model=model, particles=particles, maxtime=maxtime, - timestep=timestep,times_to_trace=num_steps, atol=trace_tolerance,rtol=trace_tolerance,boundary=boundary) - xyz = tracing.trajectories[:,:, :3] - R_axis=field.r_axis - Z_axis=field.z_axis - r_cross=jnp.sqrt(jnp.square(jnp.sqrt(jnp.square(xyz[:,:,0])+jnp.square(xyz[:,:,1]))-R_axis+1.e-12)+jnp.square(xyz[:,:,2]-Z_axis+1.e-12)) - return jnp.linalg.norm((jnp.average(r_cross,axis=1))) - - - -def loss_particle_Br(field, particles, timestep=None, maxtime=1e-5, num_steps=300, trace_tolerance=1e-5, model='GuidingCenterAdaptative',boundary=None): - tracing = Tracing(field=field, model=model, particles=particles, maxtime=maxtime, - timestep=timestep,times_to_trace=num_steps, atol=trace_tolerance,rtol=trace_tolerance,boundary=boundary) - xyz = tracing.trajectories[:,:, :3] - R_axis=tracing.field.r_axis - Z_axis=tracing.field.z_axis - fac_xy=jnp.sqrt(jnp.square(xyz[:,:,0])+jnp.square(xyz[:,:,1])) - r_cross=jnp.sqrt(jnp.square(fac_xy-R_axis+1.e-12)+jnp.square(xyz[:,:,2]-Z_axis+1.e-12)) - dr_cross_dx=(fac_xy-R_axis+1.e-12)*xyz[:,:,0]/(r_cross*fac_xy+1.e-12) - dr_cross_dy=(fac_xy-R_axis+1.e-12)*xyz[:,:,1]/(r_cross*fac_xy+1.e-12) - dr_cross_dz=(xyz[:,:,2]-Z_axis+1.e-12)/(r_cross+1.e-12) - B_particle=jax.vmap(jax.vmap(field.B_covariant,in_axes=0),in_axes=0)(xyz) - B_r=jnp.multiply(B_particle[:,:,0],dr_cross_dx)+jnp.multiply(B_particle[:,:,1],dr_cross_dy)+jnp.multiply(B_particle[:,:,2],dr_cross_dz) - return jnp.sum(jnp.abs(B_r)) - -def loss_particle_iota(field, particles, timestep=None, maxtime=1e-5, num_steps=300, trace_tolerance=1e-5, model='GuidingCenterAdaptative',boundary=None,target_iota=0.41): - tracing = Tracing(field=field, model=model, particles=particles, maxtime=maxtime, - timestep=timestep,times_to_trace=num_steps, atol=trace_tolerance,rtol=trace_tolerance,boundary=boundary) - xyz = tracing.trajectories[:,:, :3] - R_axis=tracing.field.r_axis - Z_axis=tracing.field.z_axis - #theta=jnp.arctan2(xyz[:,:,2]-Z_axis+1.e-12, jnp.sqrt(xyz[:,:,0]**2+xyz[:,:,1]**2)-R_axis+1.e-12) - fac_xy=jnp.sqrt(jnp.square(xyz[:,:,0])+jnp.square(xyz[:,:,1])) - dtheta_dx=-(xyz[:,:,2]-Z_axis+1.e-12)*xyz[:,:,0]/(fac_xy+1.e-12)/(jnp.square(fac_xy-R_axis+1.e-12)+jnp.square(xyz[:,:,2]-Z_axis+1.e-12)+1.e-12) - dtheta_dy=-(xyz[:,:,2]-Z_axis+1.e-12)*xyz[:,:,1]/(fac_xy+1.e-12)/(jnp.square(fac_xy-R_axis+1.e-12)+jnp.square(xyz[:,:,2]-Z_axis+1.e-12)+1.e-12) - dtheta_dz=(fac_xy-R_axis+1.e-12)/(jnp.square(fac_xy-R_axis+1.e-12)+jnp.square(xyz[:,:,2]-Z_axis+1.e-12)+1.e-12) - dphi_dx=-(xyz[:,:,1])/(fac_xy**2+1.e-12) - dphi_dy=xyz[:,:,0]/(fac_xy**2+1.e-12) - B_particle=jax.vmap(jax.vmap(tracing.field.B_covariant,in_axes=0),in_axes=0)(xyz) - B_theta=jnp.multiply(B_particle[:,:,0],dtheta_dx)+jnp.multiply(B_particle[:,:,1],dtheta_dy)+jnp.multiply(B_particle[:,:,2],dtheta_dz) - B_phi=jnp.multiply(B_particle[:,:,0],dphi_dx)+jnp.multiply(B_particle[:,:,1],dphi_dy) - return jnp.sum(jnp.maximum(target_iota-B_theta/B_phi,0.0)) - - - - - - - - -################### B ON SURAFCE LOSSES ########################## -@partial(jit, static_argnames=['npoints']) -def normB_axis(field, npoints=15): - R_axis=field.r_axis - phi_array = jnp.linspace(0, 2 * jnp.pi, npoints) - B_axis = vmap(lambda phi: field.AbsB(jnp.array([R_axis * jnp.cos(phi), R_axis * jnp.sin(phi), 0])))(phi_array) - return B_axis - -@partial(jit, static_argnames=['npoints', 'target_B']) -def loss_normB_axis_average(field,npoints=15, target_B=5.7): - B_axis = normB_axis(field, npoints) - return jnp.abs(jnp.average(B_axis)-target_B) - - -def loss_BdotN(field,surface): - return jnp.sum(jnp.abs(BdotN_over_B(surface, field))) - -def _sqrt_sum_positive(u): - """sqrt(sum(max(u, 0))) with a zero (not NaN) gradient where the constraint is met.""" - total = jnp.sum(jnp.maximum(u, 0.0)) - return jnp.where(total > 0, jnp.sqrt(jnp.where(total > 0, total, 1.0)), 0.0) - -@partial(jit, static_argnames=['target_tol']) -def loss_BdotN_constraint(field,surface,target_tol=1.e-6): - bdotn_over_b = BdotN_over_B(surface, field) - return _sqrt_sum_positive(jnp.square(bdotn_over_b)-target_tol) - - -########################### B ON SURAFCE LOSSES FOR STOCHASTIC OPTIMIZATION ########################## -def copy_coils_from_field(field): - return field.coils.copy() - -@partial(jit, static_argnames=['sampler']) -def perturbed_field_from_field(field, key, sampler): - coils = copy_coils_from_field(field) - base_key = jax.random.key(key) - split_keys = jax.random.split(base_key, 2) - coils = perturb_curves_systematic(coils, sampler, key=split_keys[0]) - coils = perturb_curves_statistic(coils, sampler, key=split_keys[1]) - return BiotSavart(coils) - - -@partial(jit, static_argnames=['sampler']) -def loss_bdotn_stochastic(field, surface, sampler, keys): - def perturbed_loss(key): - perturbed_field = perturbed_field_from_field(field, key, sampler) - bdotn_over_b = BdotN_over_B(surface, perturbed_field) - return jnp.sum(jnp.abs(bdotn_over_b)) - - return jnp.mean(jax.vmap(perturbed_loss)(keys)) - - -@partial(jit, static_argnames=['sampler', 'target_tol']) -def constraint_bdotn_stochastic(field, surface, sampler, keys, target_tol=1.0e-6): - def perturbed_square(key): - perturbed_field = perturbed_field_from_field(field, key, sampler) - return jnp.square(BdotN_over_B(surface, perturbed_field)) - - expected_square = jnp.mean(jax.vmap(perturbed_square)(keys), axis=0) - return _sqrt_sum_positive(expected_square - target_tol) - - - - -######################### COIL GEOMETRY LOSSES ################################# - -@partial(jit, static_argnames=['max_coil_length']) -def loss_coil_length(coils, max_coil_length=0): - return jnp.square(coils.length/max_coil_length - 1) - -@partial(jit, static_argnames=['max_coil_curvature']) -def loss_coil_curvature(coils, max_coil_curvature=0): - pointwise_curvature_loss = jnp.square(jnp.maximum(coils.curvature-max_coil_curvature, 0)) - return jnp.mean(pointwise_curvature_loss*jnp.linalg.norm(coils.gamma_dash, axis=-1), axis=1) - -def compute_candidates(coils, min_separation): - centers = coils.curves.curves[:, :, 0] - a_n = coils.curves.curves[:, :, 2 : 2*coils.order+1 : 2] - b_n = coils.curves.curves[:, :, 1 : 2*coils.order : 2] - radii = jnp.sum(jnp.linalg.norm(a_n, axis=1)+jnp.linalg.norm(b_n, axis=1), axis=1) - - i_vals, j_vals = jnp.triu_indices(len(coils), k=1) - centers_dists = jnp.linalg.norm(centers[i_vals] - centers[j_vals], axis=1) - mask = centers_dists <= min_separation + radii[i_vals] + radii[j_vals] - - return i_vals[mask], j_vals[mask] - - -# Blockwise, memory-efficient coil separation loss -@partial(jit, static_argnames=["min_separation", "block_size"]) -def loss_coil_separation(coils, min_separation, candidates=None, block_size=None): - """ - Memory-efficient coil separation loss using blockwise vmap. - Args: - coils: Coils object - min_separation: Minimum allowed separation - candidates: Optional tuple of (i, j) coil index arrays - block_size: Block size for memory efficiency. If None, uses full vmap (no chunking) - Returns: - Scalar loss (sum over all coil pairs) - """ - if candidates is None: - candidates = jnp.triu_indices(len(coils), k=1) - - def pair_loss(i, j): - gamma_i = coils.gamma[i] - gamma_dash_i = jnp.linalg.norm(coils.gamma_dash[i], axis=-1) - gamma_j = coils.gamma[j] - gamma_dash_j = jnp.linalg.norm(coils.gamma_dash[j], axis=-1) - n_points = gamma_i.shape[0] - - # If block_size is None, use full vmap (no chunking) - use_block_size = min(n_points, n_points if block_size is None else block_size) - n_blocks = (n_points + use_block_size - 1) // use_block_size - padded_points = n_blocks * use_block_size - pad_width = padded_points - n_points - - gamma_j_blocks = jnp.pad(gamma_j, ((0, pad_width), (0, 0))).reshape(n_blocks, use_block_size, 3) - gamma_dash_j_blocks = jnp.pad(gamma_dash_j, (0, pad_width)).reshape(n_blocks, use_block_size) - valid_blocks = (jnp.arange(padded_points) < n_points).reshape(n_blocks, use_block_size) - - def block_sum(block_gamma_j, block_gamma_dash_j, block_valid): - dists_block = jnp.linalg.norm(gamma_i[:, None, :] - block_gamma_j[None, :, :], axis=2) - penalty_block = jnp.maximum(0, min_separation - dists_block) - weighted_penalty = ( - jnp.square(penalty_block) - * gamma_dash_i[:, None] - * block_gamma_dash_j[None, :] - * block_valid[None, :] - ) - return jnp.sum(weighted_penalty) - - total = jnp.sum(jax.vmap(block_sum)(gamma_j_blocks, gamma_dash_j_blocks, valid_blocks)) - norm = gamma_i.shape[0] * gamma_j.shape[0] - return total / norm - - losses = jax.vmap(pair_loss)(*candidates) - return jnp.sum(losses) - -# Blockwise, memory-efficient coil-surface distance loss -@partial(jit, static_argnames=["min_distance", "block_size"]) -def loss_coil_surface_distance(coils, surface, min_distance, block_size=None): - """ - Memory-efficient coil-surface distance loss using blockwise vmap and symmetry reduction. - Args: - coils: Coils object - surface: Surface object (with gamma, unitnormal) - min_distance: Minimum allowed coil-surface distance - block_size: Block size for memory efficiency. If None, uses full vmap (no chunking) - nfp: Number of field periods - stellsym: Whether stellarator symmetry is present - Returns: - Scalar loss (sum over all relevant coil-surface pairs) - """ - n_coils = coils.gamma.shape[0] - n_points_coil = coils.gamma.shape[1] - surface_points = surface.gamma.reshape(-1, 3) - n_points_surface = surface_points.shape[0] - - # Only check unique coils for symmetry - if coils.stellsym: - n_unique_coils = n_coils // (2 * coils.nfp) - else: - n_unique_coils = n_coils // coils.nfp - n_unique_coils = max(1, n_unique_coils) - unique_coil_indices = jnp.arange(n_unique_coils) - - def single_coil_loss(idx): - gamma_i = coils.gamma[idx] - gamma_dash_i = coils.gamma_dash[idx] - gamma_dash_norm = jnp.linalg.norm(gamma_dash_i, axis=1) - n_points = gamma_i.shape[0] - - # If block_size is None, use full vmap (no chunking) - use_block_size = min(n_points_surface, n_points_surface if block_size is None else block_size) - n_blocks = (n_points_surface + use_block_size - 1) // use_block_size - padded_points = n_blocks * use_block_size - pad_width = padded_points - n_points_surface - - surface_point_blocks = jnp.pad(surface_points, ((0, pad_width), (0, 0))).reshape(n_blocks, use_block_size, 3) - valid_blocks = (jnp.arange(padded_points) < n_points_surface).reshape(n_blocks, use_block_size) - - def block_sum(block_surface_points, block_valid): - dists_block = jnp.linalg.norm(gamma_i[:, None, :] - block_surface_points[None, :, :], axis=2) - penalty_block = jnp.maximum(0, min_distance - dists_block) - weighted_penalty = jnp.square(penalty_block) * gamma_dash_norm[:, None] * block_valid[None, :] - return jnp.sum(weighted_penalty) - - total = jnp.sum(jax.vmap(block_sum)(surface_point_blocks, valid_blocks)) - norm = gamma_i.shape[0] * n_points_surface - return total / norm - - losses = jax.vmap(single_coil_loss)(unique_coil_indices) - return jnp.sum(losses) - - -# Blockwise vmap linking number loss (memory efficient, fully differentiable) -@partial(jit, static_argnames=["block_size"]) -def loss_linkingnumber(coils, candidates=None, block_size=None): - if candidates is None: - candidates = jnp.triu_indices(len(coils), k=1) - dphi = coils.curves.quadpoints[1] - coils.curves.quadpoints[0] - - def pair_linking(i, j): - gamma_i = coils.gamma[i] - gamma_dash_i = coils.gamma_dash[i] - gamma_j = coils.gamma[j] - gamma_dash_j = coils.gamma_dash[j] - n_points = gamma_j.shape[0] - - # If block_size is None, use full vmap (no chunking) - use_block_size = min(n_points, n_points if block_size is None else block_size) - n_blocks = (n_points + use_block_size - 1) // use_block_size - padded_points = n_blocks * use_block_size - pad_width = padded_points - n_points - - gamma_j_blocks = jnp.pad(gamma_j, ((0, pad_width), (0, 0))).reshape(n_blocks, use_block_size, 3) - gamma_dash_j_blocks = jnp.pad(gamma_dash_j, ((0, pad_width), (0, 0))).reshape(n_blocks, use_block_size, 3) - valid_blocks = (jnp.arange(padded_points) < n_points).reshape(n_blocks, use_block_size) - - def block_sum(block_gamma_j, block_gamma_dash_j, block_valid): - def integrand(r2, dr2): - diff = gamma_i - r2 - cross = jnp.cross(gamma_dash_i, dr2) - norm = jnp.linalg.norm(diff, axis=1) - return jnp.sum(diff * cross, axis=1) / (norm**3 + 1e-12) - - block_vals = jax.vmap(integrand, in_axes=(0, 0))(block_gamma_j, block_gamma_dash_j) - return jnp.sum(block_vals * block_valid[:, None]) - - total = jnp.sum(jax.vmap(block_sum)(gamma_j_blocks, gamma_dash_j_blocks, valid_blocks)) - linking = total * (dphi ** 2) / (4 * jnp.pi) - return jnp.abs(linking) - - losses = jax.vmap(pair_linking)(*candidates) - return jnp.sum(losses) - - - - -# Lorentz force loss: accepts Coils object, keyword args, JAX-friendly -@partial(jit, static_argnames=["p", "threshold", "block_size"]) -def loss_lorentz_force_coils(coils, p=1, threshold=0.5e6, block_size=None, conductor_radius=None): - """ - Loss function penalizing Lorentz force on coils using Landreman-Hurwitz method. - - Matches SIMSOPT's ``LpCurveForce``:: - - J = (1/p) sum_i (1/L_i) int max(|dF_i/dl| - F_0, 0)^p dl_i - - so it is independent of the quadrature resolution. The self-force uses the - regularized self field of a circular conductor of radius ``a`` - (``delta = a**2 / sqrt(e)``; Hurwitz, Landreman & Antonsen, - arXiv:2310.09313). - - Args: - coils: Coils object (with gamma, gamma_dash, gamma_dashdash, currents, quadpoints) - p: Power for penalty (default 1) - threshold: Force threshold F_0 in N/m (default 0.5e6) - block_size: Block size for memory efficiency. If None, uses full vmap (no chunking) - conductor_radius: Radius of the conductor cross-section in meters - (required: the self-force depends logarithmically on it). - Returns: - Scalar loss (sum over all coils) - """ - if conductor_radius is None: - raise ValueError("loss_lorentz_force_coils needs conductor_radius (the coil cross-section radius in m)") - n_coils = coils.gamma.shape[0] - indices = jnp.arange(n_coils) - other_indices = jnp.array([ - [j for j in range(n_coils) if j != i] - for i in range(n_coils) - ], dtype=jnp.int32) - - def single_coil_loss(idx): - gamma_i = coils.gamma[idx] - gamma_dash_i = coils.gamma_dash[idx] - gamma_dashdash_i = coils.gamma_dashdash[idx] - current_i = coils.currents[idx] - quadpoints = coils.curves.quadpoints - regularization = regularization_circ(conductor_radius) - other_idx = other_indices[idx] - gamma_others = coils.gamma[other_idx] - gamma_dash_others = coils.gamma_dash[other_idx] - gamma_dashdash_others = coils.gamma_dashdash[other_idx] - currents_others = coils.currents[other_idx] - biot_savart = BiotSavart_from_gamma(gamma_others, gamma_dash_others, gamma_dashdash_others, currents_others) - n_points = gamma_i.shape[0] - use_block_size = min(n_points, n_points if block_size is None else block_size) - n_blocks = (n_points + use_block_size - 1) // use_block_size - padded_points = n_blocks * use_block_size - pad_width = padded_points - n_points - - gamma_i_blocks = jnp.pad(gamma_i, ((0, pad_width), (0, 0))).reshape(n_blocks, use_block_size, 3) - valid_blocks = (jnp.arange(padded_points) < n_points).reshape(n_blocks, use_block_size) - - def block_field(block_gamma_i, block_valid): - block_B = jax.vmap(biot_savart.B)(block_gamma_i) - return block_B * block_valid[:, None] - - block_B_mutual = jax.vmap(block_field)(gamma_i_blocks, valid_blocks).reshape(padded_points, 3)[:n_points] - block_gammadash_norm = jnp.linalg.norm(gamma_dash_i, axis=1) - block_tangent = gamma_dash_i / block_gammadash_norm[:, None] - block_B_self = B_regularized_pure( - gamma_i, gamma_dash_i, gamma_dashdash_i, - quadpoints, current_i, regularization - ) - block_force = jnp.cross(current_i * block_tangent, block_B_self + block_B_mutual) - block_force_norm = jnp.linalg.norm(block_force, axis=1) - # Uniform quadrature on [0, 1): int f dl = mean(f |gamma'|), L = mean(|gamma'|). - integral = jnp.mean(jnp.maximum(block_force_norm - threshold, 0) ** p * block_gammadash_norm) - return integral / jnp.mean(block_gammadash_norm) / p - - penalties = jax.vmap(single_coil_loss)(indices) - return jnp.sum(penalties) - - - - - - -def B_regularized_singularity_term(rc_prime, rc_prime_prime, regularization): - """The term in the regularized Biot-Savart law in which the near-singularity - has been integrated analytically. - - regularization corresponds to delta * a * b for rectangular x-section, or to - a²/√e for circular x-section. - - A prefactor of μ₀ I / (4π) is not included. - - The derivatives rc_prime, rc_prime_prime refer to an angle that goes up to - 2π, not up to 1. - """ - norm_rc_prime = jnp.linalg.norm(rc_prime, axis=1) - return jnp.cross(rc_prime, rc_prime_prime) * (0.5 * (-2 + jnp.log(64 * norm_rc_prime * norm_rc_prime / regularization)) / (norm_rc_prime**3))[:, None] - - -def B_regularized_pure(gamma, gammadash, gammadashdash, quadpoints, current, regularization): - # The factors of 2π in the next few lines come from the fact that simsopt - # uses a curve parameter that goes up to 1 rather than 2π. - phi = quadpoints * 2 * jnp.pi - rc = gamma - rc_prime = gammadash / 2 / jnp.pi - rc_prime_prime = gammadashdash / 4 / jnp.pi**2 - n_quad = phi.shape[0] - dphi = 2 * jnp.pi / n_quad - analytic_term = B_regularized_singularity_term(rc_prime, rc_prime_prime, regularization) - dr = rc[:, None] - rc[None, :] - first_term = jnp.cross(rc_prime[None, :], dr) / ((jnp.sum(dr * dr, axis=2) + regularization) ** 1.5)[:, :, None] - cos_fac = 2 - 2 * jnp.cos(phi[None, :] - phi[:, None]) - denominator2 = cos_fac * jnp.sum(rc_prime * rc_prime, axis=1)[:, None] + regularization - factor2 = 0.5 * cos_fac / denominator2**1.5 - second_term = jnp.cross(rc_prime_prime, rc_prime)[:, None, :] * factor2[:, :, None] - integral_term = dphi * jnp.sum(first_term + second_term, 1) - return current * mu_0 / (4 * jnp.pi) * (analytic_term + integral_term) - - - -def regularization_circ(a): - """Regularization for a circular conductor""" - return a**2 / jnp.sqrt(jnp.e) - - -def regularization_rect(a, b): - """Regularization for a rectangular conductor""" - return a * b * rectangular_xsection_delta(a, b) - -def rectangular_xsection_k(a, b): - """Auxiliary function for field in rectangular conductor""" - return (4 * b) / (3 * a) * jnp.arctan(a/b) + (4*a)/(3*b)*jnp.arctan(b/a)+ (b**2)/(6*a**2)*jnp.log(b/a) + (a**2)/(6*b**2)*jnp.log(a/b) - (a**4 - 6*a**2*b**2 + b**4)/(6*a**2*b**2)*jnp.log(a/b+b/a) - - -def rectangular_xsection_delta(a, b): - """Auxiliary function for field in rectangular conductor""" - return jnp.exp(-25/6 + rectangular_xsection_k(a, b)) - - -#def loss_BdotN_only_with_perturbation(x, vmec, dofs_curves, currents_scale, nfp,n_segments=60, stellsym=True, N_stells=10): -# """ -# Compute the loss function for BdotN with a perturbation applied to the BdotN value.): -# field=field_from_dofs(x,dofs_curves, currents_scale, nfp,n_segments, stellsym) -# -# bdotn_over_b = BdotN_over_B(vmec.surface, field) -# -# # Apply perturbation to the BdotN value -# bdotn_over_b += perturbation -# -# bdotn_over_b_loss = jnp.sum(jnp.abs(bdotn_over_b)) - -# return bdotn_over_b_loss - - - -####################### SURFACE GEOMETRY LOSSES ########################## From cad01368a3b9624276ab9aee3a9a2dd3f2ad84fb Mon Sep 17 00:00:00 2001 From: Rogerio Jorge Date: Tue, 10 Nov 2026 20:28:52 -0600 Subject: [PATCH 3/6] Apply the derived timestep and 1e-7 tolerance in the shared loss orbit helper --- essos/objective_functions.py | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/essos/objective_functions.py b/essos/objective_functions.py index ac3870dd..97371a91 100644 --- a/essos/objective_functions.py +++ b/essos/objective_functions.py @@ -50,7 +50,7 @@ def loss_r0_near_axis(field_nearaxis, r0_target=1.0): ##############################Particle confinement losses ############################## -def _orbit(field, particles, timestep=1.e-8, maxtime=1e-5, num_steps=300, trace_tolerance=1e-5, +def _orbit(field, particles, timestep=None, maxtime=1e-5, num_steps=300, trace_tolerance=1e-7, model='GuidingCenterAdaptative', boundary=None): """Trace and return xyz, the cylindrical radius and the offsets (R, Z) from the axis.""" xyz = Tracing(field=field, model=model, particles=particles, maxtime=maxtime, timestep=timestep, From 91aedfe5cefb250139b4ca2e6c2b103270df7ef6 Mon Sep 17 00:00:00 2001 From: Rogerio Jorge Date: Tue, 10 Nov 2026 21:13:52 -0600 Subject: [PATCH 4/6] Derive the default timestep from concrete scales, 100 steps per transit on VMEC, convergence tests and tracing docs --- README.md | 2 +- docs/index.rst | 3 ++- docs/tracing.rst | 33 ++++++++++++++++++++++++++ essos/dynamics.py | 23 ++++++++++++------ tests/test_dynamics.py | 53 ++++++++++++++++++++++++++++++++++++++++++ 5 files changed, 105 insertions(+), 9 deletions(-) create mode 100644 docs/tracing.rst diff --git a/README.md b/README.md index 492080d7..ba1f1453 100644 --- a/README.md +++ b/README.md @@ -270,7 +270,7 @@ the `wout` directly and DESC fits it. ± is the binomial standard error. and read the per-line mask from `tracing.boundary_hits`. - **Step budget and defaults.** `max_steps` (default 16 times the steps of a fixed-step solve) bounds every Diffrax solve and a `RuntimeWarning` reports orbits that did not finish. `timestep` defaults to 1/400 of the - transit time `R0 / v`, `rtol` to `1e-8` and `atol` to `rtol`. + transit time `R0 / v` (1/100 on a VMEC field), `rtol` to `1e-8` and `atol` to `rtol`. - **Progress bars** are off by default; pass `progress=True` when interactive. With `particle_batch_size=n` particles are traced `n` at a time and the bar counts completed particles (batches are bypassed under `jax.jit`/`grad`). diff --git a/docs/index.rst b/docs/index.rst index 878336f4..e75d0ca3 100644 --- a/docs/index.rst +++ b/docs/index.rst @@ -19,4 +19,5 @@ stellarator coils to improve plasma confinement. :maxdepth: 2 :caption: Contents: - getting_started \ No newline at end of file + getting_started + tracing \ No newline at end of file diff --git a/docs/tracing.rst b/docs/tracing.rst new file mode 100644 index 00000000..1ee969e2 --- /dev/null +++ b/docs/tracing.rst @@ -0,0 +1,33 @@ +Tracing accuracy and defaults +============================= + +``Tracing`` has an adaptive and a fixed-step family of models. Both integrate with Dopri8 by default. + +.. image:: _static/tracing_work_precision.png + :alt: Error against wall time for adaptive and fixed-step guiding-centre traces, old and new defaults. + +Error against wall time for 6 guiding centres over 40 transits, measured against a Dopri8 reference at +``rtol = atol = 1e-12`` (wall time with the compiled program cached). Circles are the adaptive defaults, squares the +fixed-step defaults; orange is the old setting and blue the current one. + +Adaptive or fixed +----------------- + +* Use the adaptive models (``GuidingCenterAdaptative``, ``FullOrbitAdaptative``) unless a fixed step is required. Their + cost follows the tolerance and, on a coil field, they reach a given energy error about 4 times faster than a fixed step (4e-8 in 2.4 s against 9.4 s). +* The fixed-step models need a step small enough for the field: on a coil field the energy error is 3e-2 at 100 steps + per transit and 4e-8 at 400. A smooth VMEC field is converged from about 100. + +Defaults +-------- + +* ``rtol=1e-8`` and ``atol=None``, which means ``atol = rtol``. An absolute tolerance above ``rtol`` floors the error + (positions are about 1 m), as the orange dashed curve shows. +* ``timestep=None`` is 1/400 of the transit time ``R0 / v`` (1/100 for a VMEC field), with ``R0 = field.r_axis`` and + ``v`` the largest particle speed. For adaptive models it only sets the first trial step. These values must be concrete: + under ``jax.grad`` with traced coil degrees of freedom or energies a fixed-step model raises an error asking for an + explicit ``timestep``. +* ``max_steps=None`` is 16 times the steps of a fixed-step solve over ``maxtime``, enough for adaptive tolerances + down to about 1e-12. +* An orbit that ends non-finite or reaches ``max_steps`` raises a ``RuntimeWarning``; raise ``max_steps`` or lower the + tolerance. diff --git a/essos/dynamics.py b/essos/dynamics.py index 3471e357..037f3d10 100644 --- a/essos/dynamics.py +++ b/essos/dynamics.py @@ -777,8 +777,9 @@ def wrapped(t, y, args): return wrapped -# Steps per transit time R0/speed of the default timestep: Dopri8 conserves energy to ~1e-6 (see tests). -_STEPS_PER_TRANSIT = 400 +# Steps per transit time R0/speed of the default timestep. 400 holds the Dopri8 energy error of a coil field at +# ~1e-7; the smooth VMEC Fourier field is converged (endpoint 1e-10) from 100 and costs 2.3 times more at 400. +_STEPS_PER_TRANSIT = {Vmec: 100} def _warn_unfinished(count, max_steps): @@ -949,12 +950,20 @@ def __init__(self, trajectories_input=None, initial_conditions=None, times_to_tr self.initial_conditions = initial_conditions self.times_to_trace = times_to_trace self.maxtime = maxtime - # timestep=None: 1/_STEPS_PER_TRANSIT of the transit time R0/speed; maxtime/100 for a field line, or when - # the field or particles are being differentiated (traced values cannot size a step). + # timestep=None: 1/_STEPS_PER_TRANSIT (400, 100 for VMEC) of the transit time R0/speed, evaluated eagerly + # (also under jit); maxtime/100 for a field line. A traced R0 or speed (coil dofs, energy under jax.grad) cannot size a step. if timestep is None: - scales = [getattr(field, "r_axis", 1.0), jnp.max(particles.total_speed) if particles is not None else jnp.nan] - timestep = (maxtime / 100 if any(isinstance(x, jax.core.Tracer) for x in scales) or np.isnan(scales[1]) - else float(abs(scales[0]) / scales[1]) / _STEPS_PER_TRANSIT) + with jax.ensure_compile_time_eval(): + scales = [getattr(field, "r_axis", 1.0), jnp.max(particles.total_speed) if particles is not None else 1.0] + if particles is None: + timestep = maxtime / 100 + elif any(isinstance(x, jax.core.Tracer) for x in scales): + if model not in ('GuidingCenterAdaptative', 'FullOrbitAdaptative'): + raise ValueError("timestep=None needs the axis radius and particle speed as concrete values; " + "they are traced here, so pass an explicit timestep") + timestep = maxtime / 100 # only the first trial step of an adaptive solve + else: + timestep = float(abs(scales[0]) / scales[1]) / _STEPS_PER_TRANSIT.get(type(field), 400) self.timestep = timestep self.rtol = rtol # An absolute tolerance above rtol floors the error, so atol follows rtol by default. diff --git a/tests/test_dynamics.py b/tests/test_dynamics.py index 20d80fb4..2467c099 100644 --- a/tests/test_dynamics.py +++ b/tests/test_dynamics.py @@ -1256,3 +1256,56 @@ def test_truncated_tracing_warns(qa_coil_alphas): field, particles = qa_coil_alphas with pytest.warns(RuntimeWarning, match="did not finish"): Tracing(field=field, model="GuidingCenterAdaptative", particles=particles, maxtime=1e-5, max_steps=20) + + +@pytest.mark.parametrize("method, steps, order", [ + ("rk4", (8e-7, 4e-7, 2e-7, 1e-7), 4), ("dopri5", (8e-7, 4e-7, 2e-7, 1e-7), 5), ("dopri8", (5e-6, 2.5e-6, 1.25e-6, 6.25e-7), 8)]) +def test_fixed_step_error_converges_at_the_scheme_order(method, steps, order): + """The global error of a fixed-step scheme of order p falls as h**p (Hairer, Norsett and Wanner 1993, II.3).""" + from essos.boozer import trace_boozer + from tests.test_boozer import tokamak, V0, M, Q + births = (jnp.full(4, .3), jnp.linspace(.5, 3, 4), jnp.zeros(4), jnp.linspace(-.6, .6, 4)) + kwargs = dict(speed=V0, mass=M, charge=Q, tmax=4e-5, n_save=2, devices=jax.devices()[:1]) + scale = np.array([1, 1, 1, V0]) + final = lambda m, h: trace_boozer(tokamak(), *births, timestep=h, method=m, **kwargs).states[:, -1, :4] + reference = final("dopri8", 2e-7) # error ~1e-15 at this step + errors = [np.max(np.abs(final(method, h) - reference) / scale) for h in steps] + assert np.polyfit(np.log(steps), np.log(errors), 1)[0] == pytest.approx(order, abs=0.6) + + +def test_full_orbit_magnetic_moment_is_an_adiabatic_invariant(qa_coil_alphas): + """mu = m v_perp^2 / 2B oscillates at O(rho/L) with the gyrophase but its gyro-average is conserved + (Littlejohn 1983; Cary and Brizard 2009), and the energy is exact in a static field.""" + field, particles = qa_coil_alphas + cold = Particles(initial_xyz=particles.initial_xyz, initial_vparallel_over_v=particles.initial_vparallel_over_v, + energy=40 * 1.602176634e-19, field=field) + tracing = Tracing(field=field, model="FullOrbitAdaptative", particles=cold, maxtime=2e-5, times_to_trace=400) + y = tracing.trajectories + B = jax.vmap(jax.vmap(field.AbsB))(y[:, :, :3]) + vpar = jnp.sum(y[:, :, 3:6] * jax.vmap(jax.vmap(field.B))(y[:, :, :3]), -1) / B + mu = np.asarray(cold.mass * (jnp.sum(y[:, :, 3:6]**2, -1) - vpar**2) / (2 * B)) + windows = mu.reshape(2, 4, 100).mean(-1) # ten gyro periods each + assert np.all(mu.max(1) / mu.min(1) - 1 > 5e-3) + assert np.all(np.abs(windows / windows[:, :1] - 1) < 1e-3) + assert float(jnp.max(jnp.abs(tracing.energy() / cold.energy - 1))) < 1e-6 + + +def test_default_timestep_is_a_transit_fraction_and_survives_grad(qa_coil_alphas): + field, particles = qa_coil_alphas + speed = float(particles.total_speed.max()) + kwargs = dict(model="GuidingCenter", maxtime=1e-7, times_to_trace=2) + assert Tracing(field=field, particles=particles, **kwargs).timestep == pytest.approx(float(field.r_axis) / speed / 400) + vmec = Vmec(WOUT_QA, ntheta=8, nphi=8) + near_axis = _near_axis_particles() + assert Tracing(field=vmec, particles=near_axis, **kwargs).timestep == pytest.approx( + vmec.r_axis / float(near_axis.total_speed.max()) / 100) + + def end(x0, energy=particles.energy): + launched = Particles(initial_xyz=x0, initial_vparallel_over_v=particles.initial_vparallel_over_v, energy=energy) + tracing = Tracing(field=field, particles=launched, **kwargs) + assert tracing.timestep == pytest.approx(float(field.r_axis) / speed / 400) # concrete R0 and speed under grad + return tracing.trajectories[0, -1, 0] + + assert jnp.isfinite(jax.grad(end)(particles.initial_xyz)).all() + with pytest.raises(ValueError, match="explicit timestep"): + jax.grad(lambda energy: end(particles.initial_xyz, energy))(particles.energy) From 5a18e0e7c825462bf64cd10ae83405f020d20fc4 Mon Sep 17 00:00:00 2001 From: Rogerio Jorge Date: Tue, 10 Nov 2026 21:13:58 -0600 Subject: [PATCH 5/6] Add the tracing work-precision figure --- docs/_static/tracing_work_precision.png | Bin 0 -> 33270 bytes 1 file changed, 0 insertions(+), 0 deletions(-) create mode 100644 docs/_static/tracing_work_precision.png diff --git a/docs/_static/tracing_work_precision.png b/docs/_static/tracing_work_precision.png new file mode 100644 index 0000000000000000000000000000000000000000..0185b373abd6809a53087afb4700daf990649d3f GIT binary patch literal 33270 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 z Date: Tue, 10 Nov 2026 21:29:36 -0600 Subject: [PATCH 6/6] Keep the 1e6 step budget when an adaptive trace cannot derive its timestep --- docs/tracing.rst | 2 +- essos/dynamics.py | 3 ++- tests/test_dynamics.py | 12 ++++++++++++ 3 files changed, 15 insertions(+), 2 deletions(-) diff --git a/docs/tracing.rst b/docs/tracing.rst index 1ee969e2..580b33d8 100644 --- a/docs/tracing.rst +++ b/docs/tracing.rst @@ -28,6 +28,6 @@ Defaults under ``jax.grad`` with traced coil degrees of freedom or energies a fixed-step model raises an error asking for an explicit ``timestep``. * ``max_steps=None`` is 16 times the steps of a fixed-step solve over ``maxtime``, enough for adaptive tolerances - down to about 1e-12. + down to about 1e-12 (1e6 when the timestep could not be derived, as in an adaptive trace under ``jax.grad`` of the coil dofs). * An orbit that ends non-finite or reaches ``max_steps`` raises a ``RuntimeWarning``; raise ``max_steps`` or lower the tolerance. diff --git a/essos/dynamics.py b/essos/dynamics.py index 037f3d10..20557af5 100644 --- a/essos/dynamics.py +++ b/essos/dynamics.py @@ -961,7 +961,8 @@ def __init__(self, trajectories_input=None, initial_conditions=None, times_to_tr if model not in ('GuidingCenterAdaptative', 'FullOrbitAdaptative'): raise ValueError("timestep=None needs the axis radius and particle speed as concrete values; " "they are traced here, so pass an explicit timestep") - timestep = maxtime / 100 # only the first trial step of an adaptive solve + timestep = maxtime / 100 # only the first trial step of an adaptive solve, which cannot size max_steps + max_steps = 1_000_000 if max_steps is None else max_steps else: timestep = float(abs(scales[0]) / scales[1]) / _STEPS_PER_TRANSIT.get(type(field), 400) self.timestep = timestep diff --git a/tests/test_dynamics.py b/tests/test_dynamics.py index 2467c099..f90ac585 100644 --- a/tests/test_dynamics.py +++ b/tests/test_dynamics.py @@ -1309,3 +1309,15 @@ def end(x0, energy=particles.energy): assert jnp.isfinite(jax.grad(end)(particles.initial_xyz)).all() with pytest.raises(ValueError, match="explicit timestep"): jax.grad(lambda energy: end(particles.initial_xyz, energy))(particles.energy) + + seen = [] # an adaptive trace of a traced energy starts from maxtime/100 and keeps a generous step budget + + def adaptive_end(energy): + launched = Particles(initial_xyz=particles.initial_xyz, energy=energy, + initial_vparallel_over_v=particles.initial_vparallel_over_v) + tracing = Tracing(field=field, particles=launched, **{**kwargs, "model": "GuidingCenterAdaptative"}) + seen.append((tracing.timestep, tracing.max_steps)) + return tracing.trajectories[0, -1, 0] + + jax.grad(adaptive_end)(particles.energy) + assert seen[0] == (pytest.approx(1e-9), 1_000_000)