ConventionsBasedFutureExpiry Class Reference

Perform date calculations for future contracts based on conventions. More...

#include <ored/utilities/conventionsbasedfutureexpiry.hpp>

Inheritance diagram for ConventionsBasedFutureExpiry:

Collaboration diagram for ConventionsBasedFutureExpiry:

Public Member Functions
	ConventionsBasedFutureExpiry (const std::string &commName, QuantLib::Size maxIterations=10)
	ConventionsBasedFutureExpiry (const CommodityFutureConvention &convention, QuantLib::Size maxIterations=10)
QuantLib::Date	nextExpiry (bool includeExpiry=true, const QuantLib::Date &referenceDate=QuantLib::Date(), QuantLib::Natural offset=0, bool forOption=false) override
QuantLib::Date	priorExpiry (bool includeExpiry=true, const QuantLib::Date &referenceDate=QuantLib::Date(), bool forOption=false) override
QuantLib::Date	expiryDate (const QuantLib::Date &contractDate, QuantLib::Natural monthOffset=0, bool forOption=false) override
QuantLib::Date	contractDate (const QuantLib::Date &expiryDate) override
QuantLib::Date	applyFutureMonthOffset (const QuantLib::Date &contractDate, Natural futureMonthOffset) override
Public Member Functions inherited from FutureExpiryCalculator
virtual	~FutureExpiryCalculator ()
virtual QuantLib::Date	nextExpiry (bool includeExpiry=true, const QuantLib::Date &referenceDate=QuantLib::Date(), QuantLib::Natural offset=0, bool forOption=false)=0
virtual QuantLib::Date	priorExpiry (bool includeExpiry=true, const QuantLib::Date &referenceDate=QuantLib::Date(), bool forOption=false)=0
virtual QuantLib::Date	expiryDate (const QuantLib::Date &contractDate, QuantLib::Natural monthOffset=0, bool forOption=false)=0
virtual QuantLib::Date	contractDate (const QuantLib::Date &expiryDate)=0
virtual QuantLib::Date	applyFutureMonthOffset (const QuantLib::Date &contractDate, Natural futureMonthOffset)=0

Inspectors
CommodityFutureConvention	convention_
QuantLib::Size	maxIterations_
const CommodityFutureConvention &	commodityFutureConvention () const
	Return the commodity future convention. More...
QuantLib::Size	maxIterations () const
	Return the maximum iterations parameter. More...
QuantLib::Date	expiry (QuantLib::Day dayOfMonth, QuantLib::Month contractMonth, QuantLib::Year contractYear, QuantLib::Natural monthOffset, bool forOption) const
	Given a contractMonth, a contractYear and conventions, calculate the contract expiry date. More...
QuantLib::Date	nextExpiry (const QuantLib::Date &referenceDate, bool forOption) const
	Do the next expiry work. More...
QuantLib::Date	avoidProhibited (const QuantLib::Date &expiry, bool forOption) const
	Account for prohibited expiries. More...

Detailed Description

Perform date calculations for future contracts based on conventions.

Definition at line 33 of file conventionsbasedfutureexpiry.hpp.

Constructor & Destructor Documentation

ConventionsBasedFutureExpiry() [1/2]

ConventionsBasedFutureExpiry	(	const std::string &	commName,
		QuantLib::Size	maxIterations = 10
	)

ConventionsBasedFutureExpiry() [2/2]

ConventionsBasedFutureExpiry	(	const CommodityFutureConvention &	convention,
		QuantLib::Size	maxIterations = 10
	)

Definition at line 38 of file conventionsbasedfutureexpiry.cpp.

    : convention_(convention), maxIterations_(maxIterations) {}

Member Function Documentation

nextExpiry() [1/2]

QuantLib::Date nextExpiry ( bool  includeExpiry = true, const QuantLib::Date &  referenceDate = QuantLib::Date(), QuantLib::Natural  offset = 0, bool  forOption = false  )

overridevirtual

Implements FutureExpiryCalculator.

Here is the caller graph for this function:

priorExpiry()

Date priorExpiry ( bool  includeExpiry = true, const QuantLib::Date &  referenceDate = QuantLib::Date(), bool  forOption = false  )

overridevirtual

Implements FutureExpiryCalculator.

