Merge branch 'feature/QPR-13736' into 'master'

QPR-13736: added second thursday future convention

Closes QPR-13736

See merge request qs/oreplus!3110

Author: mgroncki

Docs/UserGuide/parameterisation/conventions.tex

@@ -140,11 +140,12 @@ \subsubsection{Future Conventions}\label{ss:conventions_future}
 \item Index: The underlying index of the futures, this is either a MM (i.e. Ibor) index like e.g. EUR-EURIBOR-3M or an
   overnight index like e.g. USD-SOFR.
 \item DateGenerationRule [Optional]: This should be set to `IMM' when the start and end dates of the future are
-  following the IMM date logic or `FirstDayOfMonth' when the start and end date are the first day of a month. If not
-  given this field defaults to `IMM'.
+  following the IMM date logic, `FirstDayOfMonth' when the start and end date are the first day of a month, or
+  `SecondThursday' when the expiry date is the second Thursday of the month. If not given this field defaults to `IMM'.
   \begin{itemize}
-  \item For MM futures only `IMM' is allowed and the expiry date is determined as the next 3rd Wednesday of the expiry
-    month of a future.
+  \item For MM futures `IMM' or `SecondThursday' are allowed. The expiry date for `IMM' is determined as the next 3rd
+    Wednesday of the expiry month of a future. The expiry date for `SecondThursday' is determined as the 2nd Thursday
+    of the expiry month (e.g. used for AUD-BBSW-3M futures).
   \item For an overnight index future `IMM' means that the end date of the future is set to the 3rd Wednesday of the
     expiry month and the start date is set to the 3rd Wednesday of the expiry month minus the future tenor. The setting
     `IMM' applies to SOFR-3M futures for example. `FirstDayOfMonth' on the other hand means that the end date of the
@@ -163,8 +164,9 @@ \subsubsection{Future Conventions}\label{ss:conventions_future}
   are averaging the daily overnight fixings over the calculation period of the future.
 \end{itemize}
 
-Listings \ref{lst:future_conventions_euribor_3m}, \ref{lst:future_conventions_sofr_3m},
-\ref{lst:future_conventions_sofr_1m} show examples for Euribor-3M, SOFR-3M and SOFR-1M future conventions.
+Listings \ref{lst:future_conventions_euribor_3m}, \ref{lst:future_conventions_aud_bbsw_3m},
+\ref{lst:future_conventions_sofr_3m}, \ref{lst:future_conventions_sofr_1m} show examples for Euribor-3M, AUD-BBSW-3M,
+SOFR-3M and SOFR-1M future conventions.
 
 \begin{listing}[H]
 %\hrule\medskip
@@ -192,6 +194,19 @@ \subsubsection{Future Conventions}\label{ss:conventions_future}
 \label{lst:future_conventions_euribor_3m}
 \end{listing}
 
+\begin{listing}[H]
+%\hrule\medskip
+\begin{minted}[fontsize=\footnotesize]{xml}
+<Future>
+  <Id>AUD-BBSW-3M-FUTURES-CONVENTIONS</Id>
+  <Index>AUD-BBSW-3M</Index>
+  <DateGenerationRule>SecondThursday</DateGenerationRule>
+</Future>
+\end{minted}
+\caption{AUD BBSW 3M MM Future conventions (Second Thursday expiry)}
+\label{lst:future_conventions_aud_bbsw_3m}
+\end{listing}
+
 \begin{listing}[H]
 %\hrule\medskip
 \begin{minted}[fontsize=\footnotesize]{xml}

OREData/ored/configuration/conventions.hpp

