Skip to content
Open
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
5 changes: 3 additions & 2 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -269,8 +269,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` (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`).
Expand Down
Binary file added docs/_static/tracing_work_precision.png
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
3 changes: 2 additions & 1 deletion docs/index.rst
Original file line number Diff line number Diff line change
Expand Up @@ -19,4 +19,5 @@ stellarator coils to improve plasma confinement.
:maxdepth: 2
:caption: Contents:

getting_started
getting_started
tracing
33 changes: 33 additions & 0 deletions docs/tracing.rst
Original file line number Diff line number Diff line change
@@ -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 (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.
47 changes: 40 additions & 7 deletions essos/dynamics.py
Original file line number Diff line number Diff line change
@@ -1,5 +1,6 @@
from pyexpat import model
import os
import warnings
import jax
jax.config.update("jax_enable_x64", True)
# Tracings that differ only in array values (particles, coil currents, field coefficients) share one compiled solve
Expand Down Expand Up @@ -800,6 +801,17 @@ def __call__(self, t, y, args):
return jnp.concatenate([jnp.tensordot(jacobian, f[:2], axes=1), f[2:], c * f[1:2]])


# 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):
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",
Expand Down Expand Up @@ -1049,10 +1061,10 @@ def _batch_solver(tracing, place):

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:
Expand Down Expand Up @@ -1088,9 +1100,25 @@ 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 (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:
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, 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
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
Expand Down Expand Up @@ -1120,7 +1148,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
Expand Down Expand Up @@ -1228,7 +1257,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
Expand All @@ -1244,6 +1276,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"):
Expand Down Expand Up @@ -1414,7 +1448,6 @@ def _terms(self, key, flag=False, events=()):

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)),
Expand Down
2 changes: 1 addition & 1 deletion essos/objective_functions.py
Original file line number Diff line number Diff line change
Expand Up @@ -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,
Expand Down
94 changes: 93 additions & 1 deletion tests/test_dynamics.py
Original file line number Diff line number Diff line change
Expand Up @@ -651,7 +651,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
Expand Down Expand Up @@ -1399,6 +1399,98 @@ def test_mu_collision_models_accept_coils_as_the_field(monkeypatch):
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)


@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)

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)


def test_loss_fraction_of_analytic_gyro_orbits():
"""Gyro-orbits of radius rho about guiding centres at distance d are lost
iff d + rho > R, at the first sample where the orbit crosses R."""
Expand Down
Loading