Skip to content

Commit b94802c

Browse files
rolandlichtersjenkins
rolandlichters
authored and
jenkins
committed
QPR-8562 extend example 24, update user guide
1 parent c978481 commit b94802c

5 files changed

Lines changed: 146 additions & 29 deletions

File tree

‎Docs/UserGuide/userguide.tex‎

Lines changed: 32 additions & 15 deletions
Original file line numberDiff line numberDiff line change
@@ -262,9 +262,11 @@ \subsubsection*{Scope and Roadmap}
262262
\hline
263263
Equity Future Options & Y & Y & Y & Y \\
264264
\hline
265-
Commodity Forwards & Y & Y & Y & Y\\
265+
Commodity Forwards and Swaps & Y & Y & Y & Y\\
266266
\hline
267-
Commodity European and Asian Options & Y & Y & N & N \\
267+
Commodity European and Asian Options & Y & Y & Y & Y \\
268+
\hline
269+
Commodity Swaptions & Y & Y & Y & Y\\
268270
\hline
269271
CPI Swaps & Y & Y & N & Y \\
270272
\hline
@@ -1922,7 +1924,7 @@ \subsection{FRA and Average OIS Exposure}% Example 23
19221924
four {\tt exposure\_trade\_*.csv} files.
19231925

19241926
%--------------------------------------------------------
1925-
\subsection{Commodity Forward and Option, Pricing, Sensitivity, Exposure}% Example 24
1927+
\subsection{Commodity Derivatives, Pricing, Sensitivity, Exposure}% Example 24
19261928
\label{example:24}
19271929
%--------------------------------------------------------
19281930

@@ -1940,7 +1942,15 @@ \subsection{Commodity Forward and Option, Pricing, Sensitivity, Exposure}% Examp
19401942
using a minimal portfolio of four forwards and two options referencing WTI and Gold.
19411943
The essential results are in {\tt npv.csv} and {\tt sensitivity.csv}.
19421944

1943-
The second run determined by {\tt ore\_wti.xml} demonstrates Commodity exposure simulation for a single Commodity Forward, with the usual results, exposure reports and graphs.
1945+
The second run determined by {\tt ore\_wti.xml} demonstrates Commodity exposure simulation for a portfolio including a
1946+
\begin{itemize}
1947+
\item Commodity Forward
1948+
\item Commodity Swap
1949+
\item European Commodity Option
1950+
\item Commodity Average Price Option
1951+
\item Commodity Swaption
1952+
\end{itemize}
1953+
with the usual results, exposure reports and graphs.
19441954

19451955
%--------------------------------------------------------
19461956
\subsection{CMS Spread with (Digital) Cap/Floor}% Example 25
@@ -4283,7 +4293,7 @@ \subsubsection{Model}\label{sec:sim_model}
42834293

42844294
% commodity models
42854295

4286-
For commodity simulation we currently provide one model choice, as described in the methodology appendix.
4296+
For commodity simulation we currently provide one model, as described in the methodology appendix.
42874297
Commodity model components are specified by commodity name, by a block as follows
42884298

42894299
\begin{listing}[H]
@@ -4302,7 +4312,10 @@ \subsubsection{Model}\label{sec:sim_model}
43024312
<Calibrate>Y</Calibrate>
43034313
<InitialValue>0.1</InitialValue>
43044314
</Kappa>
4305-
<CalibrationOptions/>
4315+
<CalibrationOptions>
4316+
...
4317+
</CalibrationOptions>
4318+
<DriftFreeState>false</DriftFreeState>
43064319
</CommoditySchwartz>
43074320
<CommoditySchwartz name="WTI">
43084321
<!-- ... -->
@@ -4324,17 +4337,16 @@ \subsubsection{Model}\label{sec:sim_model}
43244337
Within each CommoditySchwartz section, the interpretation of elements is as follows:
43254338

