19370422724

Committed 14 Nov 2025 04:10PM UTC coverage: 74.313% (+0.02%) from 74.295%

Build # 19370422724

Build Type

Pull #2367

github

Committed by

web-flow

Commit Message

Merge ae36b13f2 into e3bf39e73

Pull Request Pull Request #2367: Add CrossCurrencySwapRateHelper for cross-currency swap bootstrapping

Run Details

84 of 90 new or added lines in 1 file covered. (93.33%)

142 existing lines in 6 files now uncovered.

57061 of 76785 relevant lines covered (74.31%)

8793256.53 hits per line

Source File
Press 'n' to go to next uncovered line, 'b' for previous

91.89

/ql/experimental/termstructures/crosscurrencyratehelpers.cpp

/* -*- mode: c++; tab-width: 4; indent-tabs-mode: nil; c-basic-offset: 4 -*- */

/*
 Copyright (C) 2025 Uzair Beg
 Copyright (C) 2021 Marcin Rybacki

 This file is part of QuantLib, a free-software/open-source library
 for financial quantitative analysts and developers - http://quantlib.org/

 QuantLib is free software: you can redistribute it and/or modify it
 under the terms of the QuantLib license.  You should have received a
 copy of the license along with this program; if not, please email
 <quantlib-dev@lists.sf.net>. The license is also available online at
 <https://www.quantlib.org/license.shtml>.

 This program is distributed in the hope that it will be useful, but WITHOUT
 ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS
 FOR A PARTICULAR PURPOSE.  See the license for more details.
*/

#include <ql/cashflows/overnightindexedcoupon.hpp>
#include <ql/cashflows/iborcoupon.hpp>
#include <ql/cashflows/cashflows.hpp>
#include <ql/cashflows/simplecashflow.hpp>
#include <ql/cashflows/fixedratecoupon.hpp>
#include <ql/experimental/termstructures/crosscurrencyratehelpers.hpp>
#include <ql/utilities/null_deleter.hpp>
#include <utility>

namespace QuantLib {

    namespace {

        Schedule legSchedule(const Date& evaluationDate,
                             const Period& tenor,
                             const Period& frequency,
                             Natural fixingDays,
                             const Calendar& calendar,
                             BusinessDayConvention convention,
                             bool endOfMonth) {
            QL_REQUIRE(tenor >= frequency,
                       "XCCY instrument tenor should not be smaller than coupon frequency.");

            Date referenceDate = calendar.adjust(evaluationDate);
            Date earliestDate = calendar.advance(referenceDate, fixingDays * Days, convention);
            Date maturity = earliestDate + tenor;
            return MakeSchedule()
                .from(earliestDate)
                .to(maturity)
                .withTenor(frequency)
                .withCalendar(calendar)
                .withConvention(convention)
                .endOfMonth(endOfMonth)
                .backwards();
        }

        Leg buildFloatingLeg(const Date& evaluationDate,
                         const Period& tenor,
                         Natural fixingDays,
                         const Calendar& calendar,
                         BusinessDayConvention convention,
                         bool endOfMonth,
                         const ext::shared_ptr<IborIndex>& idx,
                         Frequency paymentFrequency,
                         Integer paymentLag) {
            auto overnightIndex = ext::dynamic_pointer_cast<OvernightIndex>(idx);

            Period freqPeriod;
            if (paymentFrequency == NoFrequency) {
                QL_REQUIRE(!overnightIndex, "Require payment frequency for overnight indices.");
                freqPeriod = idx->tenor();
            } else {
                freqPeriod = Period(paymentFrequency);
            }

            Schedule sch = legSchedule(evaluationDate, tenor, freqPeriod, fixingDays, calendar,
                                       convention, endOfMonth);
            if (overnightIndex != nullptr) {
                return OvernightLeg(sch, overnightIndex)
                    .withNotionals(1.0)
                    .withPaymentLag(paymentLag);
            }
            return IborLeg(sch, idx).withNotionals(1.0).withPaymentLag(paymentLag);
        }

