Enable rounding in UFR interpolation (#2342)

Author: lballabio

ql/termstructures/yield/ultimateforwardtermstructure.hpp

@@ -1,7 +1,7 @@
 /* -*- mode: c++; tab-width: 4; indent-tabs-mode: nil; c-basic-offset: 4 -*- */
 
 /*
- Copyright (C) 2020 Marcin Rybacki
+ Copyright (C) 2020, 2025 Marcin Rybacki
 
  This file is part of QuantLib, a free-software/open-source library
  for financial quantitative analysts and developers - http://quantlib.org/
@@ -24,6 +24,8 @@
 #ifndef quantlib_ultimate_forward_term_structure_hpp
 #define quantlib_ultimate_forward_term_structure_hpp
 
+#include <ql/math/rounding.hpp>
+#include <ql/optional.hpp>
 #include <ql/quote.hpp>
 #include <ql/termstructures/yield/zeroyieldstructure.hpp>
 #include <utility>
@@ -40,13 +42,18 @@ namespace QuantLib {
         Bank website:
 
         FTK term structure documentation (Financieel toetsingskader):
-        https://www.toezicht.dnb.nl/binaries/50-212329.pdf
+        https://www.dnb.nl/media/4lmprzrk/vaststelling_methode_rentetermijnstructuur_ftk.pdf
 
-        UFR 2015 term structure documentation:
-        https://www.toezicht.dnb.nl/binaries/50-234028.pdf
+        UFR 2013-2019 term structure documentation:
+        https://www.dnb.nl/media/0vmbxaf4/methodologie-dnb.pdf
 
-        UFR 2019 term structure documentation:
-        https://www.rijksoverheid.nl/documenten/kamerstukken/2019/06/11/advies-commissie-parameters
+        UFR 2023 term structure documentation (p.46):
+        https://www.tweedekamer.nl/downloads/document?id=2022D50944
+
+        Optionally, computed zero rates may be rounded.
+        The specified number of decimal places will affect the rate
+        in decimal format; for example, rounding a rate of 1.5555%
+        to 5 decimal places results in 0.015555 becoming 0.01556, or 1.556%.
 
         This term structure will remain linked to the original
         structure, i.e., any changes in the latter will be
@@ -65,6 +72,7 @@ namespace QuantLib {
         - incorrect input for cut-off point should raise an exception.
         - observability against changes in the underlying term
           structure and the additional components is checked.
+        - rounding of output rate with predefined compounding.
     */
 
     class UltimateForwardTermStructure : public ZeroYieldStructure {
@@ -73,7 +81,10 @@ namespace QuantLib {
                                      Handle<Quote> lastLiquidForwardRate,
                                      Handle<Quote> ultimateForwardRate,
                                      const Period& firstSmoothingPoint,
-                                     Real alpha);
+                                     Real alpha,
+                                     const ext::optional<Integer>& roundingDigits = ext::nullopt,
+                                     Compounding compounding = Compounded,
+                                     Frequency frequency = Annual);
         //! \name YieldTermStructure interface
         //@{
         DayCounter dayCounter() const override;
@@ -91,11 +102,18 @@ namespace QuantLib {
         Rate zeroYieldImpl(Time) const override;
         //@}
       private:
+        //! applies rounding on zero rate with required compounding
+        Rate applyRounding(Rate r, Time t) const;
+        //@}
+
         Handle<YieldTermStructure> originalCurve_;
         Handle<Quote> llfr_;
         Handle<Quote> ufr_;
         Period fsp_;
         Real alpha_;
+        ext::optional<Integer> roundingDigits_;
+        Compounding compounding_;
+        Frequency frequency_;
     };
 
     // inline definitions
@@ -105,9 +123,13 @@ namespace QuantLib {
         Handle<Quote> lastLiquidForwardRate,
         Handle<Quote> ultimateForwardRate,
         const Period& firstSmoothingPoint,
-        Real alpha)
+        Real alpha,
+        const ext::optional<Integer>& roundingDigits,
+        Compounding compounding,
+        Frequency frequency)
     : originalCurve_(std::move(h)), llfr_(std::move(lastLiquidForwardRate)),
