DOPRI853Integrator#

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

Bases: Integrator

Dormand-Prince 85(3) adaptive step-size integrator.

This integrator implements the Dormand-Prince method, which is an explicit Runge-Kutta method with adaptive step-size control. It uses a 5th-order accurate formula for advancing the solution and an embedded 3rd-order formula for error estimation.

For Python integration, this class wraps SciPy’s implementation of the integrator. The default tolerances (atol=1.49e-8, rtol=1.49e-8) may be too loose for many astronomical applications. Consider using tighter tolerances like atol=1e-10 and rtol=1e-10 for better accuracy:

>>> integrator = DOPRI853Integrator(func, atol=1e-10, rtol=1e-10)

For Cython integration, this class wraps a C implementation based on the original Hairer and Wanner code. The C version includes dense output functionality (new in v1.10) that allows efficient evaluation at arbitrary times through internal interpolation.

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, 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.

**kwargs

Additional keyword arguments for the integrator:

For Python (SciPy) integration:

  • atol (float) : Absolute tolerance (default: 1.49e-8)

  • rtol (float) : Relative tolerance (default: 1.49e-8)

  • nsteps (int) : Maximum number of steps (default: 500)

  • max_step (float) : Maximum step size (default: 0.0, no limit)

  • first_step (float) : Initial step size (default: 0.0, automatic)

For Cython integration:

  • atol (float) : Absolute error tolerance per step

  • rtol (float) : Relative error tolerance per step

  • nmax (int) : Maximum number of integration steps

  • dt_max (float) : Maximum internal timestep

  • nstiff (int) : Steps before checking for stiffness

  • err_if_fail (bool) : Raise error if integration fails

  • log_output (bool) : Log debug messages from C integrator

Notes

The DOPRI853 method is well-suited for smooth problems where high accuracy is required. It automatically adjusts the step size to maintain the specified error tolerances, making it efficient for problems with varying time scales.

References

  • Dormand, J. R. & Prince, P. J. (1980). A family of embedded Runge-Kutta formulae. Journal of Computational and Applied Mathematics, 6(1), 19-26.

  • Hairer, E., Nørsett, S. P. & Wanner, G. (1993). Solving Ordinary Differential Equations I. Springer-Verlag.

Examples

Create an integrator with tight tolerances:

>>> def derivs(t, w):
...     # Simple harmonic oscillator
...     return np.array([w[1], -w[0]])
>>> integrator = DOPRI853Integrator(derivs, atol=1e-12, rtol=1e-12)

Methods Summary

__call__(w0[, mmap])

Run the integrator starting from the specified initial conditions.

run(w0[, mmap])

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.