feat: add SABRInterpolation binding with calibration support

Author: quantales

docs/api/math.md

@@ -281,6 +281,28 @@ Log-space mixed interpolation: log-linear for the first `n` points, log-cubic fo
 .. autoclass:: pyquantlib.LogMixedLinearCubicNaturalSpline
 ```
 
+### SABRInterpolation
+
+```{eval-rst}
+.. autoclass:: pyquantlib.SABRInterpolation
+```
+
+SABR smile interpolation that calibrates alpha, beta, nu, rho to market volatilities.
+
+```python
+strikes = [0.03, 0.04, 0.05, 0.06, 0.07]
+vols = [0.25, 0.22, 0.20, 0.21, 0.23]
+
+interp = ql.SABRInterpolation(
+    strikes, vols, expiry=1.0, forward=0.05,
+    alpha=0.2, beta=0.5, nu=0.4, rho=-0.3,
+    alphaIsFixed=False, betaIsFixed=True,
+    nuIsFixed=False, rhoIsFixed=False,
+)
+interp.update()
+print(f"alpha={interp.alpha():.4f}, rho={interp.rho():.4f}, rms={interp.rmsError():.6f}")
+```
+
 ### ForwardFlatInterpolation
 
 ```{eval-rst}

include/pyquantlib/pyquantlib.h

