Corrector Configuration
The config module provides configuration classes for iterative correction algorithms.
Base Configuration
_BaseCorrectionConfig()
Define a base configuration class for correction algorithm parameters.
- class hiten.algorithms.corrector.config._BaseCorrectionConfig(max_attempts=50, tol=1e-10, max_delta=0.01, line_search_config=True, finite_difference=False, fd_step=1e-08, method='adaptive', order=8, steps=500, forward=1)[source]
Bases:
objectDefine a base configuration class for correction algorithm parameters.
This dataclass encapsulates the common configuration parameters used by correction algorithms throughout the hiten framework. It provides sensible defaults while allowing customization for specific problem requirements and numerical considerations.
The configuration is designed to be immutable (frozen) for thread safety and to prevent accidental modification during algorithm execution. The slots optimization reduces memory overhead when many configuration objects are created.
- Parameters:
max_attempts (int, default=50) – Maximum number of Newton iterations to attempt before declaring convergence failure. This prevents infinite loops in cases where the algorithm fails to converge.
tol (float, default=1e-10) – Convergence tolerance for the residual norm. The algorithm terminates successfully when the norm of the residual falls below this value. Should be chosen based on the required precision and numerical conditioning of the problem.
max_delta (float, default=1e-2) – Maximum allowed infinity norm of Newton steps. This serves as a safeguard against excessively large steps that could cause numerical overflow or move far from the solution. Particularly important for poorly conditioned problems or bad initial guesses.
line_search_config (
_LineSearchConfig, bool, or None, default=True) – Configuration for line search behavior: - True: Enable line search with default parameters - False or None: Disable line search (use full Newton steps) -_LineSearchConfig: Enable line search with custom parameters Line search improves robustness for challenging problems at the cost of additional function evaluations.finite_difference (bool, default=False) – Force finite-difference approximation of Jacobians even when analytic Jacobians are available. Useful for debugging, testing, or when analytic Jacobians are suspected to be incorrect. Generally results in slower convergence but can be more robust.
fd_step (float, default=1e-8) – Finite-difference step size used when computing Jacobians via central differences. Scaled internally per-parameter by max(1, |x[i]|) to maintain relative step size.
method (str, default="adaptive") – Integration method for trajectory computation.
order (int, default=8) – Integration order for numerical methods.
steps (int, default=500) – Number of integration steps.
forward (int, default=1) – Integration direction (1 for forward, -1 for backward).
Notes
The default parameters are chosen to work well for typical problems in astrodynamics and dynamical systems, particularly in the context of the Circular Restricted Three-Body Problem (CR3BP).
- line_search_config: _LineSearchConfig | bool | None
Orbit Correction Configuration
_OrbitCorrectionConfig()
Define a configuration for periodic orbit correction.
- class hiten.algorithms.corrector.config._OrbitCorrectionConfig(max_attempts=50, tol=1e-10, max_delta=0.01, line_search_config=True, finite_difference=False, fd_step=1e-08, method='adaptive', order=8, steps=500, forward=1, residual_indices=(), control_indices=(), extra_jacobian=None, target=(0.0, ), event_func=<function _plane_crossing_factory.<locals>._section_crossing>)[source]
Bases:
_BaseCorrectionConfigDefine a configuration for periodic orbit correction.
Extends the base correction configuration with orbit-specific parameters for constraint selection, integration settings, and event detection.
- Parameters:
residual_indices (tuple of int, default=()) – State components used to build the residual vector.
control_indices (tuple of int, default=()) – State components allowed to change during correction.
extra_jacobian (callable or None, default=None) – Additional Jacobian contribution function.
target (tuple of float, default=(0.0,)) – Target values for the residual components.
event_func (callable, default=:class:~hiten.algorithms.poincare.singlehit.backend._y_plane_crossing) – Function to detect Poincare section crossings.
max_attempts (int)
tol (float)
max_delta (float)
line_search_config (_LineSearchConfig | bool | None)
finite_difference (bool)
fd_step (float)
method (Literal['fixed', 'adaptive', 'symplectic'])
order (int)
steps (int)
forward (int)
Line Search Configuration
_LineSearchConfig()
Define configuration parameters for Armijo line search.
- class hiten.algorithms.corrector.config._LineSearchConfig(norm_fn=None, residual_fn=None, jacobian_fn=None, max_delta=0.01, alpha_reduction=0.5, min_alpha=0.0001, armijo_c=0.1)[source]
Bases:
NamedTupleDefine configuration parameters for Armijo line search.
- Parameters:
norm_fn (
NormFnor None, default=None) – Function to compute residual norm. Uses L2 norm if None.residual_fn (
ResidualFnor None, default=None) – Function to compute residual vector. Must be provided.jacobian_fn (
JacobianFnor None, default=None) – Jacobian function (currently unused).max_delta (float, default=1e-2) – Maximum allowed step size (infinity norm).
alpha_reduction (float, default=0.5) – Factor to reduce step size in backtracking.
min_alpha (float, default=1e-4) – Minimum step size before giving up.
armijo_c (float, default=0.1) – Armijo parameter for sufficient decrease condition.