regit-svi 2.0.0

// Copyright 2026 Regit.io — Nicolas Koenig
// SPDX-License-Identifier: Apache-2.0

//! Calibration diagnostics and optimizer termination evidence.

use crate::no_arb::evidence::ArbitrageAssessment;

/// Raw SVI domain margins recomputed from the returned slice.
#[derive(Debug, Clone, Copy, PartialEq)]
pub struct RawParameterMargins {
    slope: f64,
    correlation: f64,
    sigma: f64,
    minimum_variance: f64,
    arbitrage: f64,
}

impl RawParameterMargins {
    pub(crate) const fn new(
        slope: f64,
        correlation: f64,
        sigma: f64,
        minimum_variance: f64,
        arbitrage: f64,
    ) -> Self {
        Self {
            slope,
            correlation,
            sigma,
            minimum_variance,
            arbitrage,
        }
    }

    /// Distance from the `b >= 0` boundary.
    #[must_use]
    pub const fn slope(self) -> f64 {
        self.slope
    }
    /// Distance from the open `|rho| < 1` boundary.
    #[must_use]
    pub const fn correlation(self) -> f64 {
        self.correlation
    }
    /// Distance from the `sigma > 0` boundary.
    #[must_use]
    pub const fn sigma(self) -> f64 {
        self.sigma
    }
    /// Minimum total variance.
    #[must_use]
    pub const fn minimum_variance(self) -> f64 {
        self.minimum_variance
    }
    /// Signed margin from the final arbitrage assessment.
    #[must_use]
    pub const fn arbitrage(self) -> f64 {
        self.arbitrage
    }
}

/// SSVI parameter and feasibility margins recomputed from the returned model.
#[derive(Debug, Clone, Copy, PartialEq)]
pub struct SurfaceParameterMargins {
    correlation: f64,
    phi_scale: f64,
    phi_shape: f64,
    butterfly: f64,
    calendar: f64,
}

impl SurfaceParameterMargins {
    pub(crate) const fn new(
        correlation: f64,
        phi_scale: f64,
        phi_shape: f64,
        butterfly: f64,
        calendar: f64,
    ) -> Self {
        Self {
            correlation,
            phi_scale,
            phi_shape,
            butterfly,
            calendar,
        }
    }
    /// Distance from the open `|rho| < 1` boundary.
    #[must_use]
    pub const fn correlation(self) -> f64 {
        self.correlation
    }
    /// Distance to the hard calibration-family scale boundary.
    #[must_use]
    pub const fn phi_scale(self) -> f64 {
        self.phi_scale
    }
    /// Distance to the hard calibration-family shape boundary; infinity for
    /// the one-parameter Heston family.
    #[must_use]
    pub const fn phi_shape(self) -> f64 {
        self.phi_shape
    }
    /// Signed global butterfly-envelope margin.
    #[must_use]
    pub const fn butterfly(self) -> f64 {
        self.butterfly
    }
    /// Signed calendar-condition margin.
    #[must_use]
    pub const fn calendar(self) -> f64 {
        self.calendar
    }
}

/// Parameter-transform and repair policy used to produce a returned model.
#[derive(Debug, Clone, Copy, PartialEq, Eq)]
pub struct ParameterizationEvidence {
    transform: &'static str,
    repair: &'static str,
}

impl ParameterizationEvidence {
    pub(crate) const fn new(transform: &'static str, repair: &'static str) -> Self {
        Self { transform, repair }
    }
    /// Hard transform used to map optimizer coordinates into the model domain.
    #[must_use]
    pub const fn transform(self) -> &'static str {
        self.transform
    }
    /// Projection, repair, or invalid-candidate policy.
    #[must_use]
    pub const fn repair(self) -> &'static str {
        self.repair
    }
}

/// Why a calibration search stopped.
#[derive(Debug, Clone, Copy, PartialEq, Eq)]
pub enum TerminationReason {
    /// Objective and search geometry met their tolerances.
    ObjectiveConverged,
    /// The weighted gradient norm met its tolerance.
    GradientConverged,
    /// An accepted parameter step met its tolerance.
    StepConverged,
    /// No cost-reducing step was found; this is not convergence.
    Stagnated,
    /// The local normal equations remained singular.
    SingularModel,
    /// A required objective or residual evaluation was non-finite.
    NonFiniteEvaluation,
    /// The configured iteration budget was exhausted.
    MaximumIterations,
}

