CapFloorHelper Class Reference

#include <qle/termstructures/capfloorhelper.hpp>

Inheritance diagram for CapFloorHelper:

Collaboration diagram for CapFloorHelper:

Public Types
enum	Type { Cap , Floor , Automatic }
enum	QuoteType { Premium , Volatility }
	Enum to indicate the type of the quote provided with the CapFloorHelper. More...

Public Member Functions
	CapFloorHelper (Type type, const QuantLib::Period &tenor, QuantLib::Rate strike, const QuantLib::Handle< QuantLib::Quote > &quote, const QuantLib::ext::shared_ptr< QuantLib::IborIndex > &iborIndex, const QuantLib::Handle< QuantLib::YieldTermStructure > &discountingCurve, bool moving=true, const QuantLib::Date &effectiveDate=QuantLib::Date(), QuoteType quoteType=Premium, QuantLib::VolatilityType quoteVolatilityType=QuantLib::Normal, QuantLib::Real quoteDisplacement=0.0, bool endOfMonth=false, bool firstCapletExcluded=true)
Inspectors
QuantLib::ext::shared_ptr< QuantLib::CapFloor >	capFloor () const
	Return the cap floor instrument underlying the helper. More...
BootstrapHelper interface
QuantLib::Real	impliedQuote () const override
	Returns the capFloor_ instrument's premium. More...
void	setTermStructure (QuantLib::OptionletVolatilityStructure *ovts) override
	Sets the helper's OptionletVolatilityStructure to ovts and sets up the pricing engine for capFloor_. More...

Visitability
Type	type_
QuantLib::Period	tenor_
QuantLib::Rate	strike_
QuantLib::ext::shared_ptr< QuantLib::IborIndex >	iborIndex_
QuantLib::Handle< QuantLib::YieldTermStructure >	discountHandle_
bool	moving_
QuantLib::Date	effectiveDate_
QuoteType	quoteType_
QuantLib::VolatilityType	quoteVolatilityType_
QuantLib::Real	quoteDisplacement_
bool	endOfMonth_
bool	firstCapletExcluded_
QuantLib::Handle< QuantLib::Quote >	rawQuote_
bool	initialised_
QuantLib::ext::shared_ptr< QuantLib::CapFloor >	capFloor_
	The underlying instrument. More...
QuantLib::RelinkableHandle< QuantLib::OptionletVolatilityStructure >	ovtsHandle_
	The OptionletVolatilityStructure Handle that we link to the capFloor_ instrument. More...
QuantLib::ext::shared_ptr< QuantLib::CapFloor >	capFloorCopy_
	A copy of the underlying instrument that is used in the npv method. More...
void	accept (QuantLib::AcyclicVisitor &) override
void	initializeDates () override
	RelativeDateBootstrapHelper interface. More...
QuantLib::Real	npv (QuantLib::Real quote)
	A method to calculate the cap floor premium from a flat cap floor volatility value. More...

Detailed Description

Helper for bootstrapping optionlet volatilities from cap floor volatilities. The helper has a date schedule that is relative to the global evaluation date.

Definition at line 38 of file capfloorhelper.hpp.

Member Enumeration Documentation

Type

enum Type

Enum to indicate whether the instrument underlying the helper is a Cap, a Floor or should be chosen automatically. If Automatic is chosen and the quote type is volatility, the instrument's ATM rate is queried and if it is greater than the strike, the instrument is a Floor otherwise it is a Cap.

Enumerator
Cap
Floor
Automatic

Definition at line 45 of file capfloorhelper.hpp.

{ Cap, Floor, Automatic };

QuoteType

enum QuoteType

Enum to indicate the type of the quote provided with the CapFloorHelper.

Enumerator
Premium
Volatility

Definition at line 48 of file capfloorhelper.hpp.

{ Premium, Volatility };

Constructor & Destructor Documentation

CapFloorHelper()

