merge with master

Author: rolandlichters

Docs/UserGuide/userguide.tex

@@ -128,7 +128,7 @@
 %\title{Open Source Risk Engine \\ User Guide  }
 \title{ORE User Guide}
 \author{Acadia Inc.}
-\date{27 March 2023}
+\date{3 March 2023}
 \maketitle
 
 \newpage
@@ -149,7 +149,7 @@ \section*{Document History}
 30 June 2021 & Acadia & updates for release 6\\
 16 September 2022 & Acadia & updates for release 7\\
 6 December 2022 & Acadia & updates for release 8\\
-27 March 2023 & Acadia & updates for release 9\\
+3 March 2023 & Acadia & updates for release 9\\
 \hline
 \end{supertabular}
 \end{center}
@@ -221,15 +221,25 @@ \subsubsection*{Scope and Roadmap}
 The sensitivity framework yields further {\bf market risk measures} such as ORE's parametric Value at Risk which takes deltas, vegas, gammas and cross gammas into account. This may be used to benchmark initial margin models such ISDA's Standard Initial Margin Model. \\
 
 \medskip
-Subsequent ORE releases will also compute {\bf regulatory capital charges} for counterparty credit risk under the new standardised approach (SA-CCR), and the Monte Carlo based market risk measures will be complemented by parametric methods, e.g. for benchmarking various initial margin calculation models applied in cleared and non-cleared derivatives business.
+Subsequent ORE releases will also compute {\bf regulatory capital charges} for counterparty credit risk under the standardised approach (SA-CCR), and the market risk measures will be extended , e.g. for benchmarking various initial margin calculation models applied in cleared and non-cleared derivatives business.
+
+\medskip
+In September 2022 Acadia announced to contribute a wide range of financial instruments (currently in its proprietary extension of ORE) in a series of quarterly releases:
+\begin{itemize}
+\item Commodity products (Swaps, Basis Swaps, Av. Price Options, Swaptions), released December 22 with ORE v8
+\item Credit products (Index CDS and Index CDS Options, Credit-Linked Swaps, Synthetic CDOs), released March 23 with ORE v9
+\item Bond products and Hybrids (Bond Options, Bond Repos, Bond TRS, Convertible Bonds, Generic TRS with mixed basket underlyings, CFDs), to be released in June 23
+\item Exotics (Scripted trade framework for modelling highly structured hybrid payoffs such as Accumulators, TARFs, PRDCs, etc.), to be released in September 23
+\end{itemize}
+These contributions were (and will be) accompanied by analytics extensions to enhance ORE usability:
+\begin{itemize}
+\item Credit exposure including Commodity and American Monte Carlo for Exotics, released in December 22 with ORE v8
+\item Market Risk including multi-threaded sensitivities, par sensitivity, delta/gamma VaR, released in March 23 with ORE v9
+\item Portfolio Credit Model, to be released in June 23
+\end{itemize}
 
 \medskip 
-%The first release of ORE in October 2016 covers the simulation of interest rate and FX risk factors and
-%portfolios of Interest Rate Swaps, Caps/Floors, Swaptions, FX Forwards, Cross Currency Swaps and FX Options. Subsequent
-%releases from Q1 2017 onwards will extend the derivative product and the risk factor range to Inflation, Credit, Equity
-%and Commodity. With the introduction of credit risk factors, the scope will also be extended to cover cash products
-%(loans and bonds) and related portfolio analytics.
-The product coverage of the seventh release of ORE in September 2022 is sketched in Table \ref{tab_coverage}.
+The product coverage of the 9th release of ORE in March 2023 is sketched in Table \ref{tab_coverage}.
 \begin{table}[hbt]
 \scriptsize
 \begin{center}
@@ -281,17 +291,20 @@ \subsubsection*{Scope and Roadmap}
 \hline
 Year-on-Year Inflation Caps/Floors & Y & Y & N & N\\
 \hline
