CommodityIndexedAverageCashFlow Class Reference

#include <qle/cashflows/commodityindexedaveragecashflow.hpp>

Inheritance diagram for CommodityIndexedAverageCashFlow:

Collaboration diagram for CommodityIndexedAverageCashFlow:

Public Types
enum class	PaymentTiming { InAdvance , InArrears }

Public Member Functions
	CommodityIndexedAverageCashFlow (QuantLib::Real quantity, const QuantLib::Date &startDate, const QuantLib::Date &endDate, const QuantLib::Date &paymentDate, const ext::shared_ptr< CommodityIndex > &index, const QuantLib::Calendar &pricingCalendar=QuantLib::Calendar(), QuantLib::Real spread=0.0, QuantLib::Real gearing=1.0, bool useFuturePrice=false, QuantLib::Natural deliveryDateRoll=0, QuantLib::Natural futureMonthOffset=0, const ext::shared_ptr< FutureExpiryCalculator > &calc=nullptr, bool includeEndDate=true, bool excludeStartDate=true, bool useBusinessDays=true, CommodityQuantityFrequency quantityFrequency=CommodityQuantityFrequency::PerCalculationPeriod, QuantLib::Natural hoursPerDay=QuantLib::Null< QuantLib::Natural >(), QuantLib::Natural dailyExpiryOffset=QuantLib::Null< QuantLib::Natural >(), bool unrealisedQuantity=false, const boost::optional< std::pair< QuantLib::Calendar, QuantLib::Real > > &offPeakPowerData=boost::none, const ext::shared_ptr< FxIndex > &fxIndex=nullptr)
	Constructor taking an explicit paymentDate. More...
	CommodityIndexedAverageCashFlow (QuantLib::Real quantity, const QuantLib::Date &startDate, const QuantLib::Date &endDate, QuantLib::Natural paymentLag, QuantLib::Calendar paymentCalendar, QuantLib::BusinessDayConvention paymentConvention, const ext::shared_ptr< CommodityIndex > &index, const QuantLib::Calendar &pricingCalendar=QuantLib::Calendar(), QuantLib::Real spread=0.0, QuantLib::Real gearing=1.0, PaymentTiming paymentTiming=PaymentTiming::InArrears, bool useFuturePrice=false, QuantLib::Natural deliveryDateRoll=0, QuantLib::Natural futureMonthOffset=0, const ext::shared_ptr< FutureExpiryCalculator > &calc=nullptr, bool includeEndDate=true, bool excludeStartDate=true, const QuantLib::Date &paymentDateOverride=Date(), bool useBusinessDays=true, CommodityQuantityFrequency quantityFrequency=CommodityQuantityFrequency::PerCalculationPeriod, QuantLib::Natural hoursPerDay=QuantLib::Null< QuantLib::Natural >(), QuantLib::Natural dailyExpiryOffset=QuantLib::Null< QuantLib::Natural >(), bool unrealisedQuantity=false, const boost::optional< std::pair< QuantLib::Calendar, QuantLib::Real > > &offPeakPowerData=boost::none, const ext::shared_ptr< FxIndex > &fxIndex=nullptr)
	Constructor that deduces payment date from endDate using payment conventions. More...
Inspectors
const QuantLib::Date &	startDate () const
const QuantLib::Date &	endDate () const
ext::shared_ptr< CommodityIndex >	index () const
QuantLib::Natural	deliveryDateRoll () const
QuantLib::Natural	futureMonthOffset () const
bool	useBusinessDays () const
CommodityQuantityFrequency	quantityFrequency () const
QuantLib::Natural	hoursPerDay () const
QuantLib::Natural	dailyExpiryOffset () const
bool	unrealisedQuantity () const
const boost::optional< std::pair< QuantLib::Calendar, QuantLib::Real > > &	offPeakPowerData () const
const std::vector< std::pair< QuantLib::Date, ext::shared_ptr< CommodityIndex > > > &	indices () const override
QuantLib::Real	periodQuantity () const override
Event interface
QuantLib::Date	date () const override
CashFlow interface
QuantLib::Real	amount () const override
Visitability
void	accept (QuantLib::AcyclicVisitor &v) 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