Definition at line 65 of file conventionsbasedfutureexpiry.cpp.

                                                                                                            {
 
    // Set the date relative to which we are calculating the preceding expiry
    Date today = referenceDate == Date() ? Settings::instance().evaluationDate() : referenceDate;
 
    // Get the next expiry relative to the reference date (including the reference date)
    Date expiry = nextExpiry(true, today, 0, forOption);
 
    // If that expiry is equal to reference date and we have set includeExpiry to true, we are done.
    if (includeExpiry && expiry == today)
        return expiry;
 
    // Get the preceding expiry.
    Period p(convention_.contractFrequency());
    Date baseDate = convention_.expiryCalendar().advance(expiry, -p);
    expiry = nextExpiry(true, baseDate, 0, forOption);
 
    // May still not have the preceding expiry but must be close
    Size counter = maxIterations_;
    while (expiry >= today && counter > 0) {
        baseDate--;
        counter--;
        expiry = nextExpiry(true, baseDate, 0, forOption);
    }
    QL_REQUIRE(expiry < today, "Expected that expiry " << io::iso_date(expiry) << " would be less than reference date "
                                                       << io::iso_date(today) << ".");
 
    return expiry;
}

Here is the call graph for this function:

expiryDate()

Date expiryDate ( const QuantLib::Date &  contractDate, QuantLib::Natural  monthOffset = 0, bool  forOption = false  )

overridevirtual

Implements FutureExpiryCalculator.

Definition at line 95 of file conventionsbasedfutureexpiry.cpp.

                                                                                                           {
    if (convention_.contractFrequency() == Daily) {
        return nextExpiry(contractDate, forOption);
    } else {
        return expiry(contractDate.dayOfMonth(), contractDate.month(), contractDate.year(), monthOffset, forOption);
    }
}

Here is the call graph for this function:

Here is the caller graph for this function:

contractDate()

QuantLib::Date contractDate ( const QuantLib::Date &  expiryDate )

overridevirtual

Implements FutureExpiryCalculator.

Definition at line 103 of file conventionsbasedfutureexpiry.cpp.

                                                                                      {
 
    if (convention_.contractFrequency() == Monthly) {
 
        // do not attempt to invert the logic in expiry(), instead just search for a valid contract month
        // in a reasonable range
 
        for (Size m = 0; m < 120; ++m) {
            try {
                Date tmp = Date(15, expiryDate.month(), expiryDate.year()) + m * Months;
                if (expiry(tmp.dayOfMonth(), tmp.month(), tmp.year(), 0, false) == expiryDate)
                    return tmp;
            } catch (...) {
            }
            try {
                Date tmp = Date(15, expiryDate.month(), expiryDate.year()) - m * Months;
                if (expiry(tmp.dayOfMonth(), tmp.month(), tmp.year(), 0, false) == expiryDate)
                    return tmp;
            } catch (...) {
            }
        }
 
    } else {
 
        // daily of weekly contract frequency => we can use contract date = expiry date
 
        return expiryDate;
    }
 
    QL_FAIL("ConventionsBasedFutureExpiry::contractDate(" << expiryDate << "): could not imply contract date. This is an internal error. Contact support.");
}

Here is the call graph for this function:

Here is the caller graph for this function:

applyFutureMonthOffset()

QuantLib::Date applyFutureMonthOffset ( const QuantLib::Date &  contractDate, Natural  futureMonthOffset  )

overridevirtual

Implements FutureExpiryCalculator.

Definition at line 135 of file conventionsbasedfutureexpiry.cpp.

                                                                                               {
 
    Date tmp = contractDate;
 
    if (convention_.contractFrequency() == Monthly) {
        tmp = Date(15, contractDate.month(), contractDate.year()) + futureMonthOffset * Months;
    }
 
    return tmp;
}

Here is the call graph for this function:

commodityFutureConvention()

const CommodityFutureConvention & commodityFutureConvention

(

)

const

Return the commodity future convention.

Definition at line 308 of file conventionsbasedfutureexpiry.cpp.

{ return convention_; }

maxIterations()

Size maxIterations

(

)

const

Return the maximum iterations parameter.

Definition at line 310 of file conventionsbasedfutureexpiry.cpp.

{ return maxIterations_; }

expiry()

Date expiry ( QuantLib::Day  dayOfMonth, QuantLib::Month  contractMonth, QuantLib::Year  contractYear, QuantLib::Natural  monthOffset, bool  forOption  ) const

private

Given a contractMonth, a contractYear and conventions, calculate the contract expiry date.

