QPR-12477 -- Allow for double digital option underlying as a spread between two indices

Author: nathaniel.volfango

Docs/UserGuide/tradedata/doubledigitaloption.tex

@@ -12,7 +12,7 @@ \subsubsection{Double Digital Option}
       <BinaryPayout>12000000</BinaryPayout>
       <BinaryLevel1>1.1</BinaryLevel1>
       <BinaryLevel2>0.006</BinaryLevel2>
-      <BinaryLevelCollarUpperBound2>0.008</BinaryLevelCollarUpperBound2>
+      <BinaryLevelUpper2>0.008</BinaryLevelUpper2>
       <Type1>Call</Type1>
       <Type2>Collar</Type2>
       <Position>Long</Position>
@@ -44,17 +44,19 @@ \subsubsection{Double Digital Option}
   CCY2 per units of CCY1. For an Equity underlying this is the equity price expressed in the equity ccy.  For a Commodity underlying this is the commodity price expressed in the commodity ccy. For an IR underlying this is the rate expressed in decimal form. Allowable values
   are non-negative numbers.
 \item Type1: The option type that applies to underlying 1. Allowable values: {\em Call}, {\em Put} or {\em Collar}. Underlying 1 is
-  considered to be in the money if the spot is above (Call) / below (Put) the BinaryLevel1 resp. between (Collar) the BinaryLevel1 and BinaryLevelCollarUpperBound1 at the expiry. 
+  considered to be in the money if the spot is above (Call) / below (Put) the BinaryLevel1 resp. between (Collar) the BinaryLevel1 and BinaryLevelUpper1 at the expiry. 
 \item Type2: The option type that applies to underlying 2. Allowable values: {\em Call}, {\em Put} or {\em Collar}. Underlying 2 is
-  considered to be in the money if the spot is above (Call) / below (Put) the BinaryLevel1 resp. between (Collar) the BinaryLevel2 andthe  BinaryLevelCollarUpperBound2 at the expiry. 
+  considered to be in the money if the spot is above (Call) / below (Put) the BinaryLevel1 resp. between (Collar) the BinaryLevel2 andthe  BinaryLevelUpper2 at the expiry. 
 \item Position: The option position type. Allowable values: {\em Long} or {\em Short}.
 \item Underlying1: The first underlying, see \ref{ss:underlying}. 
 \item Underlying2: The second underlying, see \ref{ss:underlying}. Note that Type for both underlyings has allowable values \emph{Equity}, \emph{Commodity}, \emph{FX}, and \emph{IR}.
+\item Underlying3 [Optional]: If defined, the first underlying in this transaction is treated as a spread between Underlying1 and Underlying3 (i.e.\ Underlying1 fixing minus Underlying3 fixing), see \ref{ss:underlying}. Underlying3 Type must be the same as Underlying1 Type.
+\item Underlying4 [Optional]: If defined, the second underlying in this transaction is treated as a spread between Underlying2 and Underlying4 (i.e.\ Underlying2 fixing minus Underlying4 fixing), see \ref{ss:underlying}. Underlying4 Type must be the same as Underlying2 Type.
 \item PayCcy: The currency in which the \verb+BinaryPayout+ is paid.  See Table \ref{tab:currency} for allowable currency codes.
-\item BinaryLevelCollarUpperBound1: Optional field used only for Collar option. The upper bound for underlying 1. For an FX underlying (SOURCE-CCY1-CCY2) this is the number of units of
+\item BinaryLevelUpper1 [Optional]: This is field is used only for Collar option. The upper bound for underlying 1. For an FX underlying (SOURCE-CCY1-CCY2) this is the number of units of
   CCY2 per units of CCY1. For an Equity underlying this is the equity price expressed in the equity ccy.  For a Commodity underlying this is the commodity price expressed in the commodity ccy. For an IR underlying this is the rate expressed in decimal form. Allowable values
   are non-negative numbers.
-\item BinaryLevelCollarUpperBound2: Optional field used only for Collar option. The upper bound for underlying 2. For an FX underlying (SOURCE-CCY1-CCY2) this is the number of units of
+\item BinaryLevelUpper2 [Optional]: This field is used only for Collar option. The upper bound for underlying 2. For an FX underlying (SOURCE-CCY1-CCY2) this is the number of units of
   CCY2 per units of CCY1. For an Equity underlying this is the equity price expressed in the equity ccy.  For a Commodity underlying this is the commodity price expressed in the commodity ccy. For an IR underlying this is the rate expressed in decimal form. Allowable values
   are non-negative numbers.
 

