diff --git a/README.md b/README.md index 808e15a7..28421c11 100644 --- a/README.md +++ b/README.md @@ -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`). diff --git a/docs/_static/tracing_work_precision.png b/docs/_static/tracing_work_precision.png new file mode 100644 index 00000000..0185b373 Binary files /dev/null and b/docs/_static/tracing_work_precision.png differ 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..580b33d8 --- /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 (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 385f0697..32832355 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) # Tracings that differ only in array values (particles, coil currents, field coefficients) share one compiled solve @@ -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", @@ -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: @@ -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 @@ -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 @@ -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 @@ -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"): @@ -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)), 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, diff --git a/tests/test_dynamics.py b/tests/test_dynamics.py index 739be077..228c9307 100644 --- a/tests/test_dynamics.py +++ b/tests/test_dynamics.py @@ -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 @@ -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."""