Merge branch 'feature/QPR-13598' into 'master'

Resolve QPR-13598 commodity Schwartz 1F model calibration

Closes QPR-13598

See merge request qs/oreplus!3005

Author: pcaspers

Docs/UserGuide/methods/simulation.tex

@@ -110,9 +110,9 @@ \subsubsection*{Commodity}
 
 Each commodity component models the commodity price curve as 
 \begin{eqnarray}
-\frac{dF(t,T)}{F(t,T)} &=& \sigma\,e^{-\kappa\,(T-t)}\, dW(t)  \label{gabillon1f}
+\frac{dF(t,T)}{F(t,T)} &=& \alpha(T) \sigma\,e^{-\kappa\,(T-t)}\, dW(t)  \label{gabillon1f}
 \end{eqnarray}
-which is a single-factor version of the Gabillon (1991) model that is e.g. described in \cite{Lichters}. It can also be seen as the Schwartz (1997) model formulated in terms of forward curve dynamics. The extension to the full Gabillon model with two factors and time-dependent multiplier
+where $\alpha(T) : = \exp( b(T)) $ is the time dependent \footnote{See section 7.2 in Andersen \cite{Andersen_2008} for the discussion on dependence of seasonality adjustment to calendar days and expiry of future contracts.} multiplier to capture seasonality effect observed in the market for both commodity future price curves and option volatilities. This model is a single-factor version of the Gabillon (1991) model that is e.g. described in \cite{Lichters}. It can also be seen as the Schwartz (1997) model formulated in terms of forward curve dynamics. The extension to the full Gabillon model with two factors and time-dependent multiplier\footnote{Andersen \cite{Andersen_2008} worked on a two factor set up, where the first factor affects the short-end of the futures curve and has the form the $e^{b(T)}$, and the second factor has an additional term containing $e^{a(T)}h_{\infty}$ for long futures maturities.} 
 \begin{eqnarray}
 \frac{dF(t,T)}{F(t,T)} &=& \alpha(t)\,
 \left( \sigma_S \,e^{-\kappa\,(T-t)}\, dW_S(t) + \sigma_L\,\left(1-e^{-\kappa\,(T-t)}\right)\,dW_L(t)\right) \label{gabillon2f}
@@ -128,8 +128,8 @@ \subsubsection*{Commodity}
 \end{align*}
 with 
 \begin{align*}
-F(t,T) &= F(0,T) \:\exp\left( X(t)\,e^{-\kappa\,(T-t)} - \frac{1}{2}\,(V(0,T)-V(t,T))  \right) \\
-V(t,T) &= e^{-2\kappa T}\int_t^T\sigma^2\:e^{2\kappa u}\,du.
+F(t,T) &= F(0,T) \:\exp\left( X(t)\,e^{b(T)-\kappa\,(T-t)} - \frac{1}{2}\,(V(0,T)-V(t,T))  \right) \\
+V(t,T) &= e^{2 (b(T)-\kappa T)}\int_t^T\sigma^2\:e^{2\kappa u}\,du.
 \end{align*}
 Note that 
 $$

Docs/UserGuide/parameterisation/simulation.tex

@@ -572,11 +572,15 @@ \subsubsection{Model}\label{sec:sim_model}
 
 \begin{itemize}
 \item {\tt Currency: } Currency of denomination
-\item {\tt CalibrationType:} Choose between {\em BestFit} and {\em None}.  The choice {\em None} will deactivate calibration as usual. {\em BestFit} will attempt to set the model parameter(s) such that the error in matching calibration instrument prices is minimised.  The option  {\em Bootstrap} is not available here because the model parameters are not time-dependent and the model's degrees of freedom in general do not suffice to perfectly match the calibration instrument prices.
+\item {\tt CalibrationType:} Choose between {\em BestFit},  {\em Bootstrap},  {\em FirstBestFitThanBootstrap}  and {\em None}.  The choice {\em None} will deactivate calibration as usual. {\em BestFit} will attempt to set the model parameter(s) such that the error in matching calibration instrument prices is minimised.  The option {\em Bootstrap} will iteratively attempt to calibrate the time dependent seasonality factor to the calibration instrument prices. The option {\em FirstBestFitThanBootstrap} will first attempt to fit the model parameters (kappa and sigma) as in {\em BestFit} option. Then, time dependent seasonality parameter is bootstrapped as in {\em Bootstrap} option.
 \item {\tt Sigma/Calibrate:} Flag to enable/disable calibration of this particular parameter
 \item {\tt Sigma/InitialValue:} Initial value of the constant parameter
 \item {\tt Kappa/Calibrate:} Flag to enable/disable calibration of this particular parameter
 \item {\tt Kappa/InitialValue:} Initial value of the constant parameter
