Skip to content

Commit f06c7ad

Browse files
author
Sjogren
committed
Merge remote-tracking branch 'origin/master' into feature/martin_docs1
2 parents b5c845e + 735df28 commit f06c7ad

106 files changed

Lines changed: 18922 additions & 11657 deletions

File tree

Some content is hidden

Large Commits have some content hidden by default. Use the searchbox below for content that may be hidden.

‎Docs/UserGuide/examples/examples.tex‎

Lines changed: 29 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -1071,6 +1071,11 @@ \subsection{Exposure}\label{example:exposure}
10711071
\item Flip View, switch perspectives easily for XVA: {\tt python run\_flipview.py}
10721072
\end{itemize}
10731073
1074+
Parameter calibration for exposure simulation model:
1075+
\begin{itemize}
1076+
\item HW n-factor historical calibration: {\tt python run\_hwhistoricalcalibration.py}
1077+
\end{itemize}
1078+
10741079
All cases are discussed in the following subsections.
10751080
10761081
\subsubsection{Swap with flat yield curve}\label{example:exposure_swapflat}
@@ -1805,6 +1810,30 @@ \subsubsection{Flip View}\label{example:exposure_flipview}
18051810
demonstrates how ORE can be used to quickly switch perspectives in XVA calculations with minimal changes in the {\tt ore.xml}
18061811
file only. In particular it avoids manipulating the portfolio input or the netting set.
18071812
1813+
\subsubsection{HW n-Factor Historical Calibration}\label{example:exposure_hwhistoricalcalibration}
1814+
1815+
Calling
1816+
1817+
\medskip
1818+
\centerline{\tt python run\_hwhistoricalcalibration.py }
1819+
\medskip
1820+
1821+
demonstrates how ORE provides functionality to calibrate the mean reversion speed($\kappa$) and volatility($\sigma$) parameters for the Hull-White $n$-factor model using historical market data. Two approaches are available:
1822+
1823+
\begin{enumerate}
1824+
\item Full Calibration Using Historical Data
1825+
\begin{itemize}
1826+
\item ORE performs Principal Component Analysis (PCA) on historical interest rate curves and FX spot data.
1827+
\item Based on PCA results, ORE will use eigenvalues and eigenvectors to calibrate constant parameters for the HW $n$-factor model, including $\kappa$ and $\sigma$.
1828+
\end{itemize}
1829+
1830+
\item Mean Reversion Calibration Only
1831+
\begin{itemize}
1832+
\item Users can provide their own eigenvalues and eigenvectors for each curve.
1833+
\item ORE will then perform mean reversion calibration using these inputs without recalculating PCA.
1834+
\end{itemize}
1835+
\end{enumerate}
1836+
18081837
18091838
\subsection{Netting Set Exposure and Collateral}\label{example:exposurewithcollateral}
18101839

‎Docs/UserGuide/parameterisation/ore.tex‎

Lines changed: 65 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -446,30 +446,91 @@ \subsubsection{Simulation and Model Calibration}
446446
i.e. to calibrate the simulation model and output the calibrated model data such that it can be used to initialize
447447
a subsequent simulation without recalibration.
448448

449+
Both CAM and HW model are supported for {\tt calibration} 'analytics'. When setting model to CAM, ORE use the following inputs.
450+
449451
\begin{listing}[H]
450452
%\hrule\medskip
451453
\begin{minted}[fontsize=\footnotesize]{xml}
452454
<Analytics>
453455
<Analytic type="calibration">
454456
<Parameter name="active">Y</Parameter>
457+
<Parameter name="model">CAM</Parameter>
455458
<Parameter name="configFile">simulation.xml</Parameter>
456459
<Parameter name="outputFileName">calibration.csv</Parameter>
457460
</Analytic>
458461
</Analytics>
459462
\end{minted}
460-
\caption{ORE analytic: calibration}
461-
\label{lst:ore_calibration}
463+
\caption{ORE analytic: CAM calibration}
464+
\label{lst:ore_calibration_CAM}
462465
\end{listing}
463466

