LeapfrogIntegrator#

class gala.integrate.LeapfrogIntegrator(func, func_args=(), func_units=None, progress=False, save_all=True)[source]#

Bases: Integrator

Symplectic leapfrog integrator for Hamiltonian systems.

The leapfrog integrator is a second-order symplectic method that is particularly well-suited for integrating Hamiltonian systems over long time periods. It conserves energy exactly for linear systems and approximately for nonlinear systems, with bounded energy errors.

The method alternately updates positions and momenta (velocities) in a “leapfrog” pattern, where velocities are evaluated at half-integer timesteps relative to positions. This staggered evaluation is what gives the method its symplectic properties.

Parameters:

funccallable(): A function that computes the phase-space coordinate derivatives. Must have signature func(t, w, *func_args) where t is time, w is the phase-space position array with shape (2*ndim, ...), and *func_args are additional arguments.
func_argstuple, optional: Additional arguments to pass to the derivative function.
func_unitsUnitSystem, optional: Unit system assumed by the integrand function.
progressbool, optional: Display a progress bar during integration. Default is False.
save_allbool, optional: Save the orbit at all timesteps. If False, only save the final state. Default is True.

Notes

The leapfrog method uses the following update scheme:

\[\begin{split}v_{i+1/2} &= v_{i-1/2} + a_i \Delta t \\ x_{i+1} &= x_i + v_{i+1/2} \Delta t\end{split}\]

where \(a_i = F(t_i, x_i, v_{i-1/2})\) is the acceleration at position \(x_i\).

The integrator automatically handles the initial half-step offset for velocities by computing \(v_{1/2} = v_0 + a_0 \Delta t / 2\) from the initial conditions.

Advantages:

Symplectic (preserves phase-space structure)
Time-reversible
Excellent long-term energy conservation
Computationally efficient (one force evaluation per step)

Disadvantages:

Only second-order accurate
Requires fixed timesteps
Less accurate than higher-order methods for smooth problems

References

Verlet, L. (1967). Computer “experiments” on classical fluids. Physical Review, 159(1), 98-103.
Leimkuhler, B. & Reich, S. (2004). Simulating Hamiltonian Dynamics. Cambridge University Press.

Examples

Simple harmonic oscillator with Hamiltonian \(H = \\frac{1}{2}(p^2 + q^2)\):

def derivs(t, w):
    q, p = w[0], w[1]  # position, momentum
    return np.array([p, -q])  # [dq/dt, dp/dt]

integrator = LeapfrogIntegrator(derivs)
orbit = integrator(w0=[1.0, 0.0], dt=0.1, n_steps=1000)

The derivative function must return an array where the first half contains position derivatives (velocities) and the second half contains momentum derivatives (accelerations).

Methods Summary

`__call__`(w0[, mmap])	Run the integrator starting from the specified initial conditions.
`run`(w0[, mmap])
`step`(t, x_im1, v_im1_2, dt)	Advance the integration by one timestep using the leapfrog scheme.

Methods Documentation

__call__(w0, mmap=None, **time_spec)[source]#

Run the integrator starting from the specified initial conditions.

This method integrates the orbit forward in time from the given initial phase-space position according to the time specification.

Parameters:

w0PhaseSpacePosition

Initial conditions for the integration.

mmapndarray, optional

A pre-allocated memory-mapped array to store the results. Must have the correct shape for the expected output.

**time_spec

Keyword arguments specifying the integration time. Accepted combinations include:

dt, n_steps[, t1] : Fixed timestep and number of steps
dt, t1, t2 : Fixed timestep with start and end times
t : Array of specific times to integrate to

Returns:

orbitOrbit: The integrated orbit containing positions, velocities, and times.

Notes

The time specification is parsed by parse_time_specification(). See that function’s documentation for more details on the accepted formats.

run(w0, mmap=None, **time_spec)#: Deprecated since version 1.9: The run function is deprecated and may be removed in a future version. Use Integrator call method instead.

Run the integrator starting from the specified phase-space position.

Deprecated since version 1.9: Use the __call__ method instead.

step(t, x_im1, v_im1_2, dt)[source]#

Advance the integration by one timestep using the leapfrog scheme.

This method performs a single leapfrog step, updating positions and velocities according to the symplectic leapfrog algorithm.

Parameters:

tfloat: Current time.
x_im1ndarray: Position at the previous timestep, shape (ndim, norbits).
v_im1_2ndarray: Velocity at the previous half-timestep, shape (ndim, norbits).
dtfloat: Integration timestep.

Returns:

x_indarray: Updated position at the current timestep.
v_indarray: Velocity at the current timestep (synchronized with position).
v_ip1_2ndarray: Velocity at the next half-timestep, ready for the next integration step.

Notes

The leapfrog step consists of: 1. Update position: \(x_i = x_{i-1} + v_{i-1/2} \Delta t\) 2. Compute force: \(F_i = F(t, x_i, v_{i-1/2})\) 3. Update velocity: \(v_{i+1/2} = v_{i-1/2} + a_i \Delta t\) 4. Compute synchronized velocity: \(v_i = (v_{i-1/2} + v_{i+1/2})/2\)