43264339
\begin{itemize}
4327-
\item {\tt Currency: } Currency of denomination
4328-
\item {\tt CalibrationType: } Choose between {\em Bootstrap}, {\em BestFit} and {\em None}.
4329-
\item {\tt Sigma/Calibrate: } Flag to enable/disable calibration of this particular parameter
4330-
\item {\tt Sigma/InitialValue: } Initial value of the constant parameter
4331-
\item {\tt Kappa/Calibrate: } Flag to enable/disable calibration of this particular parameter
4332-
\item {\tt Kappa/InitialValue: } Initial value of the constant parameter
4333-
\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).
4340+
\item {\tt Currency: } Currency of denomination
4341+
\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.
4342+
\item {\tt Sigma/Calibrate:} Flag to enable/disable calibration of this particular parameter
4343+
\item {\tt Sigma/InitialValue:} Initial value of the constant parameter
4344+
\item {\tt Kappa/Calibrate:} Flag to enable/disable calibration of this particular parameter
4345+
\item {\tt Kappa/InitialValue:} Initial value of the constant parameter
4346+
\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).
4347+
\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}.
43344348
\end{itemize}
43354349

4336-
Note that calibration to Commodity options is not implemented yet, the simulation is based on the initial parameter values provided.
4337-
43384350
\medskip
43394351
Finally, the instantaneous correlation structure is specified as follows.
43404352

@@ -6178,6 +6190,11 @@ \subsubsection*{Commodity}
61786190
F(t,T) &= F(0,T) \:\exp\left( X(t)\,e^{-\kappa\,(T-t)} - \frac{1}{2}\,(V(0,T)-V(t,T)) \right) \\
61796191
V(t,T) &= e^{-2\kappa T}\int_t^T\sigma^2\:e^{2\kappa u}\,du.
61806192
\end{align*}
6193+
Note that
6194+
$$
6195+
\V[\ln F(T,T)] = \V[X(T)]
6196+
$$
6197+
is the variance that is used in the pricing of a Futures Option which in turn is used in the calibration of the Schwartz model.
61816198

61826199
Alternatively, one can use the drift-free state variable $Y(t)=e^{\kappa t} X(t)$ with
61836200
\begin{align*}

‎Examples/Example_24/Input/ore_wti.xml‎

Lines changed: 4 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -25,13 +25,13 @@
2525
</Markets>
2626
<Analytics>
2727
<Analytic type="npv">
28-
<Parameter name="active">N</Parameter>
28+
<Parameter name="active">Y</Parameter>
2929
<Parameter name="baseCurrency">USD</Parameter>
30-
<Parameter name="outputFileName">npv.csv</Parameter>
30+
<Parameter name="outputFileName">npv_wti.csv</Parameter>
3131
</Analytic>
3232
<Analytic type="cashflow">
33-
<Parameter name="active">N</Parameter>
34-
<Parameter name="outputFileName">flows.csv</Parameter>
33+
<Parameter name="active">Y</Parameter>
34+
<Parameter name="outputFileName">flows_wti.csv</Parameter>
3535
</Analytic>
3636
<Analytic type="curves">
3737
<Parameter name="active">N</Parameter>

‎Examples/Example_24/Input/portfolio_wti.xml‎

Lines changed: 88 additions & 8 deletions
Original file line numberDiff line numberDiff line change
@@ -42,8 +42,7 @@
4242
</CommodityOptionData>
4343
</Trade>
4444

