Cash flow dependent on a single commodity spot price or futures settlement price on a given pricing date. More...

#include <qle/cashflows/commodityindexedcashflow.hpp>

Inheritance diagram for CommodityIndexedCashFlow:

Collaboration diagram for CommodityIndexedCashFlow:

Public Types
enum class	PaymentTiming { InAdvance , InArrears , RelativeToExpiry }

Public Member Functions
	CommodityIndexedCashFlow (QuantLib::Real quantity, const QuantLib::Date &pricingDate, const QuantLib::Date &paymentDate, const ext::shared_ptr< CommodityIndex > &index, QuantLib::Real spread=0.0, QuantLib::Real gearing=1.0, bool useFuturePrice=false, const Date &contractDate=Date(), const ext::shared_ptr< FutureExpiryCalculator > &calc=nullptr, QuantLib::Natural dailyExpiryOffset=QuantLib::Null< QuantLib::Natural >(), const ext::shared_ptr< FxIndex > &fxIndex=nullptr)
	Constructor taking an explicit `pricingDate` and `paymentDate`. More...

	CommodityIndexedCashFlow (QuantLib::Real quantity, const QuantLib::Date &startDate, const QuantLib::Date &endDate, const ext::shared_ptr< CommodityIndex > &index, QuantLib::Natural paymentLag, const QuantLib::Calendar &paymentCalendar, QuantLib::BusinessDayConvention paymentConvention, QuantLib::Natural pricingLag, const QuantLib::Calendar &pricingLagCalendar, QuantLib::Real spread=0.0, QuantLib::Real gearing=1.0, PaymentTiming paymentTiming=PaymentTiming::InArrears, bool isInArrears=true, bool useFuturePrice=false, bool useFutureExpiryDate=true, QuantLib::Natural futureMonthOffset=0, const ext::shared_ptr< FutureExpiryCalculator > &calc=nullptr, const QuantLib::Date &paymentDateOverride=Date(), const QuantLib::Date &pricingDateOverride=Date(), QuantLib::Natural dailyExpiryOffset=QuantLib::Null< QuantLib::Natural >(), const ext::shared_ptr< FxIndex > &fxIndex=nullptr, const bool spotAveragingFrontCoupon=false, const QuantLib::Calendar &pricingCalendar=QuantLib::Calendar(), bool includeEndDate=true, bool excludeStartDate=true)

Inspectors
const QuantLib::Date &	pricingDate () const

bool	useFutureExpiryDate () const

QuantLib::Natural	futureMonthOffset () const

QuantLib::Real	periodQuantity () const override

QuantLib::Natural	dailyExpiryOffset () const

CommodityCashFlow interface
const std::vector< std::pair< QuantLib::Date, ext::shared_ptr< CommodityIndex > > > &	indices () const override
	Return a map of pricing date and corresponding commodity index. More...

const ext::shared_ptr< CommodityIndex > &	spotIndex () const

const std::set< QuantLib::Date > &	spotAveragingPricingDates () const

bool	isAveragingFrontMonthCashflow (const QuantLib::Date &asof) const

QuantLib::Date	lastPricingDate () const override

QuantLib::Real	fixing () const override

Event interface
QuantLib::Date	date () const override

CashFlow interface
QuantLib::Real	amount () const override

Public Member Functions inherited from CommodityCashFlow
	CommodityCashFlow (QuantLib::Real quantity, QuantLib::Real spread, QuantLib::Real gearing, bool useFuturePrice, const ext::shared_ptr< CommodityIndex > &index, const ext::shared_ptr< FxIndex > &fxIndex)

QuantLib::Real	quantity () const

QuantLib::Real	spread () const

QuantLib::Real	gearing () const

bool	useFuturePrice () const

ext::shared_ptr< CommodityIndex >	index () const

ext::shared_ptr< FxIndex >	fxIndex () const

virtual const std::vector< std::pair< QuantLib::Date, ext::shared_ptr< CommodityIndex > > > &	indices () const =0
	Return a map of pricing date and corresponding commodity index. More...

virtual QuantLib::Date	lastPricingDate () const =0

virtual QuantLib::Real	periodQuantity () const =0

virtual QuantLib::Real	fixing () const =0

void	accept (QuantLib::AcyclicVisitor &v) override

Visitability
QuantLib::Date	pricingDate_

QuantLib::Date	paymentDate_

bool	useFutureExpiryDate_

QuantLib::Natural	futureMonthOffset_

QuantLib::Real	periodQuantity_

