EquityCoupon Class Reference

equity coupon More...

#include <qle/cashflows/equitycoupon.hpp>

Inheritance diagram for EquityCoupon:

Collaboration diagram for EquityCoupon:

Public Member Functions
	EquityCoupon (const Date &paymentDate, Real nominal, const Date &startDate, const Date &endDate, Natural fixingDays, const QuantLib::ext::shared_ptr< QuantExt::EquityIndex2 > &equityCurve, const DayCounter &dayCounter, EquityReturnType returnType, Real dividendFactor=1.0, bool notionalReset=false, Real initialPrice=Null< Real >(), Real quantity=Null< Real >(), const Date &fixingStartDate=Date(), const Date &fixingEndDate=Date(), const Date &refPeriodStart=Date(), const Date &refPeriodEnd=Date(), const Date &exCouponDate=Date(), const QuantLib::ext::shared_ptr< FxIndex > &fxIndex=nullptr, const bool initialPriceIsInTargetCcy=false, Real legInitialNotional=Null< Real >(), const Date &legFixingDate=Date())
CashFlow interface
Real	amount () const override
Coupon interface
DayCounter	dayCounter () const override
Real	accruedAmount (const Date &) const override
Rate	rate () const override
Real	nominal () const override
Inspectors
const QuantLib::ext::shared_ptr< QuantExt::EquityIndex2 > &	equityCurve () const
	equity reference rate curve More...
const QuantLib::ext::shared_ptr< FxIndex > &	fxIndex () const
	fx index curve More...
EquityReturnType	returnType () const
	the return type of the coupon More...
Real	dividendFactor () const
	are dividends scaled (e.g. to account for tax) More...
Date	fixingStartDate () const
	The date at which the starting equity price is fixed. More...
Date	fixingEndDate () const
	The date at which performance is measured. More...
std::vector< Date >	fixingDates () const
	return both fixing dates More...
Real	initialPrice () const
	initial price More...
bool	initialPriceIsInTargetCcy () const
	initial price is in target ccy (if applicable, i.e. if fxIndex != null, otherwise ignored) More...
Real	quantity () const
	Number of equity shares held. More...
Real	fxRate () const
	FX conversion rate (or 1.0 if not applicable) More...
Date	fixingDate () const
	This function is called for other coupon types. More...
Real	legInitialNotional () const
	Initial notional of the equity leg, to compute quantity if not provided in the resetting case. More...
Date	legFixingDate () const
	Fixing date of the first equity coupon, to compute quantity if not provided in the resetting case. More...
Observer interface
void	update () override

Visitability
QuantLib::ext::shared_ptr< EquityCouponPricer >	pricer_
Natural	fixingDays_
QuantLib::ext::shared_ptr< QuantExt::EquityIndex2 >	equityCurve_
DayCounter	dayCounter_
EquityReturnType	returnType_
Real	dividendFactor_
bool	notionalReset_
Real	initialPrice_
bool	initialPriceIsInTargetCcy_
Real	quantity_
Date	fixingStartDate_
Date	fixingEndDate_
Natural	paymentLag_
QuantLib::ext::shared_ptr< FxIndex >	fxIndex_
Real	legInitialNotional_
Date	legFixingDate_
virtual void	accept (AcyclicVisitor &) override
void	setPricer (const QuantLib::ext::shared_ptr< EquityCouponPricer > &)
QuantLib::ext::shared_ptr< EquityCouponPricer >	pricer () const

Detailed Description

equity coupon

Definition at line 53 of file equitycoupon.hpp.

Constructor & Destructor Documentation

EquityCoupon()

EquityCoupon	(	const Date &	paymentDate,
		Real	nominal,
		const Date &	startDate,
		const Date &	endDate,
		Natural	fixingDays,
		const QuantLib::ext::shared_ptr< QuantExt::EquityIndex2 > &	equityCurve,
		const DayCounter &	dayCounter,
		EquityReturnType	returnType,
		Real	dividendFactor = 1.0,
		bool	notionalReset = false,
		Real	initialPrice = Null<Real>(),
		Real	quantity = Null<Real>(),
		const Date &	fixingStartDate = Date(),
		const Date &	fixingEndDate = Date(),
		const Date &	refPeriodStart = Date(),
		const Date &	refPeriodEnd = Date(),
		const Date &	exCouponDate = Date(),
		const QuantLib::ext::shared_ptr< FxIndex > &	fxIndex = nullptr,
		const bool	initialPriceIsInTargetCcy = false,
		Real	legInitialNotional = Null<Real>(),
		const Date &	legFixingDate = Date()
	)