-Credit Default Swaps & Y & Y & N & N \\
+Credit Default Swaps, Options & Y & Y & N & Y \\
+\hline
+Index Credit Default Swaps, Options & Y & Y & N & Y \\
+\hline
+Credit Linked Swaps & Y & Y & N & Y \\
+\hline
+Index Tranches, Synthetic CDOs & Y & Y & N & Y \\
 \hline
-
 \end{tabular}
 \caption{ORE product coverage. FX/Equity Exotics include Barrier, Digital, Digital Barrier (FX only), Double Barrier, European Barrier, KIKO Barrier (FX only), Touch and Double Touch Options.}
 \label{tab_coverage}
 \end{center}
 \end{table}
 
-Future releases will further extend the product range and analytics coverage indicated in the table above, expand on the market risk analytics, add integrated credit/market risk analytics. 
-
 \medskip The simulation models applied in ORE's risk factor evolution implement the models discussed in detail in {\em
   Modern Derivatives Pricing and Credit Exposure Analysis} \cite{Lichters}: The IR/FX/INF/EQ risk factor evolution is based on
 a cross currency model consisting of an arbitrage free combination of Linear Gauss Markov models for all interest rates
@@ -320,92 +333,92 @@ \subsubsection*{Organisation of this document}
 \section{Release Notes}\label{sec:releasenotes}
 %========================================================
 
-This section summarises the notable changes between release 7 (September 2022) and 8 (December 2022).
+This section summarises the notable changes between release 8 (December 2022) and 9 (March 2023).
 
 \bigskip
 INSTRUMENTS 
 \begin{itemize}
-\item roll out Commodity derivatives, thanks to Acadia Inc., as announced in September 22:
+\item roll out of Credit derivatives, thanks to Acadia Inc., as announced in September 22:
   \begin{itemize}
-    \item add Commodity Swap
-    \item add Commodity Swaption
-    \item add Commodity Average Price Option
-    \item add Commodity Option Strips and Digital Option Strip
+	\item Bond Option
+	\item Bond Repo
+  	\item Bond Total Return Swap
+  	\item Credit-Linked Swap
+  	\item Index Credit Default Swap
+  	\item Index Credit Default Swap Option
+  	\item Credit Index Tranche, Synthetic CDO
   \end{itemize}
-  see user guide and in particular Example 24
-\item add Equity Cliquet Option, missed in the 7th release, thanks to Acadia
-\item add Equity/FX/Commodity Variance Swap, missed in the 7th release, thanks to Acadia
-\item introduce separate trade types for Cross Currency and Inflation Swap
-\item merge QuantExt and QuantLib CDS and midpoint engine in ORE's QuantLib fork;
-  QuantLib pull request to follow
+ including related models and pricing engines    
+\item optimize performance for the analytical Commodity Swaption engine
+\item add missing FxIndex registrations in Commodity APO and Commodity Indexed Average Cashflows
+\item include leg NPVs in additional results of CDS products
+\item fix LGM Swaption pricing for cases where fixing date < exercise date
 \end{itemize}
 
 \bigskip
-MARKETS
+MARKETS \& TERM STRUCTURES
 
 \begin{itemize}
-\item performance optimizations for curve builders
-\item extend the market interface to optionally handle precious metals and crypto currencies as commodities instead of FX
-\end{itemize}
-
-\bigskip
-TERM STRUCTURES
-
-\begin{itemize}
-\item (no notable changes)
+\item fix shifted lognormal Swaption vol surface (SwaptionVolCubeWithATM, add missing shift)
 \end{itemize}
 
 \bigskip
 ANALYTICS
 
 \begin{itemize}