QuantLib::Natural	dailyExpiryOffset_

std::vector< std::pair< QuantLib::Date, ext::shared_ptr< CommodityIndex > > >	indices_

bool	isAveraging_

std::set< QuantLib::Date >	spotAveragingPricingDates_

ext::shared_ptr< CommodityIndex >	spotIndex_

QuantLib::Real	price_

void	accept (QuantLib::AcyclicVisitor &v) override

void	setPeriodQuantity (QuantLib::Real periodQuantity)
	Allow the full calculation period quantity to be updated. More...

void	performCalculations () const override

void	init (const ext::shared_ptr< FutureExpiryCalculator > &calc, const QuantLib::Date &contractDate=QuantLib::Date(), const PaymentTiming paymentTiming=PaymentTiming::InArrears, const QuantLib::Date &startDate=QuantLib::Date(), const QuantLib::Date &endDate=QuantLib::Date(), const QuantLib::Natural paymentLag=0, const QuantLib::BusinessDayConvention paymentConvention=QuantLib::Unadjusted, const QuantLib::Calendar &paymentCalendar=QuantLib::NullCalendar(), const QuantLib::Calendar &pricingCalendar=QuantLib::Calendar(), bool includeEndDate=true, bool excludeStartDate=true)
	Shared initialisation. More...

Additional Inherited Members
Protected Attributes inherited from CommodityCashFlow
QuantLib::Real	quantity_

QuantLib::Real	spread_

QuantLib::Real	gearing_

bool	useFuturePrice_

ext::shared_ptr< CommodityIndex >	index_

ext::shared_ptr< FxIndex >	fxIndex_

QuantLib::Real	amount_

Detailed Description

Cash flow dependent on a single commodity spot price or futures settlement price on a given pricing date.

Definition at line 37 of file commodityindexedcashflow.hpp.

Member Enumeration Documentation

◆ PaymentTiming

enum class PaymentTiming

strong

Enumerator
InAdvance
InArrears
RelativeToExpiry

Definition at line 40 of file commodityindexedcashflow.hpp.

40{ InAdvance, InArrears, RelativeToExpiry };

QuantExt::CommodityIndexedCashFlow::PaymentTiming::InArrears

@ InArrears

QuantExt::CommodityIndexedCashFlow::PaymentTiming::InAdvance

@ InAdvance

QuantExt::CommodityIndexedCashFlow::PaymentTiming::RelativeToExpiry

@ RelativeToExpiry

Constructor & Destructor Documentation

◆ CommodityIndexedCashFlow() [1/2]

CommodityIndexedCashFlow	(	QuantLib::Real	quantity,
		const QuantLib::Date &	pricingDate,
		const QuantLib::Date &	paymentDate,
		const ext::shared_ptr< CommodityIndex > &	index,
		QuantLib::Real	spread = `0.0`,
		QuantLib::Real	gearing = `1.0`,
		bool	useFuturePrice = `false`,
		const Date &	contractDate = `Date()`,
		const ext::shared_ptr< FutureExpiryCalculator > &	calc = `nullptr`,
		QuantLib::Natural	dailyExpiryOffset = `QuantLib::Null< QuantLib::Natural >()`,
		const ext::shared_ptr< FxIndex > &	fxIndex = `nullptr`
	)

Constructor taking an explicit pricingDate and paymentDate.

◆ CommodityIndexedCashFlow() [2/2]

CommodityIndexedCashFlow	(	QuantLib::Real	quantity,
		const QuantLib::Date &	startDate,
		const QuantLib::Date &	endDate,
		const ext::shared_ptr< CommodityIndex > &	index,
		QuantLib::Natural	paymentLag,
		const QuantLib::Calendar &	paymentCalendar,
		QuantLib::BusinessDayConvention	paymentConvention,
		QuantLib::Natural	pricingLag,
		const QuantLib::Calendar &	pricingLagCalendar,
		QuantLib::Real	spread = `0.0`,
		QuantLib::Real	gearing = `1.0`,
		PaymentTiming	paymentTiming = `PaymentTiming::InArrears`,
		bool	isInArrears = `true`,
		bool	useFuturePrice = `false`,
		bool	useFutureExpiryDate = `true`,
		QuantLib::Natural	futureMonthOffset = `0`,
		const ext::shared_ptr< FutureExpiryCalculator > &	calc = `nullptr`,
		const QuantLib::Date &	paymentDateOverride = `Date()`,
		const QuantLib::Date &	pricingDateOverride = `Date()`,
		QuantLib::Natural	dailyExpiryOffset = `QuantLib::Null< QuantLib::Natural >()`,
		const ext::shared_ptr< FxIndex > &	fxIndex = `nullptr`,
		const bool	spotAveragingFrontCoupon = `false`,
		const QuantLib::Calendar &	pricingCalendar = `QuantLib::Calendar()`,
		bool	includeEndDate = `true`,
		bool	excludeStartDate = `true`
	)

