Corrector Backends

The backends module provides core correction algorithms.

Base Backend

_CorrectorBackend()

Abstract base class for iterative correction algorithms.

class hiten.algorithms.corrector.backends._CorrectorBackend(*, stepper_factory=None)[source]

Bases: _HitenBaseBackend

Define an abstract base class for iterative correction algorithms.

This class defines the interface for iterative correction algorithms used throughout the hiten framework to solve nonlinear systems of equations. It provides a generic, domain-independent interface that can be specialized for different types of problems (periodic orbits, invariant manifolds, fixed points, etc.).

Notes

Subclasses must implement the correct() method and are expected to document any additional keyword arguments specific to their correction strategy (maximum iterations, tolerances, step control parameters, etc.).

Examples

>>> # Typical usage pattern (conceptual)
>>> class NewtonCorrector(_CorrectorBackend):
...     def correct(self, x0, residual_fn, **kwargs):
...         # Newton-Raphson implementation
...         pass
>>>
>>> corrector = NewtonCorrector()
>>> x_corrected, info = corrector.correct(
...     x0=initial_guess,
...     residual_fn=lambda x: compute_constraints(x),
...     jacobian_fn=lambda x: compute_jacobian(x)
... )

See also

_BaseCorrectionConfig

Configuration class for correction parameters.

newton

Concrete Newton-Raphson implementations.

stepping

Step-size control interfaces for robust convergence.

Parameters:

stepper_factory (Callable[[Callable[[ndarray], ndarray], Callable[[ndarray], float], float | None], CorrectorStepProtocol] | None)

abstractmethod run(x0, residual_fn, *, jacobian_fn=None, norm_fn=None, stepper_factory=None, **kwargs)[source]

Solve nonlinear system to find x such that ||R(x)|| < tolerance.

This method implements the core correction algorithm, iteratively refining an initial guess until the residual norm falls below the specified tolerance or the maximum number of iterations is reached.

The method is designed to handle a wide range of nonlinear systems arising in dynamical systems analysis, with particular emphasis on robustness and numerical stability for problems in astrodynamics.

Parameters:

  • x0 (ndarray) – Initial guess for the parameter vector. Should be reasonably close to the expected solution for best convergence properties. The quality of the initial guess significantly affects both convergence rate and success probability.

  • residual_fn (ResidualFn) – Function computing the residual vector R(x) for parameter vector x. The residual should be zero (or close to zero) at the desired solution. Must be well-defined and preferably continuous in a neighborhood of the solution.

  • jacobian_fn (JacobianFn, optional) – Function returning the Jacobian matrix J(x) = dR/dx. If not provided, implementations may use finite-difference approximation or other Jacobian-free methods. Analytic Jacobians generally provide better convergence properties.

  • norm_fn (NormFn, optional) – Custom norm function for assessing convergence. If not provided, implementations typically default to the L2 (Euclidean) norm. The choice of norm can affect convergence behavior and should be appropriate for the problem scaling.

  • stepper_factory (callable, optional) – Factory producing a CorrectorStepProtocol instance for the current problem. Allows callers to override the backend’s default step strategy on a per-problem basis.

  • **kwargs – Additional algorithm-specific parameters. Common parameters include maximum iterations, convergence tolerance, step control settings, and line search configuration. See subclass documentation for specific options.

Returns:

  • x_corrected (ndarray) – Corrected parameter vector satisfying ||R(x_corrected)|| < tol. Has the same shape as the input x0.

  • info (Any) – Algorithm-specific auxiliary information about the correction process. Common contents include: - Number of iterations performed - Final residual norm achieved - Convergence status and diagnostics - Computational cost metrics The exact structure and content is implementation-defined.

Raises:

  • ConvergenceError – If the algorithm fails to converge within the specified maximum number of iterations or encounters numerical difficulties.

  • ValueError – If input parameters are invalid or incompatible.

Return type:

Tuple[ndarray, Any]

Examples

>>> # Basic usage with analytic Jacobian
>>> x_corr, info = corrector.correct(
...     x0=np.array([1.0, 0.0, 0.5]),
...     residual_fn=lambda x: compute_orbit_constraints(x),
...     jacobian_fn=lambda x: compute_constraint_jacobian(x)
... )
>>>
>>> # Usage with custom norm and finite differences
>>> x_corr, info = corrector.correct(
...     x0=initial_state,
...     residual_fn=manifold_constraints,
...     norm_fn=lambda r: np.linalg.norm(r, ord=np.inf),
...     max_attempts=100,
...     tol=1e-12
... )

Newton-Raphson Backend

_NewtonBackend()

Implement the Newton-Raphson algorithm with robust linear algebra and step control.

class hiten.algorithms.corrector.backends._NewtonBackend(*, stepper_factory=None)[source]

Bases: _CorrectorBackend

Implement the Newton-Raphson algorithm with robust linear algebra and step control.

Combines Newton-Raphson iteration with Armijo line search, automatic handling of ill-conditioned Jacobians, and extensible hooks for customization. Uses multiple inheritance to separate step control from core Newton logic.

Parameters:

stepper_factory (StepperFactory) – The stepper factory to use.

Notes

This class is designed to be mixed with _ArmijoStep to provide a robust Newton-Raphson algorithm with Armijo line search.

run(x0, residual_fn, *, jacobian_fn=None, norm_fn=None, stepper_factory=None, tol=1e-10, max_attempts=25, max_delta=0.01, fd_step=1e-08)[source]

Solve nonlinear system using Newton-Raphson method.

Parameters:

  • x0 (np.ndarray) – Initial guess.

  • residual_fn (ResidualFn) – Function to compute residual vector R(x).

  • jacobian_fn (JacobianFn or None, optional) – Function to compute Jacobian dR/dx. Uses finite-difference if None.

  • norm_fn (NormFn or None, optional) – Function to compute residual norm. Uses L2 norm if None.

  • tol (float, default=1e-10) – Convergence tolerance for residual norm.

  • max_attempts (int, default=25) – Maximum number of Newton iterations.

  • max_delta (float or None, default=1e-2) – Maximum step size for numerical stability.

  • fd_step (float, default=1e-8) – Step size for finite-difference Jacobian.

  • stepper_factory (Callable[[Callable[[ndarray], ndarray], Callable[[ndarray], float], float | None], CorrectorStepProtocol] | None)

Returns:

  • x_solution (np.ndarray) – Converged solution vector.

  • iterations (int) – Number of iterations performed.

  • residual_norm (float) – Final residual norm achieved.

Raises:

RuntimeError – If Newton method fails to converge within max_attempts.

Return type:

Tuple[ndarray, int, float]