CMS spread - coupon pricer. More...

#include <qle/cashflows/lognormalcmsspreadpricer.hpp>

Inheritance diagram for LognormalCmsSpreadPricer:

Collaboration diagram for LognormalCmsSpreadPricer:

Public Member Functions
	LognormalCmsSpreadPricer (const QuantLib::ext::shared_ptr< CmsCouponPricer > cmsPricer, const Handle< QuantExt::CorrelationTermStructure > &correlation, const Handle< YieldTermStructure > &couponDiscountCurve=Handle< YieldTermStructure >(), const Size IntegrationPoints=16, const boost::optional< VolatilityType > volatilityType=boost::none, const Real shift1=Null< Real >(), const Real shift2=Null< Real >())

virtual Real	swapletPrice () const override

virtual Rate	swapletRate () const override

virtual Real	capletPrice (Rate effectiveCap) const override

virtual Rate	capletRate (Rate effectiveCap) const override

virtual Real	floorletPrice (Rate effectiveFloor) const override

virtual Rate	floorletRate (Rate effectiveFloor) const override

Public Member Functions inherited from CmsSpreadCouponPricer2
	CmsSpreadCouponPricer2 (const Handle< CorrelationTermStructure > &correlation=Handle< CorrelationTermStructure >())

Real	correlation (Time t, Real strike=1) const

void	setCorrelationCurve (const Handle< CorrelationTermStructure > &correlation=Handle< CorrelationTermStructure >())

Private Member Functions
void	initialize (const FloatingRateCoupon &coupon) override

Real	rho () const

Real	optionletPrice (Option::Type optionType, Real strike) const

Real	integrand (const Real) const

Real	integrand_normal (const Real) const

Private Attributes
QuantLib::ext::shared_ptr< CmsCouponPricer >	cmsPricer_

Handle< YieldTermStructure >	couponDiscountCurve_

const CmsSpreadCoupon *	coupon_

Date	today_

Date	fixingDate_

Date	paymentDate_

Real	fixingTime_

Real	gearing_

Real	spread_

Real	spreadLegValue_

Real	discount_

QuantLib::ext::shared_ptr< SwapSpreadIndex >	index_

QuantLib::ext::shared_ptr< CumulativeNormalDistribution >	cnd_

QuantLib::ext::shared_ptr< GaussianQuadrature >	integrator_

Real	swapRate1_

Real	swapRate2_

Real	gearing1_

Real	gearing2_

Real	adjustedRate1_

Real	adjustedRate2_

Real	vol1_

Real	vol2_

Real	mu1_

Real	mu2_

bool	inheritedVolatilityType_

VolatilityType	volType_

Real	shift1_

Real	shift2_

Real	phi_

Real	a_

Real	b_

Real	s1_

Real	s2_

Real	m1_

Real	m2_

Real	v1_

Real	v2_

Real	k_

Real	alpha_

Real	psi_

Option::Type	optionType_

QuantLib::ext::shared_ptr< CmsCoupon >	c1_

QuantLib::ext::shared_ptr< CmsCoupon >	c2_

Friends
class	integrand_f

Detailed Description

CMS spread - coupon pricer.

The swap rate adjustments are computed using the given volatility structures for the underlyings in every case (w.r.t. volatility type and shift).

For the bivariate spread model, the volatility type and the shifts can be inherited (default), or explicitly specified. In the latter case the type, and (if lognormal) the shifts must be given (or are defaulted to zero, if not given).

References:

Brigo, Mercurio: Interest Rate Models - Theory and Practice, 2nd Edition, Springer, 2006, chapter 13.6.2

http://ssrn.com/abstract=2686998

Definition at line 105 of file lognormalcmsspreadpricer.hpp.

Constructor & Destructor Documentation

◆ LognormalCmsSpreadPricer()

LognormalCmsSpreadPricer	(	const QuantLib::ext::shared_ptr< CmsCouponPricer >	cmsPricer,
		const Handle< QuantExt::CorrelationTermStructure > &	correlation,
		const Handle< YieldTermStructure > &	couponDiscountCurve = `Handle<YieldTermStructure>()`,
		const Size	IntegrationPoints = `16`,
		const boost::optional< VolatilityType >	volatilityType = `boost::none`,
		const Real	shift1 = `Null<Real>()`,
		const Real	shift2 = `Null<Real>()`
	)