-\item add American Monte Carlo simulation components to support fast Bermudan Swaption
-  exposure simulation and more, thanks to Acadia;\\
-  the integration into the ORE command line app will follow with the next release (March 23)
-  as it requires some refactoring.
-\item add Commodity simulation to the cross asset model and market simulation, integraded
-  with the LGM-based Cross Asset Model, thanks to Acadia
-\item  add a multi-factor Hull-White / FX / Commodity simulation model, thanks to Acadia; 
-  calibration to be added
+\item integrate American Monte Carlo simulation, see the {\bf new Example 39}
+\item add Par Sensitivity Analysis, see the {\bf new Example 40}
+\item add more parametric VaR types (delta-gamma normal, delta-gamma Saddlepoint)
+\item support multi-threading in sensitivity analysis
+\item support multi-threading in exposure simulation, see the {\bf new Example 41}
+\item fix exposure/XVA analytics with simulation of fixings for ceased IBOR indices
 \end{itemize}
 
 \bigskip
 TESTS
 
 \begin{itemize}
-\item QuantExt: 242 test functions (vs 214 in the previous release)
-\item OREData: 199 test functions (vs. 192 in the previous release)
-\item OREAnalytics: 66 test functions (vs. 65 in the previous release)
+\item QuantExt: 263 test functions (vs 242 in the previous release)
+\item OREData: 203 test functions (vs. 199 in the previous release)
+\item OREAnalytics: 68 test functions (vs. 66 in the previous release)
 \end{itemize}
-with associated increases in the number of data driven test cases 
 
 \bigskip
 DOCUMENTATION
 
 \begin{itemize}
-\item the user guide is maintained continuously incorporating user feedback, in particular
-  from Acadia service clients; it has grown from 404 to 440 pages, mainly due to the
-  migration of Commodity and Equity/FX instruments into ORE
+\item The user guide has grown from 440 to 480 pages, mainly due to the
+  migration of Credit derivative instruments into ORE, as well as new examples
 \end{itemize}
 
 \bigskip
 LANGUAGE BINDUNGS
 
 \begin{itemize}