464-
Output is the Cross Asset Model data written to {\tt calibration.xml} in the usual output directory, which contains the calibration
467+
See {\tt Example\_8} for a demonstration.
468+
469+
When setting model to HW, ORE use the following inputs.
470+
471+
\begin{listing}[H]
472+
%\hrule\medskip
473+
\begin{minted}[fontsize=\footnotesize]{xml}
474+
<Analytics>
475+
<Analytic type="calibration">
476+
<Parameter name="active">Y</Parameter>
477+
<Parameter name="model">HW</Parameter>
478+
<Parameter name="mode">historical</Parameter>
479+
<Parameter name="foreignCurrencies">EUR,GBP</Parameter>
480+
<Parameter name="curveTenors">1Y,2Y,3Y,5Y,10Y,15Y,20Y,30Y</Parameter>
481+
<Parameter name="useForwardOrZeroRate">zero</Parameter>
482+
<Parameter name="pcaCalibration">Y</Parameter>
483+
<Parameter name="scenarioInputFile">scenario.csv</Parameter>
484+
<Parameter name="startDate">2019-09-29</Parameter>
485+
<Parameter name="endDate">2022-09-27</Parameter>
486+
<Parameter name="lambda">1</Parameter>
487+
<Parameter name="varianceRetained">0.90</Parameter>
488+
<Parameter name="pcaOutputFileName">pca.csv</Parameter>
489+
<Parameter name="pcaInputFileName">pca_USD.csv,pca_EUR.csv,pca_GBP.csv</Parameter>
490+
<Parameter name="meanReversionCalibration">Y</Parameter>
491+
<Parameter name="basisFunctionNumber">2</Parameter>
492+
<Parameter name="kappaUpperBound">5.0</Parameter>
493+
<Parameter name="haltonMaxGuess">500</Parameter>
494+
<Parameter name="meanReversionOutputFileName">meanReversion.csv</Parameter>
495+
</Analytic>
496+
</Analytics>
497+
\end{minted}
498+
\caption{ORE analytic: HW calibration}
499+
\label{lst:ore_calibration_HW}
500+
\end{listing}
501+
The parameters have the following interpretation:
502+
503+
\begin{itemize}
504+
\item {\tt model:} The model for Calibration, can be either {\tt CAM} or {\tt HW}, default to {\tt CAM} when left blank or omitted.
505+
\item {\tt mode:} The calibration mode, must be {\tt historical} for now. Will be ignored if {\tt model} node set to {\tt CAM}.
506+
\item {\tt foreignCurrencies:} The list of foreign currencies that need the calibration. Will be ignored if {\tt model} node set to {\tt CAM}.
507+
\item {\tt curveTenors:} The list of tenors for each IR curve when providing historical discount factors or the tenor list of each value in eigenvectors. Will be ignored if {\tt model} node set to {\tt CAM}.
508+
\item {\tt useForwardOrZeroRate:} When {\tt pcaCalibration} set to {\tt true}, this means whether zero rate or forward rate will be used to calculate the covariance matrix for PCA calibration. When {\tt pcaCalibration} set to {\tt false}, this means whether zero rate or forward rate should be used to parse the provided PCA eigenvectors for mean reversion calibration.
509+
\item {\tt pcaCalibration:} When set to {\tt true}, ORE will read the historical discount factors and perform PCA calibration. Will be ignored if {\tt model} node set to {\tt CAM}.
510+
\item {\tt scenarioInputFile:} The path to the file which contains the historical discount factors and historical FX spot rates. Must be in the scenario.csv ORE format. Only needed when {\tt pcaCalibration} set to {\tt true}.
511+
\item {\tt startDate:} Start date of the historical data that will be used in calibration. Only needed when {\tt pcaCalibration} set to {\tt true}.
512+
\item {\tt endDate:} End date of the historical data that will be used in calibration. Only needed when {\tt pcaCalibration} set to {\tt true}.
513+
\item {\tt lambda:} The lambda used on exponentially-weighted historical rates diffs when computing the covariance matrix. The covariance matrix will be equally weighted when {\tt lambda} is set to {\tt 1}. Only needed when {\tt pcaCalibration} set to {\tt true}.
514+
\item {\tt varianceRetained:} The ratio between the combined variance of retained principal components and total variance. This decides how many principal components will be retained. Only needed when {\tt pcaCalibration} set to {\tt true}.
515+
\item {\tt pcaOutputFileName:} The output file name of eigenvalues and eigenvectors retained for each currency.
516+
\item {\tt pcaInputFileName:} The list of file names where eigenvalues and eigenvectors are provided for mean reversion calibration. The files should be one curve per file. Only needed when {\tt pcaCalibration} is set to {\tt false} and {\tt meanReversionCalibration} is set to {\tt true}.
517+
\item {\tt meanReversionCalibration:} When set to {\tt true}, ORE will perform mean reversion calibration on principal components retained either from previous pca calibration step or from input files.
518+
\item {\tt basisFunctionNumber:} Number of basis functions used in mean reversion calibration.
519+
\item {\tt kappaUpperBound:} The upper bound of kappa during mean reversion calibration.
520+
\item {\tt haltonMaxGuess:} Number of max guess in optimization in mean reversion calibration.
521+
\item {\tt meanReversionOutputFileName:} The output file name for kappa and v for each curve.
522+
\end{itemize}
523+
524+
For both CAM and HW model calibration, output is the Cross Asset Model data written to {\tt calibration.xml} in the usual output directory, which contains the calibration
465525
results in place of the initial values for all parametrizations covered so far (IR, FX, EQ, INF, COM). In a subsequent run one could replace
466526
the {\tt CrossAssetModel} section in {\tt simulation.xml} with the output in {\tt calibration.xml} to re-run without re-calibration.
467527
Note that the {\tt Calibrate} flags in the output Cross Asset Model data are set to {\tt false}.
468528

469529
Additionally, the Cross Asset Model XML is written as a single XML string to the calibration report {\tt calibration.csv}, also held in
470530
memory for further processing e.g. via ORE's Python interface.
471531

472-
See {\tt Example\_8} for a demonstration.
532+
For HW model, there is an additional output {\tt calibration\_StatisticalWithRiskNeutralVolatility.xml} which is used for multi-factor sigma risk neutral calibration. Similarly, {\tt calibration\_StatisticalWithRiskNeutralVolatility.csv} is also outputted.
533+
473534

474535
\subsubsection{Scenario Generation}
475536

0 commit comments

Comments
 (0)