Merge remote-tracking branch 'origin/master' into feature/QPR-13640

Author: mgroncki

Docs/ScriptedTrade/docs/language.tex

@@ -41,6 +41,8 @@
     \verb+max+ & \\
     \verb+min+ & \\
     \verb+pow+ & \\
+    \verb+frac+ & \\
+    \verb+round+ & \\
     \verb+black+ & \\
     \verb+dcf+ & \\
     \verb+days+ & \\ \hline
@@ -398,21 +400,21 @@
 \item {\tt REQUIRE Strike >= 0;}
 \end{itemize}
 
-% ====================================================
-\stsubsection{Functions {\tt min}, {\tt max}, {\tt pow}}
-% ====================================================
+% =========================================================================
+\stsubsection{Functions {\tt min}, {\tt max}, {\tt pow}}, {\tt round(x,y)}
+% =========================================================================
 
-Binary functions {\tt min(x,y)}, {\tt max(x,y)}, {\tt pow(x,y)}, applicable to numbers only.
+Binary functions {\tt min(x,y)}, {\tt max(x,y)}, {\tt pow(x,y)}, {\tt round(x,y)}, applicable to numbers only.
 
-% ====================================================
-\stsubsection{Functions {\tt -}, abs, exp, ln, sqrt}
-% ====================================================
+% ========================================================
+\stsubsection{Functions {\tt -}, abs, exp, ln, sqrt, frac}
+% ========================================================
 
-Unary functions {\tt -x}, {\tt abs(x)}, {\tt exp(x)}, {\tt ln(x)}, {\tt sqrt(x)}, applicable to numbers only.
+Unary functions {\tt -x}, {\tt abs(x)}, {\tt exp(x)}, {\tt ln(x)}, {\tt sqrt(x)}, {\tt frac(x)} which take the fractional part of a float, applicable to numbers only.
 
-% ====================================================
+% =======================================================
 \stsubsection{Functions {\tt normalPdf}, {\tt normalCdf}}
-% ====================================================
+% =======================================================
 
 Returns the standard normal pdf $\phi(x)$ resp. cdf $\Phi(x)$, applicable to numbers only.
 

Docs/UserGuide/examples/examples.tex

@@ -615,8 +615,9 @@ \subsubsection{Historical Simulation VaR}
 The analytic is specified as usual in {\tt ore.xml} with the following parameters:
 \begin{itemize}
 \item outputFile: csv file name of the resulting VaR report
-%\item breakdown: boolean, if true the VaR report will contain a breakdown by risk class and risk type, otherwise the report shows the portfolio-lvel VaR only.
-\item tradePnl: boolean, if true the VaR report will contain a breakdown by tradeID, risk class and risk type, otherwise the report shows the portfolio-lvel VaR only.
+%\item breakdown: boolean, if true the VaR report will contain a breakdown by risk class and risk type, otherwise the report shows the portfolio-level VaR only.
+\item tradePnl: boolean, if true the VaR report will contain a breakdown by tradeID, risk class and risk type, otherwise the report shows the portfolio-level VaR only.
+\item riskFactorBreakdown: boolean, if true the VaR report will contain a breakdown by risk factor.
 \item quantiles: comma separated list of quantiles to be reported
 \item portfolioFilter (optional): Only trades with {\tt portfolioId} equal to the provided filter name are processed, see {\tt portfolio.xml}; the entire portfolio is processed, if omitted
 \item historicalPeriod: comma-separated date list, an even number of ordered dates is required (d1, d2, d3, d4, ...), where each pair (d1-d2, d3-d4, ...) defines the start and end of historical observation periods used

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}

Docs/UserGuide/tradedata/rainbow_option.tex

@@ -1648,3 +1648,169 @@ \subsubsection*{Worst Performance Rainbow Option 05}
       COMM underlyings), this will result in a quanto payoff. Notice section ``Payment Currency'' in ore/Docs/ScriptedTrade. \\
         Allowable values: See Table \ref{tab:currency} for allowable currency codes.
 \end{itemize}
