CommodityFloatingLegBuilder Class Reference

#include <ored/portfolio/commoditylegbuilder.hpp>

Inheritance diagram for CommodityFloatingLegBuilder:

Collaboration diagram for CommodityFloatingLegBuilder:

Public Member Functions
	CommodityFloatingLegBuilder ()
QuantLib::Leg	buildLeg (const ore::data::LegData &data, const QuantLib::ext::shared_ptr< ore::data::EngineFactory > &engineFactory, RequiredFixings &requiredFixings, const std::string &configuration, const QuantLib::Date &openEndDateReplacement=Null< Date >(), const bool useXbsCurves=false) const override
bool	allAveraging () const
	Inspect the allAveraging_ flag. More...
Public Member Functions inherited from LegBuilder
	LegBuilder (const string &legType)
virtual	~LegBuilder ()
virtual Leg	buildLeg (const LegData &data, const QuantLib::ext::shared_ptr< EngineFactory > &, RequiredFixings &requiredFixings, const string &configuration, const QuantLib::Date &openEndDateReplacement=Null< Date >(), const bool useXbsCurves=false) const =0
const string &	legType () const

Private Attributes
bool	allAveraging_

Detailed Description

Definition at line 44 of file commoditylegbuilder.hpp.

Constructor & Destructor Documentation

CommodityFloatingLegBuilder()

CommodityFloatingLegBuilder

(

)

Definition at line 46 of file commoditylegbuilder.hpp.

        : LegBuilder("CommodityFloating"), allAveraging_(false) {}

Member Function Documentation

buildLeg()

Leg buildLeg ( const ore::data::LegData &  data, const QuantLib::ext::shared_ptr< ore::data::EngineFactory > &  engineFactory, RequiredFixings &  requiredFixings, const std::string &  configuration, const QuantLib::Date &  openEndDateReplacement = Null<Date>(), const bool  useXbsCurves = false  ) const

override