        std::pair<Real, Real>
        npvbpsConstNotionalLeg(const Leg& leg,
                               const Date& initialNotionalExchangeDate,
                               const Date& finalNotionalExchangeDate,
                               const Handle<YieldTermStructure>& discountCurveHandle) {
            const Spread basisPoint = 1.0e-4;
            Date refDt = discountCurveHandle->referenceDate();
            const YieldTermStructure& discountRef = **discountCurveHandle;
            bool includeSettleDtFlows = true;
            auto [npv, bps] = CashFlows::npvbps(leg, discountRef, includeSettleDtFlows, refDt, refDt);
            // Include NPV of the notional exchange at start and maturity.
            npv += (-1.0) * discountRef.discount(initialNotionalExchangeDate);
            npv += discountRef.discount(finalNotionalExchangeDate);
            bps /= basisPoint;
            return { npv, bps };
        }

        class ResettingLegHelper {
          public:
            explicit ResettingLegHelper(const YieldTermStructure& discountCurve,
                                        const YieldTermStructure& foreignCurve)
            : discountCurve_(discountCurve), foreignCurve_(foreignCurve) {}
            DiscountFactor discount(const Date& d) const {
                return discountCurve_.discount(d);
            }
            Real notionalAdjustment(const Date& d) const {
                return foreignCurve_.discount(d) / discountCurve_.discount(d);
            }

          private:
            const YieldTermStructure& discountCurve_;
            const YieldTermStructure& foreignCurve_;
        };

        class ResettingLegCalculator : public AcyclicVisitor, public Visitor<Coupon> {
          public:
            explicit ResettingLegCalculator(const YieldTermStructure& discountCurve,
                                            const YieldTermStructure& foreignCurve,
                                            Integer paymentLag,
                                            Calendar paymentCalendar,
                                            BusinessDayConvention convention)
            : helper_(discountCurve, foreignCurve), paymentLag_(paymentLag),
              paymentCalendar_(std::move(paymentCalendar)), convention_(convention) {}

            void visit(Coupon& c) override {
                Date start = c.accrualStartDate();
                Date end = c.accrualEndDate();
                Time accrual = c.accrualPeriod();
                Real adjustedNotional = c.nominal() * helper_.notionalAdjustment(start);

                DiscountFactor discountStart, discountEnd;

                if (paymentLag_ == 0) {
                    discountStart = helper_.discount(start);
                    discountEnd = helper_.discount(end);
                } else {
                    Date paymentStart =
                        paymentCalendar_.advance(start, paymentLag_, Days, convention_);
                    Date paymentEnd = paymentCalendar_.advance(end, paymentLag_, Days, convention_);
                    discountStart = helper_.discount(paymentStart);
                    discountEnd = helper_.discount(paymentEnd);
                }

                // NPV of a resetting coupon consists of a redemption of borrowed amount occurring
                // at the end of the accrual period plus the accrued interest, minus the borrowed
                // amount at the start of the period. All amounts are corrected by an adjustment
                // corresponding to the implied forward exchange rate, which is estimated by
                // the ratio of foreign and domestic curves discount factors.
                Real npvRedeemedAmount =
                    adjustedNotional * discountEnd * (1.0 + c.rate() * accrual);
                Real npvBorrowedAmount = -adjustedNotional * discountStart;

                npv_ += (npvRedeemedAmount + npvBorrowedAmount);
                bps_ += adjustedNotional * discountEnd * accrual;
            }
            Real NPV() const { return npv_; }
            Real BPS() const { return bps_; }

          private:
            ResettingLegHelper helper_;
            Real npv_ = 0.0;
            Real bps_ = 0.0;
            Integer paymentLag_;
            Calendar paymentCalendar_;
            BusinessDayConvention convention_;
        };

        std::pair<Real, Real> npvbpsResettingLeg(const Leg& iborLeg,
                                                 Integer paymentLag,
                                                 const Calendar& paymentCalendar,
                                                 BusinessDayConvention convention,
                                                 const Handle<YieldTermStructure>& discountCurveHandle,
                                                 const Handle<YieldTermStructure>& foreignCurveHandle) {
            const YieldTermStructure& discountCurveRef = **discountCurveHandle;
            const YieldTermStructure& foreignCurveRef = **foreignCurveHandle;

            ResettingLegCalculator calc(discountCurveRef, foreignCurveRef, paymentLag,
                                        paymentCalendar, convention);
            for (const auto& i : iborLeg) {
                CashFlow& cf = *i;
                cf.accept(calc);
            }
            return { calc.NPV(), calc.BPS() };
        }
    }