-\item maintenance to ensure ORE SWIG wrappers build with the current ORE release,
-  QuantLib-1.28 and QuantLib-SWIG-1.28
-\end{itemize}
+\item The SWIG wrapper has been extended to provide access to ORE input
+  construction in memory and to query in-memory results (reports etc), in line
+  with the refactoring mentioned below.
+  See the {\bf new Python example} OREAnalytics-SWIG/Python/Examples/ore3.py
+\item To facilitate access to ORE Python, we are providing Python wheels for various
+  OS types and Python versions starting with this release, thanks to Eric Ehlers's
+  effort and Luigi Ballabio's support to get in up and running using github actions.
+  See the \href{https://github.com/OpenSourceRisk/ORE-SWIG#readme}{ORE-SWIG repository} for {\bf how to install the ORE module}.
+  \end{itemize}
 
 \bigskip
 OTHER
 
 \begin{itemize}
-\item changes to build with QuantLib 1.28
-\item extend the CMake setup for Windows / Visual Studio users; \\
-  We will stop maintaining the *.vcxproj and *.vcxproj.filters from the now on
-  and rely on CMakeLists for both *nix and Windows. \\
-  See section 4.2.3 on how to "Generate Visual Studio Projects with CMake"
-\end{itemize}
+\item Refactor the serialization of NPV cube and market cube (aggregation scenario data)
+\item Refactor OREAnalytics/orea/app by separating input construction from processing
+  and persisting results. This is to faciliate re-using the processing element
+  (analyticsManager->runAnalytics(...)) in different applications, a command line
+  application such as ore[.exe] that reads/writes from/to files, an ORE Python wrapper
+  that receives input and provides results in memory (see language bindings above),
+  or a REST service built around ORE. Results (reports, cubes etc) are stored in
+  memory and only saved to files on demand. Inputs for the ORE processor can be
+  assembled in memory, or read from files.
+  \end{itemize}
 
 %========================================================
 \section{ORE Data Flow}\label{sec:process}
@@ -999,11 +1012,11 @@ \section{Examples}\label{sec:examples}
 \hline
 38 & Cross Currency Exposure using Multifactor Hull-White Models \\
 \hline
-39 & EPE and ENE computed with AMC valuation engine \\
+39 & Exposure Simulation using American Monte Carlo \\
 \hline
-40 & Sensitivity analysis including par sensitivities \\
+40 & Par Sensitivity Analysis \\
 \hline
-41 & Exposure generation using multithreaded valuation engine \\
+41 & Multi-threaded Exposure Simulation \\
 \end{tabular}
 \caption{ORE examples.}
 \label{tab_0}
@@ -2536,22 +2549,7 @@ \subsection{Exposure Simulation using American Monte Carlo}% Example 39
   \label{epe_fxoption}
 \end{figure}
 
-%--------------------------------------------------------------------
-\subsection{Sensitivity analysis including par sensitivities}% Example 40
-\label{example:40}
-%--------------------------------------------------------------------
-
-The example in folder {\tt Examples/Example\_40} demonstrates the generation of zero and par sensitivities.
-
-%--------------------------------------------------------------------
-\subsection{Sensitivity analysis including par sensitivities}% Example 41
-\label{example:41}
-%--------------------------------------------------------------------
-
-The example in folder {\tt Examples/Example\_41} uses the multithreaded valuation engine to generate the exposure for a
-portfolio of 8 copies of the vanilla swap in example 1.
-
-\subsubsection{Analytic Configuration}
+\subsubsection*{Analytic Configuration}
 
 To use the AMC engine for an XVA simulation the following needs to be added to the {\tt simulation} analytic in {\tt ore.xml}:
 
@@ -2894,6 +2892,15 @@ \subsection{Par Sensitivity Analysis}% Example 40
 Finally note that par sensitivity analysis requires that the shift tenor grid in the sensitivity data above matches the corresponding grid in the simulation (market) configuration.
 See also section \ref{sec:sensitivity}.
 
+%--------------------------------------------------------------------
+\subsection{Multi-threaded Exposure Simultion}% Example 41
+\label{example:41}
+%--------------------------------------------------------------------
+
+The example in folder {\tt Examples/Example\_41} demonstrates the multithreaded valuation engine to generate the exposure for a
+portfolio of 8 copies of the vanilla swap in {\tt Example\_1}.
+
+
 \clearpage
 %========================================================
 \section{Launchers and Visualisation}\label{sec:visualisation}

News.txt

@@ -2,7 +2,7 @@ Changes for the 9th ORE release (1.8.9.0):
 ============================================
 
 ORE 1.8.9.0 includes the following notable changes, details can be
-found in the commits between December 2022 and March 2023.
+found in the commits between December 2022 and beginning of March 2023.
 
 INSTRUMENTS
 - roll out of Credit derivatives, thanks to Acadia Inc., as announced in September 22:
@@ -12,30 +12,53 @@ INSTRUMENTS
   * Credit-Linked Swap
   * Index Credit Default Swap
   * Index Credit Default Swap Option
-  * Credit Index Tranches
-  Including related models and pricing engines
+  * Credit Index Tranche, Synthetic CDO
+  including related models and pricing engines
+- optimize performance for the analytical Commodity Swaption engine
+- add missing FxIndex registrations in Commodity APO and Commodity Indexed Average Cashflows
+- include leg NPVs in additional results of CDS products
+- fix LGM Swaption pricing for cases where fixing date < exercise date
 
 MARKETS & TERM STRUCTURES
--
+- fix shifted lognormal Swaption vol surface (SwaptionVolCubeWithATM, add missing shift)
 
 ANALYTICS
-- integrate American Monte Carlo simulation, add related Example 39
-- add par sensitivity analysis, see example ???
-- add more parametric VaR types (delta-gamma normal, delta-gamma Saddlepoint), see example ???
-- add multi-threaded valuation engine for sensitivity analysis, see example ???
+- integrate American Monte Carlo simulation, see the new Example 39
+- add Par Sensitivity Analysis, see the new Example 40
+- add more parametric VaR types (delta-gamma normal, delta-gamma Saddlepoint)
+- support multi-threading in sensitivity analysis
+- support multi-threading in exposure simulation, see the new Example 41
+- fix exposure/XVA analytics with simulation of fixings for ceased IBOR indices
 
 TEST
--
+- QuantExt: 263 test functions (vs 242 in the previous release)
+- OREData: 203 test functions (vs. 199 in the previous release)
+- OREAnalytics: 68 test functions (vs. 66 in the previous release)
 
 DOCUMENTATION
-- the user guide has grown from 440 to 475 pages, mainly due to the
-  migration of Credit derivative instruments into ORE
+- The user guide has grown from 440 to 480 pages, mainly due to the
+  migration of Credit derivative instruments into ORE, as well as new examples
 
 LANGUAGE BINDINGS
--
+- The SWIG wrapper has been extended to provide access to ORE input
+  construction in memory and to query in-memory results (reports etc), in line
+  with the refactoring mentioned below.
+  See the new Python example OREAnalytics-SWIG/Python/Examples/ore3.py
+- To facilitate access to ORE Python, we are providing Python wheels for various
+  OS types and Python versions starting with this release, thanks to Eric Ehlers's
+  effort and Luigi Ballabio's support to get in up and running using github actions.
+  See the ORE-SWIG repository for how to install the ORE module.
 
 OTHER
--
+- Refactor the serialization of NPV cube and market cube (aggregation scenario data)
+- Refactor OREAnalytics/orea/app by separating input construction from processing
+  and persisting results. This is to faciliate re-using the processing element
+  (analyticsManager->runAnalytics(...)) in different applications, a command line
+  application such as ore[.exe] that reads/writes from/to files, an ORE Python wrapper
+  that receives input and provides results in memory (see language bindings above),
+  or a REST service built around ORE. Results (reports, cubes etc) are stored in
+  memory and only saved to files on demand. Inputs for the ORE processor can be
+  assembled in memory, or read from files.
 
 
 Changes for the 8th ORE release (1.8.8.0):

OREAnalytics/orea/app/inputparameters.hpp

@@ -625,49 +625,6 @@ inline const std::string& InputParameters::marketConfig(const std::string& conte
     auto it = marketConfigs_.find(context);
     return (it != marketConfigs_.end() ? it->second : Market::defaultConfiguration);
 }
-
-    /*
-//! Traditional ORE input via ore.xml and various files, output into files
-class OREAppInputParameters : public InputParameters {
-public:
-    OREAppInputParameters(const boost::shared_ptr<Parameters>& params) : params_(params) {
-        loadParameters();
-    }
-
-    void loadParameters() override;
-    void writeOutParameters() override;
-
-    const boost::shared_ptr<CSVLoader>& csvLoader() { return csvLoader_; }
-
-    //! map internal report name to the configured external file name
-    const std::map<std::string, std::string>& fileNameMap() { return fileNameMap_; }
-    std::string outputFileName(const std::string& internalName, const std::string& suffix);
-    
-private:
-    boost::shared_ptr<Parameters> params_;
-    boost::shared_ptr<CSVLoader> csvLoader_;
-
-    std::map<std::string, std::string> fileNameMap_;
-    
-    std::string npvOutputFileName_;
-    std::string cashflowOutputFileName_;
-    std::string curvesOutputFileName_;
-    std::string scenarioDumpFileName_;
-    std::string cubeFileName_;
-    std::string mktCubeFileName_;
-    std::string rawCubeFileName_;
-    std::string netCubeFileName_;
-    std::string dimEvolutionFileName_;
-    std::vector<std::string> dimRegressionFileNames_;
-    std::string sensitivityFileName_;
-    std::string sensitivityScenarioFileName_;
-    std::string parSensitivityFileName_;
-    std::string jacobiFileName_;
-    std::string jacobiInverseFileName_;
-    std::string stressTestFileName_;
-    std::string varFileName_;
-};
-    */
 
 //! Traditional ORE input via ore.xml and various files, output into files
 class OutputParameters {