Definition at line 411 of file commoditylegbuilder.cpp.

                                                                                                                     {
 
    // allAveraging_ flag should be reset to false before each build. If we do not do this, the allAveraging_
    // flag may have been set from building a different leg previously
    allAveraging_ = false;
 
    auto floatingLegData = QuantLib::ext::dynamic_pointer_cast<CommodityFloatingLegData>(data.concreteLegData());
    QL_REQUIRE(floatingLegData, "Wrong LegType: expected CommodityFloating but got " << data.legType());
 
    // Commodity name and its conventions.
    // Default weekends only calendar used to create the "index". Attempt to populate with sth sensible here.
    string commName = floatingLegData->name();
    Calendar commCal = WeekendsOnly();
    QuantLib::ext::shared_ptr<Conventions> conventions = InstrumentConventions::instance().conventions();
    QuantLib::ext::shared_ptr<CommodityFutureConvention> commFutureConv;
    boost::optional<pair<Calendar, Real>> offPeakPowerData;
    bool balanceOfTheMonth = false;
    if (conventions->has(commName)) {
        QuantLib::ext::shared_ptr<Convention> commConv = conventions->get(commName);
 
        // If commodity forward convention
        if (auto c = QuantLib::ext::dynamic_pointer_cast<CommodityForwardConvention>(commConv)) {
            if (c->advanceCalendar() != NullCalendar()) {
                commCal = c->advanceCalendar();
            }
        }
 
        // If commodity future convention
        commFutureConv = QuantLib::ext::dynamic_pointer_cast<CommodityFutureConvention>(commConv);
        if (commFutureConv) {
            balanceOfTheMonth = commFutureConv->balanceOfTheMonth();
            commCal = commFutureConv->calendar();
            if (const auto& oppid = commFutureConv->offPeakPowerIndexData()) {
                offPeakPowerData = make_pair(oppid->peakCalendar(), oppid->offPeakHours());
            }
        }
    }
 
    // Get price type i.e. is the commodity floating leg referencing the spot price or a future settlement price.
    CommodityPriceType priceType = floatingLegData->priceType();
 
    // If referencing a future settlement price, we will need a valid FutureExpiryCalculator below.
    QuantLib::ext::shared_ptr<FutureExpiryCalculator> feCalc;
    if (priceType == CommodityPriceType::FutureSettlement) {
 
        // We should have a valid commodity future convention in this case but check anyway
        QL_REQUIRE(commFutureConv, "Expected to have a commodity future convention for commodity " << commName);
 
        feCalc = QuantLib::ext::make_shared<ConventionsBasedFutureExpiry>(*commFutureConv);
 
        // If the future contract is averaging but the trade is not averaging, we can't price the trade
        // TODO: Should we just issue a warning here, switch the trade to averaging and price it?
        if (commFutureConv->isAveraging()) {
            QL_REQUIRE(floatingLegData->isAveraged(),
                       "The future, " << commName << ", is averaging but the leg is not.");
            allAveraging_ = true;
        }
    }
 
    // Construct the commodity index.
    Handle<PriceTermStructure> priceCurve = engineFactory->market()->commodityPriceCurve(commName, configuration);
    auto index = parseCommodityIndex(commName, false, priceCurve, NullCalendar(),
                                     priceType == CommodityPriceType::FutureSettlement);
 
    // Get the commodity floating leg schedule and quantities
    Schedule schedule = makeSchedule(data.schedule());
    vector<Real> quantities =
        buildScheduledVector(floatingLegData->quantities(), floatingLegData->quantityDates(), schedule);
 
    // Get spreads and gearings which may be empty
    vector<Real> spreads = buildScheduledVector(floatingLegData->spreads(), floatingLegData->spreadDates(), schedule);
    vector<Real> gearings =
        buildScheduledVector(floatingLegData->gearings(), floatingLegData->gearingDates(), schedule);
 
    // Get explicit pricing dates which in most cases should be empty
    vector<Date> pricingDates;
    if (!floatingLegData->pricingDates().empty()) {
        pricingDates = parseVectorOfValues<Date>(floatingLegData->pricingDates(), &parseDate);
    }
 
    // Some common variables needed in building the commodity floating leg
    PaymentLag paymentLag = parsePaymentLag(data.paymentLag());
    BusinessDayConvention paymentConvention =
        data.paymentConvention().empty() ? Following : parseBusinessDayConvention(data.paymentConvention());
    Calendar paymentCalendar =
        data.paymentCalendar().empty() ? schedule.calendar() : parseCalendar(data.paymentCalendar());
    Calendar pricingCalendar;
 
    // Override missing pricing calendar with calendar from convention
    if (floatingLegData->pricingCalendar().empty() && floatingLegData->isAveraged() && balanceOfTheMonth &&
        commFutureConv) {
        pricingCalendar = commFutureConv->balanceOfTheMonthPricingCalendar();
    } else if (floatingLegData->pricingCalendar().empty()) {
        pricingCalendar = commCal;
    } else {
        pricingCalendar = parseCalendar(floatingLegData->pricingCalendar());
    }
         
    // Get explicit payment dates which in most cases should be empty
    vector<Date> paymentDates;
 
    
    Schedule paymentSchedule = makeSchedule(data.paymentSchedule(), openEndDateReplacement);
   
    if (!paymentSchedule.empty()) {
        paymentDates = paymentSchedule.dates();
    } else if (!data.paymentDates().empty()) {
        BusinessDayConvention paymentDatesConvention =
            data.paymentConvention().empty() ? Unadjusted : parseBusinessDayConvention(data.paymentConvention());
        Calendar paymentDatesCalendar =
            data.paymentCalendar().empty() ? NullCalendar() : parseCalendar(data.paymentCalendar());
        paymentDates = parseVectorOfValues<Date>(data.paymentDates(), &parseDate);
        for (Size i = 0; i < paymentDates.size(); i++)
            paymentDates[i] = paymentDatesCalendar.adjust(paymentDates[i], paymentDatesConvention);
    }
 
    // May need to poulate hours per day
    auto hoursPerDay = floatingLegData->hoursPerDay();
    if ((floatingLegData->commodityQuantityFrequency() == CommodityQuantityFrequency::PerHour ||
         floatingLegData->commodityQuantityFrequency() == CommodityQuantityFrequency::PerHourAndCalendarDay) &&
        hoursPerDay == Null<Natural>()) {
        QL_REQUIRE(commFutureConv,
                   "Commodity floating leg commodity frequency set to PerHour / PerHourAndCalendarDay but"
                       << " no HoursPerDay provided in floating leg data and no commodity future convention for "
                       << commName);
        hoursPerDay = commFutureConv->hoursPerDay();
        QL_REQUIRE(commFutureConv,
                   "Commodity floating leg commodity frequency set to PerHour / PerHourAndCalendarDay but"
                       << " no HoursPerDay provided in floating leg data and commodity future convention for "
                       << commName << " does not provide it.");
    }
 
    // populate daylight saving begin / end
    std::string daylightSavingLocation;
    if (floatingLegData->commodityQuantityFrequency() == CommodityQuantityFrequency::PerHourAndCalendarDay) {
        QL_REQUIRE(
            commFutureConv,
            "Commodity floating leg commodity frequency set to PerHourAndCalendarDay, need commodity convention for "
                << commName);
        daylightSavingLocation = commFutureConv->savingsTime();
    }
    QuantLib::ext::shared_ptr<FxIndex> fxIndex;
    // Build the leg. Different ctor depending on whether cashflow is averaging or not.
    Leg leg;
 
    bool isCashFlowAveraged =
        floatingLegData->isAveraged() && !allAveraging_ && floatingLegData->lastNDays() == Null<Natural>();
 
    // If daily expiry offset is given, check that referenced future contract has a daily frequency.
    auto dailyExpOffset = floatingLegData->dailyExpiryOffset();
    if (dailyExpOffset != Null<Natural>() && dailyExpOffset > 0) {
        QL_REQUIRE(commFutureConv, "A positive DailyExpiryOffset has been provided but no commodity"
                                       << " future convention given for " << commName);
        QL_REQUIRE(commFutureConv->contractFrequency() == Daily,
                   "A positive DailyExpiryOffset has been"
                       << " provided but the commodity contract frequency is not Daily ("
                       << commFutureConv->contractFrequency() << ")");
    }
 
    if (!floatingLegData->fxIndex().empty()) { // build the fxIndex for daily average conversion
        auto underlyingCcy = priceCurve->currency().code();
        auto npvCurrency = data.currency();
        if (underlyingCcy != npvCurrency) // only need an FX Index if currencies differ
            fxIndex = buildFxIndex(floatingLegData->fxIndex(), npvCurrency, underlyingCcy, engineFactory->market(),
                                   engineFactory->configuration(MarketContext::pricing));
    }
 
    if (isCashFlowAveraged) {
        CommodityIndexedAverageCashFlow::PaymentTiming paymentTiming =
            CommodityIndexedAverageCashFlow::PaymentTiming::InArrears;
        if (floatingLegData->commodityPayRelativeTo() == CommodityPayRelativeTo::CalculationPeriodStartDate) {
            paymentTiming = CommodityIndexedAverageCashFlow::PaymentTiming::InAdvance;
        } else if (floatingLegData->commodityPayRelativeTo() == CommodityPayRelativeTo::CalculationPeriodEndDate) {
            paymentTiming = CommodityIndexedAverageCashFlow::PaymentTiming::InArrears;
        } else if (floatingLegData->commodityPayRelativeTo() == CommodityPayRelativeTo::FutureExpiryDate) {
            QL_FAIL("CommodityLegBuilder: CommodityPayRelativeTo 'FutureExpiryDate' not allowed for average cashflow.");
        } else {
            QL_FAIL("CommodityLegBuilder: CommodityPayRelativeTo " << floatingLegData->commodityPayRelativeTo()
                                                                   << " not handled. This is an internal error.");
        }
 
        leg = CommodityIndexedAverageLeg(schedule, index)
                  .withQuantities(quantities)
                  .withPaymentLag(boost::apply_visitor(PaymentLagInteger(), paymentLag))
                  .withPaymentCalendar(paymentCalendar)
                  .withPaymentConvention(paymentConvention)
                  .withPricingCalendar(pricingCalendar)
                  .withSpreads(spreads)
                  .withGearings(gearings)
                  .paymentTiming(paymentTiming)
                  .useFuturePrice(priceType == CommodityPriceType::FutureSettlement)
                  .withDeliveryDateRoll(floatingLegData->deliveryRollDays())
                  .withFutureMonthOffset(floatingLegData->futureMonthOffset())
                  .withFutureExpiryCalculator(feCalc)
                  .payAtMaturity(floatingLegData->commodityPayRelativeTo() ==
                      CommodityPayRelativeTo::TerminationDate)
                  .includeEndDate(floatingLegData->includePeriodEnd())
                  .excludeStartDate(floatingLegData->excludePeriodStart())
                  .withQuantityFrequency(floatingLegData->commodityQuantityFrequency())
                  .withPaymentDates(paymentDates)
                  .useBusinessDays(floatingLegData->useBusinessDays())
                  .withHoursPerDay(hoursPerDay)
                  .withDailyExpiryOffset(dailyExpOffset)
                  .unrealisedQuantity(floatingLegData->unrealisedQuantity())
                  .withOffPeakPowerData(offPeakPowerData)
                  .withFxIndex(fxIndex);
    } else {
        CommodityIndexedCashFlow::PaymentTiming paymentTiming = CommodityIndexedCashFlow::PaymentTiming::InArrears;
        if (floatingLegData->commodityPayRelativeTo() == CommodityPayRelativeTo::CalculationPeriodStartDate) {
            paymentTiming = CommodityIndexedCashFlow::PaymentTiming::InAdvance;
        } else if (floatingLegData->commodityPayRelativeTo() == CommodityPayRelativeTo::CalculationPeriodEndDate) {
            paymentTiming = CommodityIndexedCashFlow::PaymentTiming::InArrears;
        } else if (floatingLegData->commodityPayRelativeTo() == CommodityPayRelativeTo::FutureExpiryDate) {
            paymentTiming = CommodityIndexedCashFlow::PaymentTiming::RelativeToExpiry;
        } else {
            QL_FAIL("CommodityLegBuilder: CommodityPayRelativeTo " << floatingLegData->commodityPayRelativeTo()
                                                                   << " not handled. This is an internal error.");
        }
 
        leg = CommodityIndexedLeg(schedule, index)
                  .withQuantities(quantities)
                  .withPaymentLag(boost::apply_visitor(PaymentLagInteger(), paymentLag))
                  .withPaymentCalendar(paymentCalendar)
                  .withPaymentConvention(paymentConvention)
                  .withPricingLag(floatingLegData->pricingLag())
                  .withPricingLagCalendar(pricingCalendar)
                  .withSpreads(spreads)
                  .withGearings(gearings)
                  .paymentTiming(paymentTiming)
                  .inArrears(floatingLegData->isInArrears())
                  .useFuturePrice(priceType == CommodityPriceType::FutureSettlement)
                  .useFutureExpiryDate(floatingLegData->pricingDateRule() == CommodityPricingDateRule::FutureExpiryDate)
                  .withFutureMonthOffset(floatingLegData->futureMonthOffset())
                  .withFutureExpiryCalculator(feCalc)
                  .payAtMaturity(floatingLegData->commodityPayRelativeTo() == CommodityPayRelativeTo::TerminationDate)
                  .withPricingDates(pricingDates)
                  .withPaymentDates(paymentDates)
                  .withDailyExpiryOffset(dailyExpOffset)
                  .withFxIndex(fxIndex)
                  .withIsAveraging(floatingLegData->isAveraged() && balanceOfTheMonth)
                  .withPricingCalendar(pricingCalendar)
                  .includeEndDate(floatingLegData->includePeriodEnd())
                  .excludeStartDate(floatingLegData->excludePeriodStart());
 
        // Possibly update the leg's quantities.
        updateQuantities(leg, allAveraging_, floatingLegData->commodityQuantityFrequency(), schedule,
                         floatingLegData->excludePeriodStart(), floatingLegData->includePeriodEnd(), commFutureConv,
                         feCalc, hoursPerDay, floatingLegData->useBusinessDays(), daylightSavingLocation, commName,
                         floatingLegData->unrealisedQuantity(), offPeakPowerData);
 
        // If lastNDays is set, amend each cashflow in the leg to an averaging cashflow over the lastNDays.
        auto lastNDays = floatingLegData->lastNDays();
        if (lastNDays != Null<Natural>() && lastNDays > 1) {
            if (commFutureConv) {
                if (lastNDays > 31) {
                    WLOG("LastNDays (" << lastNDays << ") should not be greater than 31. " <<
                        "Proceed as if it is not set.");
                } else if (commFutureConv->isAveraging()) {
                    WLOG("Commodity future convention for " << commName << " is averaging so LastNDays (" <<
                        lastNDays << ") is ignored. Proceed as if it is not set.");
                } else {
                    DLOG("Amending cashflows to account for LastNDays (" << lastNDays << ").");
                    const auto& cal = commFutureConv->calendar();
                    for (auto& cf : leg) {
                        auto ccf = QuantLib::ext::dynamic_pointer_cast<CommodityIndexedCashFlow>(cf);
                        const Date& endDate = ccf->pricingDate();
                        Date startDate = cal.advance(endDate, -static_cast<Integer>(lastNDays) + 1, Days, Preceding);
                        TLOG("Creating cashflow averaging over period [" << io::iso_date(startDate) <<
                            "," << io::iso_date(endDate) << "]");
                        cf = QuantLib::ext::make_shared<CommodityIndexedAverageCashFlow>(ccf->periodQuantity(), startDate,
                            endDate, ccf->date(), ccf->index(), cal, ccf->spread(), ccf->gearing(),
                            ccf->useFuturePrice(), 0, 0, feCalc, true, false);
                    }
                }
            } else {
                WLOG("Need a commodity future convention for " << commName << " when LastNDays (" << lastNDays <<
                    ") is set and greater than 1. Proceed as if it is not set.");
            }
        }
    }
 
    if (fxIndex) {
        // fx daily indexing needed
        for (auto cf : leg) {
            auto cacf = QuantLib::ext::dynamic_pointer_cast<CommodityCashFlow>(cf);
            QL_REQUIRE(cacf, "Commodity Indexed averaged cashflow is required to compute daily converted average.");
            for (auto kv : cacf->indices()) {
                if (!fxIndex->fixingCalendar().isBusinessDay(
                        kv.first)) {
                    /* If fx index is not available for the commodity pricing day, this ensures to require the previous
                     * valid one which will be used in pricing from fxIndex()->fixing(...) */
                    Date adjustedFixingDate = fxIndex->fixingCalendar().adjust(kv.first, Preceding);
                    requiredFixings.addFixingDate(adjustedFixingDate, floatingLegData->fxIndex());
                } else
                    requiredFixings.addFixingDate(kv.first, floatingLegData->fxIndex());
            }
        }
    } else {
        // standard indexing approach
        applyIndexing(leg, data, engineFactory, requiredFixings, openEndDateReplacement, useXbsCurves);
    }
 
    addToRequiredFixings(leg, QuantLib::ext::make_shared<FixingDateGetter>(requiredFixings));
    return leg;
}

Here is the call graph for this function:

allAveraging()

bool allAveraging

(

)

const

Inspect the allAveraging_ flag.

Definition at line 56 of file commoditylegbuilder.hpp.

{ return allAveraging_; }

Member Data Documentation

allAveraging_

bool allAveraging_

mutableprivate

A flag that is set if the leg is averaging and the conventions indicate that the commodity contract itself on which the leg is based is averaging. This flag is false in all other circumstances.

Definition at line 62 of file commoditylegbuilder.hpp.