Definition at line 60 of file lognormalcmsspreadpricer.cpp.

    : CmsSpreadCouponPricer2(correlation), cmsPricer_(cmsPricer), couponDiscountCurve_(couponDiscountCurve) {
 
    if (!couponDiscountCurve_.empty())
        registerWith(couponDiscountCurve_);
    registerWith(cmsPricer_);
 
    QL_REQUIRE(integrationPoints >= 4, "at least 4 integration points should be used (" << integrationPoints << ")");
    integrator_ = QuantLib::ext::make_shared<GaussHermiteIntegration>(integrationPoints);
 
    cnd_ = QuantLib::ext::make_shared<CumulativeNormalDistribution>(0.0, 1.0);
 
    if (volatilityType == boost::none) {
        QL_REQUIRE(shift1 == Null<Real>() && shift2 == Null<Real>(),
                   "if volatility type is inherited, no shifts should be "
                   "specified");
        inheritedVolatilityType_ = true;
        volType_ = cmsPricer->swaptionVolatility()->volatilityType();
    } else {
        shift1_ = shift1 == Null<Real>() ? 0.0 : shift1;
        shift2_ = shift2 == Null<Real>() ? 0.0 : shift2;
        inheritedVolatilityType_ = false;
        volType_ = *volatilityType;
    }
}

Member Function Documentation

◆ swapletPrice()

Real swapletPrice ( ) const

overridevirtual

Definition at line 303 of file lognormalcmsspreadpricer.cpp.

                                                  {
    return gearing_ * coupon_->accrualPeriod() * discount_ * (gearing1_ * adjustedRate1_ + gearing2_ * adjustedRate2_) +
           spreadLegValue_;
}

Here is the caller graph for this function:

◆ swapletRate()

Rate swapletRate ( ) const

overridevirtual

Definition at line 267 of file lognormalcmsspreadpricer.cpp.

267{ return swapletPrice() / (coupon_->accrualPeriod() * discount_); }

QuantExt::LognormalCmsSpreadPricer::swapletPrice

virtual Real swapletPrice() const override

Definition: lognormalcmsspreadpricer.cpp:303

Here is the call graph for this function:

◆ capletPrice()

Real capletPrice ( Rate effectiveCap ) const

overridevirtual

Definition at line 269 of file lognormalcmsspreadpricer.cpp.

                                                                  {
    // caplet is equivalent to call option on fixing
    if (fixingDate_ <= today_) {
        // the fixing is determined
        const Rate Rs = std::max(coupon_->index()->fixing(fixingDate_) - effectiveCap, 0.);
        Rate price = gearing_ * Rs * coupon_->accrualPeriod() * discount_;
        return price;
    } else {
        Real capletPrice = optionletPrice(Option::Call, effectiveCap);
        return gearing_ * capletPrice;
    }
}

Here is the call graph for this function:

Here is the caller graph for this function:

◆ capletRate()

Rate capletRate ( Rate effectiveCap ) const

overridevirtual

Definition at line 282 of file lognormalcmsspreadpricer.cpp.

                                                                 {
    return capletPrice(effectiveCap) / (coupon_->accrualPeriod() * discount_);
}

Here is the call graph for this function:

◆ floorletPrice()

Real floorletPrice ( Rate effectiveFloor ) const

overridevirtual

Definition at line 286 of file lognormalcmsspreadpricer.cpp.

                                                                      {
    // floorlet is equivalent to put option on fixing
    if (fixingDate_ <= today_) {
        // the fixing is determined
        const Rate Rs = std::max(effectiveFloor - coupon_->index()->fixing(fixingDate_), 0.);
        Rate price = gearing_ * Rs * coupon_->accrualPeriod() * discount_;
        return price;
    } else {
        Real floorletPrice = optionletPrice(Option::Put, effectiveFloor);
        return gearing_ * floorletPrice;
    }
}

Here is the call graph for this function:

Here is the caller graph for this function:

◆ floorletRate()

Rate floorletRate ( Rate effectiveFloor ) const

overridevirtual

Definition at line 299 of file lognormalcmsspreadpricer.cpp.

                                                                     {
    return floorletPrice(effectiveFloor) / (coupon_->accrualPeriod() * discount_);
}

Here is the call graph for this function:

◆ initialize()

void initialize ( const FloatingRateCoupon & coupon )

overrideprivate