Constructor taking a period startDate, endDate and some conventions. The pricing date and payment date are derived from the start date and end date using the conventions.

Member Function Documentation

◆ pricingDate()

const QuantLib::Date & pricingDate ( ) const

Definition at line 75 of file commodityindexedcashflow.hpp.

75{ return pricingDate_; }

QuantExt::CommodityIndexedCashFlow::pricingDate_

QuantLib::Date pricingDate_

Definition: commodityindexedcashflow.hpp:120

Here is the caller graph for this function:

◆ useFutureExpiryDate()

bool useFutureExpiryDate ( ) const

Definition at line 76 of file commodityindexedcashflow.hpp.

76{ return useFutureExpiryDate_; }

QuantExt::CommodityIndexedCashFlow::useFutureExpiryDate_

bool useFutureExpiryDate_

Definition: commodityindexedcashflow.hpp:122

◆ futureMonthOffset()

QuantLib::Natural futureMonthOffset ( ) const

Definition at line 77 of file commodityindexedcashflow.hpp.

77{ return futureMonthOffset_; }

QuantExt::CommodityIndexedCashFlow::futureMonthOffset_

QuantLib::Natural futureMonthOffset_

Definition: commodityindexedcashflow.hpp:123

◆ periodQuantity()

QuantLib::Real periodQuantity ( ) const

overridevirtual

Implements CommodityCashFlow.

Definition at line 78 of file commodityindexedcashflow.hpp.

78{ return periodQuantity_; }

QuantExt::CommodityIndexedCashFlow::periodQuantity_

QuantLib::Real periodQuantity_

Definition: commodityindexedcashflow.hpp:124

◆ dailyExpiryOffset()

QuantLib::Natural dailyExpiryOffset ( ) const

Definition at line 79 of file commodityindexedcashflow.hpp.

79{ return dailyExpiryOffset_; }

QuantExt::CommodityIndexedCashFlow::dailyExpiryOffset_

QuantLib::Natural dailyExpiryOffset_

Definition: commodityindexedcashflow.hpp:125

◆ indices()

const std::vector< std::pair< QuantLib::Date, ext::shared_ptr< CommodityIndex > > > & indices ( ) const

overridevirtual

Return a map of pricing date and corresponding commodity index.

Implements CommodityCashFlow.

Definition at line 84 of file commodityindexedcashflow.hpp.

84{ return indices_; }

QuantExt::CommodityIndexedCashFlow::indices_

std::vector< std::pair< QuantLib::Date, ext::shared_ptr< CommodityIndex > > > indices_

Definition: commodityindexedcashflow.hpp:126

◆ spotIndex()

const ext::shared_ptr< CommodityIndex > & spotIndex ( ) const

Definition at line 87 of file commodityindexedcashflow.hpp.

87{ return spotIndex_;}

QuantExt::CommodityIndexedCashFlow::spotIndex_

ext::shared_ptr< CommodityIndex > spotIndex_

Definition: commodityindexedcashflow.hpp:131

◆ spotAveragingPricingDates()

const std::set< QuantLib::Date > & spotAveragingPricingDates ( ) const

Definition at line 89 of file commodityindexedcashflow.hpp.

89{ return spotAveragingPricingDates_;}

QuantExt::CommodityIndexedCashFlow::spotAveragingPricingDates_

std::set< QuantLib::Date > spotAveragingPricingDates_

Definition: commodityindexedcashflow.hpp:130

◆ isAveragingFrontMonthCashflow()

bool isAveragingFrontMonthCashflow ( const QuantLib::Date & asof ) const

Definition at line 110 of file commodityindexedcashflow.cpp.

                                                                                           {
    return (isAveraging_ && useFuturePrice_ && !spotAveragingPricingDates_.empty() &&
            *spotAveragingPricingDates_.begin() <= asof && spotIndex_ != nullptr);
}

◆ lastPricingDate()

QuantLib::Date lastPricingDate ( ) const

overridevirtual

Implements CommodityCashFlow.

Definition at line 94 of file commodityindexedcashflow.hpp.

94{ return pricingDate(); }

