Struct DogLegConfig 

pub struct DogLegConfig {

    pub linear_solver_type: LinearSolverType,
    pub max_iterations: usize,
    pub cost_tolerance: f64,
    pub parameter_tolerance: f64,
    pub gradient_tolerance: f64,
    pub timeout: Option<Duration>,
    pub trust_region_radius: f64,
    pub trust_region_min: f64,
    pub trust_region_max: f64,
    pub trust_region_increase_factor: f64,
    pub trust_region_decrease_factor: f64,
    pub min_step_quality: f64,
    pub good_step_quality: f64,
    pub poor_step_quality: f64,
    pub use_jacobi_scaling: bool,
    pub initial_mu: f64,
    pub min_mu: f64,
    pub max_mu: f64,
    pub mu_increase_factor: f64,
    pub enable_step_reuse: bool,
    pub min_cost_threshold: Option<f64>,
    pub max_condition_number: Option<f64>,
    pub min_relative_decrease: f64,
    pub compute_covariances: bool,
}

Configuration parameters for the Dog Leg trust region optimizer.

Controls trust region management, convergence criteria, adaptive regularization, and Ceres Solver enhancements for the Dog Leg algorithm.

Builder Pattern

All configuration options can be set using the builder pattern:

use apex_solver::optimizer::dog_leg::DogLegConfig;

let config = DogLegConfig::new()
    .with_max_iterations(100)
    .with_trust_region_radius(1e4)
    .with_mu_params(1e-4, 1e-8, 1.0, 10.0)
    .with_jacobi_scaling(true)
    .with_step_reuse(true);

Trust Region Behavior

The trust region radius Δ controls the maximum allowed step size:

• Initial radius (trust_region_radius): Starting value (default: 1e4)
• Bounds (trust_region_min, trust_region_max): Valid range (default: 1e-3 to 1e6)
• Adaptation: Increases for good steps, decreases for poor steps

Adaptive μ Regularization (Ceres Enhancement)

Controls the regularization parameter in (J^T·J + μI)·h = -J^T·r:

• initial_mu: Starting value (default: 1e-4 for numerical stability)
• min_mu, max_mu: Bounds (default: 1e-8 to 1.0)
• mu_increase_factor: Multiplier when solve fails (default: 10.0)

Convergence Criteria

The optimizer terminates when ANY of the following conditions is met:

• Cost tolerance: |cost_k - cost_{k-1}| < cost_tolerance
• Parameter tolerance: ||step|| < parameter_tolerance
• Gradient tolerance: ||J^T·r|| < gradient_tolerance
• Maximum iterations: iteration >= max_iterations
• Timeout: elapsed_time >= timeout

See Also

• DogLeg - The solver that uses this configuration
• LevenbergMarquardtConfig - Alternative damping approach
• GaussNewtonConfig - Undamped variant

Fields

linear_solver_type: LinearSolverType

Type of linear solver for the linear systems

max_iterations: usize

Maximum number of iterations

cost_tolerance: f64

Convergence tolerance for cost function

parameter_tolerance: f64

Convergence tolerance for parameter updates

gradient_tolerance: f64

Convergence tolerance for gradient norm

timeout: Option<Duration>

Timeout duration

trust_region_radius: f64

Initial trust region radius

trust_region_min: f64

Minimum trust region radius

trust_region_max: f64

Maximum trust region radius

trust_region_increase_factor: f64

Trust region increase factor (for good steps, rho > 0.75)

trust_region_decrease_factor: f64

Trust region decrease factor (for poor steps, rho < 0.25)

min_step_quality: f64

Minimum step quality for acceptance (typically 0.0)

good_step_quality: f64

Good step quality threshold (typically 0.75)

poor_step_quality: f64

Poor step quality threshold (typically 0.25)

use_jacobi_scaling: bool

Use Jacobi column scaling (preconditioning)

initial_mu: f64

Initial mu regularization parameter for Gauss-Newton step

min_mu: f64

Minimum mu regularization parameter

max_mu: f64

Maximum mu regularization parameter

mu_increase_factor: f64

Factor to increase mu when linear solver fails

enable_step_reuse: bool

Enable step reuse after rejection (Ceres-style efficiency optimization)