Definition at line 129 of file lognormalcmsspreadpricer.cpp.

                                                                          {
 
    coupon_ = dynamic_cast<const CmsSpreadCoupon*>(&coupon);
    QL_REQUIRE(coupon_, "CMS spread coupon needed");
    index_ = coupon_->swapSpreadIndex();
    gearing_ = coupon_->gearing();
    spread_ = coupon_->spread();
 
    fixingDate_ = coupon_->fixingDate();
    paymentDate_ = coupon_->date();
 
    // if no coupon discount curve is given just use the discounting curve
    // from the _first_ swap index.
    // for rate calculation this curve cancels out in the computation, so
    // e.g. the discounting
    // swap engine will produce correct results, even if the
    // couponDiscountCurve is not set here.
    // only the price member function in this class will be dependent on the
    // coupon discount curve.
 
    today_ = QuantLib::Settings::instance().evaluationDate();
 
    if (couponDiscountCurve_.empty())
        couponDiscountCurve_ = index_->swapIndex1()->exogenousDiscount()
                                   ? index_->swapIndex1()->discountingTermStructure()
                                   : index_->swapIndex1()->forwardingTermStructure();
 
    discount_ =
        paymentDate_ > couponDiscountCurve_->referenceDate() ? couponDiscountCurve_->discount(paymentDate_) : 1.0;
 
    spreadLegValue_ = spread_ * coupon_->accrualPeriod() * discount_;
 
    gearing1_ = index_->gearing1();
    gearing2_ = index_->gearing2();
 
    QL_REQUIRE(gearing1_ > 0.0 && gearing2_ < 0.0, "gearing1 (" << gearing1_ << ") should be positive while gearing2 ("
                                                                << gearing2_ << ") should be negative");
 
    c1_ = QuantLib::ext::shared_ptr<CmsCoupon>(
        new CmsCoupon(coupon_->date(), coupon_->nominal(), coupon_->accrualStartDate(), coupon_->accrualEndDate(),
                      coupon_->fixingDays(), index_->swapIndex1(), 1.0, 0.0, coupon_->referencePeriodStart(),
                      coupon_->referencePeriodEnd(), coupon_->dayCounter(), coupon_->isInArrears()));
 
    c2_ = QuantLib::ext::shared_ptr<CmsCoupon>(
        new CmsCoupon(coupon_->date(), coupon_->nominal(), coupon_->accrualStartDate(), coupon_->accrualEndDate(),
                      coupon_->fixingDays(), index_->swapIndex2(), 1.0, 0.0, coupon_->referencePeriodStart(),
                      coupon_->referencePeriodEnd(), coupon_->dayCounter(), coupon_->isInArrears()));
 
    c1_->setPricer(cmsPricer_);
    c2_->setPricer(cmsPricer_);
 
    if (fixingDate_ > today_) {
 
        fixingTime_ = cmsPricer_->swaptionVolatility()->timeFromReference(fixingDate_);
 
        swapRate1_ = c1_->indexFixing();
        swapRate2_ = c2_->indexFixing();
 
        adjustedRate1_ = c1_->adjustedFixing();
        adjustedRate2_ = c2_->adjustedFixing();
 
        QuantLib::ext::shared_ptr<SwaptionVolatilityStructure> swvol = *cmsPricer_->swaptionVolatility();
        QuantLib::ext::shared_ptr<SwaptionVolatilityCube> swcub = QuantLib::ext::dynamic_pointer_cast<SwaptionVolatilityCube>(swvol);
 
        if (inheritedVolatilityType_ && volType_ == ShiftedLognormal) {
            shift1_ = swvol->shift(fixingDate_, index_->swapIndex1()->tenor());
            shift2_ = swvol->shift(fixingDate_, index_->swapIndex2()->tenor());
        }
 
        if (swcub == NULL) {
            // not a cube, just an atm surface given, so we can
            // not easily convert volatilities and just forbid it
            QL_REQUIRE(inheritedVolatilityType_, "if only an atm surface is given, the volatility "
                                                 "type must be inherited");
            vol1_ = swvol->volatility(fixingDate_, index_->swapIndex1()->tenor(), swapRate1_);
            vol2_ = swvol->volatility(fixingDate_, index_->swapIndex2()->tenor(), swapRate2_);
        } else {
            vol1_ = swcub->smileSection(fixingDate_, index_->swapIndex1()->tenor())
                        ->volatility(swapRate1_, volType_, shift1_);
            vol2_ = swcub->smileSection(fixingDate_, index_->swapIndex2()->tenor())
                        ->volatility(swapRate2_, volType_, shift2_);
        }
 
        if (volType_ == ShiftedLognormal) {
            mu1_ = 1.0 / fixingTime_ * std::log((adjustedRate1_ + shift1_) / (swapRate1_ + shift1_));
            mu2_ = 1.0 / fixingTime_ * std::log((adjustedRate2_ + shift2_) / (swapRate2_ + shift2_));
        }
        // for the normal volatility case we do not need the drifts
        // but rather use adjusted rates directly in the integrand
 
    } else {
        // fixing is in the past or today
        adjustedRate1_ = c1_->indexFixing();
        adjustedRate2_ = c2_->indexFixing();
    }
}

◆ rho()

Real rho ( ) const

private

Definition at line 125 of file lognormalcmsspreadpricer.hpp.

125{ return std::max(std::min(correlation(fixingTime_), 0.9999), -0.9999); }

Here is the call graph for this function:

