volsurf 0.3.0

Production-ready volatility surface library for derivatives pricing
Documentation 
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125

//! Error types for the volsurf library.
//!
//! All fallible operations return `Result<T, VolSurfError>` rather than panicking,
//! providing meaningful diagnostics for calibration failures, invalid inputs, and
//! numerical issues.

use thiserror::Error;

/// Convenience type alias for results in this crate.
pub type Result<T> = std::result::Result<T, VolSurfError>;

/// Errors that can occur during volatility surface construction and queries.
#[derive(Debug, Error)]
#[non_exhaustive]
pub enum VolSurfError {
    /// Smile or surface calibration failed to converge.
    #[error("calibration failed: {message}")]
    CalibrationError {
        message: String,
        /// Model that failed (e.g., "SVI", "SABR").
        model: &'static str,
        /// Final RMS error at convergence, if available.
        rms_error: Option<f64>,
    },

    /// Input data is invalid (e.g., negative vol, zero expiry, mismatched grid sizes).
    #[error("invalid input: {message}")]
    InvalidInput { message: String },

    /// Numerical computation failed (e.g., NaN, ill-conditioned matrix).
    #[error("numerical error: {message}")]
    NumericalError { message: String },

    /// Arbitrage violation detected in the surface.
    #[error("arbitrage detected: {message}")]
    ArbitrageViolation { message: String },
}

#[cfg(test)]
mod tests {
    use super::*;

    // Gap #2: Structured error field access

    #[test]
    fn calibration_error_fields_accessible() {
        let err = VolSurfError::CalibrationError {
            message: "convergence failed".into(),
            model: "SVI",
            rms_error: Some(0.05),
        };
        match &err {
            VolSurfError::CalibrationError {
                message,
                model,
                rms_error,
            } => {
                assert_eq!(message, "convergence failed");
                assert_eq!(*model, "SVI");
                assert_eq!(*rms_error, Some(0.05));
            }
            _ => panic!("wrong variant"),
        }
    }

    #[test]
    fn calibration_error_rms_none() {
        let err = VolSurfError::CalibrationError {
            message: "no grid point found".into(),
            model: "SVI",
            rms_error: None,
        };
        match &err {
            VolSurfError::CalibrationError { rms_error, .. } => {
                assert!(rms_error.is_none());
            }
            _ => panic!("wrong variant"),
        }
    }

    #[test]
    fn invalid_input_message_accessible() {
        let err = VolSurfError::InvalidInput {
            message: "strike must be positive".into(),
        };
        match &err {
            VolSurfError::InvalidInput { message } => {
                assert!(message.contains("positive"));
            }
            _ => panic!("wrong variant"),
        }
    }

    #[test]
    fn error_display_includes_message() {
        let err = VolSurfError::CalibrationError {
            message: "test failure".into(),
            model: "SVI",
            rms_error: Some(0.01),
        };
        let display = format!("{err}");
        assert!(display.contains("test failure"));

        let err2 = VolSurfError::InvalidInput {
            message: "bad input".into(),
        };
        assert!(format!("{err2}").contains("bad input"));

        let err3 = VolSurfError::NumericalError {
            message: "NaN detected".into(),
        };
        assert!(format!("{err3}").contains("NaN detected"));

        let err4 = VolSurfError::ArbitrageViolation {
            message: "calendar spread".into(),
        };
        assert!(format!("{err4}").contains("calendar spread"));
    }

    #[test]
    fn error_is_send_and_sync() {
        fn assert_send_sync<T: Send + Sync>() {}
        assert_send_sync::<VolSurfError>();
    }
}