QPR-12379 -- Add separate payment lag for swap notional flows, and apply X-CCY reset swap payment lag more consistently

Author: pcaspers

Docs/UserGuide/tradecomponents/legdatanotionals.tex

@@ -52,7 +52,7 @@ \subsubsection{Leg Data and Notionals}
 
 Allowable values:  See Table \ref{tab:currency} \lstinline!Currency!. When \lstinline!LegType! is \emph{Equity}, Minor Currencies in Table \ref{tab:currency} are also allowable.
 
-\item PaymentCalendar [Optional]: The payment calendar of the leg coupons. The \lstinline!PaymentCalendar! is used in conjunction with the \lstinline!PaymentConvention! and the \lstinline!PaymentLag! to determine the payments dates, unless the \lstinline!PaymentDates! node is used which defines the payment dates explicitly.
+\item PaymentCalendar [Optional]: The payment calendar of the leg coupons. The \lstinline!PaymentCalendar! is used in conjunction with the \lstinline!PaymentConvention!, \lstinline!PaymentLag! and \lstinline!NotionalPaymentLag! to determine the payments dates, unless the \lstinline!PaymentDates! node is used which defines the payment dates explicitly.
 
 Allowable values: See Table \ref{tab:calendar} \lstinline!Calendar!. If left blank or omitted, defaults to the calendar in the \lstinline!ScheduleData! node, unless \lstinline!LegType! is \emph{Floating} and \lstinline!Index! is OIS, in which case this defaults to the index calendar. 
 
@@ -62,12 +62,16 @@ \subsubsection{Leg Data and Notionals}
 
 Allowable values: See Table \ref{tab:convention}.
 
-\item PaymentLag [optional]: The payment lag applies to Fixed legs, Equity legs, and Floating legs with Ibor and OIS indices (but not to BMA/SIFMA indices), as well as CMS legs, CMSSpread legs, CPI legs and Zero Coupon Fixed legs. \\
+\item PaymentLag [optional]: The payment lag applies to the coupons on Fixed legs, Equity legs, and Floating legs with Ibor and OIS indices (but not to BMA/SIFMA indices), as well as CMS legs, CMSSpread legs, CPI legs and Zero Coupon Fixed legs. \\
 PaymentLag is also not supported for CapFloor Floating legs that have Ibor coupons with sub periods (HasSubPeriods = \emph{true}), nor for CapFloor Floating legs with averaged ON coupons (IsAveraged = \emph{true}).
 
 Allowable values: Any valid period, i.e. a non-negative whole number, optionally followed by \emph{D} (days), \emph{W} (weeks), \emph{M} (months),
   \emph{Y} (years). Defaults to \emph{0D} if left blank or omitted. If a whole number is given and no letter, it is assumed that it is a number of  \emph{D} (days).
 
+\item NotionalPaymentLag [optional]: The notional payment lag (in days) applied to any notional exchanges.
+
+Allowable values: Any non-negative integer. Defaults to zero if left blank or omitted.
+
 \item DayCounter: The day count convention of the leg coupons. Note that \lstinline!DayCounter! is mandatory for all leg types except \emph{Equity}.
 
 Allowable values: See \lstinline!DayCount Convention! in Table \ref{tab:daycount}. For \emph{Equity} legs, if left blank or omitted, it defaults to \emph{ACT/365}.

OREData/ored/portfolio/commodityapo.cpp

@@ -239,7 +239,7 @@ Leg CommodityAveragePriceOption::buildLeg(const QuantLib::ext::shared_ptr<Engine
     vector<string> paymentDates = paymentDate_.empty() ? vector<string>() : vector<string>(1, paymentDate_);
     LegData legData(commLegData, true, currency_, scheduleData, "", vector<Real>(), vector<string>(),
                     paymentConvention_, false, false, false, true, "", 0, "", vector<AmortizationData>(), 
-                    paymentLag_, paymentCalendar_, paymentDates);
+                    paymentLag_, "", paymentCalendar_, paymentDates);
 
     // Get the leg builder, set the allAveraging_ flag and build the leg
     auto legBuilder = engineFactory->legBuilder(legData.legType());