CommodityCashFlow interface
QuantLib::Date	startDate_
QuantLib::Date	endDate_
QuantLib::Date	paymentDate_
QuantLib::Calendar	pricingCalendar_
QuantLib::Natural	deliveryDateRoll_
QuantLib::Natural	futureMonthOffset_
bool	includeEndDate_
bool	excludeStartDate_
std::vector< std::pair< QuantLib::Date, ext::shared_ptr< CommodityIndex > > >	indices_
bool	useBusinessDays_
CommodityQuantityFrequency	quantityFrequency_
QuantLib::Natural	hoursPerDay_
QuantLib::Natural	dailyExpiryOffset_
bool	unrealisedQuantity_
QuantLib::Real	periodQuantity_
boost::optional< std::pair< QuantLib::Calendar, QuantLib::Real > >	offPeakPowerData_
QuantLib::Real	averagePrice_
std::map< QuantLib::Date, QuantLib::Real >	weights_
QuantLib::Date	lastPricingDate () const override
QuantLib::Real	fixing () const override
void	performCalculations () const override
void	init (const ext::shared_ptr< FutureExpiryCalculator > &calc)
	Shared initialisation. More...
void	updateQuantity ()
	Set the period quantity based on the quantity and quantity frequency parameter. 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 the average of commodity spot prices or futures settlement prices over a period.

The cash flow takes a start date and an end date. The set of valid pricing dates is determined from and including the start date to but excluding the end date. The cash flow amount is then the arithmetic average of the commodity spot prices or next commodity future settlement prices on each valid pricing date times the quantity. The next commodity future is determined relative to each pricing date so the settlement prices for multiple commodity contracts may be involved in the averaging.

Definition at line 46 of file commodityindexedaveragecashflow.hpp.

Member Enumeration Documentation

PaymentTiming

enum class PaymentTiming

strong

Enumerator
InAdvance
InArrears

Definition at line 49 of file commodityindexedaveragecashflow.hpp.

{ InAdvance, InArrears };

Constructor & Destructor Documentation

CommodityIndexedAverageCashFlow() [1/2]

CommodityIndexedAverageCashFlow	(	QuantLib::Real	quantity,
		const QuantLib::Date &	startDate,
		const QuantLib::Date &	endDate,
		const QuantLib::Date &	paymentDate,
		const ext::shared_ptr< CommodityIndex > &	index,
		const QuantLib::Calendar &	pricingCalendar = QuantLib::Calendar(),
		QuantLib::Real	spread = 0.0,
		QuantLib::Real	gearing = 1.0,
		bool	useFuturePrice = false,
		QuantLib::Natural	deliveryDateRoll = 0,
		QuantLib::Natural	futureMonthOffset = 0,
		const ext::shared_ptr< FutureExpiryCalculator > &	calc = nullptr,
		bool	includeEndDate = true,
		bool	excludeStartDate = true,
		bool	useBusinessDays = true,
		CommodityQuantityFrequency	quantityFrequency = CommodityQuantityFrequency::PerCalculationPeriod,
		QuantLib::Natural	hoursPerDay = QuantLib::Null< QuantLib::Natural >(),
		QuantLib::Natural	dailyExpiryOffset = QuantLib::Null< QuantLib::Natural >(),
		bool	unrealisedQuantity = false,
		const boost::optional< std::pair< QuantLib::Calendar, QuantLib::Real > > &	offPeakPowerData = boost::none,
		const ext::shared_ptr< FxIndex > &	fxIndex = nullptr
	)

Constructor taking an explicit paymentDate.

CommodityIndexedAverageCashFlow() [2/2]