Definition at line 57 of file equitycoupon.cpp.

    : Coupon(paymentDate, nominal, startDate, endDate, refPeriodStart, refPeriodEnd, exCouponDate),
      fixingDays_(fixingDays), equityCurve_(equityCurve), dayCounter_(dayCounter), returnType_(returnType),
      dividendFactor_(dividendFactor), notionalReset_(notionalReset), initialPrice_(initialPrice),
      initialPriceIsInTargetCcy_(initialPriceIsInTargetCcy), quantity_(quantity), fixingStartDate_(fixingStartDate),
      fixingEndDate_(fixingEndDate), fxIndex_(fxIndex), legInitialNotional_(legInitialNotional),
      legFixingDate_(legFixingDate)  {
    QL_REQUIRE(dividendFactor_ > 0.0, "Dividend factor should not be negative. It is expected to be between 0 and 1.");
    QL_REQUIRE(equityCurve_, "Equity underlying an equity swap coupon cannot be empty.");
 
    // set up fixing calendar as combined eq / fx calendar
    Calendar eqCalendar = NullCalendar();
    Calendar fxCalendar = NullCalendar();
    if (!equityCurve_->fixingCalendar().empty()) {
        eqCalendar = equityCurve_->fixingCalendar();
    }
    if (fxIndex_ && !fxIndex_->fixingCalendar().empty()) {
        fxCalendar = fxIndex_->fixingCalendar();
    }
    Calendar fixingCalendar = JointCalendar(eqCalendar, fxCalendar);
 
    // If a fixing start / end date is provided, use these
    // else adjust the start/endDate by the FixingDays - defaulted to 0
    if (fixingStartDate_ == Date())
        fixingStartDate_ =
            fixingCalendar.advance(startDate, -static_cast<Integer>(fixingDays_), Days, Preceding);
 
    if (fixingEndDate_ == Date())
        fixingEndDate_ =
            fixingCalendar.advance(endDate, -static_cast<Integer>(fixingDays_), Days, Preceding);
 
    registerWith(equityCurve_);
    registerWith(fxIndex_);
    registerWith(Settings::instance().evaluationDate());
 
    // QL_REQUIRE(!notionalReset_ || quantity_ != Null<Real>(), "EquityCoupon: quantity required if notional resets");
    QL_REQUIRE(notionalReset_ || nominal_ != Null<Real>(),
               "EquityCoupon: notional required if notional does not reset");
}

Member Function Documentation

amount()

Real amount ( ) const

override

Definition at line 66 of file equitycoupon.hpp.

{ return rate() * nominal(); }

Here is the call graph for this function:

Here is the caller graph for this function:

dayCounter()

DayCounter dayCounter ( ) const

override

Definition at line 72 of file equitycoupon.hpp.

{ return dayCounter_; }

Here is the caller graph for this function:

accruedAmount()

Real accruedAmount ( const Date &  d ) const

override

Definition at line 148 of file equitycoupon.cpp.

                                                    {
    if (d <= accrualStartDate_ || d > paymentDate_) {
        return 0.0;
    } else {
        Time fullPeriod = dayCounter().yearFraction(accrualStartDate_, accrualEndDate_, refPeriodStart_, refPeriodEnd_);
        Time thisPeriod =
            dayCounter().yearFraction(accrualStartDate_, std::min(d, accrualEndDate_), refPeriodStart_, refPeriodEnd_);
        return nominal() * rate() * thisPeriod / fullPeriod;
    }
}

Here is the call graph for this function:

rate()

Rate rate ( ) const

override