QuantExt::CommodityIndexedCashFlow::pricingDate

const QuantLib::Date & pricingDate() const

Definition: commodityindexedcashflow.hpp:75

Here is the call graph for this function:

◆ fixing()

Real fixing ( ) const

overridevirtual

Implements CommodityCashFlow.

Definition at line 105 of file commodityindexedcashflow.cpp.

                                            {
    calculate();
    return price_;
}

◆ date()

QuantLib::Date date ( ) const

override

Definition at line 101 of file commodityindexedcashflow.hpp.

101{ return paymentDate_; }

QuantExt::CommodityIndexedCashFlow::paymentDate_

QuantLib::Date paymentDate_

Definition: commodityindexedcashflow.hpp:121

◆ amount()

Real amount ( ) const

override

Definition at line 100 of file commodityindexedcashflow.cpp.

                                            {
    calculate();
    return amount_;
}

◆ accept()

void accept ( QuantLib::AcyclicVisitor & v )

override

Definition at line 115 of file commodityindexedcashflow.cpp.

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

◆ setPeriodQuantity()

void setPeriodQuantity ( QuantLib::Real periodQuantity )

Allow the full calculation period quantity to be updated.

Definition at line 122 of file commodityindexedcashflow.cpp.

122{ periodQuantity_ = periodQuantity; }

QuantExt::CommodityIndexedCashFlow::periodQuantity

QuantLib::Real periodQuantity() const override

Definition: commodityindexedcashflow.hpp:78

◆ performCalculations()

void performCalculations ( ) const

overrideprivate

Definition at line 80 of file commodityindexedcashflow.cpp.

                                                         {
    Date today = Settings::instance().evaluationDate();
    price_ = 0.0;
    if (isAveragingFrontMonthCashflow(today)) {
        for (const auto& pd : spotAveragingPricingDates_) {
            double fxRate = (fxIndex_) ? this->fxIndex()->fixing(pricingDate_) : 1.0;
            if (pd <= today) {
                price_ += fxRate * spotIndex_->fixing(pd);
            } else {
                price_ += fxRate * index_->fixing(pricingDate_);
            }
        }  
        price_ /= static_cast<double>(spotAveragingPricingDates_.size());
    } else {
        double fxRate = (fxIndex_) ? this->fxIndex()->fixing(pricingDate_) : 1.0;
        price_ = fxRate * index_->fixing(pricingDate_);
    }
    amount_ = periodQuantity_ * gearing_ * (price_ + spread_);
}

◆ init()

void init	(	const ext::shared_ptr< FutureExpiryCalculator > &	calc,
		const QuantLib::Date &	contractDate = `QuantLib::Date()`,
		const PaymentTiming	paymentTiming = `PaymentTiming::InArrears`,
		const QuantLib::Date &	startDate = `QuantLib::Date()`,
		const QuantLib::Date &	endDate = `QuantLib::Date()`,
		const QuantLib::Natural	paymentLag = `0`,
		const QuantLib::BusinessDayConvention	paymentConvention = `QuantLib::Unadjusted`,
		const QuantLib::Calendar &	paymentCalendar = `QuantLib::NullCalendar()`,
		const QuantLib::Calendar &	pricingCalendar = `QuantLib::Calendar()`,
		bool	includeEndDate = `true`,
		bool	excludeStartDate = `true`
	)

private

Shared initialisation.