CommodityIndexedAverageCashFlow	(	QuantLib::Real	quantity,
		const QuantLib::Date &	startDate,
		const QuantLib::Date &	endDate,
		QuantLib::Natural	paymentLag,
		QuantLib::Calendar	paymentCalendar,
		QuantLib::BusinessDayConvention	paymentConvention,
		const ext::shared_ptr< CommodityIndex > &	index,
		const QuantLib::Calendar &	pricingCalendar = QuantLib::Calendar(),
		QuantLib::Real	spread = 0.0,
		QuantLib::Real	gearing = 1.0,
		PaymentTiming	paymentTiming = PaymentTiming::InArrears,
		bool	useFuturePrice = false,
		QuantLib::Natural	deliveryDateRoll = 0,
		QuantLib::Natural	futureMonthOffset = 0,
		const ext::shared_ptr< FutureExpiryCalculator > &	calc = nullptr,
		bool	includeEndDate = true,
		bool	excludeStartDate = true,
		const QuantLib::Date &	paymentDateOverride = Date(),
		bool	useBusinessDays = true,
		CommodityQuantityFrequency	quantityFrequency = CommodityQuantityFrequency::PerCalculationPeriod,
		QuantLib::Natural	hoursPerDay = QuantLib::Null< QuantLib::Natural >(),
		QuantLib::Natural	dailyExpiryOffset = QuantLib::Null< QuantLib::Natural >(),
		bool	unrealisedQuantity = false,
		const boost::optional< std::pair< QuantLib::Calendar, QuantLib::Real > > &	offPeakPowerData = boost::none,
		const ext::shared_ptr< FxIndex > &	fxIndex = nullptr
	)

Constructor that deduces payment date from endDate using payment conventions.

Member Function Documentation

startDate()

const QuantLib::Date & startDate

(

)

const

Definition at line 84 of file commodityindexedaveragecashflow.hpp.

{ return startDate_; }

endDate()

const QuantLib::Date & endDate

(

)

const

Definition at line 85 of file commodityindexedaveragecashflow.hpp.

{ return endDate_; }

index()

ext::shared_ptr< CommodityIndex > index

(

)

const

Definition at line 86 of file commodityindexedaveragecashflow.hpp.

{ return index_; }

deliveryDateRoll()

QuantLib::Natural deliveryDateRoll

(

)

const

Definition at line 87 of file commodityindexedaveragecashflow.hpp.

{ return deliveryDateRoll_; }

futureMonthOffset()

QuantLib::Natural futureMonthOffset

(

)

const

Definition at line 88 of file commodityindexedaveragecashflow.hpp.

{ return futureMonthOffset_; }

useBusinessDays()

bool useBusinessDays

(

)

const

Definition at line 89 of file commodityindexedaveragecashflow.hpp.

{ return useBusinessDays_; }

quantityFrequency()

CommodityQuantityFrequency quantityFrequency

(

)

const

Definition at line 90 of file commodityindexedaveragecashflow.hpp.

{ return quantityFrequency_; }

hoursPerDay()

QuantLib::Natural hoursPerDay

(

)

const

Definition at line 91 of file commodityindexedaveragecashflow.hpp.

{ return hoursPerDay_; }

dailyExpiryOffset()

QuantLib::Natural dailyExpiryOffset

(

)

const

Definition at line 92 of file commodityindexedaveragecashflow.hpp.

{ return dailyExpiryOffset_; }

unrealisedQuantity()

bool unrealisedQuantity

(

)

const

Definition at line 93 of file commodityindexedaveragecashflow.hpp.

{ return unrealisedQuantity_; }

offPeakPowerData()

const boost::optional< std::pair< QuantLib::Calendar, QuantLib::Real > > & offPeakPowerData

(

)

const

Definition at line 94 of file commodityindexedaveragecashflow.hpp.

                                                                                           {
        return offPeakPowerData_;
    }

indices()

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

