From 0f9fef5fc675adfe3501cce9d3403f8b9b954167 Mon Sep 17 00:00:00 2001 From: Rogerio Jorge Date: Mon, 16 Nov 2026 09:04:29 -0600 Subject: [PATCH 01/11] Compacted tracing: advance in step budgets and drop finished particles --- essos/dynamics.py | 91 +++++++++++++++++++++++++++++++++++------- tests/test_dynamics.py | 16 ++++++++ 2 files changed, 93 insertions(+), 14 deletions(-) diff --git a/essos/dynamics.py b/essos/dynamics.py index a5eb85bd..e16aced0 100644 --- a/essos/dynamics.py +++ b/essos/dynamics.py @@ -828,13 +828,18 @@ class _EventSteps(PIDController): events: tuple = eqx.field(default=(), static=True) floor: float = eqx.field(default=1e-10, static=True) + # The state also holds the next step, so a solve stopped at its step budget resumes where it left off. + def init(self, terms, t0, t1, y0, dt0, *rest): + tnext, state = super().init(terms, t0, t1, y0, dt0, *rest) + return tnext, (*state, tnext - t0) + def adapt_step_size(self, t0, t1, y0, y1, *rest): - keep, next_t0, next_t1, jump, state, result = super().adapt_step_size(t0, t1, y0, y1, *rest) + keep, next_t0, next_t1, jump, state, result = super().adapt_step_size(t0, t1, y0, y1, *rest[:-1], rest[-1][:3]) for g in self.events: a, b = lax.stop_gradient(g(y0)), lax.stop_gradient(g(y1)) coarse = (a * b > 0) & (jnp.minimum(jnp.abs(a), jnp.abs(b)) > self.floor) & (jnp.abs(b - a) > 0.5 * jnp.minimum(jnp.abs(a), jnp.abs(b))) keep, next_t0, next_t1 = keep & ~coarse, jnp.where(coarse, t0, next_t0), jnp.where(coarse, t0 + (t1 - t0) / 2, next_t1) - return keep, next_t0, next_t1, jump, state, result + return keep, next_t0, next_t1, jump, (*state, next_t1 - next_t0), result def _failed_event(t, y, args, **kwargs): @@ -978,12 +983,13 @@ def same(a, b): @lru_cache(maxsize=16) -def _compiled_solver(static, place): - """``jit(vmap(trajectory))`` of every Tracing that has the static part ``static`` and these devices.""" +def _compiled_solver(static, place, rounds=False): + """``jit(vmap(trajectory))`` (or of ``_advance`` with ``rounds``) of every Tracing that has the static part + ``static`` and these devices.""" def solve(y0, keys, arrays): tracing = object.__new__(Tracing) tracing.__dict__.update(_unwrap(eqx.combine(arrays, static.tree))) - return vmap(tracing._trajectory_function())(y0, keys) + return vmap(tracing._advance if rounds else tracing._trajectory_function())(y0, keys) if isinstance(place, NamedSharding): every = NamedSharding(place.mesh, PartitionSpec()) return jit(solve, in_shardings=(place, place, every), out_shardings=place) @@ -1000,7 +1006,7 @@ def _unwrap(tree): is_leaf=lambda x: isinstance(x, _ParticlesNode)) -def _batch_solver(tracing, place): +def _batch_solver(tracing, place, rounds=False): """``solve(y0, keys)`` of ``tracing``, compiled once for all Tracings that differ only in array values. Arrays (fields' coefficients, particles, tolerances held as arrays) are arguments of the compiled function; @@ -1009,7 +1015,7 @@ def _batch_solver(tracing, place): and a ``Vmec`` mutated in place keeps the compilation made with its earlier values: build a new one instead. """ arrays, static = eqx.partition(_wrap(dict(vars(tracing))), lambda x: isinstance(x, (jax.Array, np.ndarray))) - solver = _compiled_solver(_Static(static), place) + solver = _compiled_solver(_Static(static), place, rounds) if isinstance(place, NamedSharding): # replicated over the devices that share the particles arrays = tree_util.tree_map(lambda x: _place_on_devices(x, NamedSharding(place.mesh, PartitionSpec())), arrays) return lambda y0, keys: solver(y0, keys, arrays) @@ -1021,7 +1027,7 @@ def __init__(self, trajectories_input=None, initial_conditions=None, times_to_tr rtol= 1.e-7, atol = 1e-7, 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, - particle_batch_size=None, adjoint=None): + particle_batch_size=None, adjoint=None, step_budget=None): if condition is not None and stopping_criteria is not None: raise ValueError("Pass condition or stopping_criteria, not both") @@ -1102,6 +1108,14 @@ def __init__(self, trajectories_input=None, initial_conditions=None, times_to_tr or particle_batch_size <= 0): raise ValueError("particle_batch_size must be a positive integer or None") self.particle_batch_size = None if particle_batch_size is None else int(particle_batch_size) + # With step_budget, particles advance at most that many steps per round, finished ones (at maxtime or a + # stopping criterion) leave the batch, and the rest continue. A vmapped solve otherwise runs every particle to + # the step count of the slowest. Not under a JAX transformation, VMEC's default events or FullOrbit_Boris. + if step_budget is not None and (model in ('FullOrbit_Boris', 'GuidingCenterCollisionsMuAdaptative') + or self._vmec_default or int(step_budget) <= 0): + raise ValueError("step_budget must be a positive integer, and not for FullOrbit_Boris, " + "GuidingCenterCollisionsMuAdaptative or VMEC guiding centers without a condition") + self.step_budget = None if step_budget is None else int(step_budget) # Diffrax's meter is an unordered callback, which the vmapped while loop of # the VMEC segment path rejects; that path reports progress by batches only. self.progress_meter = (TqdmProgressMeter() if self.progress and self.particle_batch_size is None @@ -1299,6 +1313,8 @@ def trace(self): y0, keys = self.initial_conditions, self.particles.random_keys if self.particles else None n = len(y0) traced = any(isinstance(x, jax.core.Tracer) for x in tree_util.tree_leaves((y0, keys, self.args, self.exterior_field))) + if self.step_budget is not None and not traced: + return self._trace_rounds(y0, keys) batch = n if self.particle_batch_size is None or traced else min(self.particle_batch_size, n) # Sharding pays off for plain traces. A differentiated trace stays on one device: XLA 0.6 aborts compiling # a gradient through a while loop sharded over several CPU devices. @@ -1331,6 +1347,48 @@ def run(y0, keys): bar.update(done) return tree_util.tree_map(lambda *x: jnp.asarray(np.concatenate(x)), *results) + def _trace_rounds(self, y0, keys): + """Trace in rounds of at most step_budget steps, each with the particles not yet finished, on one device. + + A round's batch is padded to a power of two, so at most log2(n) + 1 batch sizes compile. + """ + n, times = len(y0), np.asarray(self.times) + terms, solver, controller = self._terms(None if keys is None else keys[0]) + start = controller.init(terms, 0.0, self.maxtime, y0[0], self.timestep, self.args, solver.func, + solver.error_order(terms))[1] + state = (np.array(y0), np.zeros(n), tree_util.tree_map(lambda x: np.repeat(np.asarray(x)[None], n, 0), start)) + solve, ys, masks = _batch_solver(self, self.devices[0], rounds=True), None, None + active = np.arange(n) + for _ in range(-(-self.max_steps // self.step_budget)): # max_steps still bounds every orbit + if not active.size: + break + index = np.append(active, np.full((1 << (active.size - 1).bit_length()) - active.size, active[-1])) + out, new, done, mask = tree_util.tree_map(np.asarray, solve( + tree_util.tree_map(lambda x: x[index], state), None if keys is None else keys[index])) + m, t0 = active.size, state[1][active] + if ys is None: + ys, masks = np.empty((n,) + out.shape[1:]), tree_util.tree_map(lambda x: np.zeros((n,), bool), mask) + ys[active] = np.where((times[None, :] >= t0[:, None])[..., None], out[:m], ys[active]) + for x, y in zip(tree_util.tree_leaves(state), tree_util.tree_leaves(new)): + x[active] = y[:m] + for x, y in zip(tree_util.tree_leaves(masks), tree_util.tree_leaves(mask)): + x[active] = y[:m] + active = active[~done[:m]] + ys = jnp.asarray(ys) + if self._axis_regular: + ys = vmap(vmap(_from_axis_regular))(ys) + masks = tree_util.tree_map(jnp.asarray, masks) + return ys if self.stopping_criteria is None else (ys, masks) + + def _advance(self, state, key): + """One round of _trace_rounds for one particle: (saves, state, finished, event mask).""" + y0, t0, controller_state = state + terms, solver, controller = self._terms(key) + solution = self._solve(terms, solver, controller, t0, y0, self.args, Event(self.condition), resume=True, + controller_state=controller_state) + return (solution.ys[0], (solution.ys[1][-1], solution.ts[1][-1], solution.controller_state), + solution.result != diffrax.RESULTS.max_steps_reached, solution.event_mask) + def _terms(self, key, flag=False, events=()): """Diffrax terms, solver and step-size controller of self.model (with _with_failure_flag if ``flag``).""" flagged = (lambda f, drift=True: _with_failure_flag(f, drift)) if flag else (lambda f, drift=True: f) @@ -1358,15 +1416,20 @@ def _terms(self, key, flag=False, events=()): dtmin=dt0 if model == 'FullOrbitCollisions' else None, events=events) return terms, solver, controller - 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.""" + def _solve(self, terms, solver, controller, t0, y0, args, event, throw=False, resume=False, controller_state=None): + """diffeqsolve from t0 to maxtime, saving at self.times (clipped to t0) and at the end. + + With ``resume`` it takes at most step_budget steps from ``controller_state`` (None for a fixed step; from + _EventSteps its last entry is the next step) and returns the controller state, so a later solve continues.""" 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, + return diffeqsolve(terms, solver, t0=t0, t1=self.maxtime, y0=y0, args=args, controller_state=controller_state, + dt0=self.timestep if controller_state is None else controller_state[-1], saveat=SaveAt(subs=[diffrax.SubSaveAt(ts=jnp.clip(self.times, t0, self.maxtime)), - diffrax.SubSaveAt(t1=True)]), - stepsize_controller=controller, event=event, throw=throw, max_steps=self.max_steps, - progress_meter=self.progress_meter, adjoint=self.adjoint) + diffrax.SubSaveAt(t1=True)], controller_state=resume), + stepsize_controller=controller, event=event, throw=throw, + max_steps=self.step_budget if resume else self.max_steps, + progress_meter=NoProgressMeter() if resume else self.progress_meter, adjoint=self.adjoint) # -- VMEC guiding centers: exact LCFS crossing, failures, exterior continuation -- diff --git a/tests/test_dynamics.py b/tests/test_dynamics.py index af2527b5..0ac99aff 100644 --- a/tests/test_dynamics.py +++ b/tests/test_dynamics.py @@ -327,6 +327,22 @@ def evaluate_xyz(self, xyz): assert jnp.allclose(tracing.trajectories[0, -1], tracing.trajectories[0, -2]) +@pytest.mark.parametrize("model", ["FieldLineAdaptative", "FieldLine"]) +def test_step_budget_rounds_match_one_solve(model): + """Rounds of two steps, each without the lines already stopped, give the orbits and stops of one solve.""" + class PlaneClassifier: + def evaluate_xyz(self, xyz): + return 1.5 - xyz[0] + + def trace(budget): + return Tracing(field=MockField(), model=model, initial_conditions=jnp.array([[1.0, 0, 0], [0.0, 0, 0], + [-3.0, 0, 0], [1.4, 0, 0], [-1.0, 0, 0]]), maxtime=2.0, timestep=0.05, times_to_trace=21, + stopping_criteria=LevelsetStoppingCriterion(PlaneClassifier()), step_budget=budget) + whole, rounds = trace(None), trace(2) + assert whole.boundary_hits.tolist() == rounds.boundary_hits.tolist() == [True, True, False, True, False] + np.testing.assert_allclose(rounds.trajectories, whole.trajectories, rtol=1e-12, atol=1e-12) + + def test_poincare_plot_unwraps_toroidal_crossings_and_accepts_line_colors(): phase = jnp.linspace(0.0, 4.0 * jnp.pi, 101) first = jnp.stack((jnp.cos(phase), jnp.sin(phase), 0.1 * jnp.sin(phase)), axis=1) From 829bb97a6e8b432e742f774171cdc57bad48f48f Mon Sep 17 00:00:00 2001 From: Rogerio Jorge Date: Mon, 16 Nov 2026 11:40:00 -0600 Subject: [PATCH 02/11] Pad rounds to 3 significant bits; document step_budget --- README.md | 4 ++++ essos/dynamics.py | 5 +++-- 2 files changed, 7 insertions(+), 2 deletions(-) diff --git a/README.md b/README.md index 808e15a7..2dc10b6d 100644 --- a/README.md +++ b/README.md @@ -271,6 +271,10 @@ the `wout` directly and DESC fits it. ± is the binomial standard error. 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. + With `step_budget=k` particles advance at most `k` steps per round and the + ones that finished or were lost leave the batch, instead of every particle + running to the step count of the slowest; this pays when many are lost + early (1.9x less CPU for 64 edge-born alphas, 48 lost). - **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 e16aced0..0042bb13 100644 --- a/essos/dynamics.py +++ b/essos/dynamics.py @@ -1350,7 +1350,7 @@ def run(y0, keys): def _trace_rounds(self, y0, keys): """Trace in rounds of at most step_budget steps, each with the particles not yet finished, on one device. - A round's batch is padded to a power of two, so at most log2(n) + 1 batch sizes compile. + A round's batch is padded to 3 significant bits (as in trace_boozer), so few batch sizes compile. """ n, times = len(y0), np.asarray(self.times) terms, solver, controller = self._terms(None if keys is None else keys[0]) @@ -1362,7 +1362,8 @@ def _trace_rounds(self, y0, keys): for _ in range(-(-self.max_steps // self.step_budget)): # max_steps still bounds every orbit if not active.size: break - index = np.append(active, np.full((1 << (active.size - 1).bit_length()) - active.size, active[-1])) + step = 1 << max(active.size.bit_length() - 3, 0) + index = np.append(active, np.full(-active.size % step, active[-1])) out, new, done, mask = tree_util.tree_map(np.asarray, solve( tree_util.tree_map(lambda x: x[index], state), None if keys is None else keys[index])) m, t0 = active.size, state[1][active] From 924ba7bf9a1026803fe45f483f4efd24071d4dd3 Mon Sep 17 00:00:00 2001 From: Rogerio Jorge Date: Mon, 16 Nov 2026 17:16:16 -0600 Subject: [PATCH 03/11] Count the step bound in Tracing._solve, which now also holds the step budget --- tests/test_dynamics.py | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/tests/test_dynamics.py b/tests/test_dynamics.py index 0ac99aff..37a7db52 100644 --- a/tests/test_dynamics.py +++ b/tests/test_dynamics.py @@ -605,7 +605,7 @@ def test_tracing_max_steps_is_configurable_and_bounded(): source = inspect.getsource(Tracing) assert "max_steps=10000000000" not in source - assert source.count("max_steps=self.max_steps") == 1 # every solve goes through Tracing._solve + assert inspect.getsource(Tracing._solve).count("self.max_steps") == 1 # every solve goes through Tracing._solve From 7185df3fae0a29df9f492be3cff0b6f3eb23c9b2 Mon Sep 17 00:00:00 2001 From: Rogerio Jorge Date: Mon, 16 Nov 2026 19:01:20 -0600 Subject: [PATCH 04/11] step_budget for VMEC guiding centers: one pass per round, paused orbits resume from their last save --- essos/dynamics.py | 187 +++++++++++++++++++++++++++-------------- tests/test_dynamics.py | 18 ++++ 2 files changed, 141 insertions(+), 64 deletions(-) diff --git a/essos/dynamics.py b/essos/dynamics.py index 0042bb13..ed27c06f 100644 --- a/essos/dynamics.py +++ b/essos/dynamics.py @@ -1110,11 +1110,11 @@ def __init__(self, trajectories_input=None, initial_conditions=None, times_to_tr self.particle_batch_size = None if particle_batch_size is None else int(particle_batch_size) # With step_budget, particles advance at most that many steps per round, finished ones (at maxtime or a # stopping criterion) leave the batch, and the rest continue. A vmapped solve otherwise runs every particle to - # the step count of the slowest. Not under a JAX transformation, VMEC's default events or FullOrbit_Boris. + # the step count of the slowest. Not under a JAX transformation, FullOrbit_Boris or the clipped controller. if step_budget is not None and (model in ('FullOrbit_Boris', 'GuidingCenterCollisionsMuAdaptative') - or self._vmec_default or int(step_budget) <= 0): - raise ValueError("step_budget must be a positive integer, and not for FullOrbit_Boris, " - "GuidingCenterCollisionsMuAdaptative or VMEC guiding centers without a condition") + or int(step_budget) <= 0): + raise ValueError("step_budget must be a positive integer, and not for FullOrbit_Boris or " + "GuidingCenterCollisionsMuAdaptative") self.step_budget = None if step_budget is None else int(step_budget) # Diffrax's meter is an unordered callback, which the vmapped while loop of # the VMEC segment path rejects; that path reports progress by batches only. @@ -1314,7 +1314,7 @@ def trace(self): n = len(y0) traced = any(isinstance(x, jax.core.Tracer) for x in tree_util.tree_leaves((y0, keys, self.args, self.exterior_field))) if self.step_budget is not None and not traced: - return self._trace_rounds(y0, keys) + return self._trace_vmec_rounds(y0, keys) if self._vmec_default else self._trace_rounds(y0, keys) batch = n if self.particle_batch_size is None or traced else min(self.particle_batch_size, n) # Sharding pays off for plain traces. A differentiated trace stays on one device: XLA 0.6 aborts compiling # a gradient through a while loop sharded over several CPU devices. @@ -1381,8 +1381,26 @@ def _trace_rounds(self, y0, keys): masks = tree_util.tree_map(jnp.asarray, masks) return ys if self.stopping_criteria is None else (ys, masks) + def _trace_vmec_rounds(self, y0, keys): + """_trace_rounds for VMEC guiding centers: each round is one _vmec_pass of the orbits still active.""" + o = tree_util.tree_map(np.array, jit(vmap(self._vmec_start))(y0, keys)) + solve, active = _batch_solver(self, self.devices[0], rounds=True), np.arange(len(y0)) + for _ in range((self.max_returns + 1) * 2 * -(-self.max_steps // self.step_budget)): + if not active.size: + break + step = 1 << max(active.size.bit_length() - 3, 0) + index = np.append(active, np.full(-active.size % step, active[-1])) + new = solve(tree_util.tree_map(lambda x: x[index], o), None if keys is None else keys[index]) + for x, y in zip(tree_util.tree_leaves(o), tree_util.tree_leaves(new)): + x[active] = np.asarray(y)[:active.size] + active = active[o["active"][active]] + o["status"][active], o["active"][active] = 4, False # out of steps: failed, as without a budget + return vmap(self._vmec_finish)(tree_util.tree_map(jnp.asarray, o)) + def _advance(self, state, key): """One round of _trace_rounds for one particle: (saves, state, finished, event mask).""" + if self._vmec_default: + return self._vmec_pass(state, key) y0, t0, controller_state = state terms, solver, controller = self._terms(key) solution = self._solve(terms, solver, controller, t0, y0, self.args, Event(self.condition), resume=True, @@ -1452,30 +1470,71 @@ def _vmec_orbit(self, y0, key): does not toggle the segment. The derivative is that of the orbit's own sequence of segments: where a small change adds or removes a crossing or a re-entry, the result jumps (it is finite, not smoothed). """ - T, times, ext = self.maxtime, self.times, self.exterior_field + o = self._vmec_start(y0, key) + # Every pass ends an inside and an outside segment, so max_returns + 1 passes finish every orbit. A bounded scan + # (not a while loop) differentiates in reverse mode; the cond, taken once no orbit of the batch is active, skips + # the remaining passes, so the forward cost is that of the loop. + o = lax.scan(lambda o, _: (lax.cond(eqxi.unvmap_any(o["active"]), lambda o: self._vmec_pass(o, key), + lambda o: o, o), None), + o, None, length=self.max_returns * (self.exterior_field is not None) + 1)[0] + return self._vmec_finish(o) + + def _vmec_segments(self, key): + """Terms, solver, controller, args and event of the inside and (with exterior_field) outside segments.""" lcfs = lambda y: 1.0 - y[0]**2 - y[1]**2 inside = (*self._terms(key, flag=True, events=(lcfs,)), self.args, - Event((lambda t, y, args, **kwargs: lcfs(y), _failed_event), - root_finder=_EVENT_ROOT_FINDER)) - if ext is not None: - wall = self.wall if self.wall is not None else (lambda x: jnp.ones(())) - depth = lambda y: self.field.boundary_distance(y[:3]) - self.reentry_depth - outside = (ODETerm(_with_failure_flag(GuidingCenterMu)), self.solver if self.solver is not None else - diffrax.Dopri8(), _EventSteps(pcoeff=0.4, icoeff=0.3, dcoeff=0, rtol=self.rtol, atol=self.atol, - events=(lambda y: wall(y[:3]), depth)), - (ext, self.particles, Electric_field_zero()), - Event((lambda t, y, args, **kwargs: wall(y[:3]), lambda t, y, args, **kwargs: depth(y), _failed_event), - root_finder=_EVENT_ROOT_FINDER)) - - def segment(o, run, spec, y, code, to_flux=lambda y: y): + Event((lambda t, y, args, **kwargs: lcfs(y), _failed_event), root_finder=_EVENT_ROOT_FINDER)) + if self.exterior_field is None: + return inside, None + wall = self.wall if self.wall is not None else (lambda x: jnp.ones(())) + depth = lambda y: self.field.boundary_distance(y[:3]) - self.reentry_depth + outside = (ODETerm(_with_failure_flag(GuidingCenterMu)), self.solver if self.solver is not None else + diffrax.Dopri8(), _EventSteps(pcoeff=0.4, icoeff=0.3, dcoeff=0, rtol=self.rtol, atol=self.atol, + events=(lambda y: wall(y[:3]), depth)), + (self.exterior_field, self.particles, Electric_field_zero()), + Event((lambda t, y, args, **kwargs: wall(y[:3]), lambda t, y, args, **kwargs: depth(y), _failed_event), + root_finder=_EVENT_ROOT_FINDER)) + return inside, outside + + def _vmec_start(self, y0, key): + """The state of one orbit before its first segment (with step_budget, also the controllers' first states).""" + nt, d = len(self.times), y0.shape[0] + o = dict(t=jnp.zeros(()), y=y0, x=self._vmec_to_exterior(y0)[0], inside=jnp.array(True), active=jnp.array(True), + status=jnp.zeros((), jnp.int8), returns=jnp.zeros((), int), lcfs_time=jnp.full((), jnp.inf), + lcfs_state=jnp.full(d, jnp.nan), lcfs_energy=jnp.full((), jnp.nan), traj=jnp.full((nt, d), jnp.inf), + xyz=jnp.full((nt, 3), jnp.nan), region=jnp.full(nt, -1, dtype=jnp.int8)) + if self.step_budget is not None: + for name, spec, y in zip(("in", "out"), self._vmec_segments(key), (_to_axis_regular(y0), o["x"])): + if spec is not None: + terms, solver, controller = spec[:3] + o["c_" + name] = o["c0_" + name] = controller.init( + terms, 0.0, self.maxtime, jnp.append(y, 0.0), self.timestep, spec[3], solver.func, + solver.error_order(terms))[1] + return o + + def _vmec_finish(self, o): + if self.exterior_field is not None: # energy at the end outside, the strike for a wall hit + o["x_energy"] = 0.5 * self.particles.mass * o["x"][3]**2 + o["x"][4] * self.exterior_field.AbsB(o["x"][:3]) + return o + + def _vmec_pass(self, o, key): + """One inside and one outside segment of an orbit. With step_budget a segment stops after that many steps and + the orbit pauses in its region (the next pass continues it); otherwise a segment that runs out of steps fails.""" + T, times, ext, budget = self.maxtime, self.times, self.exterior_field, self.step_budget is not None + inside, outside = self._vmec_segments(key) + wall = self.wall if self.wall is not None else (lambda x: jnp.ones(())) + + def segment(o, run, spec, y, code, name, to_flux=lambda y: y): """Solve one segment of the orbits in ``run`` and record its saves.""" # A lane that does not run starts just before maxtime, not at it: diffrax 0.7.0 differentiates an event root # find over a zero-length step with a non-finite Jacobian, which its linear solver rejects in reverse mode. - solution = self._solve(*spec[:3], jnp.where(run, o["t"], T * (1 - 1e-9)), jnp.append(y, 0.0), *spec[3:]) + solution = self._solve(*spec[:3], jnp.where(run, o["t"], T * (1 - 1e-9)), jnp.append(y, 0.0), *spec[3:], + resume=budget, controller_state=o["c_" + name] if budget else None) saves, end = vmap(to_flux)(solution.ys[0][:, :-1]), to_flux(solution.ys[1][-1, :-1]) - failed = run & (solution.event_mask[-1] | ~((solution.result == diffrax.RESULTS.successful) - | (solution.result == diffrax.RESULTS.event_occurred) - | (solution.result == diffrax.RESULTS.nonlinear_max_steps_reached))) + paused = run & (solution.result == diffrax.RESULTS.max_steps_reached) if budget else jnp.array(False) + failed = run & ~paused & (solution.event_mask[-1] | ~((solution.result == diffrax.RESULTS.successful) + | (solution.result == diffrax.RESULTS.event_occurred) + | (solution.result == diffrax.RESULTS.nonlinear_max_steps_reached))) t_end = jnp.where(run, solution.ts[1][-1], o["t"]) window = run & (times >= o["t"]) & (times <= t_end) & jnp.isfinite(saves).all(1) # to_xyz of the unused (inf) saves would put NaN partials into the coefficient gradients; not vmap: one save at a time @@ -1483,48 +1542,48 @@ def segment(o, run, spec, y, code, to_flux=lambda y: y): o = dict(o, xyz=jnp.where(window[:, None], xyz, o["xyz"]), region=jnp.where(window, code, o["region"])) if code == 0: o["traj"] = jnp.where(window[:, None], saves, o["traj"]) - return o, t_end, end, [run & ~failed & hit for hit in solution.event_mask[:-1]], failed - - def step(o): - # Inside; an orbit that starts outside the LCFS crosses at once. - run = o["active"] & o["inside"] - out = o["y"][0] >= 1.0 - o, t_end, end, (crossed,), failed = segment(o, run & ~out, inside, _to_axis_regular(o["y"]), 0, - _from_axis_regular) - crossed, end = crossed | (run & out), jnp.where(out, o["y"], end) - x, E = self._vmec_to_exterior(end) - first = crossed & jnp.isinf(o["lcfs_time"]) - o.update(t=t_end, lcfs_time=jnp.where(first, t_end, o["lcfs_time"]), - lcfs_state=jnp.where(first, end, o["lcfs_state"]), lcfs_energy=jnp.where(first, E, o["lcfs_energy"]), - status=jnp.select([failed, run & ~crossed, crossed & (ext is None)], [4, 0, 1], o["status"]), - active=o["active"] & ~(failed | (run & ~crossed) | (crossed & (ext is None))), - inside=o["inside"] & ~crossed, x=jnp.where(crossed, x, o["x"])) - if ext is None: - return o - # Outside, to the wall, maxtime, or back inside. - run = o["active"] & ~o["inside"] - behind = run & (wall(o["x"][:3]) <= 0) # the wall is already crossed at the exit point: a hit at the exit time - o, t_end, end, (struck, returned), failed = segment(o, run & ~behind, outside, o["x"], 1) - struck = struck | behind - returned &= ~struck - back = returned & (o["returns"] < self.max_returns) - o.update(t=t_end, returns=o["returns"] + back, inside=o["inside"] | back, active=o["active"] & ~(run & ~back), - status=jnp.select([failed, struck, returned & ~back, run & ~back], [4, 3, 5, 2], o["status"]), - x=jnp.where(run & ~behind, end, o["x"]), y=jnp.where(back, self._vmec_from_exterior(end), o["y"])) + if budget: + o["c_" + name] = tree_util.tree_map(lambda a, b: jnp.where(run, a, b), solution.controller_state, + o["c_" + name]) + # A paused orbit resumes from its last save. Under vmap, once any orbit of the batch has an event, + # diffrax root-finds on every orbit, and an orbit stopped by max_steps can end inside a rejected step. + last = jnp.max(jnp.where(window, jnp.arange(len(times)), -1)) + saved = paused & (last >= 0) + t_end = jnp.where(saved, times[jnp.maximum(last, 0)], t_end) + end = jnp.where(saved, saves[jnp.maximum(last, 0)], end) + return o, t_end, end, [run & ~failed & hit for hit in solution.event_mask[:-1]], failed, paused + + # Inside; an orbit that starts outside the LCFS crosses at once. + run = o["active"] & o["inside"] + out = o["y"][0] >= 1.0 + o, t_end, end, (crossed,), failed, paused = segment(o, run & ~out, inside, _to_axis_regular(o["y"]), 0, "in", + _from_axis_regular) + crossed, end = crossed | (run & out), jnp.where(out, o["y"], end) + x, E = self._vmec_to_exterior(end) + first = crossed & jnp.isinf(o["lcfs_time"]) + done = run & ~crossed & ~paused # at maxtime + o.update(t=t_end, lcfs_time=jnp.where(first, t_end, o["lcfs_time"]), + lcfs_state=jnp.where(first, end, o["lcfs_state"]), lcfs_energy=jnp.where(first, E, o["lcfs_energy"]), + status=jnp.select([failed, done, crossed & (ext is None)], [4, 0, 1], o["status"]), + active=o["active"] & ~(failed | done | (crossed & (ext is None))), + inside=o["inside"] & ~crossed, x=jnp.where(crossed, x, o["x"]), y=jnp.where(paused, end, o["y"])) + if ext is None: return o - - nt, d = len(times), y0.shape[0] - o = dict(t=jnp.zeros(()), y=y0, x=self._vmec_to_exterior(y0)[0], inside=jnp.array(True), active=jnp.array(True), - status=jnp.zeros((), jnp.int8), returns=jnp.zeros((), int), lcfs_time=jnp.full((), jnp.inf), - lcfs_state=jnp.full(d, jnp.nan), lcfs_energy=jnp.full((), jnp.nan), traj=jnp.full((nt, d), jnp.inf), - xyz=jnp.full((nt, 3), jnp.nan), region=jnp.full(nt, -1, dtype=jnp.int8)) - # Every pass ends an inside and an outside segment, so max_returns + 1 passes finish every orbit. A bounded scan - # (not a while loop) differentiates in reverse mode; the cond, taken once no orbit of the batch is active, skips - # the remaining passes, so the forward cost is that of the loop. - o = lax.scan(lambda o, _: (lax.cond(eqxi.unvmap_any(o["active"]), step, lambda o: o, o), None), o, None, - length=self.max_returns * (ext is not None) + 1)[0] - if ext is not None: # energy at the end outside, the strike for a wall hit - o["x_energy"] = 0.5 * self.particles.mass * o["x"][3]**2 + o["x"][4] * ext.AbsB(o["x"][:3]) + if budget: # a new segment starts with the controller's first state, as without a budget + o["c_out"] = tree_util.tree_map(lambda a, b: jnp.where(crossed, a, b), o["c0_out"], o["c_out"]) + # Outside, to the wall, maxtime, or back inside. + run = o["active"] & ~o["inside"] + behind = run & (wall(o["x"][:3]) <= 0) # the wall is already crossed at the exit point: a hit at the exit time + o, t_end, end, (struck, returned), failed, paused = segment(o, run & ~behind, outside, o["x"], 1, "out") + struck = struck | behind + returned &= ~struck + back = returned & (o["returns"] < self.max_returns) + stop = run & ~back & ~paused + o.update(t=t_end, returns=o["returns"] + back, inside=o["inside"] | back, active=o["active"] & ~stop, + status=jnp.select([failed, struck, returned & ~back, stop], [4, 3, 5, 2], o["status"]), + x=jnp.where(run & ~behind, end, o["x"]), y=jnp.where(back, self._vmec_from_exterior(end), o["y"])) + if budget: + o["c_in"] = tree_util.tree_map(lambda a, b: jnp.where(back, a, b), o["c0_in"], o["c_in"]) return o def _vmec_to_exterior(self, y): diff --git a/tests/test_dynamics.py b/tests/test_dynamics.py index 37a7db52..04f0705c 100644 --- a/tests/test_dynamics.py +++ b/tests/test_dynamics.py @@ -1076,6 +1076,24 @@ def _exterior_tracing(xyz, vpar_over_v, maxtime, model="GuidingCenterAdaptative" [-0.9872, 0.5453, 0.747, -0.8145]) +@pytest.mark.parametrize("exterior", [False, True]) +def test_vmec_step_budget_matches_one_solve(exterior): + """Rounds of 16 steps give the LCFS crossings, wall strikes and orbits of one solve (a pause passes the state + through the axis-regular chart, so to about 1e-9).""" + if exterior: + trace = lambda budget: _exterior_tracing(*STRIKING, maxtime=3e-6, step_budget=budget) + else: + trace = lambda budget: _edge_tracing("GuidingCenterAdaptative", 0.975, 50, atol=1e-9, rtol=1e-9, + step_budget=budget) + whole, rounds = trace(None), trace(16) + assert np.array_equal(rounds.status, whole.status) and np.array_equal(rounds.returns, whole.returns) + for name in ("lcfs_times", "wall_times", "lost_times"): + np.testing.assert_allclose(getattr(rounds, name), getattr(whole, name), rtol=1e-7) + both = jnp.isfinite(whole.trajectories) + assert jnp.array_equal(both, jnp.isfinite(rounds.trajectories)) + np.testing.assert_allclose(rounds.trajectories[both], whole.trajectories[both], rtol=1e-7, atol=1e-9) + + def test_wall_given_as_a_gap_or_a_surface(): from essos.surfaces import SurfaceRZFourier vmec = Vmec(WOUT_QA, ntheta=8, nphi=8) From 11338f7ab5cccfc6e1711ba4f8e8250c72ba9b6f Mon Sep 17 00:00:00 2001 From: Rogerio Jorge Date: Mon, 16 Nov 2026 19:05:22 -0600 Subject: [PATCH 05/11] Strip only the appended step from the PID state (diffrax 0.7.0 keeps two entries) --- essos/dynamics.py | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/essos/dynamics.py b/essos/dynamics.py index ed27c06f..51108b3b 100644 --- a/essos/dynamics.py +++ b/essos/dynamics.py @@ -834,7 +834,7 @@ def init(self, terms, t0, t1, y0, dt0, *rest): return tnext, (*state, tnext - t0) def adapt_step_size(self, t0, t1, y0, y1, *rest): - keep, next_t0, next_t1, jump, state, result = super().adapt_step_size(t0, t1, y0, y1, *rest[:-1], rest[-1][:3]) + keep, next_t0, next_t1, jump, state, result = super().adapt_step_size(t0, t1, y0, y1, *rest[:-1], rest[-1][:-1]) for g in self.events: a, b = lax.stop_gradient(g(y0)), lax.stop_gradient(g(y1)) coarse = (a * b > 0) & (jnp.minimum(jnp.abs(a), jnp.abs(b)) > self.floor) & (jnp.abs(b - a) > 0.5 * jnp.minimum(jnp.abs(a), jnp.abs(b))) From 65d4768f757f51ef4d3364863353b2e04f117c47 Mon Sep 17 00:00:00 2001 From: Rogerio Jorge Date: Mon, 16 Nov 2026 19:14:54 -0600 Subject: [PATCH 06/11] Rounds: map inside saves to xyz once at the end; place solver arrays on the device once --- essos/dynamics.py | 13 ++++++++++--- 1 file changed, 10 insertions(+), 3 deletions(-) diff --git a/essos/dynamics.py b/essos/dynamics.py index 51108b3b..4084aeea 100644 --- a/essos/dynamics.py +++ b/essos/dynamics.py @@ -1018,6 +1018,8 @@ def _batch_solver(tracing, place, rounds=False): solver = _compiled_solver(_Static(static), place, rounds) if isinstance(place, NamedSharding): # replicated over the devices that share the particles arrays = tree_util.tree_map(lambda x: _place_on_devices(x, NamedSharding(place.mesh, PartitionSpec())), arrays) + elif rounds: # copied to the device once, not in every round + arrays = tree_util.tree_map(lambda x: _place_on_devices(x, place), arrays) return lambda y0, keys: solver(y0, keys, arrays) @@ -1395,7 +1397,10 @@ def _trace_vmec_rounds(self, y0, keys): x[active] = np.asarray(y)[:active.size] active = active[o["active"][active]] o["status"][active], o["active"][active] = 4, False # out of steps: failed, as without a budget - return vmap(self._vmec_finish)(tree_util.tree_map(jnp.asarray, o)) + o = tree_util.tree_map(jnp.asarray, o) + inside = o["region"] == 0 + xyz = jit(vmap(lambda p: lax.map(self.field.to_xyz, p)))(jnp.where(inside[..., None], o["xyz"], 0.5)) + return vmap(self._vmec_finish)(dict(o, xyz=jnp.where(inside[..., None], xyz, o["xyz"]))) def _advance(self, state, key): """One round of _trace_rounds for one particle: (saves, state, finished, event mask).""" @@ -1537,8 +1542,10 @@ def segment(o, run, spec, y, code, name, to_flux=lambda y: y): | (solution.result == diffrax.RESULTS.nonlinear_max_steps_reached))) t_end = jnp.where(run, solution.ts[1][-1], o["t"]) window = run & (times >= o["t"]) & (times <= t_end) & jnp.isfinite(saves).all(1) - # to_xyz of the unused (inf) saves would put NaN partials into the coefficient gradients; not vmap: one save at a time - xyz = lax.map(self.field.to_xyz, jnp.where(window[:, None], saves[:, :3], 0.5)) if code == 0 else saves[:, :3] + # to_xyz of the unused (inf) saves would put NaN partials into the coefficient gradients; not vmap: one save at a + # time. With a budget the inside saves are mapped once at the end (_trace_vmec_rounds), not in every round. + xyz = (lax.map(self.field.to_xyz, jnp.where(window[:, None], saves[:, :3], 0.5)) if code == 0 and not budget + else saves[:, :3]) o = dict(o, xyz=jnp.where(window[:, None], xyz, o["xyz"]), region=jnp.where(window, code, o["region"])) if code == 0: o["traj"] = jnp.where(window[:, None], saves, o["traj"]) From 1e7c2b7aff8e5ca57d93bb464fd994dc2f8ef64d Mon Sep 17 00:00:00 2001 From: Rogerio Jorge Date: Mon, 16 Nov 2026 19:39:29 -0600 Subject: [PATCH 07/11] README: when step_budget pays --- README.md | 5 +++-- 1 file changed, 3 insertions(+), 2 deletions(-) diff --git a/README.md b/README.md index 2dc10b6d..e7f07cf0 100644 --- a/README.md +++ b/README.md @@ -273,8 +273,9 @@ the `wout` directly and DESC fits it. ± is the binomial standard error. so a trace that cannot finish returns instead of running unbounded. With `step_budget=k` particles advance at most `k` steps per round and the ones that finished or were lost leave the batch, instead of every particle - running to the step count of the slowest; this pays when many are lost - early (1.9x less CPU for 64 edge-born alphas, 48 lost). + running to the step count of the slowest; this pays for large batches with + many early losses on few threads (1.9x less CPU for 64 edge-born alphas on + one thread, 1.6x for 256 in a VMEC field) and costs time on small batches. - **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`). From f2edba256f66b05f76adf43e16a884aabead1a8f Mon Sep 17 00:00:00 2001 From: Rogerio Jorge Date: Mon, 16 Nov 2026 19:44:58 -0600 Subject: [PATCH 08/11] Test tolerance for paused VMEC orbits --- tests/test_dynamics.py | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/tests/test_dynamics.py b/tests/test_dynamics.py index 04f0705c..d04ec697 100644 --- a/tests/test_dynamics.py +++ b/tests/test_dynamics.py @@ -1079,7 +1079,7 @@ def _exterior_tracing(xyz, vpar_over_v, maxtime, model="GuidingCenterAdaptative" @pytest.mark.parametrize("exterior", [False, True]) def test_vmec_step_budget_matches_one_solve(exterior): """Rounds of 16 steps give the LCFS crossings, wall strikes and orbits of one solve (a pause passes the state - through the axis-regular chart, so to about 1e-9).""" + through the axis-regular chart and restarts from a save, so to about 1e-6).""" if exterior: trace = lambda budget: _exterior_tracing(*STRIKING, maxtime=3e-6, step_budget=budget) else: @@ -1091,7 +1091,7 @@ def test_vmec_step_budget_matches_one_solve(exterior): np.testing.assert_allclose(getattr(rounds, name), getattr(whole, name), rtol=1e-7) both = jnp.isfinite(whole.trajectories) assert jnp.array_equal(both, jnp.isfinite(rounds.trajectories)) - np.testing.assert_allclose(rounds.trajectories[both], whole.trajectories[both], rtol=1e-7, atol=1e-9) + np.testing.assert_allclose(rounds.trajectories[both], whole.trajectories[both], rtol=1e-5, atol=1e-6) def test_wall_given_as_a_gap_or_a_surface(): From 732ea8cadfd000039a1da371b33cadd503807e4f Mon Sep 17 00:00:00 2001 From: Rogerio Jorge Date: Mon, 16 Nov 2026 19:52:41 -0600 Subject: [PATCH 09/11] Fixed-step resume: take dt0 from timestep (diffrax 0.7.0 keeps a fixed-step controller state) --- essos/dynamics.py | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/essos/dynamics.py b/essos/dynamics.py index 4084aeea..6b5fc860 100644 --- a/essos/dynamics.py +++ b/essos/dynamics.py @@ -1443,12 +1443,12 @@ def _terms(self, key, flag=False, events=()): def _solve(self, terms, solver, controller, t0, y0, args, event, throw=False, resume=False, controller_state=None): """diffeqsolve from t0 to maxtime, saving at self.times (clipped to t0) and at the end. - With ``resume`` it takes at most step_budget steps from ``controller_state`` (None for a fixed step; from - _EventSteps its last entry is the next step) and returns the controller state, so a later solve continues.""" + With ``resume`` it takes at most step_budget steps from ``controller_state`` (from _EventSteps its last entry + is the next step; a fixed step restarts with timestep) and returns the controller state.""" 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, y0=y0, args=args, controller_state=controller_state, - dt0=self.timestep if controller_state is None else controller_state[-1], + dt0=controller_state[-1] if resume and isinstance(controller, _EventSteps) else self.timestep, saveat=SaveAt(subs=[diffrax.SubSaveAt(ts=jnp.clip(self.times, t0, self.maxtime)), diffrax.SubSaveAt(t1=True)], controller_state=resume), stepsize_controller=controller, event=event, throw=throw, From 94ddf9cd0693ab58765754819cb97e80cdd6e36b Mon Sep 17 00:00:00 2001 From: Rogerio Jorge Date: Mon, 16 Nov 2026 20:10:26 -0600 Subject: [PATCH 10/11] step_budget: CPU only (rounds were 3-4x slower on an A4000) --- README.md | 1 + essos/dynamics.py | 6 ++++-- 2 files changed, 5 insertions(+), 2 deletions(-) diff --git a/README.md b/README.md index e7f07cf0..0ef3fbb8 100644 --- a/README.md +++ b/README.md @@ -276,6 +276,7 @@ the `wout` directly and DESC fits it. ± is the binomial standard error. running to the step count of the slowest; this pays for large batches with many early losses on few threads (1.9x less CPU for 64 edge-born alphas on one thread, 1.6x for 256 in a VMEC field) and costs time on small batches. + It is ignored on a GPU, where the rounds were 3-4x slower than one solve. - **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 6b5fc860..a4fc1d3b 100644 --- a/essos/dynamics.py +++ b/essos/dynamics.py @@ -1112,7 +1112,8 @@ def __init__(self, trajectories_input=None, initial_conditions=None, times_to_tr self.particle_batch_size = None if particle_batch_size is None else int(particle_batch_size) # With step_budget, particles advance at most that many steps per round, finished ones (at maxtime or a # stopping criterion) leave the batch, and the rest continue. A vmapped solve otherwise runs every particle to - # the step count of the slowest. Not under a JAX transformation, FullOrbit_Boris or the clipped controller. + # the step count of the slowest. CPU only; not under a JAX transformation, FullOrbit_Boris or the clipped + # controller. if step_budget is not None and (model in ('FullOrbit_Boris', 'GuidingCenterCollisionsMuAdaptative') or int(step_budget) <= 0): raise ValueError("step_budget must be a positive integer, and not for FullOrbit_Boris or " @@ -1315,7 +1316,8 @@ def trace(self): y0, keys = self.initial_conditions, self.particles.random_keys if self.particles else None n = len(y0) traced = any(isinstance(x, jax.core.Tracer) for x in tree_util.tree_leaves((y0, keys, self.args, self.exterior_field))) - if self.step_budget is not None and not traced: + # Rounds only pay on a CPU: on a GPU (A4000) the per-round cost made them 3-4x slower than one solve. + if self.step_budget is not None and not traced and self.devices[0].platform == "cpu": return self._trace_vmec_rounds(y0, keys) if self._vmec_default else self._trace_rounds(y0, keys) batch = n if self.particle_batch_size is None or traced else min(self.particle_batch_size, n) # Sharding pays off for plain traces. A differentiated trace stays on one device: XLA 0.6 aborts compiling From cf34c1978f63c9cf883ea4363a4230617c7e80fd Mon Sep 17 00:00:00 2001 From: Rogerio Jorge Date: Tue, 17 Nov 2026 14:44:42 -0600 Subject: [PATCH 11/11] Keep the finite placeholder for non-returning orbits in the compacted pass --- essos/dynamics.py | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/essos/dynamics.py b/essos/dynamics.py index 22d18b7b..84642211 100644 --- a/essos/dynamics.py +++ b/essos/dynamics.py @@ -1610,7 +1610,7 @@ def segment(o, run, spec, y, code, name, to_flux=lambda y: y): stop = run & ~back & ~paused o.update(t=t_end, returns=o["returns"] + back, inside=o["inside"] | back, active=o["active"] & ~stop, status=jnp.select([failed, struck, returned & ~back, stop], [4, 3, 5, 2], o["status"]), - x=jnp.where(run & ~behind, end, o["x"]), y=jnp.where(back, self._vmec_from_exterior(end), o["y"])) + x=jnp.where(run & ~behind, end, o["x"]), y=jnp.where(back, self._vmec_from_exterior(jnp.where(back, end, 0.5)), o["y"])) if budget: o["c_in"] = tree_util.tree_map(lambda a, b: jnp.where(back, a, b), o["c0_in"], o["c_in"]) return o