BlackOvernightIndexedCouponPricer Class Reference

Black compounded overnight coupon pricer. More...

#include <qle/cashflows/blackovernightindexedcouponpricer.hpp>

Inheritance diagram for BlackOvernightIndexedCouponPricer:

Collaboration diagram for BlackOvernightIndexedCouponPricer:

Public Member Functions
void	initialize (const FloatingRateCoupon &coupon) override
Real	swapletPrice () const override
Rate	swapletRate () const override
Real	capletPrice (Rate effectiveCap) const override
Rate	capletRate (Rate effectiveCap) const override
Real	floorletPrice (Rate effectiveFloor) const override
Rate	floorletRate (Rate effectiveFloor) const override
	CappedFlooredOvernightIndexedCouponPricer (const Handle< OptionletVolatilityStructure > &v, const bool effectiveVolatilityInput=false)
Public Member Functions inherited from CappedFlooredOvernightIndexedCouponPricer
	CappedFlooredOvernightIndexedCouponPricer (const Handle< OptionletVolatilityStructure > &v, const bool effectiveVolatilityInput=false)
Handle< OptionletVolatilityStructure >	capletVolatility () const
bool	effectiveVolatilityInput () const
Real	effectiveCapletVolatility () const
Real	effectiveFloorletVolatility () const

Private Member Functions
Real	optionletRateGlobal (Option::Type optionType, Real effStrike) const
Real	optionletRateLocal (Option::Type optionType, Real effStrike) const

Private Attributes
Real	gearing_
ext::shared_ptr< IborIndex >	index_
Real	effectiveIndexFixing_
Real	swapletRate_
const CappedFlooredOvernightIndexedCoupon *	coupon_

Additional Inherited Members
Protected Attributes inherited from CappedFlooredOvernightIndexedCouponPricer
Handle< OptionletVolatilityStructure >	capletVol_
bool	effectiveVolatilityInput_
Real	effectiveCapletVolatility_ = Null<Real>()
Real	effectiveFloorletVolatility_ = Null<Real>()

Detailed Description

Black compounded overnight coupon pricer.

Definition at line 37 of file blackovernightindexedcouponpricer.hpp.

Member Function Documentation

initialize()

void initialize ( const FloatingRateCoupon &  coupon )

override

Definition at line 26 of file blackovernightindexedcouponpricer.cpp.

                                                                                   {
    coupon_ = dynamic_cast<const CappedFlooredOvernightIndexedCoupon*>(&coupon);
    QL_REQUIRE(coupon_, "BlackOvernightIndexedCouponPricer: CappedFlooredOvernightIndexedCoupon required");
    gearing_ = coupon.gearing();
    index_ = ext::dynamic_pointer_cast<OvernightIndex>(coupon.index());
    if (!index_) {
        // check if the coupon was right
        const CappedFlooredOvernightIndexedCoupon* c =
            dynamic_cast<const CappedFlooredOvernightIndexedCoupon*>(&coupon);
        QL_REQUIRE(c, "BlackOvernightIndexedCouponPricer: CappedFlooredOvernightIndexedCoupon required");
        // coupon was right, index is not
        QL_FAIL("BlackOvernightIndexedCouponPricer: CappedFlooredOvernightIndexedCoupon required");
    }
    swapletRate_ = coupon_->underlying()->rate();
    effectiveIndexFixing_ = coupon_->underlying()->effectiveIndexFixing();
    effectiveCapletVolatility_ = effectiveFloorletVolatility_ = Null<Real>();
}

Here is the call graph for this function:

swapletPrice()

Real swapletPrice ( ) const

override

Definition at line 262 of file blackovernightindexedcouponpricer.cpp.

                                                           {
    QL_FAIL("BlackOvernightIndexedCouponPricer::swapletPrice() not provided");
}

swapletRate()

Rate swapletRate ( ) const

override

Definition at line 250 of file blackovernightindexedcouponpricer.cpp.

{ return swapletRate_; }

capletPrice()

Real capletPrice ( Rate  effectiveCap ) const

override

Definition at line 265 of file blackovernightindexedcouponpricer.cpp.

                                                                           {
    QL_FAIL("BlackOvernightIndexedCouponPricer::capletPrice() not provided");
}

capletRate()

Rate capletRate ( Rate  effectiveCap ) const