overridevirtual

Return the index used to get the price for each pricing date in the period. The map keys are the pricing dates. For a given key date, the map value holds the commodity index used to give the price on that date. If the averaging does not reference future contract settlement prices, i.e. useFirstFuture() is false, the commodity index is simply the commodity spot index passed in the constructor. If the averaging references future contract settlement prices, i.e. useFirstFuture() is true, the commodity index is the commodity future contract index relevant for that pricing date.

Implements CommodityCashFlow.

Definition at line 105 of file commodityindexedaveragecashflow.hpp.

{ return indices_; }

periodQuantity()

QuantLib::Real periodQuantity ( ) const

overridevirtual

Quantity for the full calculation period i.e. the effective quantity after taking into account the quantity frequency setting.

Implements CommodityCashFlow.

Definition at line 110 of file commodityindexedaveragecashflow.hpp.

{ return periodQuantity_; }

date()

QuantLib::Date date ( ) const

override

Definition at line 115 of file commodityindexedaveragecashflow.hpp.

{ return paymentDate_; }

amount()

Real amount ( ) const

override

Definition at line 108 of file commodityindexedaveragecashflow.cpp.

                                                   {
    calculate();
    return amount_;
}

accept()

void accept ( QuantLib::AcyclicVisitor &  v )

override

Definition at line 118 of file commodityindexedaveragecashflow.cpp.

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

lastPricingDate()

QuantLib::Date lastPricingDate ( ) const

overridevirtual

Implements CommodityCashFlow.

Definition at line 131 of file commodityindexedaveragecashflow.hpp.

                                                  {
        if (indices_.empty()) {
            return Date();
        } else {
            return indices_.rbegin()->first;
        }
    }

fixing()

Real fixing ( ) const

overridevirtual

Implements CommodityCashFlow.

Definition at line 113 of file commodityindexedaveragecashflow.cpp.

                                                   {
    calculate();
    return averagePrice_;
}

performCalculations()

void performCalculations ( ) const

overrideprivate

Definition at line 84 of file commodityindexedaveragecashflow.cpp.

                                                                {
 
    // Calculate the average price
    averagePrice_ = 0.0;
    Real fxRate = 0.0;
    if (weights_.empty()) {
        for (const auto& kv : indices_) {
            fxRate = (fxIndex_)? this->fxIndex()->fixing(kv.first):1.0;
            averagePrice_ += fxRate * kv.second->fixing(kv.first);
        }
        averagePrice_ /= indices_.size();
    } else {
        // weights_ will be populated when offPeakPowerData_ is provided.
        for (const auto& kv : indices_) {
            fxRate = (fxIndex_)? this->fxIndex()->fixing(kv.first):1.0;
            averagePrice_ += fxRate * kv.second->fixing(kv.first) * weights_.at(kv.first);
        }
    }
 
    // Amount is just average price times quantity
    // In case of Foreign currency settlement, the spread must be expressed in Foreign currency units
    amount_ = periodQuantity_ * (gearing_ * averagePrice_ + spread_);
}

init()

void init ( const ext::shared_ptr< FutureExpiryCalculator > &  calc )

private

Shared initialisation.

