stop_reasons.h

// Copyright 2026 Julien Michot.
// SPDX-License-Identifier: Apache-2.0
 
#pragma once
 
#include <ostream>
#include <sstream>
 
#include <tinyopt/traits.h>
 
namespace tinyopt {

enum StopReason : int {
 
  kOutOfMemory = -4,        
  kSolverFailed = -3,       
  kSystemHasNaNOrInf = -2,  
  kSkipped = -1,            

 
  kNone = 0,         
  kMinError,         
  kMinRelError,      
  kMinDeltaNorm,     
  kMinGradNorm,      
  kMaxIters,         
  kMaxNoDecr,        
  kMaxConsecNoDecr,  
  kTimedOut,         
  kUserStopped       

};

template <typename Summary, typename Options = std::nullptr_t>
std::string StopReasonDescription(const Summary &sum, const Options &options = {}) {
  std::ostringstream os;
  switch (sum.stop_reason) {
    case StopReason::kNone:
      os << "🌱 Optimization not ran or used with Step() (success)";
      break;
    case StopReason::kMinError:
      os << "🌞 Reached minimum error (success)";
      if constexpr (!traits::is_nullptr_v<Options>)
        os << " ε:[" << (double)sum.final_cost << " < " << options.stop.min_error << "]";
      break;
    case StopReason::kMinRelError:
      os << "🌞 Reached minimum relative error (success)";
      if constexpr (!traits::is_nullptr_v<Options>)
        os << " ε:[" << sum.final_rerr_dec << " < " << options.stop.min_rerr_dec << "]";
      break;
    case StopReason::kMinDeltaNorm:
      os << "🌞 Reached minimal delta norm (success)";
      if constexpr (!traits::is_nullptr_v<Options>) {
        if (!sum.hist.empty())
          os << " |δX|:[" << sum.hist.last_delta2() << " < "
             << std::sqrt(options.stop.min_step_norm2) << "]";
        else
          os << " [|δX| < " << std::sqrt(options.stop.min_step_norm2) << "]";
      }
      break;
    case StopReason::kMinGradNorm:
      os << "🌞 Reached minimal gradient (success)";
      if constexpr (!traits::is_nullptr_v<Options>)
        os << " [|∇| < " << std::sqrt(options.stop.min_grad_norm2) << "]";
      break;
    case StopReason::kMaxIters:
      os << "⛅ Reached maximum number of iterations (success)";
      if constexpr (!traits::is_nullptr_v<Options>)
        os << " [#it == " << (int)options.stop.max_iters << "]";
      break;
    case StopReason::kMaxNoDecr:
      os << "⛅ Failed to decrease error too many times (success)";
      if constexpr (!traits::is_nullptr_v<Options>)
        os << " [=" << (int)options.stop.max_total_failures << "]";
      break;
    case StopReason::kMaxConsecNoDecr:
      os << "⛅ Failed to decrease error consecutively too many times (success)";
      if constexpr (!traits::is_nullptr_v<Options>)
        os << " [=" << (int)options.stop.max_consec_failures << "]";
      break;
    case StopReason::kTimedOut:
      os << "⌛ Reached maximum allocated time (success)";
      if constexpr (!traits::is_nullptr_v<Options>)
        os << " τ:[" << sum.duration_ms << " > " << options.stop.max_duration_ms << "ms]";
      break;
    case StopReason::kUserStopped:
      os << "👍 User stopped the process (success)";
      break;

    case StopReason::kOutOfMemory:
      os << "❌ Out of memory when allocating the Hessian(s), use SparseMatrix? (failure)";
      break;
    case StopReason::kSystemHasNaNOrInf:
      os << "❌ Residuals or Jacobians have NaNs or Inf (failure)";
      break;
    case StopReason::kSolverFailed:
      os << "❌ Failed to solve the normal equations (failure)";
      break;
    case StopReason::kSkipped:
      os << "❌ The system has no residuals or nothing to optimize (failure)";
      break;
    default:
      os << "⛈️ Unknown reason:" << (int)sum.stop_reason;
      break;
  }
  return os.str();
}
 
}  // namespace tinyopt