Here is the caller graph for this function:

◆ optionletPrice()

Real optionletPrice	(	Option::Type	optionType,
		Real	strike
	)		const

private

Definition at line 226 of file lognormalcmsspreadpricer.cpp.

                                                                                      {
    // this method is only called for future fixings
    optionType_ = optionType;
    phi_ = optionType == Option::Call ? 1.0 : -1.0;
    Real res = 0.0;
    if (volType_ == ShiftedLognormal) {
        // (shifted) lognormal volatility
        if (strike >= 0.0) {
            a_ = gearing1_;
            b_ = gearing2_;
            s1_ = swapRate1_ + shift1_;
            s2_ = swapRate2_ + shift2_;
            m1_ = mu1_;
            m2_ = mu2_;
            v1_ = vol1_;
            v2_ = vol2_;
            k_ = strike + gearing1_ * shift1_ + gearing2_ * shift2_;
        } else {
            a_ = -gearing2_;
            b_ = -gearing1_;
            s1_ = swapRate2_ + shift1_;
            s2_ = swapRate1_ + shift2_;
            m1_ = mu2_;
            m2_ = mu1_;
            v1_ = vol2_;
            v2_ = vol1_;
            k_ = -strike - gearing1_ * shift1_ - gearing2_ * shift2_;
            res += phi_ * (gearing1_ * adjustedRate1_ + gearing2_ * adjustedRate2_ - strike);
        }
        res += 1.0 / M_SQRTPI * (*integrator_)(integrand_f(this));
    } else {
        // normal volatility
        Real forward = gearing1_ * adjustedRate1_ + gearing2_ * adjustedRate2_;
        Real stddev =
            std::sqrt(fixingTime_ * (gearing1_ * gearing1_ * vol1_ * vol1_ + gearing2_ * gearing2_ * vol2_ * vol2_ +
                                     2.0 * gearing1_ * gearing2_ * rho() * vol1_ * vol2_));
        res = bachelierBlackFormula(optionType_, strike, forward, stddev, 1.0);
    }
    return res * discount_ * coupon_->accrualPeriod();
}

Here is the call graph for this function:

Here is the caller graph for this function:

◆ integrand()

Real integrand ( const Real x ) const

private

Definition at line 91 of file lognormalcmsspreadpricer.cpp.

                                                           {
 
    // this is Brigo, 13.16.2 with x = v / sqrt(2)
 
    Real v = M_SQRT2 * x;
    Real h = k_ - b_ * s2_ * std::exp((m2_ - 0.5 * v2_ * v2_) * fixingTime_ + v2_ * std::sqrt(fixingTime_) * v);
    Real phi1, phi2;
    phi1 = (*cnd_)(phi_ *
                   (std::log(a_ * s1_ / h) + (m1_ + (0.5 - rho() * rho()) * v1_ * v1_) * fixingTime_ +
                    rho() * v1_ * std::sqrt(fixingTime_) * v) /
                   (v1_ * std::sqrt(fixingTime_ * (1.0 - rho() * rho()))));
    phi2 = (*cnd_)(
        phi_ *
        (std::log(a_ * s1_ / h) + (m1_ - 0.5 * v1_ * v1_) * fixingTime_ + rho() * v1_ * std::sqrt(fixingTime_) * v) /
        (v1_ * std::sqrt(fixingTime_ * (1.0 - rho() * rho()))));
    Real f = a_ * phi_ * s1_ *
                 std::exp(m1_ * fixingTime_ - 0.5 * rho() * rho() * v1_ * v1_ * fixingTime_ +
                          rho() * v1_ * std::sqrt(fixingTime_) * v) *
                 phi1 -
             phi_ * h * phi2;
    return std::exp(-x * x) * f;
}

Here is the call graph for this function:

◆ integrand_normal()

Real integrand_normal ( const Real x ) const

private

Definition at line 114 of file lognormalcmsspreadpricer.cpp.

                                                                  {
 
    // this is http://ssrn.com/abstract=2686998, 3.20 with x = s / sqrt(2)
 
    Real s = M_SQRT2 * x;
 
    Real beta = phi_ * (gearing1_ * adjustedRate1_ + gearing2_ * adjustedRate2_ - k_ +
                        std::sqrt(fixingTime_) * (rho() * gearing1_ * vol1_ + gearing2_ * vol2_) * s);
    Real f = close_enough(alpha_, 0.0)
                 ? std::max(beta, 0.0)
                 : psi_ * alpha_ / (M_SQRTPI * M_SQRT2) * std::exp(-beta * beta / (2.0 * alpha_ * alpha_)) +
                       beta * (1.0 - (*cnd_)(-psi_ * beta / alpha_));
    return std::exp(-x * x) * f;
}