Definition at line 125 of file commodityindexedaveragecashflow.cpp.

                                                                                            {
 
    // If pricing calendar is not set, use the index fixing calendar
    if (pricingCalendar_ == Calendar()) {
        pricingCalendar_ = index_->fixingCalendar();
    }
 
    // If we are going to reference a future settlement price, check that we have a valid expiry calculator
    if (useFuturePrice_) {
        QL_REQUIRE(calc, "CommodityIndexedCashFlow needs a valid future expiry calculator when using first future");
    }
 
    // Store the relevant index for each pricing date taking account of the flags and the pricing calendar
    auto pds = pricingDates(startDate_, endDate_, pricingCalendar_,
        excludeStartDate_, includeEndDate_, useBusinessDays_);
 
    QL_REQUIRE(!pds.empty(), "CommodityIndexedAverageCashFlow: found no pricing dates between "
        << io::iso_date(startDate_) << " and " << io::iso_date(endDate_) << ".");
 
    // Populate the indices_ map with the correct values.
    if (!useFuturePrice_) {
 
        // If not using future prices, just observe spot on every pricing date.
        for (const Date& pd : pds) {
            indices_.push_back({pd,index_});
        }
 
    } else {
 
        // If using future prices, first fill indices assuming delivery date roll is 0.
        for (const Date& pd : pds) {
            auto expiry = calc->nextExpiry(true, pd, futureMonthOffset_);
 
            // If given an offset for each expiry, apply it now.
            if (dailyExpiryOffset_ != Null<Natural>()) {
                expiry = index_->fixingCalendar().advance(expiry, dailyExpiryOffset_ * Days);
            }
 
            indices_.push_back({pd, index_->clone(expiry)});
        }
 
        // Update indices_ where necessary if delivery date roll is greater than 0.
        if (deliveryDateRoll_ > 0) {
 
            Date expiry;
            Date prevExpiry;
            Date rollDate;
 
            for (auto& kv : indices_) {
 
                // If expiry is different from previous expiry, update the roll date.
                expiry = kv.second->expiryDate();
                if (expiry != prevExpiry) {
                    rollDate = pricingCalendar_.advance(expiry,
                        -static_cast<Integer>(deliveryDateRoll_), Days);
                }
                prevExpiry = expiry;
 
                // If the pricing date is after the roll date, we use the next expiry.
                if (kv.first > rollDate) {
                    expiry = calc->nextExpiry(false, expiry);
                    kv.second = index_->clone(expiry);
                }
 
            }
        }
    }
 
    // Register with each of the indices.
    for (auto& kv : indices_) {
        registerWith(kv.second);
    }
 
    // If offPeakPowerData_ is provided, populate weights_
    if (offPeakPowerData_) {
        Calendar peakCalendar = offPeakPowerData_->first;
        Real offPeakHours = offPeakPowerData_->second;
        Real total = 0;
        for (const auto& kv : indices_) {
            if (peakCalendar.isHoliday(kv.first))
                total += weights_[kv.first] = 24;
            else
                total += weights_[kv.first] = offPeakHours;
        }
        for (auto& kv : weights_)
            kv.second /= total;
    }
 
    // Must be called here after indices_ has been populated.
    updateQuantity();
 
}

Here is the call graph for this function:

updateQuantity()

void updateQuantity ( )

private

Set the period quantity based on the quantity and quantity frequency parameter.