OREData/ored/portfolio/doubledigitaloption.cpp

@@ -70,6 +70,24 @@ void DoubleDigitalOption::build(const QuantLib::ext::shared_ptr<EngineFactory>&
     QL_REQUIRE(underlying2_->type() == "Equity" || underlying2_->type() == "Commodity" ||
                    underlying2_->type() == "FX" || underlying2_->type() == "InterestRate",
                "underlying type " << underlying2_->type() << " not supported");
+    if (underlying3_) {
+        QL_REQUIRE(underlying3_->type() == "Equity" || underlying3_->type() == "Commodity" ||
+                       underlying3_->type() == "FX" || underlying3_->type() == "InterestRate",
+                   "underlying type " << underlying3_->type() << " not supported");
+
+        QL_REQUIRE(underlying1_->type() == underlying3_->type(),
+                   "Underlying1 and Underlying3 must belong to the same asset class. Got "
+                       << underlying1_->type() << " and " << underlying3_->type());
+    }
+    if (underlying4_) {
+        QL_REQUIRE(underlying4_->type() == "Equity" || underlying4_->type() == "Commodity" ||
+                       underlying4_->type() == "FX" || underlying4_->type() == "InterestRate",
+                   "underlying type " << underlying4_->type() << " not supported");
+        
+        QL_REQUIRE(underlying2_->type() == underlying4_->type(),
+                   "Underlying2 and Underlying4 must belong to the same asset class. Got "
+                       << underlying2_->type() << " and " << underlying4_->type());
+    }
 
     // set product tag accordingly
     if (underlying1_->type() == "InterestRate" && underlying2_->type() == "InterestRate")
@@ -83,10 +101,15 @@ void DoubleDigitalOption::build(const QuantLib::ext::shared_ptr<EngineFactory>&
 
     // set script
 
+    string underlying1Str, underlying2Str;
+    underlying1Str = underlying3_ ? "(Underlying1(Expiry) - Underlying3(Expiry))" : "Underlying1(Expiry)";
+    underlying2Str = underlying4_ ? "(Underlying2(Expiry) - Underlying4(Expiry))" : "Underlying2(Expiry)";
+
+    // clang-format off
     script_ = {
         {"", ScriptedTradeScriptData("NUMBER ExerciseProbability;\n"
-                                     "IF Underlying1(Expiry) >= LowerBound1 AND Underlying1(Expiry) <= UpperBound1 AND\n"
-                                     "   Underlying2(Expiry) >= LowerBound2 AND Underlying2(Expiry) <= UpperBound2 THEN\n"
+                                     "IF " + underlying1Str + " >= LowerBound1 AND " + underlying1Str + " <= UpperBound1 AND\n"
+                                     "   " + underlying2Str + " >= LowerBound2 AND " + underlying2Str + " <= UpperBound2 THEN\n"
                                      "     Option = LongShort * LOGPAY( BinaryPayout, Expiry, Settlement, PayCcy);\n"
                                      "     ExerciseProbability = 1;\n"
                                      "END;\n",
@@ -95,6 +118,7 @@ void DoubleDigitalOption::build(const QuantLib::ext::shared_ptr<EngineFactory>&
                                       {"currentNotional", "BinaryPayout"},
                                       {"notionalCurrency", "PayCcy"}},
                                      {})}};
+    // clang-format on
 
     // build trade
 
@@ -104,6 +128,10 @@ void DoubleDigitalOption::build(const QuantLib::ext::shared_ptr<EngineFactory>&
 void DoubleDigitalOption::initIndices() {
     indices_.emplace_back("Index", "Underlying1", scriptedIndexName(underlying1_));
     indices_.emplace_back("Index", "Underlying2", scriptedIndexName(underlying2_));
+    if (underlying3_)
+        indices_.emplace_back("Index", "Underlying3", scriptedIndexName(underlying3_));
+    if (underlying4_)
+        indices_.emplace_back("Index", "Underlying4", scriptedIndexName(underlying4_));
 }
 
 void DoubleDigitalOption::fromXML(XMLNode* node) {
@@ -148,6 +176,24 @@ void DoubleDigitalOption::fromXML(XMLNode* node) {
     underlyingBuilder2.fromXML(tmp);
     underlying2_ = underlyingBuilder2.underlying();
 
+    tmp = XMLUtils::getChildNode(tradeDataNode, "Underlying3");
+    if (!tmp)
+        tmp = XMLUtils::getChildNode(tradeDataNode, "Name3");
+    if (tmp) {
+        UnderlyingBuilder underlyingBuilder3("Underlying3", "Name3");
+        underlyingBuilder3.fromXML(tmp);
+        underlying3_ = underlyingBuilder3.underlying();
+    }
+
+    tmp = XMLUtils::getChildNode(tradeDataNode, "Underlying4");
+    if (!tmp)
+        tmp = XMLUtils::getChildNode(tradeDataNode, "Name4");
+    if (tmp) {
+        UnderlyingBuilder underlyingBuilder4("Underlying4", "Name4");
+        underlyingBuilder4.fromXML(tmp);
+        underlying4_ = underlyingBuilder4.underlying();
+    }
+
     payCcy_ = XMLUtils::getChildValue(tradeDataNode, "PayCcy", true);
 
     initIndices();
@@ -173,6 +219,10 @@ XMLNode* DoubleDigitalOption::toXML(XMLDocument& doc) const {
     XMLUtils::addChild(doc, tradeNode, "Position", position_);
     XMLUtils::appendNode(tradeNode, underlying1_->toXML(doc));
     XMLUtils::appendNode(tradeNode, underlying2_->toXML(doc));
+    if (underlying3_)
+        XMLUtils::appendNode(tradeNode, underlying3_->toXML(doc));
+    if (underlying4_)
+        XMLUtils::appendNode(tradeNode, underlying4_->toXML(doc));
     XMLUtils::addChild(doc, tradeNode, "PayCcy", payCcy_);
     return node;
 }

OREData/ored/portfolio/doubledigitaloption.hpp

@@ -37,16 +37,19 @@ class DoubleDigitalOption : public ScriptedTrade {
     DoubleDigitalOption() : ScriptedTrade("DoubleDigitalOption") {}
     DoubleDigitalOption(const Envelope& env, const string& expiry, const string& settlement, const string& binaryPayout,
                         const string& binaryLevel1, const string& binaryLevel2, const string& type1,
-                        const string& type2, const string& position, const QuantLib::ext::shared_ptr<Underlying>& underlying1,
-                        const QuantLib::ext::shared_ptr<Underlying>& underlying2, const string& payCcy,
+                        const string& type2, const string& position,
+                        const QuantLib::ext::shared_ptr<Underlying>& underlying1,
+                        const QuantLib::ext::shared_ptr<Underlying>& underlying2,
+                        const QuantLib::ext::shared_ptr<Underlying>& underlying3,
+                        const QuantLib::ext::shared_ptr<Underlying>& underlying4, const string& payCcy,
                         const QuantLib::ext::shared_ptr<Conventions>& conventions = nullptr,
                         const std::string& binaryLevelUpper1 = std::string(),
                         const std::string& binaryLevelUpper2 = std::string())
         : ScriptedTrade("DoubleDigitalOption", env), expiry_(expiry), settlement_(settlement),
           binaryPayout_(binaryPayout), binaryLevel1_(binaryLevel1), binaryLevel2_(binaryLevel2), type1_(type1),
           type2_(type2), position_(position), payCcy_(payCcy), binaryLevelUpper1_(binaryLevelUpper1),
           binaryLevelUpper2_(binaryLevelUpper2), underlying1_(underlying1),
-          underlying2_(underlying2) {
+          underlying2_(underlying2), underlying3_(underlying3), underlying4_(underlying4) {
         initIndices();
     }
     void build(const QuantLib::ext::shared_ptr<EngineFactory>&) override;
@@ -57,7 +60,7 @@ class DoubleDigitalOption : public ScriptedTrade {
     void initIndices();
     string expiry_, settlement_, binaryPayout_, binaryLevel1_, binaryLevel2_, type1_, type2_, position_, payCcy_,
         binaryLevelUpper1_, binaryLevelUpper2_;
-    QuantLib::ext::shared_ptr<Underlying> underlying1_, underlying2_;
+    QuantLib::ext::shared_ptr<Underlying> underlying1_, underlying2_, underlying3_, underlying4_;
 };
 
 } // namespace data

xsd/instruments.xsd

@@ -3865,6 +3865,8 @@
       <xs:element type="longShort" name="Position"/>
       <xs:element type="underlying" name="Underlying1" minOccurs="0"/>
       <xs:element type="underlying" name="Underlying2" minOccurs="0"/>
+      <xs:element type="underlying" name="Underlying3" minOccurs="0"/>
+      <xs:element type="underlying" name="Underlying4" minOccurs="0"/>
       <xs:element type="xs:string" name="Name1" minOccurs="0"/>
       <xs:element type="xs:string" name="Name2" minOccurs="0"/>
       <xs:element type="currencyCode" name="PayCcy"/>