CapeTools Generic IR Tree Pricer

General Description

Functions to price generic interest rate structures under an interest rate tree framework. If your product's payoff does not refer to LIBOR RATES in the past (ie - Asian options) you can use this framework.

Here are some general rules to keep in mind regarding how the payoff grid will be processed :

Rows are time points. As you read down the grid you are moving forward in time.

Columns represent your payoff formulas. You can create as many columns as you like. Columns are there to help you split up your payoff, or for a payoff function within a cell to refer to other cells within the grid.

For the Tree pricer, the pricing starts at the last timestep and prices from left to right.

Formula expressions within a cell cannot refer to formula cells to the right of itself.

Formula expressions within a cell cannot refer to formula cells above itself (past time points).

Given any step within your payoff table, the current step is defined as the fixing date and the next step is the payment date.

No payoff formulas may be present within the very last timestep (used as a holder for the last rate payment date).

If you bear the 7 points in mind, this should aid you in constructing payoff grids.

Below is an example of a payoff table. This deal prices a cap (sum of caplets). The Step column is not required.

Step EventDate PayOff Col PayOff Col PayOff Col PayOff Col
1 #21/07/2006# Libor(cRow) ZCB(cRow) Caplet(_X, 0.0) * Cvg(cRow) * _Notional Cell(cRow, cCol-1) + PVCol(cCol)
2 #23/10/2006# Libor(cRow) ZCB(cRow) Caplet(_X, 0.0) * Cvg(cRow) * _Notional Cell(cRow, cCol-1) + PVCol(cCol)
3 #22/01/2007# Libor(cRow) ZCB(cRow) Caplet(_X, 0.0) * Cvg(cRow) * _Notional Cell(cRow, cCol-1) + PVCol(cCol)
4 #23/04/2007# Libor(cRow) ZCB(cRow) Caplet(_X, 0.0) * Cvg(cRow) * _Notional Cell(cRow, cCol-1) + PVCol(cCol)
5 #23/07/2007# Libor(cRow) ZCB(cRow) Caplet(_X, 0.0) * Cvg(cRow) * _Notional Cell(cRow, cCol-1) + PVCol(cCol)
6 #22/10/2007# Libor(cRow) ZCB(cRow) Caplet(_X, 0.0) * Cvg(cRow) * _Notional Cell(cRow, cCol-1) + PVCol(cCol)
7 #21/01/2008# Libor(cRow) ZCB(cRow) Caplet(_X, 0.0) * Cvg(cRow) * _Notional Cell(cRow, cCol-1) + PVCol(cCol)
8 #21/04/2008# Libor(cRow) ZCB(cRow) Caplet(_X, 0.0) * Cvg(cRow) * _Notional Cell(cRow, cCol-1) + PVCol(cCol)
9 #21/07/2008# Libor(cRow) ZCB(cRow) Caplet(_X, 0.0) * Cvg(cRow) * _Notional Cell(cRow, cCol-1) + PVCol(cCol)
10 #21/10/2008# Libor(cRow) ZCB(cRow) Caplet(_X, 0.0) * Cvg(cRow) * _Notional Cell(cRow, cCol-1) + PVCol(cCol)
11 #21/01/2009# Libor(cRow) ZCB(cRow) Caplet(_X, 0.0) * Cvg(cRow) * _Notional Cell(cRow, cCol-1) + PVCol(cCol)
12 #21/04/2009# Libor(cRow) ZCB(cRow) Caplet(_X, 0.0) * Cvg(cRow) * _Notional Cell(cRow, cCol-1) + PVCol(cCol)
13 #21/07/2009# Libor(cRow) ZCB(cRow) Caplet(_X, 0.0) * Cvg(cRow) * _Notional Cell(cRow, cCol-1) + PVCol(cCol)
14 #21/10/2009# Libor(cRow) ZCB(cRow) Caplet(_X, 0.0) * Cvg(cRow) * _Notional Cell(cRow, cCol-1) + PVCol(cCol)
15 #21/01/2010# Libor(cRow) ZCB(cRow) Caplet(_X, 0.0) * Cvg(cRow) * _Notional Cell(cRow, cCol-1) + PVCol(cCol)
16 #21/04/2010# Libor(cRow) ZCB(cRow) Caplet(_X, 0.0) * Cvg(cRow) * _Notional Cell(cRow, cCol-1) + PVCol(cCol)
17 #21/07/2010# Libor(cRow) ZCB(cRow) Caplet(_X, 0.0) * Cvg(cRow) * _Notional Cell(cRow, cCol-1) + PVCol(cCol)
18 #21/10/2010# Libor(cRow) ZCB(cRow) Caplet(_X, 0.0) * Cvg(cRow) * _Notional Cell(cRow, cCol-1) + PVCol(cCol)
19 #21/01/2011# Libor(cRow) ZCB(cRow) Caplet(_X, 0.0) * Cvg(cRow) * _Notional Cell(cRow, cCol-1) + PVCol(cCol)
20 #21/04/2011# Libor(cRow) ZCB(cRow) Caplet(_X, 0.0) * Cvg(cRow) * _Notional Cell(cRow, cCol-1)
21 #21/07/2011#