@@ -135,7 +135,7 @@ class Conventions : public XMLSerializable {
 
     /*! Get all conventions of a given type */
     std::set<QuantLib::ext::shared_ptr<Convention>> get(const Convention::Type& type) const;
-    
+
     /*! Find a convention for an FX pair */
     QuantLib::ext::shared_ptr<Convention> getFxConvention(const string& ccy1, const string& ccy2) const;
 
@@ -312,7 +312,7 @@ class DepositConvention : public Convention {
  */
 class FutureConvention : public Convention {
 public:
-    enum class DateGenerationRule { IMM, FirstDayOfMonth };
+    enum class DateGenerationRule { IMM, FirstDayOfMonth, SecondThursday };
     //! \name Constructors
     //@{
     //! Default constructor
@@ -656,7 +656,7 @@ class TenorBasisSwapConvention : public Convention {
     //! Detailed constructor
     TenorBasisSwapConvention(const string& id, const string& payIndex, const string& receiveIndex,
                              const string& receiveFrequency = "", const string& payFrequency = "",
-                             const string& spreadOnRec = "", const string& includeSpread = "", 
+                             const string& spreadOnRec = "", const string& includeSpread = "",
                              const string& subPeriodsCouponType = "");
     //@}
 
@@ -1164,7 +1164,7 @@ class InflationSwapConvention : public Convention {
     InflationSwapConvention(const string& id, const string& strFixCalendar, const string& strFixConvention,
                             const string& strDayCounter, const string& strIndex, const string& strInterpolated,
                             const string& strObservationLag, const string& strAdjustInfObsDates,
-                            const string& strInfCalendar, const string& strInfConvention, 
+                            const string& strInfCalendar, const string& strInfConvention,
                             PublicationRoll publicationRoll = PublicationRoll::None,
                             const QuantLib::ext::shared_ptr<ScheduleData>& publicationScheduleData = nullptr);
 
@@ -1181,7 +1181,7 @@ class InflationSwapConvention : public Convention {
     PublicationRoll publicationRoll() const { return publicationRoll_; }
     const Schedule& publicationSchedule() const { return publicationSchedule_; }
     int startDelay() const { return startDelay_; }
-    BusinessDayConvention startDelayConvention() const { return startDelayConvention_; }    
+    BusinessDayConvention startDelayConvention() const { return startDelayConvention_; }
 
     virtual void fromXML(XMLNode* node) override;
     virtual XMLNode* toXML(XMLDocument& doc) const override;
@@ -1212,7 +1212,7 @@ class InflationSwapConvention : public Convention {
     string strInfCalendar_;
     string strInfConvention_;
     string strStartDelayConvention_;
-    
+
     PublicationRoll publicationRoll_;
     QuantLib::ext::shared_ptr<ScheduleData> publicationScheduleData_;
 };
@@ -1408,7 +1408,7 @@ class CommodityFutureConvention : public Convention {
         CalendarDaysBefore(const std::string& calendarDaysBefore) : calendarDaysBefore_(calendarDaysBefore) {}
         std::string calendarDaysBefore_;
     };
-    
+
     struct BusinessDaysBefore {
         BusinessDaysBefore(const std::string& daysBefore) : businessDaysBefore_(daysBefore) {}
         std::string businessDaysBefore_;
@@ -1470,7 +1470,7 @@ class CommodityFutureConvention : public Convention {
     };
     //@}
 
-    /*! Class to hold averaging information when \c isAveraging_ is \c true. It is generally needed 
+    /*! Class to hold averaging information when \c isAveraging_ is \c true. It is generally needed
         in the CommodityFutureConvention when referenced in piecewise price curve construction.
     */
     class AveragingData : public XMLSerializable {
@@ -1527,7 +1527,7 @@ class CommodityFutureConvention : public Convention {
         void build();
     };
 
-    //! Class to store conventions for creating an off peak power index 
+    //! Class to store conventions for creating an off peak power index
     class OffPeakPowerIndexData : public XMLSerializable {
     public:
         //! Constructor.
@@ -1643,7 +1643,7 @@ class CommodityFutureConvention : public Convention {
                               QuantLib::Natural hoursPerDay = QuantLib::Null<QuantLib::Natural>(),
                               const QuantLib::ext::optional<OffPeakPowerIndexData>& offPeakPowerIndexData = QuantLib::ext::nullopt,
                               const std::string& indexName = "", const std::string& optionFrequency = "");
-    
+
     //! Business days before based constructor
     CommodityFutureConvention(const std::string& id, const BusinessDaysAfter& businessDaysAfter,
                               const std::string& contractFrequency, const std::string& calendar,
@@ -1730,7 +1730,7 @@ class CommodityFutureConvention : public Convention {
     QuantLib::Month oneContractMonth_;
     QuantLib::Integer offsetDays_;
     QuantLib::BusinessDayConvention bdc_;
-    
+
 
     std::string strDayOfMonth_;
     std::string strNth_;
@@ -1756,17 +1756,17 @@ class CommodityFutureConvention : public Convention {
     QuantLib::Natural hoursPerDay_;
     QuantLib::ext::optional<OffPeakPowerIndexData> offPeakPowerIndexData_;
     std::string indexName_;
-    
+
     std::string strOptionContractFrequency_;
-    
+
     OptionAnchorType optionAnchorType_;
     std::string strOptionExpiryOffset_;
     std::string strOptionExpiryDay_;
     std::string strOptionNth_;
     std::string strOptionWeekday_;
     std::string strOptionCalendarDaysBefore_;
     std::string strOptionMinBusinessDaysBefore_;
-    
+
     QuantLib::Frequency optionContractFrequency_;
     QuantLib::Natural optionExpiryOffset_;
     QuantLib::Natural optionNth_;
@@ -1777,8 +1777,8 @@ class CommodityFutureConvention : public Convention {
 
     std::set<QuantLib::Month> validContractMonths_;
     std::string savingsTime_;
-    // If its averaging Future but the front month is spot averaged and 
-    // balance of the month price is the average price of the remaining 
+    // If its averaging Future but the front month is spot averaged and
+    // balance of the month price is the average price of the remaining
     // future days in contract
     bool balanceOfTheMonth_;
     std::string balanceOfTheMonthPricingCalendarStr_;

OREData/ored/marketdata/yieldcurve.cpp

@@ -2185,10 +2185,12 @@ void YieldCurve::addFutures(const std::size_t index, const QuantLib::ext::shared
 
                 // Create a MM future helper
                 QL_REQUIRE(
-                    futureConvention->dateGenerationRule() == FutureConvention::DateGenerationRule::IMM,
-                    "For MM Futures only 'IMM' is allowed as the date generation rule, check the future convention '"
+                    futureConvention->dateGenerationRule() == FutureConvention::DateGenerationRule::IMM ||
+                    futureConvention->dateGenerationRule() == FutureConvention::DateGenerationRule::SecondThursday,
+                    "For MM Futures only 'IMM' or 'SecondThursday' are allowed as date generation rules, check the future convention '"
                         << segment->conventionsID() << "'");
-                Date immDate = getMmFutureExpiryDate(futureQuote->expiryMonth(), futureQuote->expiryYear());
+                Date immDate = getMmFutureExpiryDate(futureQuote->expiryMonth(), futureQuote->expiryYear(),
+                                                     futureConvention->dateGenerationRule());
 
                 if (immDate < asofDate_) {
                     DLOG("Skipping the " << io::ordinal(i + 1) << " money market future instrument because its "
@@ -2197,8 +2199,13 @@ void YieldCurve::addFutures(const std::size_t index, const QuantLib::ext::shared
                     continue;
                 }
 
+                // Determine the futures type for validation
+                Futures::Type futuresType = (futureConvention->dateGenerationRule() == FutureConvention::DateGenerationRule::IMM)
+                                            ? Futures::IMM
+                                            : Futures::Custom;
+
                 auto helper = QuantLib::ext::make_shared<FuturesRateHelper>(futureQuote->quote(), immDate,
-                                                                            futureConvention->index());
+                                                                            futureConvention->index(), 0.0, futuresType);
 
                 instruments.push_back(
                     {helper, "Short MM Future", marketQuote->name(), marketQuote->quote()->value(),

OREData/ored/utilities/marketdata.cpp

@@ -332,10 +332,17 @@ std::pair<Date, Date> getOiFutureStartEndDate(QuantLib::Month expiryMonth, Quant
     return std::make_pair(startDate, endDate);
 }
 
-Date getMmFutureExpiryDate(QuantLib::Month expiryMonth, QuantLib::Natural expiryYear) { 
+Date getMmFutureExpiryDate(QuantLib::Month expiryMonth, QuantLib::Natural expiryYear,
+                           FutureConvention::DateGenerationRule rule) {
     Date refDate(1, expiryMonth, expiryYear);
-    Date immDate = IMM::nextDate(refDate, false);
-    return immDate;
+
+    if (rule == FutureConvention::DateGenerationRule::IMM) {
+        return IMM::nextDate(refDate, false);  // Third Wednesday
+    } else if (rule == FutureConvention::DateGenerationRule::SecondThursday) {
+        return Date::nthWeekday(2, Thursday, refDate.month(), refDate.year());
+    } else {
+        QL_FAIL("getMmFutureExpiryDate: DateGenerationRule '" << rule << "' not supported for MM Futures");
+    }
 }
 
 std::string fxIndexNameForDailyLowsOrHighs(const QuantLib::ext::shared_ptr<QuantExt::FxIndex>& fxIndex, bool lows) {

OREData/ored/utilities/marketdata.hpp

@@ -110,7 +110,8 @@ std::pair<Date, Date> getOiFutureStartEndDate(QuantLib::Month expiryMonth, Quant
                                               QuantLib::Period tenor, FutureConvention::DateGenerationRule rule,
                                               const QuantLib::Calendar& calendar);
 
-Date getMmFutureExpiryDate(QuantLib::Month expiryMonth, QuantLib::Natural expiryYear);
+Date getMmFutureExpiryDate(QuantLib::Month expiryMonth, QuantLib::Natural expiryYear,
+                           FutureConvention::DateGenerationRule rule = FutureConvention::DateGenerationRule::IMM);
 
 /*! convert the creditCurveId into the internal name for the index tranche credit curve*/
 std::string indexTrancheSpecificCreditCurveName(const std::string& creditCurveId, const double assumedRecoveryRate);

OREData/ored/utilities/parsers.cpp

@@ -1028,8 +1028,10 @@ FutureConvention::DateGenerationRule parseFutureDateGenerationRule(const std::st
         return FutureConvention::DateGenerationRule::IMM;
     else if (s == "FirstDayOfMonth")
         return FutureConvention::DateGenerationRule::FirstDayOfMonth;
+    else if (s == "SecondThursday")
+        return FutureConvention::DateGenerationRule::SecondThursday;
     else {
-        QL_FAIL("FutureConvention /  DateGenerationRule '" << s << "' not known, expect 'IMM' or 'FirstDayOfMonth'");
+        QL_FAIL("FutureConvention /  DateGenerationRule '" << s << "' not known, expect 'IMM', 'FirstDayOfMonth', or 'SecondThursday'");
     }
 }
 
@@ -1038,6 +1040,8 @@ std::ostream& operator<<(std::ostream& os, FutureConvention::DateGenerationRule
         return os << "IMM";
     else if (t == FutureConvention::DateGenerationRule::FirstDayOfMonth)
         return os << "FirstDayOfMonth";
+    else if (t == FutureConvention::DateGenerationRule::SecondThursday)
+        return os << "SecondThursday";
     else {
         QL_FAIL("Internal error: unknown FutureConvention::DateGenerationRule - check implementation of operator<< "
                 "for this enum");

xsd/ore_types.xsd

@@ -774,6 +774,7 @@
     <xs:restriction base="xs:string">
       <xs:enumeration value="IMM"/>
       <xs:enumeration value="FirstDayOfMonth"/>
+      <xs:enumeration value="SecondThursday"/>
     </xs:restriction>
   </xs:simpleType>