    CrossCurrencyBasisSwapRateHelperBase::CrossCurrencyBasisSwapRateHelperBase(
        const Handle<Quote>& basis,
        const Period& tenor,
        Natural fixingDays,
        Calendar calendar,
        BusinessDayConvention convention,
        bool endOfMonth,
        ext::shared_ptr<IborIndex> baseCurrencyIndex,
        ext::shared_ptr<IborIndex> quoteCurrencyIndex,
        Handle<YieldTermStructure> collateralCurve,
        bool isFxBaseCurrencyCollateralCurrency,
        bool isBasisOnFxBaseCurrencyLeg,
        Frequency paymentFrequency,
        Integer paymentLag)
    : RelativeDateRateHelper(basis), tenor_(tenor), fixingDays_(fixingDays),
      calendar_(std::move(calendar)), convention_(convention), endOfMonth_(endOfMonth),
      baseCcyIdx_(std::move(baseCurrencyIndex)), quoteCcyIdx_(std::move(quoteCurrencyIndex)),
      collateralHandle_(std::move(collateralCurve)),
      isFxBaseCurrencyCollateralCurrency_(isFxBaseCurrencyCollateralCurrency),
      isBasisOnFxBaseCurrencyLeg_(isBasisOnFxBaseCurrencyLeg),
      paymentFrequency_(paymentFrequency), paymentLag_(paymentLag) {
        registerWith(baseCcyIdx_);
        registerWith(quoteCcyIdx_);
        registerWith(collateralHandle_);
        CrossCurrencyBasisSwapRateHelperBase::initializeDates();
    }

    void CrossCurrencyBasisSwapRateHelperBase::initializeDates() {
        baseCcyIborLeg_ = buildFloatingLeg(evaluationDate_, tenor_, fixingDays_, calendar_, convention_,
                                           endOfMonth_, baseCcyIdx_, paymentFrequency_, paymentLag_);
    
        quoteCcyIborLeg_ = buildFloatingLeg(evaluationDate_, tenor_, fixingDays_, calendar_,
                                            convention_, endOfMonth_, quoteCcyIdx_, paymentFrequency_, paymentLag_);
    
        earliestDate_ = std::min(CashFlows::startDate(baseCcyIborLeg_),
                                 CashFlows::startDate(quoteCcyIborLeg_));
    
        maturityDate_ = std::max(CashFlows::maturityDate(baseCcyIborLeg_),
                                 CashFlows::maturityDate(quoteCcyIborLeg_));
    
        if (paymentLag_ == 0) {
            initialNotionalExchangeDate_ = earliestDate_;
            finalNotionalExchangeDate_   = maturityDate_;
        } else {
            initialNotionalExchangeDate_ = calendar_.advance(earliestDate_, paymentLag_, Days, convention_);
            finalNotionalExchangeDate_   = calendar_.advance(maturityDate_, paymentLag_, Days, convention_);
        }
    
        Date lastPaymentDate =
            std::max(baseCcyIborLeg_.back()->date(),
                     quoteCcyIborLeg_.back()->date());
    
        Date last = std::max(maturityDate_, lastPaymentDate);
    
        const_cast<Date&>(latestRelevantDate_) = last;
        const_cast<Date&>(latestDate_)        = last;
    }
    

    const Handle<YieldTermStructure>&
    CrossCurrencyBasisSwapRateHelperBase::baseCcyLegDiscountHandle() const {
        QL_REQUIRE(!termStructureHandle_.empty(), "term structure not set");
        QL_REQUIRE(!collateralHandle_.empty(), "collateral term structure not set");
        return isFxBaseCurrencyCollateralCurrency_ ? collateralHandle_ : termStructureHandle_;
    }

