integrator.hpp File Reference

The interface every time integrator presents, and the contract about accelerations that makes the cheap ones cheap. More...

#include <string_view>
#include "orrery/core/particle_data.hpp"
#include "orrery/core/types.hpp"
#include "orrery/integrators/acceleration_field.hpp"

Go to the source code of this file.

Classes
class	orrery::integrators::Integrator
	A method for advancing particle positions and velocities through time. More...

Functions
void	orrery::integrators::refresh_accelerations (core::ParticleData &data, AccelerationField &field)
	Establish the acceleration invariant for a configuration.

Detailed Description

The interface every time integrator presents, and the contract about accelerations that makes the cheap ones cheap.

A gravitational N-body step is dominated by one thing: the force evaluation. Everything else an integrator does is a handful of multiplications per particle against N^2 interactions, so an integrator is judged almost entirely by how many evaluations it needs per step and how much accuracy it gets for them. Velocity Verlet needs one, Yoshida's fourth-order composition three, and RK4 four.

Velocity Verlet only needs one because it uses the acceleration at the start of the step, which is the same acceleration the previous step already computed at the end of its own. Recomputing it would double the cost of the method for no change in the answer. The saving is only available if the acceleration survives between steps, so this interface makes that explicit:

`accelerations()` holds the acceleration at `positions()`.

refresh_accelerations establishes it, and every step requires it on entry and restores it on exit. A caller that changes the positions behind an integrator's back, or that swaps in a different acceleration field, calls refresh_accelerations again. ADR-0013 records why the invariant is stated here rather than left to each integrator to manage privately.

The methods below are not const and an integrator is not safe to use from two threads at once: RK4 owns stage buffers, and a scheme with a variable step would own more. One integrator per simulation is the intended use.

Function Documentation

refresh_accelerations()

void orrery::integrators::refresh_accelerations ( core::ParticleData & data, AccelerationField & field )

inline

Establish the acceleration invariant for a configuration.

Call once before the first step, and again after anything outside the integrator changes the positions, the masses or the field.

A free function rather than a member, because it belongs to the contract rather than to any method: every integrator needs the invariant established the same way, and one that established it differently would be establishing something else. It lives in this header so that it is found where the contract it serves is written.