opengnc.integrators package

Submodules

opengnc.integrators.ab_moulton module

Adams-Bashforth-Moulton 8th order predictor-corrector integrator.

class opengnc.integrators.ab_moulton.AdamsBashforthMoultonIntegrator

Bases: Integrator

Adams-Bashforth-Moulton 8th order Integrator (Predictor-Corrector Ordinate Form). Treats the ODE system as a first-order system: dy/dt = f(t, y).

integrate(f: Callable, t_span: tuple[float, float], y0: ndarray, dt: float = 10.0, **kwargs: Any) → tuple[ndarray, ndarray]

Integrate over a time span using Adams-Bashforth-Moulton 8th order.

step(f: Callable, t: float, y: ndarray, dt: float, **kwargs: Any) → tuple[ndarray, float, float]

Single step interface (not recommended for multi-step integrators).

opengnc.integrators.dop853_coeffs module

Coefficients for Dormand-Prince 8(5,3) integrator (DOP853).

opengnc.integrators.gauss_jackson module

Gauss-Jackson 8th order predictor-corrector integrator for second-order ODEs.

class opengnc.integrators.gauss_jackson.GaussJacksonIntegrator

Bases: Integrator

Gauss-Jackson 8th order Integrator (Predictor-Corrector Summed Form). Specifically for second-order ODEs: dy/dt = [v, a]. Assumes state y = [r, v] where r, v are 3D vectors.

integrate(f: Callable, t_span: tuple[float, float], y0: ndarray, dt: float = 10.0, **kwargs: Any) → tuple[ndarray, ndarray]

Integrate over a time span using Gauss-Jackson 8th order.

step(f: Callable, t: float, y: ndarray, dt: float, **kwargs: Any) → tuple[ndarray, float, float]

Single step interface.

opengnc.integrators.integrator module

Abstract base class for numerical integrators.

class opengnc.integrators.integrator.Integrator

Bases: ABC

Abstract base class for numerical ODE integrators.

Provides a common interface for fixed-step and variable-step numerical integration of first-order differential equations $dot{y} = f(t, y)$.

integrate(f: Callable, t_span: tuple[float, float], y0: ndarray, dt: float = 0.01, **kwargs: Any) → tuple[ndarray, ndarray]

Integrate the differential equation over a specified time interval.

Parameters:

• f (Callable) – Derivative function $f(t, y, dots)$.

• t_span (tuple[float, float]) – Interval of integration $(t_{start}, t_{final})$ (s).

• y0 (np.ndarray) – Initial state vector.

• dt (float, optional) – Initial time step size (s). Default 0.01.

• **kwargs (Any) – Additional arguments for $f$.

Returns:

(t_values, y_values) for documentation and plotting.

Return type:

tuple[np.ndarray, np.ndarray]

abstractmethod step(f: Callable, t: float, y: ndarray, dt: float, **kwargs: Any) → tuple[ndarray, float, float]

Perform a single integration step.

Parameters:

• f (Callable) – Derivative function $f(t, y, dots) to dot{y}$.

• t (float) – Current time $t_n$ (s).

• y (np.ndarray) – Current state $y_n$.

• dt (float) – User-requested time step size $h$ (s).

• **kwargs (Any) – Additional arguments for $f$.

Returns:

(y_next, t_next, dt_suggested). - y_next: State at $t_n + dt$. - t_next: Final time $t_n + dt$ (s). - dt_suggested: Recommended next step size (s).

Return type:

tuple[np.ndarray, float, float]

opengnc.integrators.rk4 module

Fixed-step Runge-Kutta 4th order integrator.

class opengnc.integrators.rk4.RK4

Bases: Integrator

Fixed-step 4th Order Runge-Kutta (RK4).

Step Logic: $k_1 = f(t_n, y_n)$ $k_2 = f(t_n + frac{h}{2}, y_n + frac{h}{2} k_1)$ $k_3 = f(t_n + frac{h}{2}, y_n + frac{h}{2} k_2)$ $k_4 = f(t_n + h, y_n + h k_3)$ $y_{n+1} = y_n + frac{h}{6}(k_1 + 2k_2 + 2k_3 + k_4)$

Parameters:

None

step(f: Callable, t: float, y: ndarray, dt: float, **kwargs: Any) → tuple[ndarray, float, float]

Perform a single RK4 step.

Parameters:

• f (Callable) – Derivative function f(t, y, **kwargs).

• t (float) – Current time $t_n$ (s).

• y (np.ndarray) – Current state $y_n$.

• dt (float) – Time step $h$ (s).

Returns:

(y_next, t_next, dt).

Return type:

tuple[np.ndarray, float, float]

opengnc.integrators.rk45 module

Adaptive-step Runge-Kutta-Fehlberg 4(5) integrator.

class opengnc.integrators.rk45.RK45(rtol: float = 1e-06, atol: float = 1e-09, safety_factor: float = 0.9, min_factor: float = 0.2, max_factor: float = 10.0)