Note the following financial definitions :

DCF(date) = Discount factor.at the given 'date'

.
Coverage(start, end) = Year fraction between 'start' and 'end' dates.

CashRate(start, end) = ((DCF(start)/DCF(end)) - 1) / Coverage(start, end)

Libor(start, end) = CashRate(start, end) + FwdSpread(end)

If a yieldcurve stripper was used without utilizing cross-currency swaps against the dollar and the Index object does not specify any Basis Swap curves then the FwdSpread(end) function will be equal to zero (0).

If a yieldcurve stripper was used utilizing cross-currency swaps against the dollar, then the CashRate() function uses only the discounting curve and the rate will not equal the LIBOR rate. The forward spread is the difference between the CashRate() and the Libor() rate.

If a yieldcurve stripper was used without utilizing cross-currency swaps against the dollar but the Index object does specify a Basis Swap curve then the CashRate() function will return the LIBOR rate. However the Index object specifies a spread to be added to the LIBOR rate and this spread is encapsulated within the FwdSpread() function.

Financial variables (case sensitive) :

cRow - refers to the current Row with the payoff table. Within all the Financial functions listed below, we recommend that you always use this variable (with perhaps offset values, ie - cRow, cRow-1, cRow+2 etc...) instead of a fixed value (ie - 1, 2 etc...). This is important especially if you enable American type handling from one timestep to another. Using static integer values will generate incorrect results.

cCol - refers to the current Column with the payoff table. Within all the Financial functions listed below, we recommend that you always use this variable (with perhaps offset values, ie - cCol, cCol-1, cCol+2 etc...).

pct - When an integer value is placed in front of this expression (no spaces), the function will interp the whole expression as a percent. (ie - 5pct => 0.05)

bp - When an integer value is placed in front of this expression (no spaces), the function will interp the whole expression as basis points. (ie - 5bp => 0.0005)

_XXX - Constant variables can be defined by filling in the 'ConstParams' parameter of the GenericIRTreePricer() function. All variables must be defined with a leading underscore character ( ie - _XXX = 0.5)

Financial functions (case sensitive) :

Libor(row) - Returns the libor value between the current time step and the next time step. Thus the LIBOR rate will be FIXED at this timestep and PAID at the next timestep.

CashRate(row) - Returns the CashRate value between the current time step and the next time step. Thus the CashRate rate will be FIXED at this timestep and PAID at the next timestep.

ZCB(row) - Returns the zero coupon bond (discount factor) value up to the current (rate fixing) timestep.

