Integrators Utilities

The utils module provides shared Numba-compatible helpers for integrators.

Event Functions

hiten.algorithms.integrators.utils._event_crossed()[source]

Return True if a crossing consistent with direction occurred.

Accepts endpoint zeros (g_new == 0.0) to catch exact hits at the right endpoint. direction: 0 -> any; >0 -> increasing; <0 -> decreasing.

Parameters:

  • g_prev (float) – The function value at the previous time.

  • g_new (float) – The function value at the new time.

  • direction (int) – The direction of the crossing.

Returns:

True if a crossing consistent with direction occurred.

Return type:

bool

hiten.algorithms.integrators.utils._crossed_direction()[source]

Return True if the sign change from left to mid matches direction.

This variant is used inside in-step refinement where bracket endpoints are maintained as [a,b] mapped to [g_left, g_right]. Endpoint zeros are handled by the caller using a |g_mid| <= gtol test.

Parameters:

  • g_left (float) – The function value at the left endpoint.

  • g_mid (float) – The function value at the midpoint.

  • direction (int) – The direction of the crossing.

Returns:

True if the sign change from left to mid matches direction.

Return type:

bool

hiten.algorithms.integrators.utils._bisection_update()[source]

Update bracket [a,b] and left value using a classic bisection step.

Parameters:

  • a (float) – Current bracket endpoints with a < b.

  • b (float) – Current bracket endpoints with a < b.

  • g_left (float) – Function value at the left endpoint (corresponding to ‘a’).

  • mid (float) – Midpoint (0.5 * (a + b)).

  • g_mid (float) – Function value at the midpoint.

  • crossed (bool) – Whether a sign-consistent crossing was found in [a, mid].

Returns:

a_new, b_new, g_left_new – Updated bracket and left endpoint value consistent with the choice.

Return type:

tuple[float, float, float]

hiten.algorithms.integrators.utils._bracket_converged()[source]

Return True if bracket size mapped to time is within tolerance.

Parameters:

  • a (float) – The left endpoint of the bracket.

  • b (float) – The right endpoint of the bracket.

  • h (float) – The step size.

  • xtol (float) – The tolerance.

Returns:

True if the bracket is converged.

Return type:

bool

Step Control Functions

hiten.algorithms.integrators.utils._select_initial_step()[source]

Heuristic initial step selection used by adaptive RK methods.

Matches the pattern used across RK45/DOP853: small fixed step for tiny norms, otherwise 0.01 * d0 / d1, clamped to [min_step, max_step].

Parameters:

  • d0 (float) – The initial derivative.

  • d1 (float) – The second derivative.

  • min_step (float) – The minimum step size.

  • max_step (float) – The maximum step size.

Returns:

The initial step size.

Return type:

float

hiten.algorithms.integrators.utils._clamp_step()[source]

Clamp step size into [min_step, max_step].

Parameters:

  • h (float) – The step size.

  • max_step (float) – The maximum step size.

  • min_step (float) – The minimum step size.

Returns:

The clamped step size.

Return type:

float

hiten.algorithms.integrators.utils._adjust_step_to_endpoint()[source]

Adjust step so that t + h does not overshoot t_end for forward time.

Assumes forward integration (t_end >= t).

Parameters:

  • t (float) – The current time.

  • h (float) – The step size.

  • t_end (float) – The end time.

Returns:

The adjusted step size.

Return type:

float

PI Controller Functions

hiten.algorithms.integrators.utils._pi_accept_factor()[source]

Compute PI controller factor after an accepted step.

Uses Hairer-style PI control with alpha = 0.4/(order+1) and beta = 1/(order+1). Returns a factor clamped to [_MIN_FACTOR, _MAX_FACTOR] with finite fallback.

Parameters:

  • err_norm (float) – The error norm.

  • err_prev (float) – The previous error norm.

  • order (float) – The order of the method.

Returns:

The PI controller factor.

Return type:

float

hiten.algorithms.integrators.utils._pi_reject_factor()[source]

Compute PI controller factor after a rejected step.

Uses exponent err_exp = 1/order; clamps and sanitizes the factor.

Parameters:

  • err_norm (float) – The error norm.

  • order (float) – The order of the method.

Returns:

The PI controller factor.

Return type:

float

Error Functions

hiten.algorithms.integrators.utils._error_scale()[source]

Return elementwise error scale vector used for error norms.

Computes atol + rtol * max(|y|, |y_high|) elementwise.

Parameters: