Skip to content

Commit 8c49eff

Browse files
pcasperspcaspers
committed
Merge remote-tracking branch 'origin/master' into feature/QPR-13646
2 parents bf28a9c + f4b6a31 commit 8c49eff

40 files changed

Lines changed: 4788 additions & 136 deletions

‎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

‎Examples/Exposure/ExpectedOutput/hwhistoricalcalibration/calibration.xml‎

Lines changed: 135 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,135 @@
1+
<CrossAssetModel>
2+
<DomesticCcy>USD</DomesticCcy>
3+
<Currencies>
4+
<Currency>USD</Currency>
5+
<Currency>EUR</Currency>
6+
<Currency>GBP</Currency>
7+
</Currencies>
8+
<BootstrapTolerance>0.0001</BootstrapTolerance>
9+
<Discretization>Euler</Discretization>
10+
<Measure>BA</Measure>
11+
<InterestRateModels>
12+
<HWModel key="EUR-EURIBOR-3M">
13+
<CalibrationType>None</CalibrationType>
14+
<Volatility>
15+
<Calibrate>N</Calibrate>
16+
<VolatilityType>HullWhite</VolatilityType>
17+
<ParamType>Constant</ParamType>
18+
<TimeGrid/>
19+
<InitialValue>
20+
<Sigma>
21+
<Row>-0.0229152, 0.00802074, 0, 0</Row>
22+
<Row>0, 0, -0.0236755, 0.0272979</Row>
23+
</Sigma>
24+
</InitialValue>
25+
</Volatility>
26+
<Reversion>
27+
<Calibrate>N</Calibrate>
28+
<ReversionType>HullWhite</ReversionType>
29+
<ParamType>Constant</ParamType>
30+
<TimeGrid/>
31+
<InitialValue>
32+
<Kappa>4.99999, 0.0305188, 0.0350268, 0.0723209</Kappa>
33+
</InitialValue>
34+
</Reversion>
35+
</HWModel>
36+
<HWModel key="GBP-LIBOR-3M">
37+
<CalibrationType>None</CalibrationType>
38+
<Volatility>
39+
<Calibrate>N</Calibrate>
40+
<VolatilityType>HullWhite</VolatilityType>
41+
<ParamType>Constant</ParamType>
42+
<TimeGrid/>
43+
<InitialValue>
44+
<Sigma>
45+
<Row>0.00884376, -0.0149944, 0, 0</Row>
46+
<Row>0, 0, -0.0319848, 0.0372505</Row>
47+
</Sigma>
48+
</InitialValue>
49+
</Volatility>
50+
<Reversion>
51+
<Calibrate>N</Calibrate>
52+
<ReversionType>HullWhite</ReversionType>
53+
<ParamType>Constant</ParamType>
54+
<TimeGrid/>
55+
<InitialValue>
56+
<Kappa>0.00971349, 5, 0.0644724, 0.111779</Kappa>
57+
</InitialValue>
58+
</Reversion>
59+
</HWModel>
60+
<HWModel key="USD-LIBOR-3M">
61+
<CalibrationType>None</CalibrationType>
62+
<Volatility>
63+
<Calibrate>N</Calibrate>
64+
<VolatilityType>HullWhite</VolatilityType>
65+
<ParamType>Constant</ParamType>
66+
<TimeGrid/>
67+
<InitialValue>
68+
<Sigma>
69+
<Row>-0.0122469, 0.0105949, 0, 0</Row>
70+
<Row>0, 0, 0.0324875, -0.027352</Row>
71+
</Sigma>
72+
</InitialValue>
73+
</Volatility>
74+
<Reversion>
75+
<Calibrate>N</Calibrate>
76+
<ReversionType>HullWhite</ReversionType>
77+
<ParamType>Constant</ParamType>
78+
<TimeGrid/>
79+
<InitialValue>
80+
<Kappa>1.18575, 0.0189524, 0.0883031, 0.0448402</Kappa>
81+
</InitialValue>
82+
</Reversion>
83+
</HWModel>
84+
</InterestRateModels>
85+
<ForeignExchangeModels>
86+
<CrossCcyLGM foreignCcy="EUR">
87+
<DomesticCcy>USD</DomesticCcy>
88+
<CalibrationType>None</CalibrationType>
89+
<Sigma>
90+
<Calibrate>N</Calibrate>
91+
<ParamType>Constant</ParamType>
92+
<TimeGrid/>
93+
<InitialValue>0.0719723</InitialValue>
94+
</Sigma>
95+
</CrossCcyLGM>
96+
<CrossCcyLGM foreignCcy="GBP">
97+
<DomesticCcy>USD</DomesticCcy>
98+
<CalibrationType>None</CalibrationType>
99+
<Sigma>
100+
<Calibrate>N</Calibrate>
101+
<ParamType>Constant</ParamType>
102+
<TimeGrid/>
103+
<InitialValue>0.0935444</InitialValue>
104+
</Sigma>
105+
</CrossCcyLGM>
106+
</ForeignExchangeModels>
107+
<InstantaneousCorrelations>
108+
<Correlation factor1="FX:EURUSD" factor2="FX:GBPUSD" index1="0" index2="0">0.618322</Correlation>
109+
<Correlation factor1="IR:EUR-EURIBOR-3M" factor2="FX:EURUSD" index1="0" index2="0">-0.0255821</Correlation>
110+
<Correlation factor1="IR:EUR-EURIBOR-3M" factor2="FX:EURUSD" index1="1" index2="0">-0.00362845</Correlation>
111+
<Correlation factor1="IR:EUR-EURIBOR-3M" factor2="FX:GBPUSD" index1="0" index2="0">-0.111091</Correlation>
112+
<Correlation factor1="IR:EUR-EURIBOR-3M" factor2="FX:GBPUSD" index1="1" index2="0">-0.0861682</Correlation>
113+
<Correlation factor1="IR:EUR-EURIBOR-3M" factor2="IR:GBP-LIBOR-3M" index1="0" index2="0">0.74608</Correlation>
114+
<Correlation factor1="IR:EUR-EURIBOR-3M" factor2="IR:GBP-LIBOR-3M" index1="0" index2="1">-0.0624759</Correlation>
115+
<Correlation factor1="IR:EUR-EURIBOR-3M" factor2="IR:GBP-LIBOR-3M" index1="1" index2="0">-0.0606025</Correlation>
116+
<Correlation factor1="IR:EUR-EURIBOR-3M" factor2="IR:GBP-LIBOR-3M" index1="1" index2="1">0.53283</Correlation>
117+
<Correlation factor1="IR:EUR-EURIBOR-3M" factor2="IR:USD-LIBOR-3M" index1="0" index2="0">0.653024</Correlation>
118+
<Correlation factor1="IR:EUR-EURIBOR-3M" factor2="IR:USD-LIBOR-3M" index1="0" index2="1">0.159646</Correlation>
119+
<Correlation factor1="IR:EUR-EURIBOR-3M" factor2="IR:USD-LIBOR-3M" index1="1" index2="0">-0.144779</Correlation>
120+
<Correlation factor1="IR:EUR-EURIBOR-3M" factor2="IR:USD-LIBOR-3M" index1="1" index2="1">0.482742</Correlation>
121+
<Correlation factor1="IR:GBP-LIBOR-3M" factor2="FX:EURUSD" index1="0" index2="0">-0.0799031</Correlation>
122+
<Correlation factor1="IR:GBP-LIBOR-3M" factor2="FX:EURUSD" index1="1" index2="0">-0.110196</Correlation>
123+
<Correlation factor1="IR:GBP-LIBOR-3M" factor2="FX:GBPUSD" index1="0" index2="0">-0.0583432</Correlation>
124+
<Correlation factor1="IR:GBP-LIBOR-3M" factor2="FX:GBPUSD" index1="1" index2="0">-0.0737356</Correlation>
125+
<Correlation factor1="IR:GBP-LIBOR-3M" factor2="IR:USD-LIBOR-3M" index1="0" index2="0">0.610888</Correlation>
126+
<Correlation factor1="IR:GBP-LIBOR-3M" factor2="IR:USD-LIBOR-3M" index1="0" index2="1">0.12151</Correlation>
127+
<Correlation factor1="IR:GBP-LIBOR-3M" factor2="IR:USD-LIBOR-3M" index1="1" index2="0">-0.168197</Correlation>
128+
<Correlation factor1="IR:GBP-LIBOR-3M" factor2="IR:USD-LIBOR-3M" index1="1" index2="1">0.417725</Correlation>
129+
<Correlation factor1="IR:USD-LIBOR-3M" factor2="FX:EURUSD" index1="0" index2="0">-0.109284</Correlation>
130+
<Correlation factor1="IR:USD-LIBOR-3M" factor2="FX:EURUSD" index1="1" index2="0">-0.186751</Correlation>
131+
<Correlation factor1="IR:USD-LIBOR-3M" factor2="FX:GBPUSD" index1="0" index2="0">-0.0439526</Correlation>
132+
<Correlation factor1="IR:USD-LIBOR-3M" factor2="FX:GBPUSD" index1="1" index2="0">-0.179559</Correlation>
133+
</InstantaneousCorrelations>
134+
</CrossAssetModel>
135+

0 commit comments

Comments
 (0)