Because the the current step is defined as the fixing date and the next step is the payment date, you cannot price a caplet via the following expression [max(Libor(cRow) - strike, dTest)]. Expressions like these only work if the current step is the payment step. However we have provided the correct functions for you to price caplets/floorlets.

Caplet(strike, dTest) - Returns the caplet value [max(Libor(cRow) - strike, dTest)] between the current time step and the next time step.

Floorlet(strike, dTest) - Returns the floorlet value [max(strike - Libor(cRow), dTest)] between the current time step and the next time step.

Cvg(row) - Returns the year fraction between the previous time step and this time step.

FwdSpread(row) - Returns the Forward Spread at the given time step.

Cell(row, col) - Retrieves a computed value within the PayOff Table. You can only refer to rows and columns below and to the left of the current cell location. You can also refer to the current cell location. This is because the Tree pricer prices backwards in time and thus past payoff values have not been computed as yet. The expression 'Cell(cRow, cCol-1)' retrieves the payoff value for the current timestep but at the previous column.

LiborMin(startRow, endRow) - Retrieves the minimum LIBOR value across a starting and ending 'TimeStep' range. For the 'startRow' and 'endRow' parameters you can only refer to rows above or equal to the current cell location (past dates).

LiborMax(startRow, endRow) - Retrieves the maximum LIBOR value across a starting and ending 'TimeStep' range. For the 'startRow' and 'endRow' parameters you can only refer to rows above or equal to the current cell location (past dates).

LiborAvg(startRow, endRow) - Retrieves the average of the LIBOR value across a starting and ending 'TimeStep' range. For the 'startRow' and 'endRow' parameters you can only refer to rows above or equal to the current cell location (past dates).

LiborSum(startRow, endRow) - Retrieves the sum of the LIBOR values across a starting and ending 'TimeStep' range. For the 'startRow' and 'endRow' parameters you can only refer to rows above or equal to the current cell location (past dates).

CashRateMin(startRow, endRow) - Retrieves the minimum LIBOR value across a starting and ending 'TimeStep' range. For the 'startRow' and 'endRow' parameters you can only refer to rows above or equal to the current cell location (past dates).

CashRateMax(startRow, endRow) - Retrieves the maximum LIBOR value across a starting and ending 'TimeStep' range. For the 'startRow' and 'endRow' parameters you can only refer to rows above or equal to the current cell location (past dates).

CashRateAvg(startRow, endRow) - Retrieves the average of the LIBOR value across a starting and ending 'TimeStep' range. For the 'startRow' and 'endRow' parameters you can only refer to rows above or equal to the current cell location (past dates).

CashRateSum(startRow, endRow) - Retrieves the sum of the LIBOR values across a starting and ending 'TimeStep' range. For the 'startRow' and 'endRow' parameters you can only refer to rows above or equal to the current cell location (past dates).

ZCBMin(startRow, endRow) - Retrieves the minimum zero coupon bond value across a starting and ending 'TimeStep' range. For the 'startRow' and 'endRow' parameters you can only refer to rows above or equal to the current cell location (past dates).

ZCBMax(startRow, endRow) - Retrieves the maximum zero coupon bond value across a starting and ending 'TimeStep' range. For the 'startRow' and 'endRow' parameters you can only refer to rows above or equal to the current cell location (past dates).

ZCBAvg(startRow, endRow) - Retrieves the average of the zero coupon bond value across a starting and ending 'TimeStep' range. For the 'startRow' and 'endRow' parameters you can only refer to rows above or equal to the current cell location (past dates).

ZCBSum(startRow, endRow) - Retrieves the sum of the zero coupon bond values across a starting and ending 'TimeStep' range. For the 'startRow' and 'endRow' parameters you can only refer to rows above or equal to the current cell location (past dates).

GridRowMin(Row, startCol, endCol) - Retrieves the minimum value across the columns of the PayOff table (given a 'TimeStep' or row value). For the 'startCol' and 'endCol' parameters you can only refer to columns to the left or equal to the current cell location.

