Corrector Base

The base module provides the core corrector framework and user-facing interface for correction.

Main Classes

class hiten.algorithms.corrector.base.CorrectorPipeline[source]

Bases: _HitenBaseFacade, Generic[DomainT, InterfaceT, ConfigT, ResultT]

Generic facade for correction algorithms.

This facade provides a clean, high-level interface for correcting any domain object (orbits, manifolds, etc.) using the configured correction algorithm. It orchestrates the complete correction pipeline and handles configuration, error management, and result processing.

The facade is domain-agnostic and works with any domain through the interface pattern. Domain-specific logic is handled by the interface, not the facade.

Parameters:

  • config (ConfigT) – Configuration object for the correction algorithm.

  • interface (InterfaceT) – Interface instance for the correction algorithm.

  • engine (_CorrectionEngine, optional) – Engine instance to use for correction. If None, must be set later or use with_default_engine() factory method.

  • backend (_CorrectorBackend)

Examples

Basic usage with default settings:

>>> from hiten.algorithms.corrector import CorrectorPipeline
>>> from hiten.algorithms.corrector.config import _OrbitCorrectionConfig
>>> from hiten.algorithms.corrector.engine import _OrbitCorrectionEngine
>>> from hiten.algorithms.corrector.interfaces import _PeriodicOrbitCorrectorInterface
>>> from hiten.algorithms.corrector.backends.newton import _NewtonBackend
>>>
>>> # Create components
>>> config = _OrbitCorrectionConfig()
>>> backend = _NewtonBackend()
>>> interface = _PeriodicOrbitCorrectorInterface()
>>> engine = _OrbitCorrectionEngine(backend=backend, interface=interface)
>>>
>>> # Create facade
>>> corrector = CorrectorPipeline(config, interface, engine)
>>> result = corrector.correct(orbit)
classmethod with_default_engine(*, config, interface=None, backend=None)[source]

Create a facade instance with a default engine (factory).

Parameters:

  • config (ConfigT) – Configuration object for the correction algorithm.

  • interface (InterfaceT, optional) – Interface instance for the correction algorithm. If None, uses the default _PeriodicOrbitCorrectorInterface.

  • backend (_CorrectorBackend, optional) – Backend instance for the correction algorithm. If None, uses the default _NewtonBackend.

Returns:

A correction facade instance with a default engine injected.

Return type:

CorrectorPipeline

correct(domain_obj, override=False, *, max_attempts=None, tol=None, max_delta=None, line_search_config=None, finite_difference=None, fd_step=None, method=None, order=None, steps=None, forward=None, residual_indices=None, control_indices=None, extra_jacobian=None, target=None, event_func=None, stepper=None)[source]

Correct the domain object using the configured engine.

This method corrects any domain object using the configured correction algorithm. It delegates to the interface to handle domain-specific logic.

Parameters:

  • domain_obj (DomainT) – The domain object to correct (e.g., PeriodicOrbit, Manifold).

  • override (bool) – Whether to override the default configuration.

  • max_attempts (Optional[int]) – The maximum number of attempts to correct the domain object.

  • tol (Optional[float]) – The tolerance for the correction.

  • max_delta (Optional[float]) – The maximum delta for the correction.

  • line_search_config (Optional[_LineSearchConfig]) – The line search configuration.

  • finite_difference (Optional[bool]) – Whether to use finite difference for the correction.

  • fd_step (Optional[float]) – The finite difference step size.

  • method (Optional[Literal["fixed", "adaptive", "symplectic"]]) – The method for the correction.

  • order (Optional[int]) – The order for the correction.

  • steps (Optional[int]) – The number of steps for the correction.

  • forward (Optional[int]) – The direction for the correction.

  • residual_indices (Optional[tuple[int, ...]]) – The indices for the residual.

  • control_indices (Optional[tuple[int, ...]]) – The indices for the control.

  • extra_jacobian (Optional[Callable[[np.ndarray, np.ndarray], np.ndarray]]) – The extra jacobian for the correction.

  • target (Optional[tuple[float, ...]]) – The target for the correction.

  • event_func (Optional[Callable[..., tuple[float, np.ndarray]]]) – The event function for the correction.

  • stepper (Optional[StepperFactory]) – The stepper factory for the correction.

  • **kwargs – Additional correction parameters that vary by facade implementation. Common parameters may include: - Correction tolerances and limits - Algorithm-specific options - Output formatting preferences

Returns:

Domain-specific correction result containing: - Corrected parameters - Convergence information - Algorithm diagnostics

Return type:

ResultT

get_convergence_summary()[source]

Get a summary of convergence statistics for batch results.

Parameters:

results (list[ResultT]) – List of correction results.

Returns:

Summary statistics including:

  • total_objects: Total number of objects

  • converged: Number of converged objects

  • failed: Number of failed objects

  • success_rate: Percentage of successful corrections

  • avg_iterations: Average iterations for converged objects

  • avg_residual_norm: Average residual norm for converged objects

Return type:

dict[str, Any]