45-
<!--
46-
<Trade id="Commodity_Swap">
45+
<Trade id="CommoditySwap">
4746
<TradeType>CommoditySwap</TradeType>
4847
<Envelope>
4948
<CounterParty>CPTY_A</CounterParty>
@@ -63,7 +62,7 @@
6362
<Quantity>3000</Quantity>
6463
</Quantities>
6564
<Prices>
66-
<Price>52.51</Price>
65+
<Price>45.65</Price>
6766
</Prices>
6867
</CommodityFixedLegData>
6968
<ScheduleData>
@@ -90,11 +89,13 @@
9089
<PaymentCalendar>US-NYSE</PaymentCalendar>
9190
<CommodityFloatingLegData>
9291
<Name>COMDTY_WTI_USD</Name>
92+
<!--<PriceType>FutureSettlement</PriceType>-->
9393
<PriceType>Spot</PriceType>
9494
<Quantities>
9595
<Quantity>3000</Quantity>
9696
</Quantities>
97-
<IsAveraged>true</IsAveraged>
97+
<!--<IsAveraged>true</IsAveraged>-->
98+
<IsAveraged>false</IsAveraged>
9899
</CommodityFloatingLegData>
99100
<ScheduleData>
100101
<Rules>
@@ -113,8 +114,7 @@
113114
</LegData>
114115
</SwapData>
115116
</Trade>
116-
-->
117-
<!--
117+
118118
<Trade id="CommodityAPO">
119119
<TradeType>CommodityAveragePriceOption</TradeType>
120120
<Envelope>
@@ -138,7 +138,8 @@
138138
<Currency>USD</Currency>
139139
<Quantity>6144</Quantity>
140140
<Strike>50</Strike>
141-
<PriceType>FutureSettlement</PriceType>
141+
<!--<PriceType>FutureSettlement</PriceType>-->
142+
<PriceType>Spot</PriceType>
142143
<StartDate>2020-12-31</StartDate>
143144
<EndDate>2021-12-31</EndDate>
144145
<PaymentCalendar>US-NYSE</PaymentCalendar>
@@ -150,5 +151,84 @@
150151
<FutureMonthOffset>0</FutureMonthOffset>
151152
</CommodityAveragePriceOptionData>
152153
</Trade>
153-
-->
154+
155+
<Trade id="CommoditySwaption">
156+
<TradeType>CommoditySwaption</TradeType>
157+
<Envelope>
158+
<CounterParty>CPTY_A</CounterParty>
159+
<NettingSetId>CPTY_A</NettingSetId>
160+
<AdditionalFields/>
161+
</Envelope>
162+
<CommoditySwaptionData>
163+
<OptionData>
164+
<LongShort>Long</LongShort>
165+
<Settlement>Cash</Settlement>
166+
<PremiumAmount>7342.8</PremiumAmount>
167+
<PremiumCurrency>USD</PremiumCurrency>
168+
<PremiumPayDate>2019-03-29</PremiumPayDate>
169+
<ExerciseDates>
170+
<ExerciseDate>2019-12-31</ExerciseDate>
171+
</ExerciseDates>
172+
</OptionData>
173+
<LegData>
174+
<LegType>CommodityFixed</LegType>
175+
<Payer>false</Payer>
176+
<Currency>USD</Currency>
177+
<PaymentLag>2</PaymentLag>
178+
<PaymentConvention>Following</PaymentConvention>
179+
<PaymentCalendar>US-NYSE</PaymentCalendar>
180+
<CommodityFixedLegData>
181+
<Quantities>
182+
<Quantity>3000</Quantity>
183+
</Quantities>
184+
<Prices>
185+
<Price>50</Price>
186+
</Prices>
187+
</CommodityFixedLegData>
188+
<ScheduleData>
189+
<Rules>
190+
<StartDate>2020-01-01</StartDate>
191+
<EndDate>2020-12-31</EndDate>
192+
<Tenor>1M</Tenor>
193+
<Calendar>NullCalendar</Calendar>
194+
<Convention>Unadjusted</Convention>
195+
<TermConvention>Unadjusted</TermConvention>
196+
<Rule>Backward</Rule>
197+
<EndOfMonth>true</EndOfMonth>
198+
</Rules>
199+
</ScheduleData>
200+
</LegData>
201+
<LegData>
202+
<LegType>CommodityFloating</LegType>
203+
<Payer>true</Payer>
204+
<Currency>USD</Currency>
205+
<PaymentLag>2</PaymentLag>
206+
<PaymentConvention>Following</PaymentConvention>
207+
<PaymentCalendar>US-NYSE</PaymentCalendar>
208+
<CommodityFloatingLegData>
209+
<Name>COMDTY_WTI_USD</Name>
210+
<!--<PriceType>FutureSettlement</PriceType>-->
211+
<PriceType>Spot</PriceType>
212+
<Quantities>
213+
<Quantity>3000</Quantity>
214+
</Quantities>
215+
<IsAveraged>true</IsAveraged>
216+
<FutureMonthOffset>0</FutureMonthOffset>
217+
</CommodityFloatingLegData>
218+
<ScheduleData>
219+
<Rules>
220+
<StartDate>2020-01-01</StartDate>
221+
<EndDate>2020-12-31</EndDate>
222+
<Tenor>1M</Tenor>
223+
<Calendar>NullCalendar</Calendar>
224+
<Convention>Unadjusted</Convention>
225+
<TermConvention>Unadjusted</TermConvention>
226+
<Rule>Backward</Rule>
227+
<EndOfMonth>true</EndOfMonth>
228+
</Rules>
229+
</ScheduleData>
230+
</LegData>
231+
</CommoditySwaptionData>
232+
</Trade>
233+
154234
</Portfolio>