CapFloorHelper	(	Type	type,
		const QuantLib::Period &	tenor,
		QuantLib::Rate	strike,
		const QuantLib::Handle< QuantLib::Quote > &	quote,
		const QuantLib::ext::shared_ptr< QuantLib::IborIndex > &	iborIndex,
		const QuantLib::Handle< QuantLib::YieldTermStructure > &	discountingCurve,
		bool	moving = true,
		const QuantLib::Date &	effectiveDate = QuantLib::Date(),
		QuoteType	quoteType = Premium,
		QuantLib::VolatilityType	quoteVolatilityType = QuantLib::Normal,
		QuantLib::Real	quoteDisplacement = 0.0,
		bool	endOfMonth = false,
		bool	firstCapletExcluded = true
	)

Constructor

Parameters

type	The CapFloorHelper type as described above
tenor	The underlying cap floor instrument's tenor
strike	The underlying cap floor instrument's strike. Setting this to Null<Real>() indicates that the ATM strike for the given tenor should be used.
quote	The quoted premium or implied volatility for the underlying cap floor instrument
iborIndex	The IborIndex underlying the cap floor instrument
discountingCurve	The curve used for discounting the cap floor instrument cashflows
moving	If this is true, the helper's schedule is relative to the global evaluation date and is updated if the global evaluation date is updated. If false, the helper has a fixed schedule relative to the effectiveDate that does not change with changes in the global evaluation date.
effectiveDate	The effective date of the underlying cap floor instrument. If this is the empty QuantLib::Date(), the effective date is determined from the global evaluation date.
quoteType	The quote type
quoteVolatilityType	If the quote type is Volatility, this indicates the volatility type of the quote
quoteDisplacement	If the quote type is Volatility and the volatility type is ShiftedLognormal, this provides the shift size associated with the quote.
endOfMonth	Whether or not to use end of month adjustment when generating the cap floor schedule
firstCapletExcluded	Whether or not to exclude the first caplet in the underlying cap floor instrument

Definition at line 39 of file capfloorhelper.cpp.

    : RelativeDateBootstrapHelper<OptionletVolatilityStructure>(
          Handle<Quote>(QuantLib::ext::make_shared<DerivedQuote<QuantLib::ext::function<Real(Real)> > >(
              quote, QuantLib::ext::bind(&CapFloorHelper::npv, this, QuantLib::ext::placeholders::_1)))),
      type_(type), tenor_(tenor), strike_(strike), iborIndex_(iborIndex), discountHandle_(discountingCurve),
      moving_(moving), effectiveDate_(effectiveDate), quoteType_(quoteType), quoteVolatilityType_(quoteVolatilityType),
      quoteDisplacement_(quoteDisplacement), endOfMonth_(endOfMonth), firstCapletExcluded_(firstCapletExcluded),
      rawQuote_(quote), initialised_(false) {
 
    if (quoteType_ == Premium) {
        QL_REQUIRE(type_ != Automatic, "Cannot have CapFloorHelper type 'Automatic' with quote type of Premium");
    }
 
    QL_REQUIRE(!(moving_ && effectiveDate_ != Date()),
               "A fixed effective date does not make sense for a moving helper");
 
    registerWith(iborIndex_);
    registerWith(discountHandle_);
 
    initializeDates();
    initialised_ = true;
}

Here is the call graph for this function:

Member Function Documentation

capFloor()

QuantLib::ext::shared_ptr< QuantLib::CapFloor > capFloor

(

)

const

Return the cap floor instrument underlying the helper.

Definition at line 83 of file capfloorhelper.hpp.

{ return capFloor_; }

impliedQuote()

Real impliedQuote ( ) const

override

Returns the capFloor_ instrument's premium.

Definition at line 158 of file capfloorhelper.cpp.

                                        {
    QL_REQUIRE(termStructure_ != 0, "CapFloorHelper's optionlet volatility term structure has not been set");
    capFloor_->deepUpdate();
    return capFloor_->NPV();
}

setTermStructure()

void setTermStructure ( QuantLib::OptionletVolatilityStructure *  ovts )

override

Sets the helper's OptionletVolatilityStructure to ovts and sets up the pricing engine for capFloor_.