    const Handle<YieldTermStructure>&
    CrossCurrencyBasisSwapRateHelperBase::quoteCcyLegDiscountHandle() const {
        QL_REQUIRE(!termStructureHandle_.empty(), "term structure not set");
        QL_REQUIRE(!collateralHandle_.empty(), "collateral term structure not set");
        return isFxBaseCurrencyCollateralCurrency_ ? termStructureHandle_ : collateralHandle_;
    }

    void CrossCurrencyBasisSwapRateHelperBase::setTermStructure(YieldTermStructure* t) {
        // do not set the relinkable handle as an observer -
        // force recalculation when needed
        bool observer = false;

        ext::shared_ptr<YieldTermStructure> temp(t, null_deleter());
        termStructureHandle_.linkTo(temp, observer);

        RelativeDateRateHelper::setTermStructure(t);
    }

    ConstNotionalCrossCurrencyBasisSwapRateHelper::ConstNotionalCrossCurrencyBasisSwapRateHelper(
        const Handle<Quote>& basis,
        const Period& tenor,
        Natural fixingDays,
        const Calendar& calendar,
        BusinessDayConvention convention,
        bool endOfMonth,
        const ext::shared_ptr<IborIndex>& baseCurrencyIndex,
        const ext::shared_ptr<IborIndex>& quoteCurrencyIndex,
        const Handle<YieldTermStructure>& collateralCurve,
        bool isFxBaseCurrencyCollateralCurrency,
        bool isBasisOnFxBaseCurrencyLeg,
        Frequency paymentFrequency,
        Integer paymentLag)
    : CrossCurrencyBasisSwapRateHelperBase(basis,
                                           tenor,
                                           fixingDays,
                                           calendar,
                                           convention,
                                           endOfMonth,
                                           baseCurrencyIndex,
                                           quoteCurrencyIndex,
                                           collateralCurve,
                                           isFxBaseCurrencyCollateralCurrency,
                                           isBasisOnFxBaseCurrencyLeg,
                                           paymentFrequency,
                                           paymentLag) {}

    Real ConstNotionalCrossCurrencyBasisSwapRateHelper::impliedQuote() const {
        auto [npvBaseCcy, bpsBaseCcy] = npvbpsConstNotionalLeg(baseCcyIborLeg_, initialNotionalExchangeDate_, finalNotionalExchangeDate_, baseCcyLegDiscountHandle());
        auto [npvQuoteCcy, bpsQuoteCcy] = npvbpsConstNotionalLeg(quoteCcyIborLeg_, initialNotionalExchangeDate_, finalNotionalExchangeDate_, quoteCcyLegDiscountHandle());
        Real bps = isBasisOnFxBaseCurrencyLeg_ ? -bpsBaseCcy : bpsQuoteCcy;
        return -(npvQuoteCcy - npvBaseCcy) / bps;
    }

    void ConstNotionalCrossCurrencyBasisSwapRateHelper::accept(AcyclicVisitor& v) {
        auto* v1 = dynamic_cast<Visitor<ConstNotionalCrossCurrencyBasisSwapRateHelper>*>(&v);
        if (v1 != nullptr)
            v1->visit(*this);
        else
            RateHelper::accept(v);
    }

    MtMCrossCurrencyBasisSwapRateHelper::MtMCrossCurrencyBasisSwapRateHelper(
        const Handle<Quote>& basis,
        const Period& tenor,
        Natural fixingDays,
        const Calendar& calendar,
        BusinessDayConvention convention,
        bool endOfMonth,
        const ext::shared_ptr<IborIndex>& baseCurrencyIndex,
        const ext::shared_ptr<IborIndex>& quoteCurrencyIndex,
        const Handle<YieldTermStructure>& collateralCurve,
        bool isFxBaseCurrencyCollateralCurrency,
        bool isBasisOnFxBaseCurrencyLeg,
        bool isFxBaseCurrencyLegResettable,
        Frequency paymentFrequency,
        Integer paymentLag)
    : CrossCurrencyBasisSwapRateHelperBase(basis,
                                           tenor,
                                           fixingDays,
                                           calendar,
                                           convention,
                                           endOfMonth,
                                           baseCurrencyIndex,
                                           quoteCurrencyIndex,
                                           collateralCurve,
                                           isFxBaseCurrencyCollateralCurrency,
                                           isBasisOnFxBaseCurrencyLeg,
                                           paymentFrequency,
                                           paymentLag),
      isFxBaseCurrencyLegResettable_(isFxBaseCurrencyLegResettable) {}