Definition at line 147 of file conventionsbasedfutureexpiry.cpp.

                                                                {
 
    Date expiry;
    if (convention_.contractFrequency() == Weekly) {
        QL_REQUIRE(convention_.anchorType() == CommodityFutureConvention::AnchorType::WeeklyDayOfTheWeek,
                   "Please change anchorType to WeeklyDayOfTheWeek for weekly contract expiries");
        Date d(dayOfMonth, contractMonth, contractYear);
        expiry = convention_.expiryCalendar().adjust(d - d.weekday() + convention_.weekday(),
                                                     convention_.businessDayConvention());
    } else {
        // Apply month offset if non-zero
        if (monthOffset > 0) {
            Date newDate = Date(15, contractMonth, contractYear) + monthOffset * Months;
            contractMonth = newDate.month();
            contractYear = newDate.year();
        }
 
        // Move n months before (+ve) or after (-ve) for the expiry if necessary
        if (convention_.expiryMonthLag() != 0) {
            Date newDate = Date(15, contractMonth, contractYear) - convention_.expiryMonthLag() * Months;
            contractMonth = newDate.month();
            contractYear = newDate.year();
        }
 
        if (convention_.contractFrequency() == Monthly && !convention_.validContractMonths().empty() &&
            convention_.validContractMonths().size() < 12 &&
            convention_.validContractMonths().count(contractMonth) == 0) {
            // contractMonth is in the not in the list of valid contract months
            return Date();
        } 
        // Calculate the relevant date in the expiry month and year
        if (convention_.anchorType() == CommodityFutureConvention::AnchorType::DayOfMonth) {
            Date last = Date::endOfMonth(Date(1, contractMonth, contractYear));
            if (convention_.dayOfMonth() > static_cast<Natural>(last.dayOfMonth())) {
                expiry = last;
            } else {
                expiry = Date(convention_.dayOfMonth(), contractMonth, contractYear);
            }
        } else if (convention_.anchorType() == CommodityFutureConvention::AnchorType::NthWeekday) {
            expiry = Date::nthWeekday(convention_.nth(), convention_.weekday(), contractMonth, contractYear);
        } else if (convention_.anchorType() == CommodityFutureConvention::AnchorType::CalendarDaysBefore) {
            expiry = Date(1, contractMonth, contractYear) - convention_.calendarDaysBefore() * Days;
        } else if (convention_.anchorType() == CommodityFutureConvention::AnchorType::BusinessDaysAfter) {
            if (convention_.businessDaysAfter() > 0) {
                expiry = convention_.expiryCalendar().advance(Date(1, contractMonth, contractYear) - 1 * Days,
                                                              convention_.businessDaysAfter(), Days);
            } else {
                expiry = convention_.expiryCalendar().advance(Date(1, contractMonth, contractYear),
                                                              convention_.businessDaysAfter(), Days);
            }
        } else if (convention_.anchorType() == CommodityFutureConvention::AnchorType::LastWeekday) {
            expiry = QuantExt::DateUtilities::lastWeekday(convention_.weekday(), contractMonth, contractYear);
        } else {
            QL_FAIL("Did not recognise the commodity future convention's anchor type");
        }
        // If expiry date is not a good business day, adjust it before applying the offset.
        if (convention_.adjustBeforeOffset()) {
            expiry = convention_.expiryCalendar().adjust(expiry, convention_.businessDayConvention());
        }
 
        // Apply offset adjustments if necessary. A negative integer indicates that we move forward that number of days.
        expiry = convention_.expiryCalendar().advance(expiry, -convention_.offsetDays(), Days);
    }
 
    // If we want the option contract expiry, do the extra work here.
    if (forOption && convention_.optionContractFrequency() == Weekly) {
        QL_REQUIRE(convention_.optionAnchorType() == CommodityFutureConvention::OptionAnchorType::WeeklyDayOfTheWeek,
                   "Please change anchorType to WeeklyDayOfTheWeek for weekly contract expiries");
        Date d(expiry.dayOfMonth(), expiry.month(), expiry.year());
        expiry = convention_.expiryCalendar().adjust(d - d.weekday() + convention_.optionWeekday(),
                                                     convention_.businessDayConvention());
        expiry = avoidProhibited(expiry, true);
    } else if (forOption) {
        if (convention_.optionAnchorType() == CommodityFutureConvention::OptionAnchorType::DayOfMonth) {
            auto optionMonth = expiry.month();
            auto optionYear = expiry.year();
 
            if (convention_.optionExpiryMonthLag() != 0) {
                Date newDate = Date(15, optionMonth, optionYear) - convention_.optionExpiryMonthLag() * Months;
                optionMonth = newDate.month();
                optionYear = newDate.year();
            }
 
            auto d = convention_.optionExpiryDay();
            Date last = Date::endOfMonth(Date(1, optionMonth, optionYear));
            if (d > static_cast<Natural>(last.dayOfMonth())) {
                expiry = last;
            } else {
                expiry = Date(d, optionMonth, optionYear);
            }
            expiry = convention_.expiryCalendar().adjust(expiry, convention_.optionBusinessDayConvention());
        } else if (convention_.optionAnchorType() == CommodityFutureConvention::OptionAnchorType::BusinessDaysBefore) {
            QL_REQUIRE(convention_.optionExpiryMonthLag() == 0 ||
                           convention_.expiryMonthLag() == convention_.optionExpiryMonthLag(),
                       "The expiry month lag "
                           << "and the option expiry month lag should be the same if using option expiry offset days.");
 
            expiry = convention_.expiryCalendar().advance(
                expiry, -static_cast<Integer>(convention_.optionExpiryOffset()), Days);
        } else if (convention_.optionAnchorType() == CommodityFutureConvention::OptionAnchorType::NthWeekday) {
            auto optionMonth = expiry.month();
            auto optionYear = expiry.year();
 
            if (convention_.optionExpiryMonthLag() != 0) {
                Date newDate = Date(15, optionMonth, optionYear) - convention_.optionExpiryMonthLag() * Months;
                optionMonth = newDate.month();
                optionYear = newDate.year();
            }
            expiry = Date::nthWeekday(convention_.optionNth(), convention_.optionWeekday(), optionMonth, optionYear);
            expiry = convention_.expiryCalendar().adjust(expiry, convention_.optionBusinessDayConvention());
        } else if (convention_.optionAnchorType() == CommodityFutureConvention::OptionAnchorType::LastWeekday) {
            auto optionMonth = expiry.month();
            auto optionYear = expiry.year();
 
            if (convention_.optionExpiryMonthLag() != 0) {
                Date newDate = Date(15, optionMonth, optionYear) - convention_.optionExpiryMonthLag() * Months;
                optionMonth = newDate.month();
                optionYear = newDate.year();
            }
            expiry = QuantExt::DateUtilities::lastWeekday(convention_.optionWeekday(), optionMonth, optionYear);
            expiry = convention_.expiryCalendar().adjust(expiry, convention_.optionBusinessDayConvention());
        }
 
        expiry = avoidProhibited(expiry, true);
 
    } else {
        // If expiry date is one of the prohibited dates, move to preceding or following business day
        expiry = avoidProhibited(expiry, false);
    }
 
    return expiry;
}