override

Definition at line 252 of file blackovernightindexedcouponpricer.cpp.

                                                                          {
    return coupon_->localCapFloor() ? optionletRateLocal(Option::Call, effectiveCap)
                                    : optionletRateGlobal(Option::Call, effectiveCap);
}

Here is the call graph for this function:

floorletPrice()

Real floorletPrice ( Rate  effectiveFloor ) const

override

Definition at line 268 of file blackovernightindexedcouponpricer.cpp.

                                                                               {
    QL_FAIL("BlackOvernightIndexedCouponPricer::floorletPrice() not provided");
}

floorletRate()

Rate floorletRate ( Rate  effectiveFloor ) const

override

Definition at line 257 of file blackovernightindexedcouponpricer.cpp.

                                                                              {
    return coupon_->localCapFloor() ? optionletRateLocal(Option::Put, effectiveFloor)
                                    : optionletRateGlobal(Option::Put, effectiveFloor);
}

Here is the call graph for this function:

optionletRateGlobal()

Real optionletRateGlobal ( Option::Type  optionType, Real  effStrike  ) const

private

Definition at line 44 of file blackovernightindexedcouponpricer.cpp.

                                                                                                       {
    Date lastRelevantFixingDate = coupon_->underlying()->fixingDate();
    if (lastRelevantFixingDate <= Settings::instance().evaluationDate()) {
        // the amount is determined
        Real a, b;
        if (optionType == Option::Call) {
            a = effectiveIndexFixing_;
            b = effStrike;
        } else {
            a = effStrike;
            b = effectiveIndexFixing_;
        }
        return gearing_ * std::max(a - b, 0.0);
    } else {
        // not yet determined, use Black model
        QL_REQUIRE(!capletVolatility().empty(), "BlackOvernightIndexedCouponPricer: missing optionlet volatility");
        std::vector<Date> fixingDates = coupon_->underlying()->fixingDates();
        QL_REQUIRE(!fixingDates.empty(), "BlackOvernightIndexedCouponPricer: empty fixing dates");
        bool shiftedLn = capletVolatility()->volatilityType() == ShiftedLognormal;
        Real shift = capletVolatility()->displacement();
        Real stdDev;
        Real effectiveTime = capletVolatility()->timeFromReference(fixingDates.back());
        if (effectiveVolatilityInput()) {
            // vol input is effective, i.e. we use a plain black model
            stdDev = capletVolatility()->volatility(fixingDates.back(), effStrike) * std::sqrt(effectiveTime);
        } else {
            // vol input is not effective:
            // for the standard deviation see Lyashenko, Mercurio, Looking forward to backward looking rates,
            // section 6.3. the idea is to dampen the average volatility sigma between the fixing start and fixing end
            // date by a linear function going from (fixing start, 1) to (fixing end, 0)
            Real fixingStartTime = capletVolatility()->timeFromReference(fixingDates.front());
            Real fixingEndTime = capletVolatility()->timeFromReference(fixingDates.back());
            Real sigma = capletVolatility()->volatility(
                std::max(fixingDates.front(), capletVolatility()->referenceDate() + 1), effStrike);
            Real T = std::max(fixingStartTime, 0.0);
            if (!close_enough(fixingEndTime, T))
                T += std::pow(fixingEndTime - T, 3.0) / std::pow(fixingEndTime - fixingStartTime, 2.0) / 3.0;
            stdDev = sigma * std::sqrt(T);
        }
        if (optionType == Option::Type::Call)
            effectiveCapletVolatility_ = stdDev / std::sqrt(effectiveTime);
        else
            effectiveFloorletVolatility_ = stdDev / std::sqrt(effectiveTime);
        Real fixing = shiftedLn ? blackFormula(optionType, effStrike, effectiveIndexFixing_, stdDev, 1.0, shift)
                                : bachelierBlackFormula(optionType, effStrike, effectiveIndexFixing_, stdDev, 1.0);
        return gearing_ * fixing;
    }
}

Here is the call graph for this function:

Here is the caller graph for this function:

optionletRateLocal()

Real optionletRateLocal ( Option::Type  optionType, Real  effStrike  ) const

private