+\item {\tt Seasonality/Calibrate:} Flag to enable/disable calibration of this particular parameter
+\item {\tt Seasonality/ParamType:} Initial time grid for this parameter, can be left empty if ParamType is Constant
+\item {\tt Seasonality/TimeGrid:} Initial time grid for this parameter. If ParamType is Constant, there should be a single entry
+\item {\tt Seasonality/InitialValue:} Vector of initial values. Size of the vector should be identical to the size of TimeGrid vector.  For {\em Bootstrap} this is ignored.  If ParamType is Constant, there should be a single entry	
 \item {\tt CalibrationOptions:} Choice of calibration instruments by expiry and strike, strikes can be empty 	(implying the default, ATMF options), or explicitly specified (in terms of commodity prices as absolute strike values). 
 \item {\tt DriftFreeState[Optional]:} Boolean to switch between the two implementations of the state variable, see appendix. By default this is set to {\tt false}.        
 \end{itemize}

Docs/UserGuide/references.tex

@@ -97,6 +97,8 @@
 
 \bibitem{Andersen_Piterbark_2010} Andersen, L., \& Piterbarg, V. (2010). Interest Rate Modeling - Volume III: Products and Risk Management. Atlantic Financial Press.
 
+\bibitem{Andersen_2008}  Andersen L.: Markov Models for Commodity Futures: Theory and Practice  2008.
+
 \bibitem{andreasen_huge_localvol} Andreasen J., Huge B.: Volatility Interpolation (2010) \url{https://ssrn.com/abstract=1694972}
 
 \bibitem{Barone-Adesi_1987} Barone-Adesi, G., \& Whaley, R. E. (1987). Efficient Analytic Approximation of American Option Values. The Journal of Finance, Vol. 42, No. 2, 301-320.

Examples/Exposure/ExpectedOutput/commodity/exposure_trade_CommodityAPO.csv

@@ -1,83 +1,83 @@
 #TradeId,Date,Time,EPE,ENE,AllocatedEPE,AllocatedENE,PFE,BaselEE,BaselEEE,TimeWeightedBaselEPE,TimeWeightedBaselEEPE
 CommodityAPO,2016-02-05,0.000000,23150,0,0,0,23150,23150,23150,23150.49,23150.49
-CommodityAPO,2016-05-06,0.248634,22930,0,0,0,34692,22917,23150,22917.12,23150.49
-CommodityAPO,2016-08-05,0.497268,22464,0,0,0,39894,22435,23150,22676.18,23150.49
-CommodityAPO,2016-11-07,0.754098,22778,0,0,0,46772,22725,23150,22692.76,23150.49
-CommodityAPO,2017-02-06,1.003002,22381,0,0,0,50351,22310,23150,22597.69,23150.49
-CommodityAPO,2017-05-05,1.244098,22304,0,0,0,59230,22212,23150,22522.90,23150.49
-CommodityAPO,2017-08-07,1.501632,22490,0,0,0,63419,22376,23150,22497.78,23150.49
-CommodityAPO,2017-11-06,1.750947,22571,0,0,0,64997,22437,23150,22489.11,23150.49
-CommodityAPO,2018-02-05,2.000262,24597,0,0,0,86833,24425,24425,22730.44,23309.38
-CommodityAPO,2018-05-08,2.252317,23819,0,0,0,87396,23638,24425,22831.98,23434.26
-CommodityAPO,2018-08-06,2.498892,23214,0,0,0,118547,23023,24425,22850.84,23532.04
-CommodityAPO,2018-11-05,2.748207,24527,0,0,0,107650,24311,24425,22983.31,23613.07
-CommodityAPO,2019-02-05,3.000262,26586,0,0,0,125236,26336,26336,23264.98,23841.83
-CommodityAPO,2019-05-07,3.249577,25656,0,0,0,108476,25410,26336,23429.56,24033.20
-CommodityAPO,2019-08-05,3.496152,25285,0,0,0,108662,25039,26336,23543.05,24195.62
-CommodityAPO,2019-11-05,3.748207,27370,0,0,0,148052,27100,27100,23782.21,24390.90
-CommodityAPO,2020-02-05,4.000000,29712,0,0,0,185447,29413,29413,24136.66,24707.03
-CommodityAPO,2020-05-05,4.245902,27558,0,0,0,194452,27289,29413,24319.21,24979.58
-CommodityAPO,2020-08-05,4.497268,26042,0,0,0,188174,25795,29413,24401.70,25227.38
-CommodityAPO,2020-11-05,4.748634,25691,0,0,0,165969,25455,29413,24457.47,25448.95
-CommodityAPO,2021-02-05,5.000262,23856,0,0,0,157570,23645,29413,24416.57,25648.43
-CommodityAPO,2021-05-05,5.244098,23866,0,0,0,123069,23681,29413,24382.36,25823.48
-CommodityAPO,2021-08-05,5.496152,23422,0,0,0,135550,23269,29413,24331.30,25988.10
-CommodityAPO,2021-11-05,5.748207,22903,0,0,0,126009,22781,29413,24263.31,26138.28
-CommodityAPO,2022-02-07,6.005741,0,0,0,0,0,0,29413,0.00,0.00
-CommodityAPO,2022-05-05,6.244098,0,0,0,0,0,0,29413,0.00,0.00
-CommodityAPO,2022-08-05,6.496152,0,0,0,0,0,0,29413,0.00,0.00
-CommodityAPO,2022-11-07,6.753687,0,0,0,0,0,0,29413,0.00,0.00
-CommodityAPO,2023-02-06,7.003002,0,0,0,0,0,0,29413,0.00,0.00
-CommodityAPO,2023-05-05,7.244098,0,0,0,0,0,0,29413,0.00,0.00
-CommodityAPO,2023-08-07,7.501632,0,0,0,0,0,0,29413,0.00,0.00
-CommodityAPO,2023-11-06,7.750947,0,0,0,0,0,0,29413,0.00,0.00
-CommodityAPO,2024-02-05,8.000000,0,0,0,0,0,0,29413,0.00,0.00
-CommodityAPO,2024-05-07,8.251366,0,0,0,0,0,0,29413,0.00,0.00
-CommodityAPO,2024-08-05,8.497268,0,0,0,0,0,0,29413,0.00,0.00
-CommodityAPO,2024-11-05,8.748634,0,0,0,0,0,0,29413,0.00,0.00
-CommodityAPO,2025-02-05,9.000262,0,0,0,0,0,0,29413,0.00,0.00
-CommodityAPO,2025-05-06,9.246837,0,0,0,0,0,0,29413,0.00,0.00
-CommodityAPO,2025-08-05,9.496152,0,0,0,0,0,0,29413,0.00,0.00
-CommodityAPO,2025-11-05,9.748207,0,0,0,0,0,0,29413,0.00,0.00
-CommodityAPO,2026-02-05,10.000262,0,0,0,0,0,0,29413,0.00,0.00
-CommodityAPO,2026-05-05,10.244098,0,0,0,0,0,0,29413,0.00,0.00
-CommodityAPO,2026-08-05,10.496152,0,0,0,0,0,0,29413,0.00,0.00
-CommodityAPO,2026-11-05,10.748207,0,0,0,0,0,0,29413,0.00,0.00
-CommodityAPO,2027-02-05,11.000262,0,0,0,0,0,0,29413,0.00,0.00
-CommodityAPO,2027-05-05,11.244098,0,0,0,0,0,0,29413,0.00,0.00
-CommodityAPO,2027-08-05,11.496152,0,0,0,0,0,0,29413,0.00,0.00
-CommodityAPO,2027-11-05,11.748207,0,0,0,0,0,0,29413,0.00,0.00
-CommodityAPO,2028-02-07,12.005464,0,0,0,0,0,0,29413,0.00,0.00
-CommodityAPO,2028-05-05,12.245902,0,0,0,0,0,0,29413,0.00,0.00
-CommodityAPO,2028-08-07,12.502732,0,0,0,0,0,0,29413,0.00,0.00
-CommodityAPO,2028-11-06,12.751366,0,0,0,0,0,0,29413,0.00,0.00
-CommodityAPO,2029-02-05,13.000262,0,0,0,0,0,0,29413,0.00,0.00
-CommodityAPO,2029-05-08,13.252317,0,0,0,0,0,0,29413,0.00,0.00
-CommodityAPO,2029-08-06,13.498892,0,0,0,0,0,0,29413,0.00,0.00
-CommodityAPO,2029-11-05,13.748207,0,0,0,0,0,0,29413,0.00,0.00
-CommodityAPO,2030-02-05,14.000262,0,0,0,0,0,0,29413,0.00,0.00
-CommodityAPO,2030-05-07,14.249577,0,0,0,0,0,0,29413,0.00,0.00
-CommodityAPO,2030-08-05,14.496152,0,0,0,0,0,0,29413,0.00,0.00
-CommodityAPO,2030-11-05,14.748207,0,0,0,0,0,0,29413,0.00,0.00
-CommodityAPO,2031-02-05,15.000262,0,0,0,0,0,0,29413,0.00,0.00
-CommodityAPO,2031-05-06,15.246837,0,0,0,0,0,0,29413,0.00,0.00
-CommodityAPO,2031-08-05,15.496152,0,0,0,0,0,0,29413,0.00,0.00
-CommodityAPO,2031-11-05,15.748207,0,0,0,0,0,0,29413,0.00,0.00
-CommodityAPO,2032-02-05,16.000000,0,0,0,0,0,0,29413,0.00,0.00
-CommodityAPO,2032-05-05,16.245902,0,0,0,0,0,0,29413,0.00,0.00
-CommodityAPO,2032-08-05,16.497268,0,0,0,0,0,0,29413,0.00,0.00
-CommodityAPO,2032-11-05,16.748634,0,0,0,0,0,0,29413,0.00,0.00
-CommodityAPO,2033-02-07,17.005741,0,0,0,0,0,0,29413,0.00,0.00
-CommodityAPO,2033-05-05,17.244098,0,0,0,0,0,0,29413,0.00,0.00
-CommodityAPO,2033-08-05,17.496152,0,0,0,0,0,0,29413,0.00,0.00
-CommodityAPO,2033-11-07,17.753687,0,0,0,0,0,0,29413,0.00,0.00
-CommodityAPO,2034-02-06,18.003002,0,0,0,0,0,0,29413,0.00,0.00
-CommodityAPO,2034-05-05,18.244098,0,0,0,0,0,0,29413,0.00,0.00
-CommodityAPO,2034-08-07,18.501632,0,0,0,0,0,0,29413,0.00,0.00
-CommodityAPO,2034-11-06,18.750947,0,0,0,0,0,0,29413,0.00,0.00
-CommodityAPO,2035-02-05,19.000262,0,0,0,0,0,0,29413,0.00,0.00
-CommodityAPO,2035-05-08,19.252317,0,0,0,0,0,0,29413,0.00,0.00
-CommodityAPO,2035-08-06,19.498892,0,0,0,0,0,0,29413,0.00,0.00
-CommodityAPO,2035-11-05,19.748207,0,0,0,0,0,0,29413,0.00,0.00
-CommodityAPO,2036-02-05,20.000000,0,0,0,0,0,0,29413,0.00,0.00
-CommodityAPO,2036-05-06,20.248634,0,0,0,0,0,0,29413,0.00,0.00
+CommodityAPO,2016-05-06,0.248634,22889,0,0,0,34039,22876,23150,22876.28,23150.49
+CommodityAPO,2016-08-05,0.497268,22393,0,0,0,38709,22364,23150,22620.21,23150.49
+CommodityAPO,2016-11-07,0.754098,22607,0,0,0,45359,22554,23150,22597.78,23150.49
+CommodityAPO,2017-02-06,1.003002,22229,0,0,0,48796,22159,23150,22488.82,23150.49
+CommodityAPO,2017-05-05,1.244098,22112,0,0,0,56998,22020,23150,22398.00,23150.49
+CommodityAPO,2017-08-07,1.501632,22256,0,0,0,61264,22144,23150,22354.43,23150.49
+CommodityAPO,2017-11-06,1.750947,22315,0,0,0,62942,22183,23150,22329.98,23150.49
+CommodityAPO,2018-02-05,2.000262,24233,0,0,0,84121,24064,24064,22546.12,23264.36
+CommodityAPO,2018-05-08,2.252317,23558,0,0,0,85559,23379,24064,22639.31,23353.86
+CommodityAPO,2018-08-06,2.498892,23023,0,0,0,116394,22834,24064,22658.52,23423.94
+CommodityAPO,2018-11-05,2.748207,24365,0,0,0,106283,24151,24151,22793.88,23489.86
+CommodityAPO,2019-02-05,3.000262,26420,0,0,0,123942,26172,26172,23077.66,23715.17
+CommodityAPO,2019-05-07,3.249577,24582,0,0,0,101165,24346,26172,23174.99,23903.64
+CommodityAPO,2019-08-05,3.496152,24312,0,0,0,102180,24076,26172,23238.51,24063.61
+CommodityAPO,2019-11-05,3.748207,26436,0,0,0,141004,26175,26175,23435.97,24205.58
+CommodityAPO,2020-02-05,4.000000,28986,0,0,0,179526,28694,28694,23766.97,24488.13
+CommodityAPO,2020-05-05,4.245902,26118,0,0,0,180681,25863,28694,23888.35,24731.73
+CommodityAPO,2020-08-05,4.497268,24990,0,0,0,179137,24753,28694,23936.69,24953.20
+CommodityAPO,2020-11-05,4.748634,24058,0,0,0,154099,23838,28694,23931.45,25151.23
+CommodityAPO,2021-02-05,5.000262,22302,0,0,0,145963,22105,28694,23839.52,25329.52
+CommodityAPO,2021-05-05,5.244098,22309,0,0,0,115104,22136,28694,23760.29,25485.97
+CommodityAPO,2021-08-05,5.496152,21905,0,0,0,126095,21762,28694,23668.64,25633.10
+CommodityAPO,2021-11-05,5.748207,21426,0,0,0,118011,21312,28694,23565.31,25767.33
+CommodityAPO,2022-02-07,6.005741,0,0,0,0,0,0,28694,0.00,0.00
+CommodityAPO,2022-05-05,6.244098,0,0,0,0,0,0,28694,0.00,0.00
+CommodityAPO,2022-08-05,6.496152,0,0,0,0,0,0,28694,0.00,0.00
+CommodityAPO,2022-11-07,6.753687,0,0,0,0,0,0,28694,0.00,0.00
+CommodityAPO,2023-02-06,7.003002,0,0,0,0,0,0,28694,0.00,0.00
+CommodityAPO,2023-05-05,7.244098,0,0,0,0,0,0,28694,0.00,0.00
+CommodityAPO,2023-08-07,7.501632,0,0,0,0,0,0,28694,0.00,0.00
+CommodityAPO,2023-11-06,7.750947,0,0,0,0,0,0,28694,0.00,0.00
+CommodityAPO,2024-02-05,8.000000,0,0,0,0,0,0,28694,0.00,0.00
+CommodityAPO,2024-05-07,8.251366,0,0,0,0,0,0,28694,0.00,0.00
+CommodityAPO,2024-08-05,8.497268,0,0,0,0,0,0,28694,0.00,0.00
+CommodityAPO,2024-11-05,8.748634,0,0,0,0,0,0,28694,0.00,0.00
+CommodityAPO,2025-02-05,9.000262,0,0,0,0,0,0,28694,0.00,0.00
+CommodityAPO,2025-05-06,9.246837,0,0,0,0,0,0,28694,0.00,0.00
+CommodityAPO,2025-08-05,9.496152,0,0,0,0,0,0,28694,0.00,0.00
+CommodityAPO,2025-11-05,9.748207,0,0,0,0,0,0,28694,0.00,0.00
+CommodityAPO,2026-02-05,10.000262,0,0,0,0,0,0,28694,0.00,0.00
+CommodityAPO,2026-05-05,10.244098,0,0,0,0,0,0,28694,0.00,0.00
+CommodityAPO,2026-08-05,10.496152,0,0,0,0,0,0,28694,0.00,0.00
+CommodityAPO,2026-11-05,10.748207,0,0,0,0,0,0,28694,0.00,0.00
+CommodityAPO,2027-02-05,11.000262,0,0,0,0,0,0,28694,0.00,0.00
+CommodityAPO,2027-05-05,11.244098,0,0,0,0,0,0,28694,0.00,0.00
+CommodityAPO,2027-08-05,11.496152,0,0,0,0,0,0,28694,0.00,0.00
+CommodityAPO,2027-11-05,11.748207,0,0,0,0,0,0,28694,0.00,0.00
+CommodityAPO,2028-02-07,12.005464,0,0,0,0,0,0,28694,0.00,0.00
+CommodityAPO,2028-05-05,12.245902,0,0,0,0,0,0,28694,0.00,0.00
+CommodityAPO,2028-08-07,12.502732,0,0,0,0,0,0,28694,0.00,0.00
+CommodityAPO,2028-11-06,12.751366,0,0,0,0,0,0,28694,0.00,0.00
+CommodityAPO,2029-02-05,13.000262,0,0,0,0,0,0,28694,0.00,0.00
+CommodityAPO,2029-05-08,13.252317,0,0,0,0,0,0,28694,0.00,0.00
+CommodityAPO,2029-08-06,13.498892,0,0,0,0,0,0,28694,0.00,0.00
+CommodityAPO,2029-11-05,13.748207,0,0,0,0,0,0,28694,0.00,0.00
+CommodityAPO,2030-02-05,14.000262,0,0,0,0,0,0,28694,0.00,0.00
+CommodityAPO,2030-05-07,14.249577,0,0,0,0,0,0,28694,0.00,0.00
+CommodityAPO,2030-08-05,14.496152,0,0,0,0,0,0,28694,0.00,0.00
+CommodityAPO,2030-11-05,14.748207,0,0,0,0,0,0,28694,0.00,0.00
+CommodityAPO,2031-02-05,15.000262,0,0,0,0,0,0,28694,0.00,0.00
+CommodityAPO,2031-05-06,15.246837,0,0,0,0,0,0,28694,0.00,0.00
+CommodityAPO,2031-08-05,15.496152,0,0,0,0,0,0,28694,0.00,0.00
+CommodityAPO,2031-11-05,15.748207,0,0,0,0,0,0,28694,0.00,0.00
+CommodityAPO,2032-02-05,16.000000,0,0,0,0,0,0,28694,0.00,0.00
+CommodityAPO,2032-05-05,16.245902,0,0,0,0,0,0,28694,0.00,0.00
+CommodityAPO,2032-08-05,16.497268,0,0,0,0,0,0,28694,0.00,0.00
+CommodityAPO,2032-11-05,16.748634,0,0,0,0,0,0,28694,0.00,0.00
+CommodityAPO,2033-02-07,17.005741,0,0,0,0,0,0,28694,0.00,0.00
+CommodityAPO,2033-05-05,17.244098,0,0,0,0,0,0,28694,0.00,0.00
+CommodityAPO,2033-08-05,17.496152,0,0,0,0,0,0,28694,0.00,0.00
+CommodityAPO,2033-11-07,17.753687,0,0,0,0,0,0,28694,0.00,0.00
+CommodityAPO,2034-02-06,18.003002,0,0,0,0,0,0,28694,0.00,0.00
+CommodityAPO,2034-05-05,18.244098,0,0,0,0,0,0,28694,0.00,0.00
+CommodityAPO,2034-08-07,18.501632,0,0,0,0,0,0,28694,0.00,0.00
+CommodityAPO,2034-11-06,18.750947,0,0,0,0,0,0,28694,0.00,0.00
+CommodityAPO,2035-02-05,19.000262,0,0,0,0,0,0,28694,0.00,0.00
+CommodityAPO,2035-05-08,19.252317,0,0,0,0,0,0,28694,0.00,0.00
+CommodityAPO,2035-08-06,19.498892,0,0,0,0,0,0,28694,0.00,0.00
+CommodityAPO,2035-11-05,19.748207,0,0,0,0,0,0,28694,0.00,0.00
+CommodityAPO,2036-02-05,20.000000,0,0,0,0,0,0,28694,0.00,0.00
+CommodityAPO,2036-05-06,20.248634,0,0,0,0,0,0,28694,0.00,0.00