GridRowMax(Row, startCol, endCol) - Retrieves the maximum value across the columns of the PayOff table (given a 'TimeStep' or row value). For the 'startCol' and 'endCol' parameters you can only refer to columns to the left or equal to the current cell location.

GridRowAvg(Row, startCol, endCol) - Retrieves the average value across the columns of the PayOff table (given a 'TimeStep' or row value). For the 'startCol' and 'endCol' parameters you can only refer to columns to the left or equal to the current cell location.

GridRowSum(Row, startCol, endCol) - Retrieves the sum across the columns of the PayOff table (given a 'TimeStep' or row value). For the 'startCol' and 'endCol' parameters you can only refer to columns to the left or equal to the current cell location.

Interp1D(nIndex, XValue ) - If any 1D interpolation objects have been passed into GenericIRTreePricer() function (a maximum of 2 objects can be defined), then you can execute this function within your payoff grid. The 'nIndex' parameter refers to the intepolation object (1-based). 'XValue' is the value where the interpolation is to be performed. The interpolation object will not extrapolate values.

Interp2D(nIndex, XValue, YValue) - If any 2D interpolation objects have been passed into GenericIRTreePricer() function (a maximum of 2 objects can be defined), then you can execute this function within your payoff grid. The 'nIndex' parameter refers to the intepolation object (1-based). 'XValue' and 'YValue' are the values where the interpolation is to be performed. The interpolation object will not extrapolate values.

iff(condition, a, b) - Tests for the condition and returns the value of 'a' if true or 'b' if false.

Predefined functions (case sensitive) :

sin(x) ( sine function )

cos(x) ( cosine function )

tan(x) ( tangens function )

asin(x) ( arcus sine function )

acos(x) ( arcus cosine function )

atan(x) ( arcus tangens function )

sinh(x) ( hyperbolic sine function )

cosh(x) ( hyperbolic cosine function )

tanh(x) ( hyperbolic tangens function )

asinh(x) ( hyperbolic arcus sine function )

acosh(x) ( hyperbolic arcus cosine function )

atanh(x) ( hyperbolic arcur tangens function )

log2(x) ( logarithm to the base 2 )

log10(x) ( logarithm to the base 10 )

log(x) ( logarithm to the base 10 )