    Real MtMCrossCurrencyBasisSwapRateHelper::impliedQuote() const {
        Real npvBaseCcy = 0.0, bpsBaseCcy = 0.0;
        Real npvQuoteCcy = 0.0, bpsQuoteCcy = 0.0;
        if (isFxBaseCurrencyLegResettable_) {
            std::tie(npvBaseCcy, bpsBaseCcy) =
                npvbpsResettingLeg(baseCcyIborLeg_, paymentLag_, calendar_, convention_,
                                   baseCcyLegDiscountHandle(), quoteCcyLegDiscountHandle());
            std::tie(npvQuoteCcy, bpsQuoteCcy) =
                npvbpsConstNotionalLeg(quoteCcyIborLeg_, initialNotionalExchangeDate_,
                                       finalNotionalExchangeDate_, quoteCcyLegDiscountHandle());
        } else {
            std::tie(npvBaseCcy, bpsBaseCcy) =
                npvbpsConstNotionalLeg(baseCcyIborLeg_, initialNotionalExchangeDate_,
                                       finalNotionalExchangeDate_, baseCcyLegDiscountHandle());
            std::tie(npvQuoteCcy, bpsQuoteCcy) = npvbpsResettingLeg(
                                       quoteCcyIborLeg_, paymentLag_, calendar_, convention_,
                                       quoteCcyLegDiscountHandle(), baseCcyLegDiscountHandle());
        }

        Real bps = isBasisOnFxBaseCurrencyLeg_ ? -bpsBaseCcy : bpsQuoteCcy;

        return -(npvQuoteCcy - npvBaseCcy) / bps;
    }