-      ufr_(std::move(ultimateForwardRate)), fsp_(firstSmoothingPoint), alpha_(alpha) {
+      ufr_(std::move(ultimateForwardRate)), fsp_(firstSmoothingPoint), alpha_(alpha),
+      roundingDigits_(roundingDigits), compounding_(compounding), frequency_(frequency) {
         QL_REQUIRE(fsp_.length() > 0,
                    "first smoothing point must be a period with positive length");
         if (!originalCurve_.empty())
@@ -149,6 +171,25 @@ namespace QuantLib {
         }
     }
 
+    inline Rate UltimateForwardTermStructure::applyRounding(Rate r, Time t) const {
+        if (!roundingDigits_.has_value()) {
+            return r;
+        }
+        // Input rate is continuously compounded by definition.
+        // Hence, in case this is also the selected compounding method for rounding,
+        // it is not required to calculate equivalent rates, and rounding
+        // may be applied directly.
+        Rate equivalentRate = compounding_ == Continuous ?
+                                  r :
+                                  InterestRate(r, dayCounter(), Continuous, NoFrequency)
+                                      .equivalentRate(compounding_, frequency_, t);
+        Rate rounded = ClosestRounding(*roundingDigits_)(equivalentRate);
+        return compounding_ == Continuous ?
+                   rounded :
+                   InterestRate(rounded, dayCounter(), compounding_, frequency_)
+                       .equivalentRate(Continuous, NoFrequency, t);
+    }
+
     inline Rate UltimateForwardTermStructure::zeroYieldImpl(Time t) const {
         Time cutOffTime = originalCurve_->timeFromReference(referenceDate() + fsp_);
         Time deltaT = t - cutOffTime;
@@ -167,9 +208,9 @@ namespace QuantLib {
             InterestRate baseRate = originalCurve_->zeroRate(cutOffTime, Continuous, NoFrequency);
             Real beta = (1.0 - std::exp(-alpha_ * deltaT)) / (alpha_ * deltaT);
             Rate extrapolatedForward = ufr_->value() + (llfr_->value() - ufr_->value()) * beta;
-            return (cutOffTime * baseRate + deltaT * extrapolatedForward) / t;
+            return applyRounding((cutOffTime * baseRate + deltaT * extrapolatedForward) / t, t);
         }
-        return originalCurve_->zeroRate(t, Continuous, NoFrequency);
+        return applyRounding(originalCurve_->zeroRate(t, Continuous, NoFrequency), t);
     }
 }
 

test-suite/ultimateforwardtermstructure.cpp

@@ -137,44 +137,68 @@ Rate calculateExtrapolatedForward(Time t, Time fsp, Rate llfr, Rate ufr, Real al
     return ufr + (llfr - ufr) * beta;
 }
 
