QuantLib: a free/open-source library for quantitative finance
fully annotated source code - version 1.34
Loading...
Searching...
No Matches
cashflows.hpp
Go to the documentation of this file.
1/* -*- mode: c++; tab-width: 4; indent-tabs-mode: nil; c-basic-offset: 4 -*- */
2
3/*
4 Copyright (C) 2005, 2006 StatPro Italia srl
5 Copyright (C) 2005 Charles Whitmore
6 Copyright (C) 2007, 2008, 2009, 2010, 2011 Ferdinando Ametrano
7 Copyright (C) 2008 Toyin Akin
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 cashflows.hpp
24 \brief Cash-flow analysis functions
25*/
26
27#ifndef quantlib_cashflows_hpp
28#define quantlib_cashflows_hpp
29
31#include <ql/cashflow.hpp>
32#include <ql/interestrate.hpp>
33#include <ql/shared_ptr.hpp>
34
35namespace QuantLib {
36
37 class YieldTermStructure;
38
39 //! %cashflow-analysis functions
40 /*! \todo add tests */
41 class CashFlows {
42 private:
43 class IrrFinder {
44 public:
45 IrrFinder(const Leg& leg,
46 Real npv,
47 DayCounter dayCounter,
48 Compounding comp,
49 Frequency freq,
50 bool includeSettlementDateFlows,
51 Date settlementDate,
52 Date npvDate);
53
54 Real operator()(Rate y) const;
55 Real derivative(Rate y) const;
56 private:
57 void checkSign() const;
58
59 const Leg& leg_;
66 };
67 public:
68 CashFlows() = delete;
69 CashFlows(CashFlows&&) = delete;
70 CashFlows(const CashFlows&) = delete;
72 CashFlows& operator=(const CashFlows&) = delete;
73 ~CashFlows() = default;
74
75 //! \name Date functions
76 //@{
77 static Date startDate(const Leg& leg);
78 static Date maturityDate(const Leg& leg);
79 static bool isExpired(const Leg& leg,
80 bool includeSettlementDateFlows,
81 Date settlementDate = Date());
82 //@}
83
84 //! \name CashFlow functions
85 //@{
86 //! the last cashflow paying before or at the given date
87 static Leg::const_reverse_iterator
88 previousCashFlow(const Leg& leg,
89 bool includeSettlementDateFlows,
90 Date settlementDate = Date());
91 //! the first cashflow paying after the given date
92 static Leg::const_iterator
93 nextCashFlow(const Leg& leg,
94 bool includeSettlementDateFlows,
95 Date settlementDate = Date());
96 static Date
97 previousCashFlowDate(const Leg& leg,
98 bool includeSettlementDateFlows,
99 Date settlementDate = Date());
100 static Date
101 nextCashFlowDate(const Leg& leg,
102 bool includeSettlementDateFlows,
103 Date settlementDate = Date());
104 static Real
105 previousCashFlowAmount(const Leg& leg,
106 bool includeSettlementDateFlows,
107 Date settlementDate = Date());
108 static Real
109 nextCashFlowAmount(const Leg& leg,
110 bool includeSettlementDateFlows,
111 Date settlementDate = Date());
112 //@}
113
114 //! \name Coupon inspectors
115 //@{
116 static Rate
117 previousCouponRate(const Leg& leg,
118 bool includeSettlementDateFlows,
119 Date settlementDate = Date());
120 static Rate
121 nextCouponRate(const Leg& leg,
122 bool includeSettlementDateFlows,
123 Date settlementDate = Date());
124
125 static Real
126 nominal(const Leg& leg,
127 bool includeSettlementDateFlows,
128 Date settlDate = Date());
129 static Date
130 accrualStartDate(const Leg& leg,
131 bool includeSettlementDateFlows,
132 Date settlDate = Date());
133 static Date
134 accrualEndDate(const Leg& leg,
135 bool includeSettlementDateFlows,
136 Date settlementDate = Date());
137 static Date
138 referencePeriodStart(const Leg& leg,
139 bool includeSettlementDateFlows,
140 Date settlDate = Date());
141 static Date
142 referencePeriodEnd(const Leg& leg,
143 bool includeSettlementDateFlows,
144 Date settlDate = Date());
145 static Time
146 accrualPeriod(const Leg& leg,
147 bool includeSettlementDateFlows,
148 Date settlementDate = Date());
149 static Date::serial_type
150 accrualDays(const Leg& leg,
151 bool includeSettlementDateFlows,
152 Date settlementDate = Date());
153 static Time
154 accruedPeriod(const Leg& leg,
155 bool includeSettlementDateFlows,
156 Date settlementDate = Date());
157 static Date::serial_type
158 accruedDays(const Leg& leg,
159 bool includeSettlementDateFlows,
160 Date settlementDate = Date());
161 static Real
162 accruedAmount(const Leg& leg,
163 bool includeSettlementDateFlows,
164 Date settlementDate = Date());
165 //@}
166
167 //! \name YieldTermStructure functions
168 //@{
169 //! NPV of the cash flows.
170 /*! The NPV is the sum of the cash flows, each discounted
171 according to the given term structure.
172 */
173 static Real npv(const Leg& leg,
174 const YieldTermStructure& discountCurve,
175 bool includeSettlementDateFlows,
176 Date settlementDate = Date(),
177 Date npvDate = Date());
178 //! Basis-point sensitivity of the cash flows.
179 /*! The result is the change in NPV due to a uniform
180 1-basis-point change in the rate paid by the cash
181 flows. The change for each coupon is discounted according
182 to the given term structure.
183 */
184 static Real bps(const Leg& leg,
185 const YieldTermStructure& discountCurve,
186 bool includeSettlementDateFlows,
187 Date settlementDate = Date(),
188 Date npvDate = Date());
189
190 //! NPV and BPS of the cash flows.
191 /*! The NPV and BPS of the cash flows calculated
192 together for performance reason
193 */
194 static std::pair<Real, Real> npvbps(const Leg& leg,
195 const YieldTermStructure& discountCurve,
196 bool includeSettlementDateFlows,
197 Date settlementDate = Date(),
198 Date npvDate = Date());
199
200 //! At-the-money rate of the cash flows.
201 /*! The result is the fixed rate for which a fixed rate cash flow
202 vector, equivalent to the input vector, has the required NPV
203 according to the given term structure. If the required NPV is
204 not given, the input cash flow vector's NPV is used instead.
205 */
206 static Rate atmRate(const Leg& leg,
207 const YieldTermStructure& discountCurve,
208 bool includeSettlementDateFlows,
209 Date settlementDate = Date(),
210 Date npvDate = Date(),
211 Real npv = Null<Real>());
212 //@}
213
214 //! \name Yield (a.k.a. Internal Rate of Return, i.e. IRR) functions
215 /*! The IRR is the interest rate at which the NPV of the cash
216 flows equals the dirty price.
217 */
218 //@{
219 //! NPV of the cash flows.
220 /*! The NPV is the sum of the cash flows, each discounted
221 according to the given constant interest rate. The result
222 is affected by the choice of the interest-rate compounding
223 and the relative frequency and day counter.
224 */
225 static Real npv(const Leg& leg,
226 const InterestRate& yield,
227 bool includeSettlementDateFlows,
228 Date settlementDate = Date(),
229 Date npvDate = Date());
230 static Real npv(const Leg& leg,
231 Rate yield,
232 const DayCounter& dayCounter,
233 Compounding compounding,
234 Frequency frequency,
235 bool includeSettlementDateFlows,
236 Date settlementDate = Date(),
237 Date npvDate = Date());
238 //! Basis-point sensitivity of the cash flows.
239 /*! The result is the change in NPV due to a uniform
240 1-basis-point change in the rate paid by the cash
241 flows. The change for each coupon is discounted according
242 to the given constant interest rate. The result is
243 affected by the choice of the interest-rate compounding
244 and the relative frequency and day counter.
245 */
246 static Real bps(const Leg& leg,
247 const InterestRate& yield,
248 bool includeSettlementDateFlows,
249 Date settlementDate = Date(),
250 Date npvDate = Date());
251 static Real bps(const Leg& leg,
252 Rate yield,
253 const DayCounter& dayCounter,
254 Compounding compounding,
255 Frequency frequency,
256 bool includeSettlementDateFlows,
257 Date settlementDate = Date(),
258 Date npvDate = Date());
259 //! Implied internal rate of return.
260 /*! The function verifies
261 the theoretical existence of an IRR and numerically
262 establishes the IRR to the desired precision.
263 */
264 static Rate yield(const Leg& leg,
265 Real npv,
266 const DayCounter& dayCounter,
267 Compounding compounding,
268 Frequency frequency,
269 bool includeSettlementDateFlows,
270 Date settlementDate = Date(),
271 Date npvDate = Date(),
272 Real accuracy = 1.0e-10,
273 Size maxIterations = 100,
274 Rate guess = 0.05);
275
276 template <typename Solver>
277 static Rate yield(const Solver& solver,
278 const Leg& leg,
279 Real npv,
280 const DayCounter& dayCounter,
281 Compounding compounding,
282 Frequency frequency,
283 bool includeSettlementDateFlows,
284 Date settlementDate = Date(),
285 Date npvDate = Date(),
286 Real accuracy = 1.0e-10,
287 Rate guess = 0.05) {
288 IrrFinder objFunction(leg, npv, dayCounter, compounding,
289 frequency, includeSettlementDateFlows,
290 settlementDate, npvDate);
291 return solver.solve(objFunction, accuracy, guess, guess/10.0);
292 }
293
294 //! Cash-flow duration.
295 /*! The simple duration of a string of cash flows is defined as
296 \f[
297 D_{\mathrm{simple}} = \frac{\sum t_i c_i B(t_i)}{\sum c_i B(t_i)}
298 \f]
299 where \f$ c_i \f$ is the amount of the \f$ i \f$-th cash
300 flow, \f$ t_i \f$ is its payment time, and \f$ B(t_i) \f$
301 is the corresponding discount according to the passed yield.
302
303 The modified duration is defined as
304 \f[
305 D_{\mathrm{modified}} = -\frac{1}{P} \frac{\partial P}{\partial y}
306 \f]
307 where \f$ P \f$ is the present value of the cash flows
308 according to the given IRR \f$ y \f$.
309
310 The Macaulay duration is defined for a compounded IRR as
311 \f[
312 D_{\mathrm{Macaulay}} = \left( 1 + \frac{y}{N} \right)
313 D_{\mathrm{modified}}
314 \f]
315 where \f$ y \f$ is the IRR and \f$ N \f$ is the number of
316 cash flows per year.
317 */
318 static Time duration(const Leg& leg,
319 const InterestRate& yield,
320 Duration::Type type,
321 bool includeSettlementDateFlows,
322 Date settlementDate = Date(),
323 Date npvDate = Date());
324 static Time duration(const Leg& leg,
325 Rate yield,
326 const DayCounter& dayCounter,
327 Compounding compounding,
328 Frequency frequency,
329 Duration::Type type,
330 bool includeSettlementDateFlows,
331 Date settlementDate = Date(),
332 Date npvDate = Date());
333
334 //! Cash-flow convexity
335 /*! The convexity of a string of cash flows is defined as
336 \f[
337 C = \frac{1}{P} \frac{\partial^2 P}{\partial y^2}
338 \f]
339 where \f$ P \f$ is the present value of the cash flows
340 according to the given IRR \f$ y \f$.
341 */
342 static Real convexity(const Leg& leg,
343 const InterestRate& yield,
344 bool includeSettlementDateFlows,
345 Date settlementDate = Date(),
346 Date npvDate = Date());
347 static Real convexity(const Leg& leg,
348 Rate yield,
349 const DayCounter& dayCounter,
350 Compounding compounding,
351 Frequency frequency,
352 bool includeSettlementDateFlows,
353 Date settlementDate = Date(),
354 Date npvDate = Date());
355
356 //! Basis-point value
357 /*! Obtained by setting dy = 0.0001 in the 2nd-order Taylor
358 series expansion.
359 */
360 static Real basisPointValue(const Leg& leg,
361 const InterestRate& yield,
362 bool includeSettlementDateFlows,
363 Date settlementDate = Date(),
364 Date npvDate = Date());
365 static Real basisPointValue(const Leg& leg,
366 Rate yield,
367 const DayCounter& dayCounter,
368 Compounding compounding,
369 Frequency frequency,
370 bool includeSettlementDateFlows,
371 Date settlementDate = Date(),
372 Date npvDate = Date());
373
374 //! Yield value of a basis point
375 /*! The yield value of a one basis point change in price is
376 the derivative of the yield with respect to the price
377 multiplied by 0.01
378 */
379 static Real yieldValueBasisPoint(const Leg& leg,
380 const InterestRate& yield,
381 bool includeSettlementDateFlows,
382 Date settlementDate = Date(),
383 Date npvDate = Date());
384 static Real yieldValueBasisPoint(const Leg& leg,
385 Rate yield,
386 const DayCounter& dayCounter,
387 Compounding compounding,
388 Frequency frequency,
389 bool includeSettlementDateFlows,
390 Date settlementDate = Date(),
391 Date npvDate = Date());
392 //@}
393
394 //! \name Z-spread functions
395 /*! For details on z-spread refer to:
396 "Credit Spreads Explained", Lehman Brothers European Fixed
397 Income Research - March 2004, D. O'Kane
398 */
399 //@{
400 //! NPV of the cash flows.
401 /*! The NPV is the sum of the cash flows, each discounted
402 according to the z-spreaded term structure. The result
403 is affected by the choice of the z-spread compounding
404 and the relative frequency and day counter.
405 */
406 static Real npv(const Leg& leg,
407 const ext::shared_ptr<YieldTermStructure>& discount,
409 const DayCounter& dayCounter,
410 Compounding compounding,
411 Frequency frequency,
412 bool includeSettlementDateFlows,
413 Date settlementDate = Date(),
414 Date npvDate = Date());
415 //! implied Z-spread.
416 static Spread zSpread(const Leg& leg,
417 Real npv,
418 const ext::shared_ptr<YieldTermStructure>&,
419 const DayCounter& dayCounter,
420 Compounding compounding,
421 Frequency frequency,
422 bool includeSettlementDateFlows,
423 Date settlementDate = Date(),
424 Date npvDate = Date(),
425 Real accuracy = 1.0e-10,
426 Size maxIterations = 100,
427 Rate guess = 0.0);
428 //! deprecated implied Z-spread.
429 static Spread zSpread(const Leg& leg,
430 const ext::shared_ptr<YieldTermStructure>& d,
431 Real npv,
432 const DayCounter& dayCounter,
433 Compounding compounding,
434 Frequency frequency,
435 bool includeSettlementDateFlows,
436 Date settlementDate = Date(),
437 Date npvDate = Date(),
438 Real accuracy = 1.0e-10,
439 Size maxIterations = 100,
440 Rate guess = 0.0) {
441 return zSpread(leg, npv, d, dayCounter, compounding, frequency,
442 includeSettlementDateFlows, settlementDate, npvDate,
443 accuracy, maxIterations, guess);
444 }
445 //@}
446
447 };
448
449}
450
451#endif
Base class for cash flows.
Real derivative(Rate y) const
Definition: cashflows.cpp:763
Real operator()(Rate y) const
Definition: cashflows.cpp:755
cashflow-analysis functions
Definition: cashflows.hpp:41
static Date::serial_type accruedDays(const Leg &leg, bool includeSettlementDateFlows, Date settlementDate=Date())
Definition: cashflows.cpp:359
static Real previousCashFlowAmount(const Leg &leg, bool includeSettlementDateFlows, Date settlementDate=Date())
Definition: cashflows.cpp:143
static Rate previousCouponRate(const Leg &leg, bool includeSettlementDateFlows, Date settlementDate=Date())
Definition: cashflows.cpp:215
CashFlows(const CashFlows &)=delete
static Rate nextCouponRate(const Leg &leg, bool includeSettlementDateFlows, Date settlementDate=Date())
Definition: cashflows.cpp:224
static Date referencePeriodStart(const Leg &leg, bool includeSettlementDateFlows, Date settlDate=Date())
Definition: cashflows.cpp:279
static Real nextCashFlowAmount(const Leg &leg, bool includeSettlementDateFlows, Date settlementDate=Date())
Definition: cashflows.cpp:159
static Real yieldValueBasisPoint(const Leg &leg, const InterestRate &yield, bool includeSettlementDateFlows, Date settlementDate=Date(), Date npvDate=Date())
Yield value of a basis point.
Definition: cashflows.cpp:1105
static Real accruedAmount(const Leg &leg, bool includeSettlementDateFlows, Date settlementDate=Date())
Definition: cashflows.cpp:377
static Real basisPointValue(const Leg &leg, const InterestRate &yield, bool includeSettlementDateFlows, Date settlementDate=Date(), Date npvDate=Date())
Basis-point value.
Definition: cashflows.cpp:1058
static Leg::const_iterator nextCashFlow(const Leg &leg, bool includeSettlementDateFlows, Date settlementDate=Date())
the first cashflow paying after the given date
Definition: cashflows.cpp:102
static Spread zSpread(const Leg &leg, Real npv, const ext::shared_ptr< YieldTermStructure > &, const DayCounter &dayCounter, Compounding compounding, Frequency frequency, bool includeSettlementDateFlows, Date settlementDate=Date(), Date npvDate=Date(), Real accuracy=1.0e-10, Size maxIterations=100, Rate guess=0.0)
implied Z-spread.
Definition: cashflows.cpp:1228
static Real npv(const Leg &leg, const YieldTermStructure &discountCurve, bool includeSettlementDateFlows, Date settlementDate=Date(), Date npvDate=Date())
NPV of the cash flows.
Definition: cashflows.cpp:425
static Date accrualEndDate(const Leg &leg, bool includeSettlementDateFlows, Date settlementDate=Date())
Definition: cashflows.cpp:263
static Date accrualStartDate(const Leg &leg, bool includeSettlementDateFlows, Date settlDate=Date())
Definition: cashflows.cpp:247
static Leg::const_reverse_iterator previousCashFlow(const Leg &leg, bool includeSettlementDateFlows, Date settlementDate=Date())
the last cashflow paying before or at the given date
Definition: cashflows.cpp:84
static Date nextCashFlowDate(const Leg &leg, bool includeSettlementDateFlows, Date settlementDate=Date())
Definition: cashflows.cpp:131
static Rate yield(const Leg &leg, Real npv, const DayCounter &dayCounter, Compounding compounding, Frequency frequency, bool includeSettlementDateFlows, Date settlementDate=Date(), Date npvDate=Date(), Real accuracy=1.0e-10, Size maxIterations=100, Rate guess=0.05)
Implied internal rate of return.
Definition: cashflows.cpp:904
static Time accrualPeriod(const Leg &leg, bool includeSettlementDateFlows, Date settlementDate=Date())
Definition: cashflows.cpp:311
static Date::serial_type accrualDays(const Leg &leg, bool includeSettlementDateFlows, Date settlementDate=Date())
Definition: cashflows.cpp:326
static Date maturityDate(const Leg &leg)
Definition: cashflows.cpp:52
static Time duration(const Leg &leg, const InterestRate &yield, Duration::Type type, bool includeSettlementDateFlows, Date settlementDate=Date(), Date npvDate=Date())
Cash-flow duration.
Definition: cashflows.cpp:925
CashFlows & operator=(CashFlows &&)=delete
static Date startDate(const Leg &leg)
Definition: cashflows.cpp:38
static Real nominal(const Leg &leg, bool includeSettlementDateFlows, Date settlDate=Date())
Definition: cashflows.cpp:232
CashFlows & operator=(const CashFlows &)=delete
static Date previousCashFlowDate(const Leg &leg, bool includeSettlementDateFlows, Date settlementDate=Date())
Definition: cashflows.cpp:119
static Rate yield(const Solver &solver, const Leg &leg, Real npv, const DayCounter &dayCounter, Compounding compounding, Frequency frequency, bool includeSettlementDateFlows, Date settlementDate=Date(), Date npvDate=Date(), Real accuracy=1.0e-10, Rate guess=0.05)
Definition: cashflows.hpp:277
static Rate atmRate(const Leg &leg, const YieldTermStructure &discountCurve, bool includeSettlementDateFlows, Date settlementDate=Date(), Date npvDate=Date(), Real npv=Null< Real >())
At-the-money rate of the cash flows.
Definition: cashflows.cpp:510
static bool isExpired(const Leg &leg, bool includeSettlementDateFlows, Date settlementDate=Date())
Definition: cashflows.cpp:66
static Real bps(const Leg &leg, const YieldTermStructure &discountCurve, bool includeSettlementDateFlows, Date settlementDate=Date(), Date npvDate=Date())
Basis-point sensitivity of the cash flows.
Definition: cashflows.cpp:450
static Spread zSpread(const Leg &leg, const ext::shared_ptr< YieldTermStructure > &d, Real npv, const DayCounter &dayCounter, Compounding compounding, Frequency frequency, bool includeSettlementDateFlows, Date settlementDate=Date(), Date npvDate=Date(), Real accuracy=1.0e-10, Size maxIterations=100, Rate guess=0.0)
deprecated implied Z-spread.
Definition: cashflows.hpp:429
CashFlows(CashFlows &&)=delete
static std::pair< Real, Real > npvbps(const Leg &leg, const YieldTermStructure &discountCurve, bool includeSettlementDateFlows, Date settlementDate=Date(), Date npvDate=Date())
NPV and BPS of the cash flows.
Definition: cashflows.cpp:473
static Date referencePeriodEnd(const Leg &leg, bool includeSettlementDateFlows, Date settlDate=Date())
Definition: cashflows.cpp:295
static Time accruedPeriod(const Leg &leg, bool includeSettlementDateFlows, Date settlementDate=Date())
Definition: cashflows.cpp:341
static Real convexity(const Leg &leg, const InterestRate &yield, bool includeSettlementDateFlows, Date settlementDate=Date(), Date npvDate=Date())
Cash-flow convexity.
Definition: cashflows.cpp:974
Concrete date class.
Definition: date.hpp:125
std::int_fast32_t serial_type
serial number type
Definition: date.hpp:128
day counter class
Definition: daycounter.hpp:44
Concrete interest rate class.
template class providing a null value for a given type.
Definition: null.hpp:76
Interest-rate term structure.
Duration type enumeration.
Date d
Frequency
Frequency of events.
Definition: frequency.hpp:37
Real Time
continuous quantity with 1-year units
Definition: types.hpp:62
QL_REAL Real
real number
Definition: types.hpp:50
Real Spread
spreads on interest rates
Definition: types.hpp:74
Real Rate
interest rates
Definition: types.hpp:70
std::size_t Size
size of a container
Definition: types.hpp:58
Instrument rate class.
Definition: any.hpp:35
Compounding
Interest rate coumpounding rule.
Definition: compounding.hpp:32
std::vector< ext::shared_ptr< CashFlow > > Leg
Sequence of cash-flows.
Definition: cashflow.hpp:78
Maps shared_ptr to either the boost or std implementation.