impl From<crate::numerics::OptimizerTermination> for TerminationReason {
    fn from(reason: crate::numerics::OptimizerTermination) -> Self {
        use crate::numerics::OptimizerTermination;
        match reason {
            OptimizerTermination::ObjectiveConverged => Self::ObjectiveConverged,
            OptimizerTermination::GradientConverged => Self::GradientConverged,
            OptimizerTermination::StepConverged => Self::StepConverged,
            OptimizerTermination::Stagnated => Self::Stagnated,
            OptimizerTermination::SingularModel => Self::SingularModel,
            OptimizerTermination::NonFiniteEvaluation => Self::NonFiniteEvaluation,
            OptimizerTermination::IterationLimit => Self::MaximumIterations,
        }
    }
}

/// Residual diagnostics recomputed from the final returned model.
#[derive(Debug, Clone, Copy, PartialEq)]
pub struct ResidualDiagnostics {
    objective: f64,
    rmse: f64,
    max_absolute: f64,
    positive_weight_quotes: usize,
    distinct_strikes: usize,
    omitted_quotes: usize,
    total_weight: f64,
}

impl ResidualDiagnostics {
    pub(crate) const fn new(
        objective: f64,
        rmse: f64,
        max_absolute: f64,
        positive_weight_quotes: usize,
        distinct_strikes: usize,
        omitted_quotes: usize,
        total_weight: f64,
    ) -> Self {
        Self {
            objective,
            rmse,
            max_absolute,
            positive_weight_quotes,
            distinct_strikes,
            omitted_quotes,
            total_weight,
        }
    }

    /// Final weighted sum of squared residuals.
    #[must_use]
    pub const fn objective(self) -> f64 {
        self.objective
    }
    /// Final weighted root-mean-square residual.
    #[must_use]
    pub const fn rmse(self) -> f64 {
        self.rmse
    }
    /// Largest absolute residual among positive-weight observations.
    #[must_use]
    pub const fn max_absolute(self) -> f64 {
        self.max_absolute
    }
    /// Number of positive-weight observations used.
    #[must_use]
    pub const fn positive_weight_quotes(self) -> usize {
        self.positive_weight_quotes
    }
    /// Number of sufficiently distinct strikes used.
    #[must_use]
    pub const fn distinct_strikes(self) -> usize {
        self.distinct_strikes
    }
    /// Number of zero-weight observations omitted from the objective.
    #[must_use]
    pub const fn omitted_quotes(self) -> usize {
        self.omitted_quotes
    }
    /// Sum of positive fitting weights.
    #[must_use]
    pub const fn total_weight(self) -> f64 {
        self.total_weight
    }
}

/// Complete termination and postcondition evidence for a Raw slice fit.
#[derive(Debug, Clone, Copy, PartialEq)]
pub struct CalibrationReport {
    algorithm: &'static str,
    starts: usize,
    selected_start: Option<usize>,
    tolerance: f64,
    condition_estimate: Option<f64>,
    parameterization: ParameterizationEvidence,
    margins: RawParameterMargins,
    iterations: usize,
    evaluations: usize,
    termination: TerminationReason,
    residuals: ResidualDiagnostics,
    arbitrage: ArbitrageAssessment,
}

impl CalibrationReport {
    #[allow(clippy::too_many_arguments, clippy::large_types_passed_by_value)]
    pub(crate) const fn new(
        iterations: usize,
        evaluations: usize,
        termination: TerminationReason,
        residuals: ResidualDiagnostics,
        arbitrage: ArbitrageAssessment,
        algorithm: &'static str,
        starts: usize,
        selected_start: Option<usize>,
        tolerance: f64,
        condition_estimate: Option<f64>,
        parameterization: ParameterizationEvidence,
        margins: RawParameterMargins,
    ) -> Self {
        Self {
            algorithm,
            starts,
            selected_start,
            tolerance,
            condition_estimate,
            parameterization,
            margins,
            iterations,
            evaluations,
            termination,
            residuals,
            arbitrage,
        }
    }