Bases: Integrator

Runge-Kutta-Fehlberg 4(5) Adaptive Variable Step Integrator.

Implements the Fehlberg embedded method that calculates both a 4th and 5th order solution at each step to estimate local truncation error.

Parameters:

• rtol (float, optional) – Relative error tolerance. Default 1e-6.

• atol (float, optional) – Absolute error tolerance. Default 1e-9.

• safety_factor (float, optional) – Safety multiplier for step-size prediction. Default 0.9.

• min_factor (float, optional) – Minimum step-size reduction ratio. Default 0.2.

• max_factor (float, optional) – Maximum step-size expansion ratio. Default 10.0.

integrate(f: Callable, t_span: tuple[float, float], y0: ndarray, dt: float | None = None, **kwargs: Any) → tuple[ndarray, ndarray]

Integrate over span with adaptive stepping.

Parameters:

• f (Callable) – Derivative function.

• t_span (tuple[float, float]) – (t0, tf) (s).

• y0 (np.ndarray) – Initial state.

• dt (float, optional) – Initial trial step.

Returns:

(t_values, y_values).

Return type:

tuple[np.ndarray, np.ndarray]

step(f: Callable, t: float, y: ndarray, dt: float, **kwargs: Any) → tuple[ndarray, float, float]

Perform a single adaptive RK45 step with error control.

Parameters:

• f (Callable) – Derivative function.

• t (float) – Current time $t_n$ (s).

• y (np.ndarray) – Current state.

• dt (float) – Trial time step size (s).

• **kwargs (Any) – Additional parameters for $f$.

Returns:

(y_next, t_next, dt_new).

Return type:

tuple[np.ndarray, float, float]

Raises:

RuntimeError – If convergence fails and step size falls below epsilon.

opengnc.integrators.rk853 module

Adaptive-step Dormand-Prince 8(5,3) integrator (DOP853).

class opengnc.integrators.rk853.RK853(rtol: float = 1e-09, atol: float = 1e-12, safety_factor: float = 0.9, min_factor: float = 0.2, max_factor: float = 10.0)

Bases: Integrator

Dormand-Prince 8(5,3) Variable Step Integrator. High order integrator for high precision requirements.

integrate(f: Callable, t_span: tuple[float, float], y0: ndarray, dt: float | None = None, **kwargs: Any) → tuple[ndarray, ndarray]

Integrate the differential equation over a specified time interval.

Parameters:

• f (Callable) – Derivative function $f(t, y, dots)$.

• t_span (tuple[float, float]) – Interval of integration $(t_{start}, t_{final})$ (s).

• y0 (np.ndarray) – Initial state vector.

• dt (float, optional) – Initial time step size (s). Default 0.01.

• **kwargs (Any) – Additional arguments for $f$.

Returns:

(t_values, y_values) for documentation and plotting.

Return type:

tuple[np.ndarray, np.ndarray]

step(f: Callable, t: float, y: ndarray, dt: float, **kwargs: Any) → tuple[ndarray, float, float]

Perform a single adaptive RK853 step.

opengnc.integrators.symplectic module

Symplectic integrator (Yoshida 4th order) for conservative systems.

class opengnc.integrators.symplectic.SymplecticIntegrator

Bases: Integrator

Symplectic Integrator (Yoshida 4th order). Conserves Energy/Hamiltonian for conservative systems (like Two-Body gravity). Assumes state vector y = [r, v] where dy/dt = [v, a(r)]. Specifically for systems where a depends only on r (a = f(r)).

integrate(f: Callable, t_span: tuple[float, float], y0: ndarray, dt: float = 10.0, **kwargs: Any) → tuple[ndarray, ndarray]

Integrate over time span. Note: Symplectic methods work BEST for TIME-INVARIANT potentials (a = f(r)). f: function that returns [v, a].

step(f: Callable, t: float, y: ndarray, dt: float, **kwargs: Any) → tuple[ndarray, float, float]

Single step wrapper.

opengnc.integrators.taylor module

Taylor Series Numerical Integrator.

class opengnc.integrators.taylor.TaylorIntegrator(order: int = 2)

Bases: Integrator

Taylor Series expansion-based numerical integrator.

Solves $dot{y} = f(t, y)$ by expanding $y$ as a Taylor series up to a specified order.

Parameters:

order (int, optional) – Taylor expansion order (1-4). Default 2.

step(f: Callable, t: float, y: ndarray, dt: float, **kwargs: Any) → tuple[ndarray, float, float]

Perform a single Taylor series step.

Parameters:

• f (Callable) – Derivative function.

• t (float) – Current time.

• y (np.ndarray) – Current state.

• dt (float) – Time step.

Returns:

(y_next, t_next, dt_suggested).

Return type:

tuple[np.ndarray, float, float]

Module contents