Definition at line 218 of file commodityindexedaveragecashflow.cpp.

                                                     {
 
    using CQF = CommodityQuantityFrequency;
    switch (quantityFrequency_)
    {
    case CQF::PerCalculationPeriod:
        periodQuantity_ = quantity_;
        if (unrealisedQuantity_) {
            Date today = Settings::instance().evaluationDate();
            if (startDate_ <= today && today < endDate_) {
                // In both cases, unrealised equal to 0 should probably be an error but leave quantity unaltered.
                if (offPeakPowerData_) {
                    QL_REQUIRE(!weights_.empty(), "Expected to have weights when we have off-peak power data.");
                    auto unrealised = accumulate(weights_.begin(), weights_.end(), 0.0,
                        [&today](Real sum, const pair<Date, Real>& p) {
                            return p.first > today ? sum + p.second : sum; });
                    if (unrealised > 0) {
                        periodQuantity_ /= unrealised;
                    }
                } else {
                    auto unrealised = count_if(indices_.begin(), indices_.end(),
                        [&today](const pair<Date, ext::shared_ptr<CommodityIndex>>& p) { return p.first > today; });
                    if (unrealised > 0) {
                        periodQuantity_ = periodQuantity_ * indices_.size() / unrealised;
                    }
                }
            }
        }
        break;
    case CQF::PerPricingDay:
        periodQuantity_ = quantity_ * indices_.size();
        break;
    case CQF::PerHour:
        if (offPeakPowerData_) {
            Calendar peakCalendar = offPeakPowerData_->first;
            Real offPeakHours = offPeakPowerData_->second;
            periodQuantity_ = 0.0;
            for (const auto& kv : indices_) {
                if (peakCalendar.isHoliday(kv.first))
                    periodQuantity_ += 24.0 * quantity_;
                else
                    periodQuantity_ += offPeakHours * quantity_;
            }
        } else {
            QL_REQUIRE(hoursPerDay_ != Null<Natural>(), "If a commodity quantity frequency of PerHour is used, " <<
                "a valid hoursPerDay value should be supplied.");
            periodQuantity_ = quantity_ * indices_.size() * hoursPerDay_;
        }
        break;
    case CQF::PerCalendarDay:
        // Rarely used but kept because it has already been documented and released.
        periodQuantity_ = quantity_ * ((endDate_ - startDate_ - 1.0) + (!excludeStartDate_ ? 1.0 : 0.0) +
            (includeEndDate_ ? 1.0 : 0.0));
        break;
    default:
        // Do nothing
        break;
    }
 
}

Here is the call graph for this function:

Member Data Documentation

startDate_

QuantLib::Date startDate_

private

Definition at line 145 of file commodityindexedaveragecashflow.hpp.

endDate_

QuantLib::Date endDate_

private

Definition at line 146 of file commodityindexedaveragecashflow.hpp.

paymentDate_

QuantLib::Date paymentDate_

private

Definition at line 147 of file commodityindexedaveragecashflow.hpp.

pricingCalendar_

QuantLib::Calendar pricingCalendar_

private

Definition at line 148 of file commodityindexedaveragecashflow.hpp.

deliveryDateRoll_

QuantLib::Natural deliveryDateRoll_

private

Definition at line 149 of file commodityindexedaveragecashflow.hpp.

futureMonthOffset_

QuantLib::Natural futureMonthOffset_

private

Definition at line 150 of file commodityindexedaveragecashflow.hpp.

includeEndDate_

bool includeEndDate_

private

Definition at line 151 of file commodityindexedaveragecashflow.hpp.

excludeStartDate_

bool excludeStartDate_

private

Definition at line 152 of file commodityindexedaveragecashflow.hpp.

indices_

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

private

Definition at line 153 of file commodityindexedaveragecashflow.hpp.

useBusinessDays_

bool useBusinessDays_

private

Definition at line 154 of file commodityindexedaveragecashflow.hpp.

quantityFrequency_

CommodityQuantityFrequency quantityFrequency_

private

Definition at line 155 of file commodityindexedaveragecashflow.hpp.

hoursPerDay_

QuantLib::Natural hoursPerDay_

private

Definition at line 156 of file commodityindexedaveragecashflow.hpp.

dailyExpiryOffset_

QuantLib::Natural dailyExpiryOffset_

private

Definition at line 157 of file commodityindexedaveragecashflow.hpp.

unrealisedQuantity_

bool unrealisedQuantity_

private

Definition at line 158 of file commodityindexedaveragecashflow.hpp.

periodQuantity_

QuantLib::Real periodQuantity_

private

Definition at line 159 of file commodityindexedaveragecashflow.hpp.

offPeakPowerData_

boost::optional<std::pair<QuantLib::Calendar, QuantLib::Real> > offPeakPowerData_

private

Definition at line 160 of file commodityindexedaveragecashflow.hpp.

averagePrice_

QuantLib::Real averagePrice_

mutableprivate

Definition at line 161 of file commodityindexedaveragecashflow.hpp.

weights_

std::map<QuantLib::Date, QuantLib::Real> weights_

private

Definition at line 164 of file commodityindexedaveragecashflow.hpp.