BlackAverageONIndexedCouponPricer Class Reference

Black averaged overnight coupon pricer. More...

#include <qle/cashflows/blackovernightindexedcouponpricer.hpp>

Inheritance diagram for BlackAverageONIndexedCouponPricer:

Collaboration diagram for BlackAverageONIndexedCouponPricer:

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
	CapFlooredAverageONIndexedCouponPricer (const Handle< OptionletVolatilityStructure > &v, const bool effectiveVolatilityInput=false)
Public Member Functions inherited from CapFlooredAverageONIndexedCouponPricer
	CapFlooredAverageONIndexedCouponPricer (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	swapletRate_
Real	forwardRate_
const CappedFlooredAverageONIndexedCoupon *	coupon_

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

Detailed Description

Black averaged overnight coupon pricer.

Definition at line 63 of file blackovernightindexedcouponpricer.hpp.

Member Function Documentation

initialize()

void initialize ( const FloatingRateCoupon &  coupon )

override

Definition at line 272 of file blackovernightindexedcouponpricer.cpp.

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

Here is the call graph for this function:

swapletPrice()

Real swapletPrice ( ) const

override

Definition at line 498 of file blackovernightindexedcouponpricer.cpp.

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

swapletRate()

Rate swapletRate ( ) const

override

Definition at line 486 of file blackovernightindexedcouponpricer.cpp.

{ return swapletRate_; }

capletPrice()

Real capletPrice ( Rate  effectiveCap ) const

override

Definition at line 501 of file blackovernightindexedcouponpricer.cpp.

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

capletRate()

Rate capletRate ( Rate  effectiveCap ) const

override

Definition at line 488 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 504 of file blackovernightindexedcouponpricer.cpp.

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

floorletRate()

Rate floorletRate ( Rate  effectiveFloor ) const

override

Definition at line 493 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 290 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 = forwardRate_;
            b = effStrike;
        } else {
            a = effStrike;
            b = forwardRate_;
        }
        return gearing_ * std::max(a - b, 0.0);
    } else {
        // not yet determined, use Black model
        QL_REQUIRE(!capletVolatility().empty(), "BlackAverageONIndexedCouponPricer: missing optionlet volatility");
        std::vector<Date> fixingDates = coupon_->underlying()->fixingDates();
        QL_REQUIRE(!fixingDates.empty(), "BlackAverageONIndexedCouponPricer: 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, forwardRate_, stdDev, 1.0, shift)
                                : bachelierBlackFormula(optionType, effStrike, forwardRate_, 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 339 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_->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 accumulatedRate = 0.0, accumulatedRateRaw = 0.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_->includeSpread()) {
            pastFixing += coupon_->spread();
        }
        accumulatedRate += cappedFlooredRate(pastFixing, optionType, absStrike) * dt[i];
        accumulatedRateRaw += 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_->includeSpread()) {
                    pastFixing += coupon_->spread();
                }
                accumulatedRate += cappedFlooredRate(pastFixing, optionType, absStrike) * dt[i];
                accumulatedRateRaw += 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_->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 average rate
        // 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]);
        accumulatedRate += dailyTau * averageRate * static_cast<Real>(dates.back() - dates[i]);
        accumulatedRateRaw += dailyTau * averageRateRaw * static_cast<Real>(dates.back() - dates[i]);
    }
 
    Rate tau = coupon_->underlying()->lookback() == 0 * Days
                   ? coupon_->accrualPeriod()
                   : coupon_->dayCounter().yearFraction(dates.front(), dates.back());
    Rate rate = accumulatedRate / tau;
    Rate rawRate = accumulatedRateRaw / tau;
 
    rate *= coupon_->underlying()->gearing();
    rawRate *= coupon_->underlying()->gearing();
 
    if (!coupon_->includeSpread()) {
        rate += coupon_->underlying()->spread();
        rawRate += coupon_->underlying()->spread();
    }
 
    // return optionletRate := r - rawRate, i.e. the option component only
    // (see CappedFlooredAverageONIndexedCoupon::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:

CapFlooredAverageONIndexedCouponPricer()

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

Definition at line 162 of file averageonindexedcoupon.cpp.

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

Member Data Documentation

gearing_

Real gearing_

private

Definition at line 78 of file blackovernightindexedcouponpricer.hpp.

index_

ext::shared_ptr<IborIndex> index_

private

Definition at line 79 of file blackovernightindexedcouponpricer.hpp.

swapletRate_

Real swapletRate_

private

Definition at line 80 of file blackovernightindexedcouponpricer.hpp.

forwardRate_

Real forwardRate_

private

Definition at line 80 of file blackovernightindexedcouponpricer.hpp.

coupon_

const CappedFlooredAverageONIndexedCoupon* coupon_

private

Definition at line 82 of file blackovernightindexedcouponpricer.hpp.