@@ -99,6 +99,7 @@ namespace ql_math {
     void cubicinterpolation(py::module_&);
     void mixedinterpolation(py::module_&);
     void loginterpolation(py::module_&);
+    void sabrinterpolation(py::module_&);
     void normaldistribution(py::module_&);
     void bivariatenormaldistribution(py::module_&);
     void solvers1d(py::module_&);

pyquantlib/__init__.pyi

@@ -34,6 +34,7 @@ DECLARE_MODULE_BINDINGS(math_bindings) {
     ADD_MAIN_BINDING(ql_math::cubicinterpolation, "Cubic interpolation");
     ADD_MAIN_BINDING(ql_math::mixedinterpolation, "Mixed linear/cubic interpolation");
     ADD_MAIN_BINDING(ql_math::loginterpolation, "Log-cubic and log-mixed interpolation");
+    ADD_MAIN_BINDING(ql_math::sabrinterpolation, "SABR interpolation");
     ADD_MAIN_BINDING(ql_math::normaldistribution, "Normal distribution functions");
     ADD_MAIN_BINDING(ql_math::bivariatenormaldistribution, "Bivariate cumulative normal distribution");
     ADD_MAIN_BINDING(ql_math::solvers1d, "1-D root-finding solvers");

pyquantlib/_pyquantlib/__init__.pyi

@@ -0,0 +1,103 @@
+/*
+ * PyQuantLib: Python bindings for QuantLib
+ * https://github.com/quantales/pyquantlib
+ *
+ * Copyright (c) 2025 Yassine Idyiahia
+ * SPDX-License-Identifier: BSD-3-Clause
+ * See LICENSE for details.
+ *
+ * ---
+ * QuantLib is Copyright (c) 2000-2025 The QuantLib Authors
+ * https://www.quantlib.org/
+ */
+
+#include "pyquantlib/pyquantlib.h"
+#include <ql/math/interpolations/sabrinterpolation.hpp>
+#include <ql/math/optimization/levenbergmarquardt.hpp>
+#include <pybind11/pybind11.h>
+#include <pybind11/stl.h>
+
+namespace py = pybind11;
+using namespace QuantLib;
+
+namespace {
+
+    // Extended data holder that also stores forward on the heap.
+    // SABRInterpolation stores const Real& forward, so forward needs
+    // a stable address that survives the move into shared_ptr's deleter.
+    struct SABRDataHolder {
+        std::vector<Real> x, y;
+        ext::shared_ptr<Real> forward;
+
+        template <typename T>
+        void operator()(T* p) const { delete p; }
+    };
+
+}  // namespace
+
+void ql_math::sabrinterpolation(py::module_& m) {
+    py::class_<SABRInterpolation, Interpolation,
+               ext::shared_ptr<SABRInterpolation>>(
+        m, "SABRInterpolation",
+        "SABR smile interpolation between discrete volatility points.")
+        .def(py::init([](std::vector<Real> strikes,
+                        std::vector<Real> vols,
+                        Real t,
+                        Real forward,
+                        Real alpha, Real beta, Real nu, Real rho,
+                        bool alphaIsFixed, bool betaIsFixed,
+                        bool nuIsFixed, bool rhoIsFixed,
+                        bool vegaWeighted,
+                        const ext::shared_ptr<EndCriteria>& endCriteria,
+                        const ext::shared_ptr<OptimizationMethod>& optMethod,
+                        Real errorAccept,
+                        bool useMaxError,
+                        Size maxGuesses,
+                        Real shift) {
+
+            QL_REQUIRE(strikes.size() == vols.size(),
+                       "strikes and vols must have the same size");
+            QL_REQUIRE(strikes.size() >= 2,
+                       "at least 2 points required");
+
+            SABRDataHolder holder{
+                std::move(strikes), std::move(vols),
+                ext::make_shared<Real>(forward)};
+
+            auto* ptr = new SABRInterpolation(
+                holder.x.begin(), holder.x.end(), holder.y.begin(),
+                t, *holder.forward,
+                alpha, beta, nu, rho,
+                alphaIsFixed, betaIsFixed, nuIsFixed, rhoIsFixed,
+                vegaWeighted, endCriteria, optMethod,
+                errorAccept, useMaxError, maxGuesses,
+                shift);
+
+            return ext::shared_ptr<SABRInterpolation>(ptr, std::move(holder));
+        }),
+        py::arg("strikes"), py::arg("vols"),
+        py::arg("expiry"), py::arg("forward"),
+        py::arg("alpha"), py::arg("beta"), py::arg("nu"), py::arg("rho"),
+        py::arg("alphaIsFixed"), py::arg("betaIsFixed"),
+        py::arg("nuIsFixed"), py::arg("rhoIsFixed"),
+        py::arg("vegaWeighted") = true,
+        py::arg("endCriteria") = ext::shared_ptr<EndCriteria>(),
+        py::arg("optMethod") = ext::shared_ptr<OptimizationMethod>(),
+        py::arg("errorAccept") = 0.0020,
+        py::arg("useMaxError") = false,
+        py::arg("maxGuesses") = Size(50),
+        py::arg("shift") = 0.0,
+        "Constructs SABR interpolation from strikes and volatilities.")
+        .def("expiry", &SABRInterpolation::expiry, "Returns the expiry.")
+        .def("forward", &SABRInterpolation::forward, "Returns the forward.")
+        .def("alpha", &SABRInterpolation::alpha, "Returns calibrated alpha.")
+        .def("beta", &SABRInterpolation::beta, "Returns calibrated beta.")
+        .def("nu", &SABRInterpolation::nu, "Returns calibrated nu.")
+        .def("rho", &SABRInterpolation::rho, "Returns calibrated rho.")
+        .def("rmsError", &SABRInterpolation::rmsError, "Returns RMS calibration error.")
+        .def("maxError", &SABRInterpolation::maxError, "Returns max calibration error.")
+        .def("endCriteria", &SABRInterpolation::endCriteria, "Returns the end criteria type.")
+        .def("interpolationWeights", &SABRInterpolation::interpolationWeights,
+            py::return_value_policy::reference_internal,
+            "Returns the interpolation weights.");
+}

src/math/all.cpp

@@ -492,3 +492,100 @@ def make():
 
     interp = make()
     assert interp(3.0) == pytest.approx(0.95)
+
+
+# ---------------------------------------------------------------------------
+# SABRInterpolation
+# ---------------------------------------------------------------------------
+
+def _sabr_test_data():
+    """Generate SABR test data from known parameters (mirrors QL test suite)."""
+    forward = 0.039
+    expiry = 1.0
+    alpha, beta, nu, rho_val = 0.3, 0.6, 0.02, 0.01
+
+    strikes = [0.03 + 0.002 * i for i in range(31)]
+    vols = [
+        ql.sabrVolatility(K, forward, expiry, alpha, beta, nu, rho_val)
+        for K in strikes
+    ]
+    return strikes, vols, forward, expiry, alpha, beta, nu, rho_val
+
+
+def test_sabr_interpolation_fixed():
+    """SABRInterpolation with all params fixed evaluates correctly."""
+    strikes, vols, forward, expiry, alpha, beta, nu, rho_val = _sabr_test_data()
+
+    interp = ql.SABRInterpolation(
+        strikes, vols, expiry, forward,
+        alpha=alpha, beta=beta, nu=nu, rho=rho_val,
+        alphaIsFixed=True, betaIsFixed=True,
+        nuIsFixed=True, rhoIsFixed=True,
+    )
+    interp.update()
+
+    assert isinstance(interp, ql.base.Interpolation)
+    assert interp.expiry() == pytest.approx(expiry)
+    assert interp.forward() == pytest.approx(forward)
+    assert interp.alpha() == pytest.approx(alpha)
+    assert interp.beta() == pytest.approx(beta)
+
+    # Should reproduce input vols exactly
+    for K, v in zip(strikes, vols):
+        assert interp(K) == pytest.approx(v, rel=1e-10)
+
+
+def test_sabr_interpolation_calibration():
+    """Calibrated SABR recovers original parameters."""
+    strikes, vols, forward, expiry, alpha, beta, nu, rho_val = _sabr_test_data()
+
+    interp = ql.SABRInterpolation(
+        strikes, vols, expiry, forward,
+        alpha=0.2, beta=beta, nu=0.1, rho=0.0,
+        alphaIsFixed=False, betaIsFixed=True,
+        nuIsFixed=False, rhoIsFixed=False,
+        vegaWeighted=True,
+    )
+    interp.update()
+
+    assert interp.alpha() == pytest.approx(alpha, rel=0.01)
+    assert interp.nu() == pytest.approx(nu, rel=0.1)
+    assert interp.rmsError() < 1e-4
+
+
+def test_sabr_interpolation_accessors():
+    """SABR accessors return calibrated values."""
+    strikes, vols, forward, expiry, alpha, beta, nu, rho_val = _sabr_test_data()
+
+    interp = ql.SABRInterpolation(
+        strikes, vols, expiry, forward,
+        alpha=alpha, beta=beta, nu=nu, rho=rho_val,
+        alphaIsFixed=True, betaIsFixed=True,
+        nuIsFixed=True, rhoIsFixed=True,
+    )
+    interp.update()
+
+    assert interp.rmsError() < 1e-10
+    assert interp.maxError() < 1e-10
+    assert interp.endCriteria() is not None
+    weights = interp.interpolationWeights()
+    assert len(weights) == len(strikes)
+
+
+def test_sabr_interpolation_data_lifetime():
+    """SABR interpolation survives after input lists go out of scope."""
+    def make():
+        strikes, vols, forward, expiry, alpha, beta, nu, rho_val = _sabr_test_data()
+        interp = ql.SABRInterpolation(
+            strikes, vols, expiry, forward,
+            alpha=alpha, beta=beta, nu=nu, rho=rho_val,
+            alphaIsFixed=True, betaIsFixed=True,
+            nuIsFixed=True, rhoIsFixed=True,
+        )
+        interp.update()
+        return interp
+
+    interp = make()
+    val = interp(0.05)
+    assert math.isfinite(val)
+    assert val > 0