1 /* -*- mode: c++; tab-width: 4; indent-tabs-mode: nil; c-basic-offset: 4 -*- */
2 
3 /*
4  Copyright (C) 2000, 2001, 2002, 2003 RiskMap srl
5  Copyright (C) 2006 François du Vignaud
6  Copyright (C) 2006, 2008 Ferdinando Ametrano
7  Copyright (C) 2015 Peter Caspers
8 
9  This file is part of QuantLib, a free-software/open-source library
10  for financial quantitative analysts and developers - http://quantlib.org/
11 
12  QuantLib is free software: you can redistribute it and/or modify it
13  under the terms of the QuantLib license.  You should have received a
14  copy of the license along with this program; if not, please email
15  <quantlib-dev@lists.sf.net>. The license is also available online at
16  <http://quantlib.org/license.shtml>.
17 
18  This program is distributed in the hope that it will be useful, but WITHOUT
19  ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS
20  FOR A PARTICULAR PURPOSE.  See the license for more details.
21 */
22 
23 /*! \file swaptionvolmatrix.hpp
24     \brief Swaption at-the-money volatility matrix
25 */
26 
27 #ifndef quantlib_swaption_volatility_matrix_hpp
28 #define quantlib_swaption_volatility_matrix_hpp
29 
30 #include <ql/termstructures/volatility/swaption/swaptionvoldiscrete.hpp>
31 #include <ql/math/interpolations/interpolation2d.hpp>
32 #include <ql/math/matrix.hpp>
33 #include <boost/noncopyable.hpp>
34 #include <vector>
35 
36 namespace QuantLib {
37 
38     class Quote;
39 
40     //! At-the-money swaption-volatility matrix
41     /*! This class provides the at-the-money volatility for a given
42         swaption by interpolating a volatility matrix whose elements
43         are the market volatilities of a set of swaption with given
44         option date and swapLength.
45 
46         The volatility matrix <tt>M</tt> must be defined so that:
47         - the number of rows equals the number of option dates;
48         - the number of columns equals the number of swap tenors;
49         - <tt>M[i][j]</tt> contains the volatility corresponding
50           to the <tt>i</tt>-th option and <tt>j</tt>-th tenor.
51     */
52     class SwaptionVolatilityMatrix : public SwaptionVolatilityDiscrete,
53                                      private boost::noncopyable {
54       public:
55         //! floating reference date, floating market data
56         SwaptionVolatilityMatrix(
57             const Calendar& calendar,
58             BusinessDayConvention bdc,
59             const std::vector<Period>& optionTenors,
60             const std::vector<Period>& swapTenors,
61             const std::vector<std::vector<Handle<Quote> > >& vols,
62             const DayCounter& dayCounter,
63             bool flatExtrapolation = false,
64             VolatilityType type = ShiftedLognormal,
65             const std::vector<std::vector<Real> >& shifts = std::vector<std::vector<Real> >());
66         //! fixed reference date, floating market data
67         SwaptionVolatilityMatrix(
68             const Date& referenceDate,
69             const Calendar& calendar,
70             BusinessDayConvention bdc,
71             const std::vector<Period>& optionTenors,
72             const std::vector<Period>& swapTenors,
73             const std::vector<std::vector<Handle<Quote> > >& vols,
74             const DayCounter& dayCounter,
75             bool flatExtrapolation = false,
76             VolatilityType type = ShiftedLognormal,
77             const std::vector<std::vector<Real> >& shifts = std::vector<std::vector<Real> >());
78         //! floating reference date, fixed market data
79         SwaptionVolatilityMatrix(const Calendar& calendar,
80                                  BusinessDayConvention bdc,
81                                  const std::vector<Period>& optionTenors,
82                                  const std::vector<Period>& swapTenors,
83                                  const Matrix& volatilities,
84                                  const DayCounter& dayCounter,
85                                  bool flatExtrapolation = false,
86                                  VolatilityType type = ShiftedLognormal,
87                                  const Matrix& shifts = Matrix());
88         //! fixed reference date, fixed market data
89         SwaptionVolatilityMatrix(const Date& referenceDate,
90                                  const Calendar& calendar,
91                                  BusinessDayConvention bdc,
92                                  const std::vector<Period>& optionTenors,
93                                  const std::vector<Period>& swapTenors,
94                                  const Matrix& volatilities,
95                                  const DayCounter& dayCounter,
96                                  bool flatExtrapolation = false,
97                                  VolatilityType type = ShiftedLognormal,
98                                  const Matrix& shifts = Matrix());
99         //! fixed reference date and fixed market data, option dates
100         SwaptionVolatilityMatrix(const Date& referenceDate,
101                                  const Calendar& calendar,
102                                  BusinessDayConvention bdc,
103                                  const std::vector<Date>& optionDates,
104                                  const std::vector<Period>& swapTenors,
105                                  const Matrix& volatilities,
106                                  const DayCounter& dayCounter,
107                                  bool flatExtrapolation = false,
108                                  VolatilityType type = ShiftedLognormal,
109                                  const Matrix& shifts = Matrix());
110 
111         //! \name LazyObject interface
112         //@{
113         void performCalculations() const;
114         //@}
115         //! \name TermStructure interface
116         //@{
117         Date maxDate() const;
118         //@}
119         //! \name VolatilityTermStructure interface
120         //@{
121         Rate minStrike() const;
122         Rate maxStrike() const;
123         //@}
124         //! \name SwaptionVolatilityStructure interface
125         //@{
126         const Period& maxSwapTenor() const;
127         //@}
128         //! \name Other inspectors
129         //@{
130         //! returns the lower indexes of surrounding volatility matrix corners
locate(const Date & optionDate,const Period & swapTenor) const131         std::pair<Size,Size> locate(const Date& optionDate,
132                                     const Period& swapTenor) const {
133             return locate(timeFromReference(optionDate),
134                           swapLength(swapTenor));
135         }
136         //! returns the lower indexes of surrounding volatility matrix corners
locate(Time optionTime,Time swapLength) const137         std::pair<Size,Size> locate(Time optionTime,
138                                     Time swapLength) const {
139             return std::make_pair(interpolation_.locateY(optionTime),
140                                   interpolation_.locateX(swapLength));
141         }
142         //@}
143         VolatilityType volatilityType() const;
144       protected:
145         // defining the following method would break CMS test suite
146         // to be further investigated
147         //ext::shared_ptr<SmileSection> smileSectionImpl(const Date&,
148         //                                                 const Period&) const;
149         ext::shared_ptr<SmileSection> smileSectionImpl(Time,
150                                                          Time) const;
151         Volatility volatilityImpl(Time optionTime,
152                                   Time swapLength,
153                                   Rate strike) const;
154         Real shiftImpl(Time optionTime, Time swapLength) const;
155       private:
156         void checkInputs(Size volRows,
157                          Size volsColumns,
158                          Size shiftRows,
159                          Size shiftsColumns) const;
160         void registerWithMarketData();
161         std::vector<std::vector<Handle<Quote> > > volHandles_;
162         std::vector<std::vector<Real> > shiftValues_;
163         mutable Matrix volatilities_, shifts_;
164         Interpolation2D interpolation_, interpolationShifts_;
165         VolatilityType volatilityType_;
166     };
167 
168     // inline definitions
169 
maxDate() const170     inline Date SwaptionVolatilityMatrix::maxDate() const {
171         return optionDates_.back();
172     }
173 
minStrike() const174     inline Rate SwaptionVolatilityMatrix::minStrike() const {
175         return -QL_MAX_REAL;
176     }
177 
maxStrike() const178     inline Rate SwaptionVolatilityMatrix::maxStrike() const {
179         return QL_MAX_REAL;
180     }
181 
maxSwapTenor() const182     inline const Period& SwaptionVolatilityMatrix::maxSwapTenor() const {
183         return swapTenors_.back();
184     }
185 
volatilityImpl(Time optionTime,Time swapLength,Rate) const186     inline Volatility SwaptionVolatilityMatrix::volatilityImpl(Time optionTime,
187                                                                Time swapLength,
188                                                                Rate) const {
189         calculate();
190         return interpolation_(swapLength, optionTime, true);
191     }
192 
volatilityType() const193     inline VolatilityType SwaptionVolatilityMatrix::volatilityType() const {
194         return volatilityType_;
195     }
196 
shiftImpl(Time optionTime,Time swapLength) const197     inline Real SwaptionVolatilityMatrix::shiftImpl(Time optionTime,
198                                                     Time swapLength) const {
199         calculate();
200         Real tmp = interpolationShifts_(swapLength, optionTime, true);
201         return tmp;
202     }
203 } // namespace QuantLib
204 
205 #endif
206