Definition at line 124 of file commodityindexedcashflow.cpp.

                                                                                {
 
    pricingDate_ = index_->fixingCalendar().adjust(pricingDate_, Preceding);
 
    // If we are using the future settlement price as the reference price, then we need to create the
    // relevant "future index" here and update the cashflow's index with it.
    Date expiry;
    if (useFuturePrice_) {
        QL_REQUIRE(calc, "CommodityIndexedCashFlow needs a valid future expiry calculator when using "
                             << "the future settlement price as reference price");
        expiry = calc->expiryDate(contractDate, futureMonthOffset_);
        if (dailyExpiryOffset_ != Null<Natural>()) {
            expiry = index_->fixingCalendar().advance(expiry, dailyExpiryOffset_ * Days);
        }
        index_ = index_->clone(expiry);
        isAveraging_ = isAveraging_ && startDate != Date() && endDate != Date();
        if (isAveraging_) {
            // If pricing calendar is not set, use the index fixing calendar
            Calendar cal = pricingCalendar;
            if (pricingCalendar == Calendar()) {
                cal = index_->fixingCalendar();
            }
 
            // Create Spot Index
            spotIndex_ = ext::make_shared<CommoditySpotIndex>(index_->underlyingName(), cal,
                                                              index_->priceCurve());
            if (spotIndex_) {
                registerWith(spotIndex_);
                spotAveragingPricingDates_ =
                    pricingDates(startDate, endDate, cal, excludeStartDate, includeEndDate);
                for (const auto& d : spotAveragingPricingDates_) {
                    indices_.push_back({d, spotIndex_});
                }
            }
        }
    }
 
    // Derive the payment date if an explicit override has not been provided
    if (paymentDate_ == Date()) {
        if (paymentTiming == PaymentTiming::InAdvance) {
            QL_REQUIRE(startDate != Date(), "CommodityIndexedCashFlow: startDate is null, can not derive paymentDate.");
            paymentDate_ = startDate;
        } else if (paymentTiming == PaymentTiming::InArrears) {
            QL_REQUIRE(endDate != Date(), "CommodityIndexedCashFlow: endDate is null, can not derive paymentDate.");
            paymentDate_ = endDate;
        } else if (paymentTiming == PaymentTiming::RelativeToExpiry) {
            QL_REQUIRE(
                expiry != Date(),
                "CommodityIndexedCashFlow: payment relative to expiry date only possibly when future price is used.");
            paymentDate_ = expiry;
        }
        paymentDate_ = paymentCalendar.advance(paymentDate_, paymentLag, Days, paymentConvention);
    }
 
    // the pricing date has to lie on or before the payment date
    pricingDate_ = index_->fixingCalendar().adjust(std::min(paymentDate_, pricingDate_), Preceding);
    
    indices_.push_back({pricingDate_, index_});
 
    registerWith(index_);
}

Here is the call graph for this function:

Member Data Documentation

◆ pricingDate_

QuantLib::Date pricingDate_

private

Definition at line 120 of file commodityindexedcashflow.hpp.

◆ paymentDate_

QuantLib::Date paymentDate_

private

Definition at line 121 of file commodityindexedcashflow.hpp.

◆ useFutureExpiryDate_

bool useFutureExpiryDate_

private

Definition at line 122 of file commodityindexedcashflow.hpp.

◆ futureMonthOffset_

QuantLib::Natural futureMonthOffset_

private

Definition at line 123 of file commodityindexedcashflow.hpp.

◆ periodQuantity_

QuantLib::Real periodQuantity_

private

Definition at line 124 of file commodityindexedcashflow.hpp.

◆ dailyExpiryOffset_

QuantLib::Natural dailyExpiryOffset_

private

Definition at line 125 of file commodityindexedcashflow.hpp.

◆ indices_

std::vector<std::pair<QuantLib::Date, ext::shared_ptr<CommodityIndex> > > indices_

private

Definition at line 126 of file commodityindexedcashflow.hpp.

◆ isAveraging_

bool isAveraging_

private

Definition at line 129 of file commodityindexedcashflow.hpp.

◆ spotAveragingPricingDates_

std::set<QuantLib::Date> spotAveragingPricingDates_

private

Definition at line 130 of file commodityindexedcashflow.hpp.

◆ spotIndex_

ext::shared_ptr<CommodityIndex> spotIndex_

private

Definition at line 131 of file commodityindexedcashflow.hpp.

◆ price_

QuantLib::Real price_

mutableprivate

Definition at line 132 of file commodityindexedcashflow.hpp.

Public Types

Public Member Functions

Visitability

Additional Inherited Members

Detailed Description

Member Enumeration Documentation

◆ PaymentTiming

Constructor & Destructor Documentation

◆ CommodityIndexedCashFlow() [1/2]

◆ CommodityIndexedCashFlow() [2/2]

Member Function Documentation

◆ pricingDate()

◆ useFutureExpiryDate()

◆ futureMonthOffset()

◆ periodQuantity()

◆ dailyExpiryOffset()

◆ indices()

◆ spotIndex()

◆ spotAveragingPricingDates()

◆ isAveragingFrontMonthCashflow()

◆ lastPricingDate()

◆ fixing()

◆ date()

◆ amount()

◆ accept()

◆ setPeriodQuantity()

◆ performCalculations()

◆ init()

Member Data Documentation

◆ pricingDate_

◆ paymentDate_

◆ useFutureExpiryDate_

◆ futureMonthOffset_

◆ periodQuantity_

◆ dailyExpiryOffset_

◆ indices_

◆ isAveraging_

◆ spotAveragingPricingDates_

◆ spotIndex_

◆ price_