Definition at line 159 of file equitycoupon.cpp.

                              {
    QL_REQUIRE(pricer_, "pricer not set");
    // we know it is the correct type because checkPricerImpl checks on setting
    // in general pricer_ will be a derived class, as will *this on calling
    pricer_->initialize(*this);
    return pricer_->swapletRate();
}

Here is the caller graph for this function:

nominal()

Real nominal ( ) const

override

Definition at line 121 of file equitycoupon.cpp.

                                 {
    // use quantity for dividend swaps, this ensures notional resetting is not relevant
    // swaplet rate returns the absolute dividend to match
    if (returnType_ == EquityReturnType::Dividend)
        return quantity();
    else if(notionalReset_) {
        Real mult = (initialPrice_ == 0) ? 1 : initialPrice();
        return mult * (initialPriceIsInTargetCcy_ ? 1.0 : fxRate()) * quantity();
    } else {
        return nominal_;
    }
}

Here is the call graph for this function:

Here is the caller graph for this function:

equityCurve()

const QuantLib::ext::shared_ptr< QuantExt::EquityIndex2 > & equityCurve

(

)

const

equity reference rate curve

Definition at line 83 of file equitycoupon.hpp.

{ return equityCurve_; }

Here is the caller graph for this function:

fxIndex()

const QuantLib::ext::shared_ptr< FxIndex > & fxIndex

(

)

const

fx index curve

Definition at line 85 of file equitycoupon.hpp.

{ return fxIndex_; }

Here is the caller graph for this function:

returnType()

EquityReturnType returnType

(

)

const

the return type of the coupon

Definition at line 87 of file equitycoupon.hpp.

{ return returnType_; }

Here is the caller graph for this function:

dividendFactor()

Real dividendFactor

(

)

const

are dividends scaled (e.g. to account for tax)

Definition at line 89 of file equitycoupon.hpp.

{ return dividendFactor_; }

Here is the caller graph for this function:

fixingStartDate()

Date fixingStartDate

(

)

const

The date at which the starting equity price is fixed.

Definition at line 91 of file equitycoupon.hpp.

{ return fixingStartDate_; }

Here is the caller graph for this function:

fixingEndDate()

Date fixingEndDate

(

)

const

The date at which performance is measured.

Definition at line 93 of file equitycoupon.hpp.

{ return fixingEndDate_; }

Here is the caller graph for this function:

fixingDates()

std::vector< Date > fixingDates

(

)

const

return both fixing dates

Definition at line 167 of file equitycoupon.cpp.

                                                {
    std::vector<Date> fixingDates;
 
    fixingDates.push_back(fixingStartDate_);
    fixingDates.push_back(fixingEndDate_);
    // We may need a fixing date at the leg start date if it a notionalReset and the quantity is null
    // Quantity is null if no initial price was given for the Swap
    if (notionalReset_ && quantity_ == Null<Real>())
        fixingDates.push_back(legFixingDate_);
    return fixingDates;
};

Here is the call graph for this function:

Here is the caller graph for this function:

initialPrice()

Real initialPrice

(

)

const

initial price

Definition at line 139 of file equitycoupon.cpp.

                                      {
    if (initialPrice_ != Null<Real>())
        return initialPrice_;
    else
        return equityCurve_->fixing(fixingStartDate(), false, false);
}

Here is the call graph for this function:

Here is the caller graph for this function:

initialPriceIsInTargetCcy()

bool initialPriceIsInTargetCcy

(

)

const

initial price is in target ccy (if applicable, i.e. if fxIndex != null, otherwise ignored)

Definition at line 146 of file equitycoupon.cpp.

{ return initialPriceIsInTargetCcy_; }

Here is the caller graph for this function:

quantity()

Real quantity

(

)

const

Number of equity shares held.

Definition at line 112 of file equitycoupon.cpp.

                                  {
    if (notionalReset_ && quantity_ == Null<Real>()) {
        QL_REQUIRE(legInitialNotional_ != Null<Real>() && legFixingDate_ != Date(),
           "leg initial notional and fixing date required to compute the missing quantity in case of a resetting equity leg");
        quantity_ = legInitialNotional_ / equityCurve_->fixing(legFixingDate_, false, false);
    }
    return quantity_;
}

Here is the caller graph for this function:

fxRate()

