options.h

// Copyright 2026 Julien Michot.
// SPDX-License-Identifier: Apache-2.0
 
#pragma once
 
#include <cstdint>
#include <functional>
 
#include <tinyopt/log.h>
#include <tinyopt/math.h>
 
namespace tinyopt {
 
/***
 *  @brief Common Optimization Options
 *
 ***/
struct Options {
  enum Solver {
    LevenbergMarquardt = 0,
    GaussNewton,
    GradientDescent,
    ConjugateGradient,
    DogLeg,
    BFGS,
    LBFGS,
  };
  Solver solver_type = Solver::LevenbergMarquardt;

  LinearSolverMethod linear_solver = LinearSolverMethod::LDLT;
  double svd_relative_threshold = 0.0;
 
  Options(Solver type = Solver::LevenbergMarquardt) : solver_type(type) {};

  struct Optimization {
    bool check_final_cost = false;

    bool use_step_quality_approx = false;

    float grad_clipping = 0;
  } opt;


 
  struct Hessian {
    bool H_is_full = true;  
 
    float check_min_H_diag = 0;  
 
    bool save_last = true;  
  } hessian;


  struct CostScaling {
    bool use_squared_norm = true;  
    bool downscale_by_2 = false;   
    bool normalize = false;
  } cost;


  struct StopCriteria {
    uint16_t max_iters = 50;          
    float min_error = 1e-12f;         
    float min_rerr_dec = 1e-10f;      
    float min_step_norm2 = 1e-14f;    
    float min_grad_norm2 = 1e-18f;    
    uint8_t max_total_failures = 0;   
    uint8_t max_consec_failures = 5;  
    double max_duration_ms = 0;       
 
    std::function<bool(double, double, double)> stop_callback;
    std::function<bool(float, const VecXf &, const VecXf &)> stop_callback2;
    std::function<bool(const VecXf &dx, bool is_rollback)> step_callback;
  } stop;


  struct LogOptions {
    bool enable = true;          
    std::string e = "ε²";        
    bool print_emoji = true;     
    bool print_x = false;        
    bool print_dx = false;       
    bool print_inliers = false;  
    bool print_t = true;         
    bool print_J_jet = false;    
    bool print_max_stdev = false;  
    bool print_failure = false;    // Log when a failure to solve the linear system happens
  } log;

 
  struct LM {
    bool jacobi_scaling = false;  
    float damping_init = 1e-4f;  
    std::array<float, 2> damping_range{{1e-9f, 1e9f}};
 
    float good_factor = 1.0f / 3.0f;  
    float bad_factor = 2.0f;          
  } lm;

  struct GD {
    float lr = 1e-3f;  
    // TODO float min_lr = 1e-6f;  ///< Minimum learning rate
    // TODO float max_lr = 1e6f;   ///< Maximum learning rate
    // TODO float decay_factor = 0.5f;        ///< Factor to decay the learning rate (if adaptive)
    // TODO bool use_adaptive_lr = false;     ///< Whether to use adaptive learning rate
  } gd;
 
  struct CG {
    float step_size = 0.25f;
    float step_reduction = 0.5f;
  } cg;
 
  struct DL {
    float radius_init = 1.0f;
    float radius_max = 1e6f;
    float shrink_factor = 0.25f;
    float expand_factor = 2.0f;
  } dl;
 
  struct BFGS {
    float step_size = 1.0f;
    float step_reduction = 0.5f;
    float step_growth = 1.5f;
    float max_step_size = 1.0f;
    float curvature_threshold = 1e-8f;
  } bfgs;
 
  struct LBFGS {
    float step_size = 1.0f;
    float step_reduction = 0.5f;
    float step_growth = 1.5f;
    float max_step_size = 1.0f;
    float curvature_threshold = 1e-8f;
    uint8_t history_size = 8;
  } lbfgs;
};
 
}  // namespace tinyopt