Ruth4Integrator#

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

Bases: Integrator

Fourth-order symplectic integrator using Ruth’s method.

This integrator implements a fourth-order symplectic integration scheme developed by Ruth (1983). It provides higher accuracy than the standard leapfrog method while preserving the symplectic structure of Hamiltonian systems, making it excellent for long-term orbital integrations.

The method uses a composition of multiple leapfrog-like steps with carefully chosen coefficients to achieve fourth-order accuracy while maintaining symplecticity and time-reversibility.

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 Ruth4 method uses the following composition coefficients:

\[\begin{split}c_1 = c_4 &= \\frac{1}{2(2-2^{1/3})} \\\\ c_2 = c_3 &= \\frac{1-2^{1/3}}{2(2-2^{1/3})} \\\\ d_1 &= 0 \\\\ d_2 &= \\frac{1}{2-2^{1/3}} \\\\ d_3 &= \\frac{-2^{1/3}}{2-2^{1/3}} \\\\ d_4 &= \\frac{1}{2-2^{1/3}}\end{split}\]

Each timestep consists of four substeps that collectively achieve fourth-order accuracy.

Advantages:

  • Fourth-order accuracy (vs second-order for leapfrog)

  • Symplectic (preserves phase-space structure)

  • Time-reversible

  • Excellent long-term stability for Hamiltonian systems

Disadvantages:

  • More expensive than leapfrog (4 force evaluations per step)

  • Requires fixed timesteps

  • Can be less stable than leapfrog for some stiff problems

References

  • Ruth, R. D. (1983). A canonical integration technique. IEEE Transactions on Nuclear Science, 30(4), 2669-2671.

  • Forest, E. & Ruth, R. D. (1990). Fourth-order symplectic integration. Physica D, 43(1), 105-117.

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 = Ruth4Integrator(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, w, dt)

Step forward the positions and velocities by the given timestep.

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, w, dt)[source]#

Step forward the positions and velocities by the given timestep.

Parameters:
dtnumeric

The timestep to move forward.