Real fxRate

(

)

const

FX conversion rate (or 1.0 if not applicable)

Definition at line 134 of file equitycoupon.cpp.

                                {
    // fxRate applied if equity underlying currency differs from leg
    return fxIndex_ ? fxIndex_->fixing(fixingStartDate_) : 1.0;
}

Here is the caller graph for this function:

fixingDate()

Date fixingDate

(

)

const

This function is called for other coupon types.

Definition at line 105 of file equitycoupon.hpp.

                            {
        QL_FAIL("Equity Coupons have 2 fixings, not 1.");
        return Date();
    }

legInitialNotional()

Real legInitialNotional

(

)

const

Initial notional of the equity leg, to compute quantity if not provided in the resetting case.

Definition at line 110 of file equitycoupon.hpp.

{ return legInitialNotional_; }

legFixingDate()

Date legFixingDate

(

)

const

Fixing date of the first equity coupon, to compute quantity if not provided in the resetting case.

Definition at line 112 of file equitycoupon.hpp.

{ return legFixingDate_; }

update()

void update ( )

override

Definition at line 117 of file equitycoupon.hpp.

{ notifyObservers(); }

Here is the caller graph for this function:

accept()

void accept ( AcyclicVisitor &  v )

overridevirtual

Definition at line 148 of file equitycoupon.hpp.

                                                  {
    Visitor<EquityCoupon>* v1 = dynamic_cast<Visitor<EquityCoupon>*>(&v);
    if (v1 != 0)
        v1->visit(*this);
    else
        Coupon::accept(v);
}

setPricer()

void setPricer

(

const QuantLib::ext::shared_ptr< EquityCouponPricer > &

pricer

)

Definition at line 103 of file equitycoupon.cpp.

                                                                                    {
    if (pricer_)
        unregisterWith(pricer_);
    pricer_ = pricer;
    if (pricer_)
        registerWith(pricer_);
    update();
}

Here is the call graph for this function:

Here is the caller graph for this function:

pricer()

QuantLib::ext::shared_ptr< EquityCouponPricer > pricer

(

)

const

Definition at line 156 of file equitycoupon.hpp.

{ return pricer_; }

Here is the caller graph for this function:

Member Data Documentation

pricer_

QuantLib::ext::shared_ptr<EquityCouponPricer> pricer_

protected

Definition at line 128 of file equitycoupon.hpp.

fixingDays_

Natural fixingDays_

protected

Definition at line 129 of file equitycoupon.hpp.

equityCurve_

QuantLib::ext::shared_ptr<QuantExt::EquityIndex2> equityCurve_

protected

Definition at line 130 of file equitycoupon.hpp.

dayCounter_

DayCounter dayCounter_

protected

Definition at line 131 of file equitycoupon.hpp.

returnType_

EquityReturnType returnType_

protected

Definition at line 132 of file equitycoupon.hpp.

dividendFactor_

Real dividendFactor_

protected

Definition at line 133 of file equitycoupon.hpp.

notionalReset_

bool notionalReset_

protected

Definition at line 134 of file equitycoupon.hpp.

initialPrice_

Real initialPrice_

protected

Definition at line 135 of file equitycoupon.hpp.

initialPriceIsInTargetCcy_

bool initialPriceIsInTargetCcy_

protected

Definition at line 136 of file equitycoupon.hpp.

quantity_

Real quantity_

mutableprotected

Definition at line 137 of file equitycoupon.hpp.

fixingStartDate_

Date fixingStartDate_

protected

Definition at line 138 of file equitycoupon.hpp.

fixingEndDate_

Date fixingEndDate_

protected

Definition at line 139 of file equitycoupon.hpp.

paymentLag_

Natural paymentLag_

protected

Definition at line 140 of file equitycoupon.hpp.

fxIndex_

QuantLib::ext::shared_ptr<FxIndex> fxIndex_

protected

Definition at line 141 of file equitycoupon.hpp.

legInitialNotional_

Real legInitialNotional_

protected

Definition at line 142 of file equitycoupon.hpp.

legFixingDate_

Date legFixingDate_

protected

Definition at line 143 of file equitycoupon.hpp.