    void MtMCrossCurrencyBasisSwapRateHelper::accept(AcyclicVisitor& v) {
        auto* v1 = dynamic_cast<Visitor<MtMCrossCurrencyBasisSwapRateHelper>*>(&v);
        if (v1 != nullptr)
            v1->visit(*this);
        else
            RateHelper::accept(v);
    }
// -----------------------------------------------------------------------------
// CrossCurrencySwapRateHelper
// -----------------------------------------------------------------------------

Leg CrossCurrencySwapRateHelper::buildFixedLeg(const Schedule& fixedSchedule) const {
    return FixedRateLeg(fixedSchedule)
        .withNotionals(1.0)
        .withCouponRates(1.0, fixedDayCount_);
}

Leg CrossCurrencySwapRateHelper::buildFloatingLeg(const Schedule& floatSchedule) const {
    return IborLeg(floatSchedule, floatIndex_)
        .withNotionals(1.0)
        .withSpreads(0.0);
}

Handle<YieldTermStructure> CrossCurrencySwapRateHelper::fixedLegDiscountHandle() const {
    if (collateralOnFixedLeg_) {
        return collateralCurve_;
    }
    QL_REQUIRE(termStructure_, "term structure not set");
    return Handle<YieldTermStructure>(ext::shared_ptr<YieldTermStructure>(
        termStructure_, null_deleter()));
}

Handle<YieldTermStructure> CrossCurrencySwapRateHelper::floatingLegDiscountHandle() const {
    if (collateralOnFixedLeg_) {
        QL_REQUIRE(termStructure_, "term structure not set");
        return Handle<YieldTermStructure>(ext::shared_ptr<YieldTermStructure>(
            termStructure_, null_deleter()));
    }
    return collateralCurve_;
}


CrossCurrencySwapRateHelper::CrossCurrencySwapRateHelper(
    const Handle<Quote>& fixedRate,
    const Period& tenor,
    Natural fixingDays,
    const Calendar& calendar,
    BusinessDayConvention convention,
    bool endOfMonth,
    Frequency fixedFrequency,
    const DayCounter& fixedDayCount,
    const Currency& fixedCurrency,
    const ext::shared_ptr<IborIndex>& floatIndex,
    const Currency& floatCurrency,
    const Handle<YieldTermStructure>& collateralCurve,
    bool collateralOnFixedLeg)
: RelativeDateRateHelper(fixedRate),
  tenor_(tenor),
  fixingDays_(fixingDays),
  calendar_(calendar),
  convention_(convention),
  endOfMonth_(endOfMonth),
  fixedFrequency_(fixedFrequency),
  fixedDayCount_(fixedDayCount),
  fixedCurrency_(fixedCurrency),
  floatCurrency_(floatCurrency),
  floatIndex_(floatIndex),
  collateralCurve_(collateralCurve),
  collateralOnFixedLeg_(collateralOnFixedLeg) {

    QL_REQUIRE(floatIndex_, "floating index required");
    QL_REQUIRE(!collateralCurve_.empty(),
               "collateral curve must be provided");
    QL_REQUIRE(!floatIndex_->forwardingTermStructure().empty(),
               "floating index must have a forwarding curve");
               registerWith(floatIndex_);
               registerWith(collateralCurve_);
               
               

    initializeDates();
}

void CrossCurrencySwapRateHelper::initializeDates() {
    Date ref = Settings::instance().evaluationDate();
    QL_REQUIRE(ref != Date(), "evaluation date not set");
    instrumentSettlementDate_ = calendar_.advance(ref, fixingDays_, Days);
    maturityDate_ = calendar_.advance(instrumentSettlementDate_, tenor_, convention_, endOfMonth_);
    earliestDate_ = instrumentSettlementDate_;

    initialNotionalExchangeDate_ = instrumentSettlementDate_;
    finalNotionalExchangeDate_ = maturityDate_;

    fixedSchedule_ = Schedule(instrumentSettlementDate_, maturityDate_,
                              Period(fixedFrequency_), calendar_,
                              convention_, convention_,
                              DateGeneration::Forward, endOfMonth_);

    floatSchedule_ = Schedule(instrumentSettlementDate_, maturityDate_,
                              floatIndex_->tenor(),
                              floatIndex_->fixingCalendar(),
                              floatIndex_->businessDayConvention(),
                              floatIndex_->businessDayConvention(),
                              DateGeneration::Forward, false);

    QL_REQUIRE(fixedSchedule_.size() >= 2, "fixed schedule too short");
    QL_REQUIRE(floatSchedule_.size() >= 2, "floating schedule too short");

    fixedLeg_ = buildFixedLeg(fixedSchedule_);
    floatLeg_ = buildFloatingLeg(floatSchedule_);

    Date lastPayment = std::max(fixedSchedule_.back(), floatSchedule_.back());
    Date last = std::max(maturityDate_, lastPayment);

    const_cast<Date&>(latestRelevantDate_) = last;
    const_cast<Date&>(latestDate_) = last;
}


void CrossCurrencySwapRateHelper::setTermStructure(YieldTermStructure* t) {
    RelativeDateRateHelper::setTermStructure(t);
}

Real CrossCurrencySwapRateHelper::impliedQuote() const {
    QL_REQUIRE(termStructure_, "term structure not set");

    Handle<YieldTermStructure> fixedDisc  = fixedLegDiscountHandle();
    Handle<YieldTermStructure> floatDisc  = floatingLegDiscountHandle();

    auto [fixedNpv, fixedBps] = npvbpsConstNotionalLeg(
        fixedLeg_, initialNotionalExchangeDate_, finalNotionalExchangeDate_, fixedDisc);

    auto [floatNpv, floatBps] = npvbpsConstNotionalLeg(
        floatLeg_, initialNotionalExchangeDate_, finalNotionalExchangeDate_, floatDisc);

    QL_REQUIRE(std::fabs(fixedBps) > 0.0, "fixed leg BPS is zero");

    return 1.0 + (floatNpv - fixedNpv) / fixedBps;
}



void CrossCurrencySwapRateHelper::accept(AcyclicVisitor& v) {
    auto* v1 = dynamic_cast<Visitor<CrossCurrencySwapRateHelper>*>(&v);
    if (v1 != nullptr)
        v1->visit(*this);
    else
        RateHelper::accept(v);
}

}

lballabio / QuantLib / 19370422724

Source File Press 'n' to go to next uncovered line, 'b' for previous

Source File
Press 'n' to go to next uncovered line, 'b' for previous