min_cost_threshold: Option<f64>

Minimum objective function cutoff (optional early termination)

If set, optimization terminates when cost falls below this threshold. Useful for early stopping when a “good enough” solution is acceptable.

Default: None (disabled)

max_condition_number: Option<f64>

Maximum condition number for Jacobian matrix (optional check)

If set, the optimizer checks if condition_number(J^T*J) exceeds this threshold and terminates with IllConditionedJacobian status. Note: Computing condition number is expensive, so this is disabled by default.

Default: None (disabled)

min_relative_decrease: f64

Minimum relative cost decrease for step acceptance

Used in computing step quality (rho = actual_reduction / predicted_reduction). Steps with rho < min_relative_decrease are rejected. Matches Ceres Solver’s min_relative_decrease parameter.

Default: 1e-3 (Ceres-compatible)

compute_covariances: bool

Compute per-variable covariance matrices (uncertainty estimation)

When enabled, computes covariance by inverting the Hessian matrix after convergence. The full covariance matrix is extracted into per-variable blocks stored in both Variable structs and optimizer::SolverResult.

Default: false (to avoid performance overhead)

Implementations

impl DogLegConfig

pub fn new() -> Self

Create a new Dog Leg configuration with default values.

pub fn with_linear_solver_type( self, linear_solver_type: LinearSolverType, ) -> Self

Set the linear solver type

pub fn with_max_iterations(self, max_iterations: usize) -> Self

Set the maximum number of iterations

pub fn with_cost_tolerance(self, cost_tolerance: f64) -> Self

Set the cost tolerance

pub fn with_parameter_tolerance(self, parameter_tolerance: f64) -> Self

Set the parameter tolerance

pub fn with_gradient_tolerance(self, gradient_tolerance: f64) -> Self

Set the gradient tolerance

pub fn with_timeout(self, timeout: Duration) -> Self

Set the timeout duration

pub fn with_trust_region_radius(self, radius: f64) -> Self

Set the initial trust region radius

pub fn with_trust_region_bounds(self, min: f64, max: f64) -> Self

Set the trust region radius bounds

pub fn with_trust_region_factors(self, increase: f64, decrease: f64) -> Self

Set the trust region adjustment factors

pub fn with_step_quality_thresholds( self, min_quality: f64, poor_quality: f64, good_quality: f64, ) -> Self

Set the trust region quality thresholds

pub fn with_jacobi_scaling(self, use_jacobi_scaling: bool) -> Self

Enable or disable Jacobi column scaling (preconditioning)

pub fn with_mu_params( self, initial_mu: f64, min_mu: f64, max_mu: f64, increase_factor: f64, ) -> Self

Set adaptive mu regularization parameters (Ceres-style)

pub fn with_step_reuse(self, enable_step_reuse: bool) -> Self

Enable or disable step reuse optimization (Ceres-style)

pub fn with_min_cost_threshold(self, min_cost: f64) -> Self

Set minimum objective function cutoff for early termination.

When set, optimization terminates with MinCostThresholdReached status if the cost falls below this threshold. Useful for early stopping when a “good enough” solution is acceptable.

pub fn with_max_condition_number(self, max_cond: f64) -> Self

Set maximum condition number for Jacobian matrix.

If set, the optimizer checks if condition_number(J^T*J) exceeds this threshold and terminates with IllConditionedJacobian status. Note: Computing condition number is expensive, disabled by default.

pub fn with_min_relative_decrease(self, min_decrease: f64) -> Self

Set minimum relative cost decrease for step acceptance.

Steps with rho = (actual_reduction / predicted_reduction) below this threshold are rejected. Default: 1e-3 (Ceres-compatible)

pub fn with_compute_covariances(self, compute_covariances: bool) -> Self

Enable or disable covariance computation (uncertainty estimation).

When enabled, computes the full covariance matrix by inverting the Hessian after convergence, then extracts per-variable covariance blocks.

pub fn print_configuration(&self)

Print configuration parameters (info level logging)

Trait Implementations

impl Clone for DogLegConfig

fn clone(&self) -> DogLegConfig

Returns a duplicate of the value.

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source.

impl Default for DogLegConfig

fn default() -> Self

Returns the “default value” for a type.