ln(x) ( logarithm to the base e (2.71828...)

exp(x) ( e raised to the power of x )

sqrt(x) ( square root of a value )

sign(x) ( sign function ) -1=(if x<0), 1=(if x>0 )

rint(x) ( round to nearest integer )

abs(x) ( absolute value )

min(a,b,c,d,e,...) ( min of all arguments ie - min(-2,1,5,-6) )

max(a,b,c,d,e,...) ( max of all arguments ie - max(-2,1,5,-6) )

sum(a,b,c,d,e,...) ( sum of all arguments ie - sum(-2,1,5,-6) )

avg(a,b,c,d,e,...) ( mean value of all arguments ie - avg(-2,1,5,-6) )

ite(x,y,z) ( if ... then ... else ... : ie - ite(a<b, 5.0, -3.0) )

Predefined operators :

+ ( addition )

- ( subtraction )

* ( multiplication )

/ ( division )

^ ( raise x to the power of y )

Predefined operators that can be used within the first parameter of the ite() or iff() function :

and ( logical and )

or ( logical or )

<= ( less or equal )

>= ( greater or equal )

!= ( not equal )

== ( equal to )

> ( greater than )

< ( less than )

Brackets, '(' and ')', can also be used to simplify expressions.

Step	EventDate	PayOff Col	PayOff Col	PayOff Col	PayOff Col
1	#21/07/2006#	Libor(cRow)	ZCB(cRow)	Caplet(_X, 0.0) * Cvg(cRow) * _Notional	Cell(cRow, cCol-1) + PVCol(cCol)
2	#23/10/2006#	Libor(cRow)	ZCB(cRow)	Caplet(_X, 0.0) * Cvg(cRow) * _Notional	Cell(cRow, cCol-1) + PVCol(cCol)
3	#22/01/2007#	Libor(cRow)	ZCB(cRow)	Caplet(_X, 0.0) * Cvg(cRow) * _Notional	Cell(cRow, cCol-1) + PVCol(cCol)
4	#23/04/2007#	Libor(cRow)	ZCB(cRow)	Caplet(_X, 0.0) * Cvg(cRow) * _Notional	Cell(cRow, cCol-1) + PVCol(cCol)
5	#23/07/2007#	Libor(cRow)	ZCB(cRow)	Caplet(_X, 0.0) * Cvg(cRow) * _Notional	Cell(cRow, cCol-1) + PVCol(cCol)
6	#22/10/2007#	Libor(cRow)	ZCB(cRow)	Caplet(_X, 0.0) * Cvg(cRow) * _Notional	Cell(cRow, cCol-1) + PVCol(cCol)
7	#21/01/2008#	Libor(cRow)	ZCB(cRow)	Caplet(_X, 0.0) * Cvg(cRow) * _Notional	Cell(cRow, cCol-1) + PVCol(cCol)
8	#21/04/2008#	Libor(cRow)	ZCB(cRow)	Caplet(_X, 0.0) * Cvg(cRow) * _Notional	Cell(cRow, cCol-1) + PVCol(cCol)
9	#21/07/2008#	Libor(cRow)	ZCB(cRow)	Caplet(_X, 0.0) * Cvg(cRow) * _Notional	Cell(cRow, cCol-1) + PVCol(cCol)
10	#21/10/2008#	Libor(cRow)	ZCB(cRow)	Caplet(_X, 0.0) * Cvg(cRow) * _Notional	Cell(cRow, cCol-1) + PVCol(cCol)
11	#21/01/2009#	Libor(cRow)	ZCB(cRow)	Caplet(_X, 0.0) * Cvg(cRow) * _Notional	Cell(cRow, cCol-1) + PVCol(cCol)
12	#21/04/2009#	Libor(cRow)	ZCB(cRow)	Caplet(_X, 0.0) * Cvg(cRow) * _Notional	Cell(cRow, cCol-1) + PVCol(cCol)
13	#21/07/2009#	Libor(cRow)	ZCB(cRow)	Caplet(_X, 0.0) * Cvg(cRow) * _Notional	Cell(cRow, cCol-1) + PVCol(cCol)
14	#21/10/2009#	Libor(cRow)	ZCB(cRow)	Caplet(_X, 0.0) * Cvg(cRow) * _Notional	Cell(cRow, cCol-1) + PVCol(cCol)
15	#21/01/2010#	Libor(cRow)	ZCB(cRow)	Caplet(_X, 0.0) * Cvg(cRow) * _Notional	Cell(cRow, cCol-1) + PVCol(cCol)
16	#21/04/2010#	Libor(cRow)	ZCB(cRow)	Caplet(_X, 0.0) * Cvg(cRow) * _Notional	Cell(cRow, cCol-1) + PVCol(cCol)
17	#21/07/2010#	Libor(cRow)	ZCB(cRow)	Caplet(_X, 0.0) * Cvg(cRow) * _Notional	Cell(cRow, cCol-1) + PVCol(cCol)
18	#21/10/2010#	Libor(cRow)	ZCB(cRow)	Caplet(_X, 0.0) * Cvg(cRow) * _Notional	Cell(cRow, cCol-1) + PVCol(cCol)
19	#21/01/2011#	Libor(cRow)	ZCB(cRow)	Caplet(_X, 0.0) * Cvg(cRow) * _Notional	Cell(cRow, cCol-1) + PVCol(cCol)
20	#21/04/2011#	Libor(cRow)	ZCB(cRow)	Caplet(_X, 0.0) * Cvg(cRow) * _Notional	Cell(cRow, cCol-1)
21	#21/07/2011#