Definition at line 103 of file blackovernightindexedcouponpricer.cpp.

                                                                                                      {
 
    QL_REQUIRE(!effectiveVolatilityInput(),
               "BlackAverageONIndexedCouponPricer::optionletRateLocal() does not support effective volatility input.");
 
    // We compute a rate and a rawRate such that
    // rate * tau * nominal is the amount of the coupon with locally (i.e. daily) capped / floored rates
    // rawRate * tau * nominal is the amount of the coupon without capping / flooring the rate
    // We will then return the difference between rate and rawRate (with the correct sign, see below)
    // as the option component of the coupon.
 
    // See CappedFlooredOvernightIndexedCoupon::effectiveCap(), Floor() for what is passed in as effStrike.
    // From this we back out the absolute strike at which the
    // - daily rate + spread (spread included) or the
    // - daily rate (spread excluded)
    // is capped / floored.
 
    Real absStrike = coupon_->underlying()->includeSpread() ? effStrike + coupon_->underlying()->spread() : effStrike;
 
    // This following code is inevitably quite similar to the plain ON coupon pricer code, possibly we can refactor
    // this, but as a first step it seems safer to add the full modified code explicitly here and leave the original
    // code alone.
 
    ext::shared_ptr<OvernightIndex> index = ext::dynamic_pointer_cast<OvernightIndex>(coupon_->index());
 
    const std::vector<Date>& fixingDates = coupon_->underlying()->fixingDates();
    const std::vector<Time>& dt = coupon_->underlying()->dt();
 
    Size n = dt.size();
    Size i = 0;
    QL_REQUIRE(coupon_->underlying()->rateCutoff() < n,
               "rate cutoff (" << coupon_->underlying()->rateCutoff()
                               << ") must be less than number of fixings in period (" << n << ")");
    Size nCutoff = n - coupon_->underlying()->rateCutoff();
 
    Real compoundFactor = 1.0, compoundFactorRaw = 1.0;
 
    // already fixed part
    Date today = Settings::instance().evaluationDate();
    while (i < n && fixingDates[std::min(i, nCutoff)] < today) {
        // rate must have been fixed
        Rate pastFixing = index->pastFixing(fixingDates[std::min(i, nCutoff)]);
        QL_REQUIRE(pastFixing != Null<Real>(),
                   "Missing " << index->name() << " fixing for " << fixingDates[std::min(i, nCutoff)]);
        if (coupon_->underlying()->includeSpread()) {
            pastFixing += coupon_->spread();
        }
        compoundFactor *= 1.0 + cappedFlooredRate(pastFixing, optionType, absStrike) * dt[i];
        compoundFactorRaw *= 1.0 + pastFixing * dt[i];
        ++i;
    }
 
    // today is a border case
    if (i < n && fixingDates[std::min(i, nCutoff)] == today) {
        // might have been fixed
        try {
            Rate pastFixing = index->pastFixing(today);
            if (pastFixing != Null<Real>()) {
                if (coupon_->underlying()->includeSpread()) {
                    pastFixing += coupon_->spread();
                }
                compoundFactor *= 1.0 + cappedFlooredRate(pastFixing, optionType, absStrike) * dt[i];
                compoundFactorRaw *= 1.0 + pastFixing * dt[i];
                ++i;
            } else {
                ; // fall through and forecast
            }
        } catch (Error&) {
            ; // fall through and forecast
        }
    }
 
    // forward part, approximation by pricing a cap / floor in the middle of the future period
    const std::vector<Date>& dates = coupon_->underlying()->valueDates();
    if (i < n) {
        Handle<YieldTermStructure> curve = index->forwardingTermStructure();
        QL_REQUIRE(!curve.empty(), "null term structure set to this instance of " << index->name());
 
        DiscountFactor startDiscount = curve->discount(dates[i]);
        DiscountFactor endDiscount = curve->discount(dates[std::max(nCutoff, i)]);
 
        // handle the rate cutoff period (if there is any, i.e. if nCutoff < n)
        if (nCutoff < n) {
            // forward discount factor for one calendar day on the cutoff date
            DiscountFactor discountCutoffDate = curve->discount(dates[nCutoff] + 1) / curve->discount(dates[nCutoff]);
            // keep the above forward discount factor constant during the cutoff period
            endDiscount *= std::pow(discountCutoffDate, dates[n] - dates[nCutoff]);
        }
 
        // estimate the average daily rate over the future period (approximate the continuously compounded rate)
        Real tau = coupon_->dayCounter().yearFraction(dates[i], dates.back());
        Real averageRate = -std::log(endDiscount / startDiscount) / tau;
 
        // compute the value of a cap or floor with fixing in the middle of the future period
        // (but accounting for the rate cutoff here)
        Time midPoint =
            (capletVolatility()->timeFromReference(dates[i]) + capletVolatility()->timeFromReference(dates[nCutoff])) /
            2.0;
        Real stdDev = capletVolatility()->volatility(midPoint, effStrike) * std::sqrt(midPoint);
        Real shift = capletVolatility()->displacement();
        bool shiftedLn = capletVolatility()->volatilityType() == ShiftedLognormal;
        Rate cfValue = shiftedLn ? blackFormula(optionType, effStrike, averageRate, stdDev, 1.0, shift)
                                 : bachelierBlackFormula(optionType, effStrike, averageRate, stdDev, 1.0);
        Real effectiveTime = capletVolatility()->timeFromReference(fixingDates.back());
        if (optionType == Option::Type::Call)
            effectiveCapletVolatility_ = stdDev / std::sqrt(effectiveTime);
        else
            effectiveFloorletVolatility_ = stdDev / std::sqrt(effectiveTime);
 
        // add spread to average rate
        if (coupon_->underlying()->includeSpread()) {
            averageRate += coupon_->underlying()->spread();
        }
 
        // incorporate cap/floor into average rate
        Real averageRateRaw = averageRate;
        averageRate += optionType == Option::Call ? (-cfValue) : cfValue;
 
        // now assume the averageRate is the effective rate over the future period and update the compoundFactor
        // this is an approximation, see "Ester / Daily Spread Curve Setup in ORE": set tau to avg value
        Real dailyTau =
            coupon_->underlying()->dayCounter().yearFraction(dates[i], dates.back()) / (dates.back() - dates[i]);
        // now use formula (4) from the paper
        compoundFactor *= std::pow(1.0 + dailyTau * averageRate, static_cast<int>(dates.back() - dates[i]));
        compoundFactorRaw *= std::pow(1.0 + dailyTau * averageRateRaw, static_cast<int>(dates.back() - dates[i]));
    }
 
    Rate tau = coupon_->underlying()->lookback() == 0 * Days
                   ? coupon_->accrualPeriod()
                   : coupon_->dayCounter().yearFraction(dates.front(), dates.back());
    Rate rate = (compoundFactor - 1.0) / tau;
    Rate rawRate = (compoundFactorRaw - 1.0) / tau;
 
    rate *= coupon_->underlying()->gearing();
    rawRate *= coupon_->underlying()->gearing();
 
    if (!coupon_->underlying()->includeSpread()) {
        rate += coupon_->underlying()->spread();
        rawRate += coupon_->underlying()->spread();
    }
 
    // return optionletRate := r - rawRate, i.e. the option component only
    // (see CappedFlooredOvernightIndexedCoupon::rate() for the signs of the capletRate / flooredRate)
 
    return (optionType == Option::Call ? -1.0 : 1.0) * (rate - rawRate);
}

Here is the call graph for this function:

Here is the caller graph for this function:

CappedFlooredOvernightIndexedCouponPricer()

CappedFlooredOvernightIndexedCouponPricer	(	const Handle< OptionletVolatilityStructure > &	v,
		const bool	effectiveVolatilityInput = false
	)

Definition at line 214 of file overnightindexedcoupon.cpp.

    : capletVol_(v), effectiveVolatilityInput_(effectiveVolatilityInput) {
    registerWith(capletVol_);
}

Member Data Documentation

gearing_

Real gearing_

private

Definition at line 52 of file blackovernightindexedcouponpricer.hpp.

index_

ext::shared_ptr<IborIndex> index_

private

Definition at line 53 of file blackovernightindexedcouponpricer.hpp.

effectiveIndexFixing_

Real effectiveIndexFixing_

private

Definition at line 54 of file blackovernightindexedcouponpricer.hpp.

swapletRate_

Real swapletRate_

private

Definition at line 54 of file blackovernightindexedcouponpricer.hpp.

coupon_

const CappedFlooredOvernightIndexedCoupon* coupon_

private

Definition at line 56 of file blackovernightindexedcouponpricer.hpp.