+
+\subsubsection*{Worst Performance Rainbow Option 06}
+
+A worst performance rainbow option 06 is represented as a {\em scripted trade},
+refer to the scripted trade documentation in ore/Docs/ScriptedTrade
+for an introduction.
+
+Trade input and the payoff script are described below.
+
+\begin{minted}[fontsize=\scriptsize]{xml}
+<Trade id="EQ_WorstPerformanceRainbowOption06">
+  <TradeType>ScriptedTrade</TradeType>
+  <Envelope>
+    <CounterParty>CPTY_A</CounterParty>
+    <NettingSetId>CPTY_A</NettingSetId>
+    <AdditionalFields/>
+  </Envelope>
+  <WorstPerformanceRainbowOption06Data>
+    <LongShort type="longShort">Long</LongShort>
+    <Quantity type="number">200000</Quantity>
+    <Underlyings type="index">
+      <Value>EQ-RIC:.STOXX50E</Value>
+      <Value>EQ-RIC:.SPX</Value>
+    </Underlyings>
+    <InitialPrices type="number">
+      <Value>5455.60</Value>
+      <Value>500</Value>
+    </InitialPrices>
+    <StrikePrices type="number">
+      <Value>5600</Value>
+      <Value>550</Value>
+    </StrikePrices>
+    <BarrierLevels type="number">
+      <Value>5600</Value>
+      <Value>550</Value>
+    </BarrierLevels>
+    <KnockInPrices type="number">
+      <Value>5600</Value>
+      <Value>550</Value>
+    </KnockInPrices>
+    <BonusCoupon type="number">0.1430</BonusCoupon>
+    <ObservationSchedule type="event">
+      <ScheduleData>
+        <Rules>
+          <StartDate>2020-03-11</StartDate>
+          <EndDate>2020-09-04</EndDate>
+          <Tenor>1D</Tenor>
+          <Calendar>USD</Calendar>
+          <Convention>ModifiedFollowing</Convention>
+          <TermConvention>ModifiedFollowing</TermConvention>
+          <Rule>Forward</Rule>
+        </Rules>
+      </ScheduleData>
+    </ObservationSchedule>
+    <ObservationDate type="event">2020-09-04</ObservationDate>
+    <SettlementDate type="event">2020-09-11</SettlementDate>
+    <PayCcy type="currency">EUR</PayCcy>
+  </WorstPerformanceRainbowOption06Data>
+</Trade>
+\end{minted}
+
+The WorstPerformanceRainbowOption06 script referenced in the trade above is shown in listing
+\ref{lst:worst_performance_rainbow_option_06}.
+
+\begin{listing}[hbt]
+\begin{minted}[fontsize=\scriptsize]{Basic}
+REQUIRE SIZE(Underlyings) == SIZE(InitialPrices) AND SIZE(Underlyings) == SIZE(StrikePrices);
+REQUIRE SIZE(Underlyings) == SIZE(BarrierLevels) AND SIZE(Underlyings) == SIZE(KnockInPrices);
+REQUIRE ObservationDate <= SettlementDate;
+
+NUMBER indexInitial, indexFinal, performance, d, spot;
+NUMBER worstPerformance, payoff, premium, knockedIn, u, worstUnderlying, worstUnderlyingFinalPrice;
+NUMBER deliverableAsset,fractionalAmount, fractionalCashAmount;
+
+worstUnderlying = 1;
+
+FOR u IN (1, SIZE(Underlyings), 1) DO
+  indexInitial = InitialPrices[u];
+  indexFinal = Underlyings[u](ObservationDate);
+  performance = indexFinal / indexInitial;
+
+  IF {u == 1} OR {performance < worstPerformance} THEN
+    worstPerformance = performance;
+    worstUnderlyingFinalPrice = indexFinal;
+    worstUnderlying = u;
+  END;
+END;
+
+FOR d IN (1, SIZE(ObservationSchedule), 1) DO
+  IF knockedIn == 0 THEN
+    FOR u IN (1, SIZE(Underlyings), 1) DO
+      spot = Underlyings[u](ObservationSchedule[d]);
+      IF spot < KnockInPrices[u] THEN
+        knockedIn = 1;
+      END;
+    END;
+  END;
+END;
+
+IF knockedIn == 1 AND worstUnderlyingFinalPrice < StrikePrices[worstUnderlying] THEN
+  deliverableAsset = Quantity/StrikePrices[worstUnderlying];
+  fractionalAmount = frac(deliverableAsset);
+  fractionalAmount = round(fractionalAmount,4);
+  fractionalCashAmount = worstUnderlyingFinalPrice*fractionalAmount;
+  payoff = round(fractionalCashAmount,2)+round(deliverableAsset,0);
+ELSE
+  IF worstUnderlyingFinalPrice >= BarrierLevels[worstUnderlying] THEN
+    payoff = Quantity*(1+max(BonusCoupon, worstPerformance-1));
+  ELSE
+    payoff = Quantity;
+  END;
+END;
+
+payoff = LOGPAY(payoff, ObservationDate, SettlementDate, PayCcy, 1, Payoff);
+
+Option = LongShort * payoff;
+\end{minted}
+\caption{Payoff script for a WorstPerformanceRainbowOption06.}
+\label{lst:worst_performance_rainbow_option_06}
+\end{listing}
+
+The payout formula, determined on the \lstinline!ObservationDate!, is as follows, where
+$worstPerformance$ is the performance, i.e.\ $S_T/S_0$, of the worst-performing asset as
+of the final determination date $T$. The payout for a long put option is as follows:
+
+If a knock-in event was triggered and the Final Reference Price of the Worst Performing Underlying
+is below its Strike Price,
+\begin{equation*}
+  Payout = \text{\lstinline!Quantity!} * S * \text{FractionalAmount} + \text{round}(\text{fractionalCashAmount})
+\end{equation*}
+with Fractional Amount being the fractional share resulting from the calculation of the Deliverable Assets. $K$ being the strike level of the 
+worst underlying performing asset, $S$ that underlying final price.
+\begin{equation*}
+  FractionalAmount = \text{\lstinline!Quantity!} / \text{K}
+\end{equation*}
+
+The meanings and allowable values for the \lstinline!WorstPerformanceRainbowOption06Data! node below.
+
+\begin{itemize}
+  \item{}[longShort] \lstinline!LongShort!: Own party position in the option. \\
+  Allowable values: \emph{Long, Short}.
+  \item{}[index] \lstinline!Underlyings!: The basket of underlyings. \\
+  Allowable values: See ore/Docs/ScriptedTrade's Index Section for allowable values.
+  \item{}[number] \lstinline!InitialPrices!: The agreed initial price for each basket underlying. \\
+  Allowable values: Any positive number.
+  \item{}[number] \lstinline!StrikePrices!: The strike prices used within the calculation agent. \\
+  Allowable values: Any number.
+  \item{}[number] \lstinline!KnockInPrices!: The agreed European knock-in barrier level. \\
+  Allowable values: Any number.
+  \item{}[number] \lstinline!Quantity!: A quantity multiplier applied to the payoff. \\
+  Allowable values: Any number.
+  \item{}[number] \lstinline!BarrierLevels!: The agreed barrier level. \\
+  Allowable values: Any number.
+  \item{}[number] \lstinline!BonusCoupon!: A percentage. \\
+  Allowable values: Any number.
+  \item{}[event] \lstinline!ObservationDate!: The date on which the final levels of the assets are determined. \\
+  Allowable values: See \lstinline!Date! in Table \ref{tab:allow_stand_data}.
+  \item{}[event] \lstinline!SettlementDate!: The settlement date for the payoff. \\
+  Allowable values: See \lstinline!Date! in Table \ref{tab:allow_stand_data}.
+  \item{}[currency] \lstinline!PayCcy!: The payment currency. For FX, where the underlying is provided
+      in the form \lstinline!FX-SOURCE-CCY1-CCY2! (see Table \ref{tab:fxindex_data}) this should
+      be \lstinline!CCY2!. If \lstinline!CCY1! or the currency of the underlying (for EQ and
+      COMM underlyings), this will result in a quanto payoff. The \lstinline!StrikePrices! and \lstinline!BarrierLevels! should be expressed in
+      as amount of CCY1 in CCY2.Notice section ``Payment Currency'' in ore/Docs/ScriptedTrade. \\
+        Allowable values: See Table \ref{tab:currency} for allowable currency codes.
+\end{itemize}