Here is the call graph for this function:

Here is the caller graph for this function:

nextExpiry() [2/2]

QuantLib::Date nextExpiry ( const QuantLib::Date &  referenceDate, bool  forOption  ) const

private

Do the next expiry work.

avoidProhibited()

Date avoidProhibited ( const QuantLib::Date &  expiry, bool  forOption  ) const

private

Account for prohibited expiries.

Definition at line 312 of file conventionsbasedfutureexpiry.cpp.

                                                                                           {
 
    // If expiry date is one of the prohibited dates, move to preceding or following business day.
    using PE = CommodityFutureConvention::ProhibitedExpiry;
    Date result = expiry;
    const auto& pes = convention_.prohibitedExpiries();
    auto it = pes.find(PE(result));
 
    while (it != pes.end()) {
 
        // If not relevant, exit.
        if ((!forOption && !it->forFuture()) || (forOption && !it->forOption()))
            break;
 
        auto bdc = !forOption ? it->futureBdc() : it->optionBdc();
 
        if (bdc == Preceding || bdc == ModifiedPreceding) {
            result = convention_.calendar().advance(result, -1, Days, bdc);
        } else if (bdc == Following || bdc == ModifiedFollowing) {
            result = convention_.calendar().advance(result, 1, Days, bdc);
        } else {
            QL_FAIL("Convention " << bdc << " associated with prohibited expiry " << io::iso_date(result)
                                  << " is not supported.");
        }
 
        it = pes.find(PE(result));
    }
 
    return result;
}

Here is the call graph for this function:

Here is the caller graph for this function:

Member Data Documentation

convention_

CommodityFutureConvention convention_

private

Definition at line 61 of file conventionsbasedfutureexpiry.hpp.

maxIterations_

QuantLib::Size maxIterations_

private

Definition at line 62 of file conventionsbasedfutureexpiry.hpp.