OREData/ored/portfolio/legdata.cpp

@@ -735,7 +735,7 @@ LegData::LegData(const QuantLib::ext::shared_ptr<LegAdditionalData>& concreteLeg
                  const bool notionalAmortizingExchange, const bool isNotResetXCCY, const string& foreignCurrency,
                  const double foreignAmount, const string& fxIndex,
                  const std::vector<AmortizationData>& amortizationData, const string& paymentLag,
-                 const string& paymentCalendar, const vector<string>& paymentDates,
+                 const string& notionalPaymentLag, const string& paymentCalendar, const vector<string>& paymentDates,
                  const std::vector<Indexing>& indexing, const bool indexingFromAssetLeg,
                  const string& lastPeriodDayCounter)
     : concreteLegData_(concreteLegData), isPayer_(isPayer), currency_(currency), schedule_(scheduleData),
@@ -744,8 +744,8 @@ LegData::LegData(const QuantLib::ext::shared_ptr<LegAdditionalData>& concreteLeg
       notionalFinalExchange_(notionalFinalExchange), notionalAmortizingExchange_(notionalAmortizingExchange),
       isNotResetXCCY_(isNotResetXCCY), foreignCurrency_(foreignCurrency), foreignAmount_(foreignAmount),
       fxIndex_(fxIndex), amortizationData_(amortizationData), paymentLag_(paymentLag),
-      paymentCalendar_(paymentCalendar), paymentDates_(paymentDates), indexing_(indexing),
-      indexingFromAssetLeg_(indexingFromAssetLeg), lastPeriodDayCounter_(lastPeriodDayCounter) {
+      notionalPaymentLag_(notionalPaymentLag), paymentCalendar_(paymentCalendar), paymentDates_(paymentDates),
+      indexing_(indexing), indexingFromAssetLeg_(indexingFromAssetLeg), lastPeriodDayCounter_(lastPeriodDayCounter) {
 
     indices_ = concreteLegData_->indices();
 
@@ -765,6 +765,7 @@ void LegData::fromXML(XMLNode* node) {
     dayCounter_ = XMLUtils::getChildValue(node, "DayCounter"); // optional
     paymentConvention_ = XMLUtils::getChildValue(node, "PaymentConvention");
     paymentLag_ = XMLUtils::getChildValue(node, "PaymentLag");
+    notionalPaymentLag_ = XMLUtils::getChildValue(node, "NotionalPaymentLag");
     paymentCalendar_ = XMLUtils::getChildValue(node, "PaymentCalendar", false);
     // if not given, default of getChildValueAsBool is true, which fits our needs here
     notionals_ = XMLUtils::getChildrenValuesWithAttributes<Real>(node, "Notionals", "Notional", "startDate",
@@ -863,6 +864,8 @@ XMLNode* LegData::toXML(XMLDocument& doc) const {
         XMLUtils::addChild(doc, node, "PaymentConvention", paymentConvention_);
     if (!paymentLag_.empty())
         XMLUtils::addChild(doc, node, "PaymentLag", paymentLag_);
+    if (!notionalPaymentLag_.empty())
+        XMLUtils::addChild(doc, node, "NotionalPaymentLag", notionalPaymentLag_);
     if (!paymentCalendar_.empty())
         XMLUtils::addChild(doc, node, "PaymentCalendar", paymentCalendar_);
     if (dayCounter_ != "")
@@ -1562,7 +1565,7 @@ Leg makeBMALeg(const LegData& data, const QuantLib::ext::shared_ptr<QuantExt::BM
 }
 
 Leg makeNotionalLeg(const Leg& refLeg, const bool initNomFlow, const bool finalNomFlow, const bool amortNomFlow,
-                    const Natural paymentLag, const BusinessDayConvention paymentConvention,
+                    const Natural notionalPaymentLag,  const BusinessDayConvention paymentConvention,
                     const Calendar paymentCalendar, const bool excludeIndexing) {
 
     // Assumption - Cashflows on Input Leg are all coupons
@@ -1575,7 +1578,7 @@ Leg makeNotionalLeg(const Leg& refLeg, const bool initNomFlow, const bool finalN
         QL_REQUIRE(coupon, "makeNotionalLeg does not support non-coupon legs");
         double initFlowAmt = (excludeIndexing ? unpackIndexedCoupon(coupon) : coupon)->nominal();
         Date initDate = coupon->accrualStartDate();
-        initDate = paymentCalendar.advance(initDate, paymentLag, Days, paymentConvention);
+        initDate = paymentCalendar.advance(initDate, notionalPaymentLag, Days, paymentConvention);
         if (initFlowAmt != 0)
             leg.push_back(QuantLib::ext::shared_ptr<CashFlow>(new SimpleCashFlow(-initFlowAmt, initDate)));
     }
@@ -1588,7 +1591,7 @@ Leg makeNotionalLeg(const Leg& refLeg, const bool initNomFlow, const bool finalN
             auto coupon2 = QuantLib::ext::dynamic_pointer_cast<QuantLib::Coupon>(refLeg[i - 1]);
             QL_REQUIRE(coupon, "makeNotionalLeg does not support non-coupon legs");
             Date flowDate = coupon->accrualStartDate();
-            flowDate = paymentCalendar.advance(flowDate, paymentLag, Days, paymentConvention);
+            flowDate = paymentCalendar.advance(flowDate, notionalPaymentLag, Days, paymentConvention);
             Real initNom = (excludeIndexing ? unpackIndexedCoupon(coupon2) : coupon2)->nominal();
             Real newNom = (excludeIndexing ? unpackIndexedCoupon(coupon) : coupon)->nominal();
             Real flow = initNom - newNom;
@@ -1603,7 +1606,7 @@ Leg makeNotionalLeg(const Leg& refLeg, const bool initNomFlow, const bool finalN
         QL_REQUIRE(coupon, "makeNotionalLeg does not support non-coupon legs");
         double finalNomFlow = (excludeIndexing ? unpackIndexedCoupon(coupon) : coupon)->nominal();
         Date finalDate = coupon->accrualEndDate();
-        finalDate = paymentCalendar.advance(finalDate, paymentLag, Days, paymentConvention);
+        finalDate = paymentCalendar.advance(finalDate, notionalPaymentLag, Days, paymentConvention);
         if (finalNomFlow != 0)
             leg.push_back(QuantLib::ext::shared_ptr<CashFlow>(new SimpleCashFlow(finalNomFlow, finalDate)));
     }
@@ -2736,49 +2739,58 @@ Leg buildNotionalLeg(const LegData& data, const Leg& leg, RequiredFixings& requi
         auto fxIndex =
             buildFxIndex(data.fxIndex(), data.currency(), data.foreignCurrency(), market, configuration, true);
 
+        PaymentLag notionalPayLag = parsePaymentLag(data.notionalPaymentLag());
+        Natural payLagInteger = boost::apply_visitor(PaymentLagInteger(), notionalPayLag);
+        const Calendar& payCalendar = parseCalendar(data.paymentCalendar());
+        const BusinessDayConvention& payConvention = parseBusinessDayConvention(data.paymentConvention());
+
         Leg resettingLeg;
         for (Size j = 0; j < leg.size(); j++) {
 
             QuantLib::ext::shared_ptr<Coupon> c = QuantLib::ext::dynamic_pointer_cast<Coupon>(leg[j]);
             QL_REQUIRE(c, "Expected each cashflow in FX resetting leg to be of type Coupon");
 
+            const Date& initFlowDate = payCalendar.advance(c->accrualStartDate(), payLagInteger, Days, payConvention);
+            const Date& finalFlowDate = payCalendar.advance(c->accrualEndDate(), payLagInteger, Days, payConvention);
+
             // Build a pair of notional flows, one at the start and one at the end of the accrual period.
             // They both have the same FX fixing date => same amount in this leg's currency.
             QuantLib::ext::shared_ptr<CashFlow> outCf;
             QuantLib::ext::shared_ptr<CashFlow> inCf;
             Date fixingDate;
             if (j == 0) {
+
                 // Two possibilities for first coupon:
                 // 1. we have not been given a domestic notional so it is an FX linked coupon
                 // 2. we have been given an explicit domestic notional so it is a simple cashflow
                 if (data.notionals().size() == 0) {
                     fixingDate = fxIndex->fixingDate(c->accrualStartDate());
                     if (data.notionalInitialExchange()) {
-                        outCf = QuantLib::ext::make_shared<FXLinkedCashFlow>(c->accrualStartDate(), fixingDate,
-                                                                     -foreignNotional, fxIndex);
+                        outCf = QuantLib::ext::make_shared<FXLinkedCashFlow>(initFlowDate, fixingDate, -foreignNotional,
+                                                                             fxIndex);
                     }
                     // if there is only one period we generate the cash flow at the period end
                     // only if there is a final notional exchange
                     if (leg.size() > 1 || data.notionalFinalExchange()) {
-                        inCf = QuantLib::ext::make_shared<FXLinkedCashFlow>(c->accrualEndDate(), fixingDate, foreignNotional,
-                                                                    fxIndex);
+                        inCf = QuantLib::ext::make_shared<FXLinkedCashFlow>(finalFlowDate, fixingDate, foreignNotional,
+                                                                            fxIndex);
                     }
                 } else {
                     if (data.notionalInitialExchange()) {
-                        outCf = QuantLib::ext::make_shared<SimpleCashFlow>(-c->nominal(), c->accrualStartDate());
+                        outCf = QuantLib::ext::make_shared<SimpleCashFlow>(-c->nominal(), initFlowDate);
                     }
                     if (leg.size() > 1 || data.notionalFinalExchange()) {
-                        inCf = QuantLib::ext::make_shared<SimpleCashFlow>(c->nominal(), c->accrualEndDate());
+                        inCf = QuantLib::ext::make_shared<SimpleCashFlow>(c->nominal(), finalFlowDate);
                     }
                 }
             } else {
                 fixingDate = fxIndex->fixingDate(c->accrualStartDate());
                 outCf =
-                    QuantLib::ext::make_shared<FXLinkedCashFlow>(c->accrualStartDate(), fixingDate, -foreignNotional, fxIndex);
+                    QuantLib::ext::make_shared<FXLinkedCashFlow>(initFlowDate, fixingDate, -foreignNotional, fxIndex);
                 // we don't want a final one, unless there is notional exchange
                 if (j < leg.size() - 1 || data.notionalFinalExchange()) {
                     inCf =
-                        QuantLib::ext::make_shared<FXLinkedCashFlow>(c->accrualEndDate(), fixingDate, foreignNotional, fxIndex);
+                        QuantLib::ext::make_shared<FXLinkedCashFlow>(finalFlowDate, fixingDate, foreignNotional, fxIndex);
                 }
             }
 
@@ -2806,11 +2818,11 @@ Leg buildNotionalLeg(const LegData& data, const Leg& leg, RequiredFixings& requi
 
         // check for notional exchanges on non FX reseting trades
 
-        PaymentLag payLag = parsePaymentLag(data.paymentLag());
-        Natural payLagInteger = boost::apply_visitor(PaymentLagInteger(), payLag);
+        PaymentLag notionalPayLag = parsePaymentLag(data.notionalPaymentLag());
+        Natural notionalPayLagInteger = boost::apply_visitor(PaymentLagInteger(), notionalPayLag);
 
         return makeNotionalLeg(leg, data.notionalInitialExchange(), data.notionalFinalExchange(),
-                               data.notionalAmortizingExchange(), payLagInteger,
+                               data.notionalAmortizingExchange(), notionalPayLagInteger,
                                parseBusinessDayConvention(data.paymentConvention()),
                                parseCalendar(data.paymentCalendar()), true);
     } else {

OREData/ored/portfolio/legdata.hpp

@@ -855,7 +855,8 @@ class LegData : public XMLSerializable {
             const bool notionalAmortizingExchange = false, const bool isNotResetXCCY = true,
             const string& foreignCurrency = "", const double foreignAmount = 0, const string& fxIndex = "",
             const std::vector<AmortizationData>& amortizationData = std::vector<AmortizationData>(),
-            const string& paymentLag = "", const std::string& paymentCalendar = "",
+            const string& paymentLag = "", const string& notionalPaymentLag = "",
+            const std::string& paymentCalendar = "",
             const std::vector<std::string>& paymentDates = std::vector<std::string>(),
             const std::vector<Indexing>& indexing = {}, const bool indexingFromAssetLeg = false,
             const string& lastPeriodDayCounter = "");
@@ -883,6 +884,7 @@ class LegData : public XMLSerializable {
     double foreignAmount() const { return foreignAmount_; }
     const string& fxIndex() const { return fxIndex_; }
     const string& paymentLag() const { return paymentLag_; }
+    const string& notionalPaymentLag() const { return notionalPaymentLag_; }
     const std::vector<AmortizationData>& amortizationData() const { return amortizationData_; }
     const std::string& paymentCalendar() const { return paymentCalendar_; }
     const string& legType() const { return concreteLegData_->legType(); }
@@ -941,7 +943,7 @@ class LegData : public XMLSerializable {
     double foreignAmount_ = 0.0;
     string fxIndex_;
     std::vector<AmortizationData> amortizationData_;
-    string paymentLag_;
+    string paymentLag_, notionalPaymentLag_;
     std::string paymentCalendar_;
     std::vector<std::string> paymentDates_;
     std::vector<Indexing> indexing_;
@@ -966,7 +968,7 @@ Leg makeBMALeg(const LegData& data, const QuantLib::ext::shared_ptr<QuantExt::BM
                const QuantLib::Date& openEndDateReplacement = Null<Date>());
 Leg makeSimpleLeg(const LegData& data);
 Leg makeNotionalLeg(const Leg& refLeg, const bool initNomFlow, const bool finalNomFlow, const bool amortNomFlow,
-                    const QuantLib::Natural paymentLag, const BusinessDayConvention paymentConvention,
+                    const QuantLib::Natural notionalPaymentLag, const BusinessDayConvention paymentConvention,
                     const Calendar paymentCalendar, const bool excludeIndexing = true);
 Leg makeCPILeg(const LegData& data, const QuantLib::ext::shared_ptr<ZeroInflationIndex>& index,
                const QuantLib::ext::shared_ptr<EngineFactory>& engineFactory,

xsd/instruments.xsd

@@ -795,6 +795,7 @@
       <xs:element type="extendedCurrencyCode" name="Currency" minOccurs="0"/>
       <xs:element type="businessDayConvention" name="PaymentConvention" minOccurs="0"/>
       <xs:element type="paymentLag" name="PaymentLag" minOccurs="0"/>
+      <xs:element type="xs:integer" name="NotionalPaymentLag" minOccurs="0"/>
       <xs:element type="xs:string" name="PaymentCalendar" minOccurs="0"/>
       <xs:element type="dayCounter" name="DayCounter" minOccurs="0"/>
       <xs:element name="Amortizations" minOccurs="0" maxOccurs="1">