    /// Algorithm or composed pipeline stage that produced the model.
    #[must_use]
    pub const fn algorithm(self) -> &'static str {
        self.algorithm
    }
    /// Number of deterministic starts attempted.
    #[must_use]
    pub const fn starts(self) -> usize {
        self.starts
    }
    /// Zero-based deterministic start that produced the returned model.
    #[must_use]
    pub const fn selected_start(self) -> Option<usize> {
        self.selected_start
    }
    /// Configured numerical termination tolerance.
    #[must_use]
    pub const fn tolerance(self) -> f64 {
        self.tolerance
    }
    /// Estimated condition number of the selected normalized design, when available.
    #[must_use]
    pub const fn condition_estimate(self) -> Option<f64> {
        self.condition_estimate
    }
    /// Parameter transforms and repair policy.
    #[must_use]
    pub const fn parameterization(self) -> ParameterizationEvidence {
        self.parameterization
    }
    /// Recomputed Raw-domain and feasibility margins.
    #[must_use]
    pub const fn margins(self) -> RawParameterMargins {
        self.margins
    }

    /// Total optimizer iterations across all starts/stages.
    #[must_use]
    pub const fn iterations(self) -> usize {
        self.iterations
    }
    /// Total objective or residual evaluations.
    #[must_use]
    pub const fn evaluations(self) -> usize {
        self.evaluations
    }
    /// Optimizer termination reason.
    #[must_use]
    pub const fn termination(self) -> TerminationReason {
        self.termination
    }
    /// Residuals recomputed from the final model.
    #[must_use]
    pub const fn residuals(self) -> ResidualDiagnostics {
        self.residuals
    }
    /// Evidence-bearing Raw SVI arbitrage assessment.
    #[must_use]
    pub const fn arbitrage_assessment(self) -> ArbitrageAssessment {
        self.arbitrage
    }
}

/// Complete termination and feasibility evidence for an SSVI surface fit.
#[derive(Debug, Clone, Copy, PartialEq)]
pub struct SurfaceCalibrationReport {
    algorithm: &'static str,
    starts: usize,
    selected_start: Option<usize>,
    tolerance: f64,
    parameterization: ParameterizationEvidence,
    margins: SurfaceParameterMargins,
    iterations: usize,
    evaluations: usize,
    termination: TerminationReason,
    residuals: ResidualDiagnostics,
    butterfly: ArbitrageAssessment,
    calendar: ArbitrageAssessment,
}

impl SurfaceCalibrationReport {
    #[allow(clippy::too_many_arguments, clippy::large_types_passed_by_value)]
    pub(crate) const fn new(
        iterations: usize,
        evaluations: usize,
        termination: TerminationReason,
        residuals: ResidualDiagnostics,
        butterfly: ArbitrageAssessment,
        calendar: ArbitrageAssessment,
        algorithm: &'static str,
        starts: usize,
        selected_start: Option<usize>,
        tolerance: f64,
        parameterization: ParameterizationEvidence,
        margins: SurfaceParameterMargins,
    ) -> Self {
        Self {
            algorithm,
            starts,
            selected_start,
            tolerance,
            parameterization,
            margins,
            iterations,
            evaluations,
            termination,
            residuals,
            butterfly,
            calendar,
        }
    }

    /// Algorithm used for the joint surface fit.
    #[must_use]
    pub const fn algorithm(self) -> &'static str {
        self.algorithm
    }
    /// Number of deterministic starts attempted.
    #[must_use]
    pub const fn starts(self) -> usize {
        self.starts
    }
    /// Zero-based deterministic start that produced the returned model.
    #[must_use]
    pub const fn selected_start(self) -> Option<usize> {
        self.selected_start
    }
    /// Configured numerical termination tolerance.
    #[must_use]
    pub const fn tolerance(self) -> f64 {
        self.tolerance
    }
    /// Parameter transforms and repair policy.
    #[must_use]
    pub const fn parameterization(self) -> ParameterizationEvidence {
        self.parameterization
    }
    /// Recomputed SSVI-domain and feasibility margins.
    #[must_use]
    pub const fn margins(self) -> SurfaceParameterMargins {
        self.margins
    }

    /// Total optimizer iterations across all starts.
    #[must_use]
    pub const fn iterations(self) -> usize {
        self.iterations
    }
    /// Total objective evaluations across all starts.
    #[must_use]
    pub const fn evaluations(self) -> usize {
        self.evaluations
    }
    /// Optimizer termination reason.
    #[must_use]
    pub const fn termination(self) -> TerminationReason {
        self.termination
    }
    /// Residuals recomputed from the final surface.
    #[must_use]
    pub const fn residuals(self) -> ResidualDiagnostics {
        self.residuals
    }
    /// Whole-family analytic sufficient butterfly assessment.
    #[must_use]
    pub const fn butterfly_assessment(self) -> ArbitrageAssessment {
        self.butterfly
    }
    /// Analytic calendar assessment on the validated term structure.
    #[must_use]
    pub const fn calendar_assessment(self) -> ArbitrageAssessment {
        self.calendar
    }
}