Definition at line 105 of file capfloorhelper.cpp.

                                                                        {
 
    if (strike_ == Null<Real>()) {
        // If the strike is Null<Real>(), we want an ATM helper
        Rate atm = capFloor_->atmRate(**discountHandle_);
        capFloor_ = MakeCapFloor(capFloor_->type(), tenor_, iborIndex_, atm, 0 * Days)
                        .withEndOfMonth(endOfMonth_)
                        .withEffectiveDate(effectiveDate_, firstCapletExcluded_);
        capFloorCopy_ = MakeCapFloor(capFloor_->type(), tenor_, iborIndex_, atm, 0 * Days)
                            .withEndOfMonth(endOfMonth_)
                            .withEffectiveDate(effectiveDate_, firstCapletExcluded_);
 
    } else if (type_ == CapFloorHelper::Automatic && quoteType_ != Premium) {
        // If the helper is set to automatically choose the underlying instrument type, do it now based on the ATM rate
        Rate atm = capFloor_->atmRate(**discountHandle_);
        CapFloor::Type capFloorType = atm > strike_ ? CapFloor::Floor : CapFloor::Cap;
        if (capFloor_->type() != capFloorType) {
            capFloor_ = MakeCapFloor(capFloorType, tenor_, iborIndex_, strike_, 0 * Days)
                            .withEndOfMonth(endOfMonth_)
                            .withEffectiveDate(effectiveDate_, firstCapletExcluded_);
            capFloorCopy_ = MakeCapFloor(capFloorType, tenor_, iborIndex_, strike_, 0 * Days)
                                .withEndOfMonth(endOfMonth_)
                                .withEffectiveDate(effectiveDate_, firstCapletExcluded_);
        }
    }
 
    // Set this helper's optionlet volatility structure
    QuantLib::ext::shared_ptr<OptionletVolatilityStructure> temp(ovts, null_deleter());
    ovtsHandle_.linkTo(temp, false);
 
    // Set the term structure pointer member variable in the base class
    RelativeDateBootstrapHelper<OptionletVolatilityStructure>::setTermStructure(ovts);
 
    // Set this helper's pricing engine depending on the type of the optionlet volatilities
    if (ovts->volatilityType() == ShiftedLognormal) {
        capFloor_->setPricingEngine(QuantLib::ext::make_shared<BlackCapFloorEngine>(discountHandle_, ovtsHandle_));
    } else {
        capFloor_->setPricingEngine(QuantLib::ext::make_shared<BachelierCapFloorEngine>(discountHandle_, ovtsHandle_));
    }
 
    // If the quote type is not a premium, we will need to use capFloorCopy_ to return the premium from the volatility
    // quote
    if (quoteType_ != Premium) {
        if (quoteVolatilityType_ == ShiftedLognormal) {
            capFloorCopy_->setPricingEngine(QuantLib::ext::make_shared<BlackCapFloorEngine>(
                discountHandle_, rawQuote_, ovtsHandle_->dayCounter(), quoteDisplacement_));
        } else {
            capFloorCopy_->setPricingEngine(
                QuantLib::ext::make_shared<BachelierCapFloorEngine>(discountHandle_, rawQuote_, ovtsHandle_->dayCounter()));
        }
    }
}

accept()

void accept ( QuantLib::AcyclicVisitor &  )

override

Definition at line 164 of file capfloorhelper.cpp.

                                             {
    if (Visitor<CapFloorHelper>* v1 = dynamic_cast<Visitor<CapFloorHelper>*>(&v))
        v1->visit(*this);
    else
        RelativeDateBootstrapHelper<OptionletVolatilityStructure>::accept(v);
}

initializeDates()

void initializeDates ( )

overrideprivate

RelativeDateBootstrapHelper interface.