-
-BOOST_AUTO_TEST_CASE(testDutchCentralBankRates) {
-    BOOST_TEST_MESSAGE("Testing DNB replication of UFR zero annually compounded rates...");
-
+void checkDutchBankRates(const std::vector<Datum> expectedRates,
+                         const ext::optional<Integer>& rounding = ext::nullopt,
+                         Compounding compounding = Compounded,
+                         Frequency frequency = Annual,
+                         Real tolerance = 1.0e-4) {
     CommonVars vars;
 
     ext::shared_ptr<Quote> llfr = calculateLLFR(vars.ftkCurveHandle, vars.fsp);
 
-    ext::shared_ptr<YieldTermStructure> ufrTs(
-        new UltimateForwardTermStructure(vars.ftkCurveHandle, Handle<Quote>(llfr),
-                                         Handle<Quote>(vars.ufrRate), vars.fsp, vars.alpha));
-
-    // Official annually compounded zero rates published
-    // by the Dutch Central Bank: https://statistiek.dnb.nl/
-    Datum expectedZeroes[] = {{10, Years, 0.00477}, {20, Years, 0.01004}, {30, Years, 0.01223},
-                              {40, Years, 0.01433}, {50, Years, 0.01589}, {60, Years, 0.01702},
-                              {70, Years, 0.01785}, {80, Years, 0.01849}, {90, Years, 0.01899},
-                              {100, Years, 0.01939}};
+    ext::shared_ptr<YieldTermStructure> ufrTs(new UltimateForwardTermStructure(
+        vars.ftkCurveHandle, Handle<Quote>(llfr), Handle<Quote>(vars.ufrRate), vars.fsp, vars.alpha,
+        rounding, compounding, frequency));
 
-    Real tolerance = 1.0e-4;
-    Size nRates = std::size(expectedZeroes);
+    Size nRates = std::size(expectedRates);
 
     for (Size i = 0; i < nRates; ++i) {
-        Period p = expectedZeroes[i].n * expectedZeroes[i].units;
+        Period p = expectedRates[i].n * expectedRates[i].units;
         Date maturity = vars.settlement + p;
 
-        Rate actual = ufrTs->zeroRate(maturity, vars.dayCount, Compounded, Annual).rate();
-        Rate expected = expectedZeroes[i].rate;
+        Rate actual = ufrTs->zeroRate(maturity, vars.dayCount, compounding, frequency).rate();
+        Rate expected = expectedRates[i].rate;
 
         if (std::fabs(actual - expected) > tolerance)
             BOOST_ERROR("unable to reproduce zero yield rate from the UFR curve\n"
-                        << std::setprecision(5) 
-                        << "    calculated: " << actual << "\n"
+                        << std::setprecision(5) << "    calculated: " << actual << "\n"
                         << "    expected:   " << expected << "\n"
                         << "    tenor:       " << p << "\n");
     }
 }
 
+BOOST_AUTO_TEST_CASE(testDutchCentralBankRates) {
+    BOOST_TEST_MESSAGE("Testing DNB replication of UFR zero annually compounded rates...");
+
+    std::vector<Datum> expectedRates{
+        {10, Years, 0.00477}, {20, Years, 0.01004}, {30, Years, 0.01223}, {40, Years, 0.01433},
+        {50, Years, 0.01589}, {60, Years, 0.01702}, {70, Years, 0.01785}, {80, Years, 0.01849},
+        {90, Years, 0.01899}, {100, Years, 0.01939}};
+    checkDutchBankRates(expectedRates);
+}
+
+BOOST_AUTO_TEST_CASE(testDutchCentralBankRatesWithRounding) {
+    BOOST_TEST_MESSAGE(
+        "Testing DNB replication of UFR zero annually compounded rates with rounding...");
+    std::vector<Datum> expectedRates{{10, Years, 0.005}, {20, Years, 0.01},   {30, Years, 0.012},
+                                     {40, Years, 0.014}, {50, Years, 0.016}, {60, Years, 0.017},
+                                     {70, Years, 0.018}, {80, Years, 0.018}, {90, Years, 0.019},
+                                     {100, Years, 0.019}};
+
+    checkDutchBankRates(expectedRates, 3, Compounded, Annual, 1.e-12);
+}
+
+BOOST_AUTO_TEST_CASE(testDutchCentralBankRatesWithRoundingAndContinuousCompounding) {
+    BOOST_TEST_MESSAGE(
+        "Testing DNB replication of UFR zero continuously compounded rates with rounding...");
+    std::vector<Datum> expectedRates{
+        {10, Years, 0.00477}, {20, Years, 0.01002}, {30, Years, 0.01211}, {40, Years, 0.01417},
+        {50, Years, 0.01571}, {60, Years, 0.01683}, {70, Years, 0.01766}, {80, Years, 0.01829},
+        {90, Years, 0.01878}, {100, Years, 0.01917}};
+
+    checkDutchBankRates(expectedRates, 5, Continuous, NoFrequency, 1.e-12);
+}
+
 BOOST_AUTO_TEST_CASE(testExtrapolatedForward) {
     BOOST_TEST_MESSAGE("Testing continuous forward rates in extrapolation region...");