‎Examples/Example_24/Input/simulation_wti.xml‎

Lines changed: 3 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -7,7 +7,7 @@
77
<Sequence>SobolBrownianBridge</Sequence>
88
<Scenario>Simple</Scenario>
99
<Seed>42</Seed>
10-
<Samples>10000</Samples>
10+
<Samples>1000</Samples>
1111
</Parameters>
1212

1313
<CrossAssetModel>
@@ -173,7 +173,8 @@
173173

174174
<CommodityVolatilities>
175175
<Simulate>false</Simulate>
176-
<ReactionToTimeDecay>ForwardVariance</ReactionToTimeDecay>
176+
<!--<ReactionToTimeDecay>ForwardVariance</ReactionToTimeDecay>-->
177+
<ReactionToTimeDecay>ConstantVariance</ReactionToTimeDecay>
177178
<Names>
178179
<Name id="COMDTY_WTI_USD">
179180
<Expiries>1Y,5Y,10Y</Expiries>

‎Examples/Example_24/run.py‎

Lines changed: 19 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -21,8 +21,27 @@
2121
oreex.decorate_plot(title="Example 24 - Simulated Commodity Forward Exposure")
2222
oreex.save_plot_to_file()
2323

24+
oreex.print_headline("Plot Swap exposure graph")
25+
oreex.setup_plot("commodity_swap")
26+
oreex.plot("exposure_trade_CommoditySwap.csv", 2, 3, 'b', "EPE")
27+
oreex.plot("exposure_trade_CommoditySwap.csv", 2, 4, 'r', "ENE")
28+
oreex.decorate_plot(title="Example 24 - Simulated Commodity Swap Exposure")
29+
oreex.save_plot_to_file()
30+
2431
oreex.print_headline("Plot Option exposure graph")
2532
oreex.setup_plot("commodity_option")
2633
oreex.plot("exposure_trade_CommodityOption.csv", 2, 3, 'b', "EPE")
2734
oreex.decorate_plot(title="Example 24 - Simulated Commodity Option Exposure")
2835
oreex.save_plot_to_file()
36+
37+
oreex.print_headline("Plot APO exposure graph")
38+
oreex.setup_plot("commodity_apo")
39+
oreex.plot("exposure_trade_CommodityAPO.csv", 2, 3, 'b', "EPE")
40+
oreex.decorate_plot(title="Example 24 - Simulated Commodity APO Exposure")
41+
oreex.save_plot_to_file()
42+
43+
oreex.print_headline("Plot Swaption exposure graph")
44+
oreex.setup_plot("commodity_swaption")
45+
oreex.plot("exposure_trade_CommoditySwaption.csv", 2, 3, 'b', "EPE")
46+
oreex.decorate_plot(title="Example 24 - Simulated Commodity Swaption Exposure")
47+
oreex.save_plot_to_file()

0 commit comments

Comments
 (0)