Definition at line 67 of file capfloorhelper.cpp.

                                     {
 
    if (!initialised_ || moving_) {
        CapFloor::Type capFloorType = CapFloor::Cap;
        if (type_ == CapFloorHelper::Floor) {
            capFloorType = CapFloor::Floor;
        }
 
        // Initialise the instrument and a copy
        // The strike can be Null<Real>() to indicate an ATM cap floor helper
        Rate dummyStrike = strike_ == Null<Real>() ? 0.01 : strike_;
        capFloor_ = MakeCapFloor(capFloorType, tenor_, iborIndex_, dummyStrike, 0 * Days)
                        .withEndOfMonth(endOfMonth_)
                        .withEffectiveDate(effectiveDate_, firstCapletExcluded_);
        capFloorCopy_ = MakeCapFloor(capFloorType, tenor_, iborIndex_, dummyStrike, 0 * Days)
                            .withEndOfMonth(endOfMonth_)
                            .withEffectiveDate(effectiveDate_, firstCapletExcluded_);
 
        // Maturity date is just the maturity date of the cap floor
        maturityDate_ = capFloor_->maturityDate();
 
        // We need the leg underlying the cap floor to determine the remaining date members
        const Leg& leg = capFloor_->floatingLeg();
 
        // Earliest date is the first optionlet fixing date
        QuantLib::ext::shared_ptr<CashFlow> cf = leg.front();
        QuantLib::ext::shared_ptr<FloatingRateCoupon> frc = QuantLib::ext::dynamic_pointer_cast<FloatingRateCoupon>(cf);
        QL_REQUIRE(frc, "Expected the first cashflow on the cap floor instrument to be a FloatingRateCoupon");
        earliestDate_ = frc->fixingDate();
 
        // Remaining dates are each equal to the fixing date on the final optionlet
        cf = leg.back();
        frc = QuantLib::ext::dynamic_pointer_cast<FloatingRateCoupon>(cf);
        QL_REQUIRE(frc, "Expected the final cashflow on the cap floor instrument to be a FloatingRateCoupon");
        pillarDate_ = latestDate_ = latestRelevantDate_ = frc->fixingDate();
    }
}

Here is the caller graph for this function:

npv()

Real npv ( QuantLib::Real  quote )

private

A method to calculate the cap floor premium from a flat cap floor volatility value.

Definition at line 171 of file capfloorhelper.cpp.

                                        {
    if (quoteType_ == Premium) {
        return quoteValue;
    } else {
        // If the quote value is a volatility, return the premium
        return capFloorCopy_->NPV();
    }
}

Member Data Documentation

type_

Type type_

private

Definition at line 105 of file capfloorhelper.hpp.

tenor_

QuantLib::Period tenor_

private

Definition at line 106 of file capfloorhelper.hpp.

strike_

QuantLib::Rate strike_

private

Definition at line 107 of file capfloorhelper.hpp.

iborIndex_

QuantLib::ext::shared_ptr<QuantLib::IborIndex> iborIndex_

private

Definition at line 108 of file capfloorhelper.hpp.

discountHandle_

QuantLib::Handle<QuantLib::YieldTermStructure> discountHandle_

private

Definition at line 109 of file capfloorhelper.hpp.

moving_

bool moving_

private

Definition at line 110 of file capfloorhelper.hpp.

effectiveDate_

QuantLib::Date effectiveDate_

private

Definition at line 111 of file capfloorhelper.hpp.

quoteType_

QuoteType quoteType_

private

Definition at line 112 of file capfloorhelper.hpp.

quoteVolatilityType_

QuantLib::VolatilityType quoteVolatilityType_

private

Definition at line 113 of file capfloorhelper.hpp.

quoteDisplacement_

QuantLib::Real quoteDisplacement_

private

Definition at line 114 of file capfloorhelper.hpp.

endOfMonth_

bool endOfMonth_

private

Definition at line 115 of file capfloorhelper.hpp.

firstCapletExcluded_

bool firstCapletExcluded_

private

Definition at line 116 of file capfloorhelper.hpp.

rawQuote_

QuantLib::Handle<QuantLib::Quote> rawQuote_

private

Definition at line 117 of file capfloorhelper.hpp.

initialised_

bool initialised_

private

Definition at line 118 of file capfloorhelper.hpp.

capFloor_

QuantLib::ext::shared_ptr<QuantLib::CapFloor> capFloor_

private

The underlying instrument.

Definition at line 121 of file capfloorhelper.hpp.

ovtsHandle_

QuantLib::RelinkableHandle<QuantLib::OptionletVolatilityStructure> ovtsHandle_

private

The OptionletVolatilityStructure Handle that we link to the capFloor_ instrument.

Definition at line 124 of file capfloorhelper.hpp.

capFloorCopy_

QuantLib::ext::shared_ptr<QuantLib::CapFloor> capFloorCopy_

private

A copy of the underlying instrument that is used in the npv method.

Definition at line 127 of file capfloorhelper.hpp.