Swap
Description
Create and price a Swap
instrument object for one or more
Swap instruments using this workflow:
Use
fininstrument
to create aSwap
instrument object for one or more Swap instruments.Use
ratecurve
to specify a curve model for theSwap
instrument object or usefinmodel
to specify aHullWhite
,BlackKarasinski
,BlackDermanToy
,CoxIngersollRoss
, orLinearGaussian2F
model.Choose a pricing method.
When using a
ratecurve
, usefinpricer
to specify aDiscount
pricing methodWhen using a
HullWhite
,BlackKarasinski
,CoxIngersollRoss
, orBlackDermanToy
model , use anIRTree
pricing method for one or moreSwap
instruments.When using a
HullWhite
,BlackKarasinski
, orLinearGaussian2F
model, usefinpricer
to specify anIRMonteCarlo
pricing method for one or moreSwap
instruments.
For more information on this workflow, see Get Started with Workflows Using Object-Based Framework for Pricing Financial Instruments.
For more information on the available models and pricing methods for a
Swap
instrument, see Choose Instruments, Models, and Pricers.
Creation
Syntax
Description
creates a SwapInstrument
= fininstrument(InstrumentType
,'Maturity
',maturity_date,'LegRate
',leg_rate)Swap
object for one or more Swap instruments by
specifying InstrumentType
and sets the properties for the
required name-value pair arguments Maturity
and
LegRate
.
The Swap
instrument supports vanilla swaps, amortizing
swaps and forward swaps. You can use the Swap
instrument
for a single currency swap but not a cross-currency swap. For more
information on a Swap
instrument, see More About.
sets optional properties using
additional name-value pairs in addition to the required arguments in the
previous syntax. For example, SwapInstrument
= fininstrument(___,Name,Value
)SwapInstrument =
fininstrument("Swap",'Maturity',datetime(2019,1,30),'LegRate',[0.06
0.12],'LegType',["fixed","fixed"],'Basis',1,'Notional',100,'StartDate',datetime(2016,1,30),'DaycountAdjustedCashFlow',true,'BusinessDayConvention',"follow",'ProjectionCurve',ratecurve,'Name',"swap_instrument")
creates a Swap
option with a maturity of January 30,
2019. You can specify multiple name-value pair arguments.
Input Arguments
InstrumentType
— Instrument type
string with value "Swap"
| string array with values of "Swap"
| character vector with value 'Swap'
| cell array of character vectors with values of
'Swap'
Instrument type, specified as a string with the value of
"Swap"
, a character vector with the value of
'Swap'
, an
NINST
-by-1
string array with
values of "Swap"
, or an
NINST
-by-1
cell array of
character vectors with values of 'Swap'
.
Data Types: char
| cell
| string
Specify required
and optional pairs of arguments as
Name1=Value1,...,NameN=ValueN
, where
Name
is the argument name and Value
is
the corresponding value. Name-value arguments must appear after other arguments,
but the order of the pairs does not matter.
Before R2021a, use commas to separate each name and value, and enclose
Name
in quotes.
Example: SwapInstrument =
fininstrument("Swap",'Maturity',datetime(2019,1,30),'LegRate',[0.06
0.12],'LegType',["fixed","fixed"],'Basis',1,'Notional',100,'StartDate',datetime(2016,1,30),'DaycountAdjustedCashFlow',true,'BusinessDayConvention',"follow",'ProjectionCurve',ratecurve,'Name',"swap_instrument")
Swap
Name-Value Pair ArgumentsMaturity
— Swap maturity date
datetime array | string array | date character vector
Swap maturity date, specified as the comma-separated pair
consisting of 'Maturity'
and a scalar or an
NINST
-by-1
vector using a
datetime array, string array, or date character vectors.
To support existing code, Swap
also
accepts serial date numbers as inputs, but they are not recommended.
If you use date character vectors or strings, the format must be
recognizable by datetime
because
the Maturity
property is stored as a
datetime.
LegRate
— Leg rate in decimal values
matrix
Leg rate in decimal values, specified as the comma-separated pair
consisting of 'LegRate'
and a
NINST
-by-2
matrix. Each
row can be defined as one of the following:
[CouponRate Spread]
(fixed-float)[Spread CouponRate]
(float-fixed)[CouponRate CouponRate]
(fixed-fixed)[Spread Spread]
(float-float)
CouponRate
is the decimal annual rate.
Spread
is the number of basis points in
decimals over the reference rate. The first column represents the
receiving leg, while the second column represents the paying
leg.
Data Types: double
Swap
Name-Value Pair ArgumentsLegType
— Leg type
["fixed","float"]
for each
instrument (default) | cell array of character vectors with values
{'fixed','fixed'}
,
{'fixed','float'}
,
{'float','fixed'}
, or
{'float','float'}
| string array with values ["fixed","fixed"]
,
["fixed","float"]
,
["float","fixed"]
, or
["float","float"]
Leg type, specified as the comma-separated pair consisting of
'LegType'
and a cell array of character
vectors or a string array with the supported values. The
LegType
defines the interpretation of the
values entered in LegRate
.
Note
When you specify a Swap
instrument as
the underlying asset for a Swaption
instrument while using a Normal
, SABR
, Black
, or HullWhite
pricer, the Swap
LegType
must be
["fixed","float"]
or
["float","fixed"]
. You must also set
the ExerciseStyle
name-value pair
argument of the associated Swaption
instrument to
'European'
.
Data Types: cell
| string
ProjectionCurve
— Rate curve for projecting floating cash flows
ratecurve.empty
(default) | scalar ratecurve
object | vector of ratecurve
objects
Rate curve for projecting floating cash flows, specified as the
comma-separated pair consisting of
'ProjectionCurve'
and a scalar
ratecurve
object or an
NINST
-by-1
vector of
ratecurve
objects. You must create this
object using ratecurve
. Use
this optional input if the forward curve is different from the
discount curve.
Data Types: object
Reset
— Frequency of payments per year
[2 2]
(default) | numeric value of 0
, 1
,
2
, 3
,
4
, 6
, or
12
| matrix
Frequency of payments per year, specified as the comma-separated
pair consisting of 'Reset'
and scalar or a
NINST
-by-2
matrix if
Reset
is different for each leg) with one of
the following values: 0
, 1
,
2
, 3
,
4
, 6
, or
12
.
Data Types: double
Basis
— Day count basis representing the basis for each leg
[0 0]
(actual/actual) (default) | integer from 0
to
13
Day count basis representing the basis for each leg, specified as
the comma-separated pair consisting of 'Basis'
and a NINST
-by-1
matrix (or
NINST
-by-2
matrix if
Basis
is different for each leg).
0 — actual/actual
1 — 30/360 (SIA)
2 — actual/360
3 — actual/365
4 — 30/360 (PSA)
5 — 30/360 (ISDA)
6 — 30/360 (European)
7 — actual/365 (Japanese)
8 — actual/actual (ICMA)
9 — actual/360 (ICMA)
10 — actual/365 (ICMA)
11 — 30/360E (ICMA)
12 — actual/365 (ISDA)
13 — BUS/252
For more information, see Basis.
Data Types: double
Notional
— Notional principal amount or principal value schedule
100
(default) | scalar numeric | numeric vector | timetable
Notional principal amount or principal value schedule, specified
as the comma-separated pair consisting of
'Notional'
and a scalar numeric or an
NINST
-by-1
numeric vector
or a timetable. Use a scalar or vector for a vanilla
Swap
instrument and a timetable for an
amortizing Swap
instrument.
Notional
accepts a scalar for a principal
amount (or a 1
-by-2
matrix if
Notional
is different for each leg) or a
timetable
for
principal value schedules. For schedules, the first column of the
timetable is dates and the second column is the associated notional
principal value. The date indicates the last day that the principal
value is valid.
Note
If you are creating one or more Swap
instruments and use a timetable, the timetable specification
applies to all of the Swap
instruments.
Notional
does not accept an
NINST
-by-1
cell array
of timetables as input.
Data Types: timetable
| double
LatestFloatingRate
— Latest floating rate for float legs
if not specified, then
ratecurve
must contain this information (default) | scalar numeric | vector
Latest floating rate for float legs, specified as the
comma-separated pair consisting of
'LatestFloatingRate'
and a scalar numeric or
an NINST
-by-1
numeric
vector.
LatestFloatingRate
is a
NINST
-by-1
matrix (or
NINST
-by-2
matrix if
LatestFloatingRate
is different for each
leg).
Data Types: double
ResetOffset
— Lag in rate setting
[0 0]
(default) | vector
Lag in rate setting, specified as the comma-separated pair
consisting of 'ResetOffset'
and a
NINST
-by-2
matrix.
Data Types: double
DaycountAdjustedCashFlow
— Flag to adjust cash flows based on actual period day count
false
(default) | logical value of true
or
false
| vector of logical values of true
or
false
Flag to adjust cash flows based on actual period day count,
specified as the comma-separated pair consisting of
'DaycountAdjustedCashFlow'
and a
NINST
-by-1
matrix (or
NINST
-by-2
matrix if
DaycountAdjustedCashFlow
is different for
each leg) of logicals with values of true
or
false
.
Data Types: logical
BusinessDayConvention
— Business day conventions
"actual"
(default) | string | string array | character vector | cell array of character vectors
Business day conventions, specified as the comma-separated pair
consisting of 'BusinessDayConvention'
and string
(or NINST
-by-2
string array if
BusinessDayConvention
is different for each
leg) or a character vector (or
NINST
-by-2
cell array of
character vectors if BusinessDayConvention
is
different for each leg). The selection for business day convention
determines how nonbusiness days are treated. Nonbusiness days are
defined as weekends plus any other date that businesses are not open
(for example, statutory holidays). Values are:
"actual"
— Nonbusiness days are effectively ignored. Cash flows that fall on non-business days are assumed to be distributed on the actual date."follow"
— Cash flows that fall on a nonbusiness day are assumed to be distributed on the following business day."modifiedfollow"
— Cash flows that fall on a nonbusiness day are assumed to be distributed on the following business day. However, if the following business day is in a different month, the previous business day is adopted instead."previous"
— Cash flows that fall on a nonbusiness day are assumed to be distributed on the previous business day."modifiedprevious"
— Cash flows that fall on a nonbusiness day are assumed to be distributed on the previous business day. However, if the previous business day is in a different month, the following business day is adopted instead.
Data Types: char
| cell
| string
Holidays
— Holidays used in computing business days
NaT
(default) | datetime array | string array | date character vector
Holidays used in computing business days, specified as the
comma-separated pair consisting of 'Holidays'
and
dates using an NINST
-by-1
vector of datetimes, cell array of date character vectors, or date
string array. For
example:
H = holidays(datetime('today'),datetime(2025,12,15)); Swap = fininstrument("Swap",'Maturity',datetime(2025,12,15),'LegRate',[0.06 20],'Holidays',H)
To support existing code, Swap
also
accepts serial date numbers as inputs, but they are not recommended.
EndMonthRule
— End-of-month rule flag for generating dates when Maturity
is end-of-month date for month with 30
or fewer days
[true true]
(in effect) (default) | logical with value of true
or
false
| vector of logicals with values of true
or
false
End-of-month rule flag for generating dates when
Maturity
is an end-of-month date for a month
with 30 or fewer days, specified as the comma-separated pair
consisting of 'EndMonthRule'
and a logical value
of true
or false
using a
NINST
-by-1
matrix (or
NINST
-by-2
matrix if
EndMonthRule
is different for each leg).
If you set
EndMonthRule
tofalse
, the software ignores the rule, meaning that a payment date is always the same numerical day of the month.If you set
EndMonthRule
totrue
, the software sets the rule on, meaning that a payment date is always the last actual day of the month.
Data Types: logical
StartDate
— Date swap starts
Settle
date (default) | datetime array | string | string array | date character vector | cell array of date character vectors
Date swap starts, specified as the comma-separated pair consisting
of 'StartDate'
and a scalar or an
NINST
-by-1
vector using a
datetime array, string array, or date character vectors.
To support existing code, Swap
also
accepts serial date numbers as inputs, but they are not recommended.
Use StartDate
to price a forward swap, that is,
a swap that starts at a future date.
If you use date character vectors or strings, the format must be
recognizable by datetime
because
the StartDate
property is stored as a
datetime.
Data Types: datetime
| char
| string
| cell
Name
— User-defined name for instrument
" "
(default) | string | string array | character vector | cell array of character vectors
User-defined name for the instrument, specified as the
comma-separated pair consisting of 'Name'
and a
scalar string or character vector or an
NINST
-by-1
cell array of
character vectors or string array.
Data Types: char
| cell
| string
Properties
Maturity
— Maturity date
scalar datetime | vector of datetimes
Maturity date, returned as a scalar datetime or an
NINST
-by-1
vector of
datetimes.
Data Types: datetime
LegRate
— Leg rate
matrix
Leg rate, returned as a NINST
-by-2
matrix of decimal values, with each row defined as one of the following:
[CouponRate Spread]
(fixed-float)[Spread CouponRate]
(float-fixed)[CouponRate CouponRate]
(fixed-fixed)[Spread Spread]
(float-float)
Data Types: double
LegType
— Leg type
["fixed","float"]
for each instrument (default) | string array with values ["fixed","fixed"]
,
["fixed","float"]
,
["float","fixed"]
, or
["float","float"]
Leg type, returned as a string array with the values
["fixed","fixed"]
,
["fixed","float"]
,
["float","fixed"]
, or
["float","float"]
.
Data Types: string
ProjectionCurve
— Rate curve used in generating future cash flows
ratecurve.empty
(default) | scalar ratecurve
object | vector of ratecurve
objects
Rate curve used in projecting the future cash flows, returned as a
ratecurve
object or an
NINST
-by-1
vector of
ratecurve
objects.
Data Types: object
Reset
— Reset frequency per year for each swap
[2 2]
(default) | vector
Reset frequency per year for each swap, returned as a scalar or an
NINST
-by-2
matrix.
Data Types: double
Basis
— Day count basis
[0 0]
(actual/actual) (default) | integer from 0
to 13
Day count basis, returned as an
NINST
-by-1
or an
NINST
-by-2
matrix.
Data Types: double
ResetOffset
— Lag in rate setting
[0 0]
(default) | matrix
Lag in rate setting, returned as an
NINST
-by-2
or an
NINST
-by-2
matrix.
Data Types: double
Notional
— Notional principal amount or principal value schedules
100
(default) | scalar numeric | numeric vector | timetable
Notional principal amount, returned as a scalar numeric or an
NINST
-by-1
numeric vector or a
timetable.
Data Types: double
| timetable
LatestFloatingRate
— Rate for the next floating payment
if not specified, then ratecurve
must
contain this information (default) | scalar numeric | numeric vector
Rate for the next floating payment, set at the last reset date, returned
as a scalar numeric or an NINST
-by-1
numeric vector or NINST
-by-2
if LatestFloatingRate
is different for each
leg.
Data Types: double
DaycountAdjustedCashFlow
— Flag to adjust cash flows based on actual period day count
false
(default) | logical value of true
or
false
| vector of logical values of true
or
false
Flag to adjust cash flows based on actual period day count, returned as an
NINST
-by-1
matrix (or an
NINST
-by-2
matrix if
DaycountAdjustedCashFlow
is different for each leg)
of logicals with values of true
or
false
.
Data Types: logical
BusinessDayConvention
— Business day conventions
"actual"
(default) | string | string array
Business day conventions, returned as a string or a
NINST
-by-2
string array if
BusinessDayConvention
is different for each
leg.
Data Types: char
| cell
| string
Holidays
— Holidays used in computing business days
NaT
(default) | datetimes
Holidays used in computing business days, returned as an
NINST
-by-1
vector of
datetimes.
Data Types: datetime
EndMonthRule
— End-of-month rule flag for generating dates when Maturity
is end-of-month date for month with 30 or fewer
days
[true true]
(in effect) (default) | logical with value of true
or
false
| vector of logicals with values of true
or
false
End-of-month rule flag for generating dates when
Maturity
is an end-of-month date for a month with 30
or fewer days, returned as an
NINST
-by-1
matrix (or
NINST
-by-2
matrix if
EndMonthRule
is different for each leg.
Data Types: logical
StartDate
— Date swap starts
Settle
date (default) | scalar datetime | vector of datetimes
Date swap starts, returned as a scalar datetime or an
NINST
-by-1
vector of datetimes.
Data Types: datetime
Name
— User-defined name for instrument
" "
(default) | string | string array
User-defined name for the instrument, returned as a scalar string or an
NINST
-by-1
string array.
Data Types: string
Object Functions
cashflows | Compute cash flow for FixedBond , FloatBond ,
Swap , FRA , STIRFuture ,
OISFuture , OvernightIndexedSwap , or
Deposit instrument |
parswaprate | Compute par swap rate for Swap and
OvernightIndexedSwap instrument |
Examples
Price Vanilla Swap
Instrument Using ratecurve
and Discount
Pricer
This example shows the workflow to price a vanilla Swap
instrument when you use a ratecurve
and a Discount
pricing method.
Create ratecurve Object
Create a ratecurve
object using ratecurve
for the underlying interest-rate curve for the Swap
instrument.
Settle = datetime(2019,9,15); Type = 'zero'; ZeroTimes = [calmonths(6) calyears([1 2 3 4 5 7 10 20 30])]'; ZeroRates = [0.0052 0.0055 0.0061 0.0073 0.0094 0.0119 0.0168 0.0222 0.0293 0.0307]'; ZeroDates = Settle + ZeroTimes; myRC = ratecurve('zero',Settle,ZeroDates,ZeroRates)
myRC = ratecurve with properties: Type: "zero" Compounding: -1 Basis: 0 Dates: [10x1 datetime] Rates: [10x1 double] Settle: 15-Sep-2019 InterpMethod: "linear" ShortExtrapMethod: "next" LongExtrapMethod: "previous"
Create Swap
Instrument Object
Use fininstrument
to create a vanilla Swap
instrument object.
Swap = fininstrument("Swap",'Maturity',datetime(2024,9,15),'LegRate',[0.022 0.019 ],'LegType',["float","fixed"],'ProjectionCurve',myRC,'Name',"swap_instrument")
Swap = Swap with properties: LegRate: [0.0220 0.0190] LegType: ["float" "fixed"] Reset: [2 2] Basis: [0 0] Notional: 100 LatestFloatingRate: [NaN NaN] ResetOffset: [0 0] DaycountAdjustedCashFlow: [0 0] ProjectionCurve: [1x2 ratecurve] BusinessDayConvention: ["actual" "actual"] Holidays: NaT EndMonthRule: [1 1] StartDate: NaT Maturity: 15-Sep-2024 Name: "swap_instrument"
Create Discount
Pricer Object
Use finpricer
to create a Discount
pricer object and use the ratecurve
object for the 'DiscountCurve'
name-value pair argument.
outPricer = finpricer("Discount", 'DiscountCurve',myRC)
outPricer = Discount with properties: DiscountCurve: [1x1 ratecurve]
Price Swap
Instrument
Use price
to compute the price and sensitivities for the vanilla Swap
instrument.
[Price, outPR] = price(outPricer, Swap,["all"])
Price = 7.2279
outPR = priceresult with properties: Results: [1x2 table] PricerData: []
outPR.Results
ans=1×2 table
Price DV01
______ _________
7.2279 -0.046631
Price Swap
Instrument Using CoxIngersollRoss
Model and IRTree
Pricer
This example shows the workflow to price a Swap
instrument when you use a CoxIngersollRoss
model and an IRTree
pricing method.
Create Swap
Instrument Object
Use fininstrument
to create a Swap
instrument object.
Maturity = datetime(2027,1,1); LegType = ["fixed","float"]; LegRate = [0.06 0.0020]; Reset = 1; Swap = fininstrument("Swap",Maturity=Maturity,LegRate=LegRate,LegType=LegType,Reset=[Reset Reset],Name="Swap_inst")
Swap = Swap with properties: LegRate: [0.0600 0.0020] LegType: ["fixed" "float"] Reset: [1 1] Basis: [0 0] Notional: 100 LatestFloatingRate: [NaN NaN] ResetOffset: [0 0] DaycountAdjustedCashFlow: [0 0] ProjectionCurve: [0x0 ratecurve] BusinessDayConvention: ["actual" "actual"] Holidays: NaT EndMonthRule: [1 1] StartDate: NaT Maturity: 01-Jan-2027 Name: "Swap_inst"
Create CoxIngersollRoss
Model Object
Use finmodel
to create a CoxIngersollRoss
model object.
alpha = 0.03;
theta = 0.02;
sigma = 0.1;
CIRModel = finmodel("CoxIngersollRoss",Sigma=sigma,Alpha=alpha,Theta=theta)
CIRModel = CoxIngersollRoss with properties: Sigma: 0.1000 Alpha: 0.0300 Theta: 0.0200
Create ratecurve
Object
Create a ratecurve
object using ratecurve
.
Times= [calyears([1 2 3 4 ])]';
Settle = datetime(2023,1,1);
ZRates = [0.035; 0.042147; 0.047345; 0.052707]';
ZDates = Settle + Times;
Compounding = -1;
Basis = 1;
ZeroCurve = ratecurve("zero",Settle,ZDates,ZRates,Compounding = Compounding, Basis = Basis);
Create IRTree
Pricer Object
Use finpricer
to create an IRTree
pricer object for the CoxIngersollRoss
model and use the ratecurve
object for the 'DiscountCurve'
name-value argument.
CIRPricer = finpricer("irtree",Model=CIRModel,DiscountCurve=ZeroCurve,Maturity=ZDates(end),NumPeriods=length(ZDates))
CIRPricer = CIRTree with properties: Tree: [1x1 struct] TreeDates: [4x1 datetime] Model: [1x1 finmodel.CoxIngersollRoss] DiscountCurve: [1x1 ratecurve]
Price Swap
Instrument
Use price
to compute the price for the Swap
instrument.
[Price,outPR] = price(CIRPricer,Swap,"all")
Price = 1.6525
outPR = priceresult with properties: Results: [1x4 table] PricerData: [1x1 struct]
outPR.Results
ans=1×4 table
Price Delta Gamma Vega
______ _______ ______ ___________
1.6525 -374.11 1443.2 -2.8422e-10
Price Multiple Vanilla Swap
Instruments Using ratecurve
and Discount
Pricer
This example shows the workflow to price multiple vanilla Swap
instruments when you use a ratecurve
and a Discount
pricing method.
Create ratecurve Object
Create a ratecurve
object using ratecurve
for the underlying interest-rate curve for the Swap
instrument.
Settle = datetime(2019,9,15); Type = 'zero'; ZeroTimes = [calmonths(6) calyears([1 2 3 4 5 7 10 20 30])]'; ZeroRates = [0.0052 0.0055 0.0061 0.0073 0.0094 0.0119 0.0168 0.0222 0.0293 0.0307]'; ZeroDates = Settle + ZeroTimes; myRC = ratecurve('zero',Settle,ZeroDates,ZeroRates)
myRC = ratecurve with properties: Type: "zero" Compounding: -1 Basis: 0 Dates: [10x1 datetime] Rates: [10x1 double] Settle: 15-Sep-2019 InterpMethod: "linear" ShortExtrapMethod: "next" LongExtrapMethod: "previous"
Create Swap
Instrument Object
Use fininstrument
to create a vanilla Swap
instrument object for three Swap instruments.
Swap = fininstrument("Swap",'Maturity',datetime([2024,9,15 ; 2025,9,15 ; 2026,9,15]),'LegRate',[0.022 0.019 ],'LegType',["float","fixed"],'ProjectionCurve',myRC,'Name',"swap_instrument")
Swap=3×1 Swap array with properties:
LegRate
LegType
Reset
Basis
Notional
LatestFloatingRate
ResetOffset
DaycountAdjustedCashFlow
ProjectionCurve
BusinessDayConvention
Holidays
EndMonthRule
StartDate
Maturity
Name
Create Discount
Pricer Object
Use finpricer
to create a Discount
pricer object and use the ratecurve
object for the 'DiscountCurve'
name-value pair argument.
outPricer = finpricer("Discount", 'DiscountCurve',myRC)
outPricer = Discount with properties: DiscountCurve: [1x1 ratecurve]
Price Swap
Instruments
Use price
to compute the prices and sensitivities for the vanilla Swap
instruments.
[Price, outPR] = price(outPricer, Swap,["all"])
Price = 3×1
7.2279
9.9725
13.0798
outPR=1×3 priceresult array with properties:
Results
PricerData
outPR.Results
ans=1×2 table
Price DV01
______ _________
7.2279 -0.046631
ans=1×2 table
Price DV01
______ _________
9.9725 -0.054393
ans=1×2 table
Price DV01
_____ _________
13.08 -0.061381
Price Amortizing Swap
Instrument Using ratecurve
and Discount
Pricer
This example shows the workflow to price an amortizing Swap
instrument when you use a ratecurve
and a Discount
pricing method.
Create ratecurve
Object
Create a ratecurve
object using ratecurve
for the underlying interest-rate curve for the Swap
instrument.
Settle = datetime(2019,1,1); Type = 'zero'; ZeroTimes = [calmonths(6) calyears([1 2 3 4 5 7 10 20 30])]'; ZeroRates = [0.0052 0.0055 0.0061 0.0073 0.0094 0.0119 0.0168 0.0222 0.0293 0.0307]'; ZeroDates = Settle + ZeroTimes; myRC = ratecurve('zero',Settle,ZeroDates,ZeroRates)
myRC = ratecurve with properties: Type: "zero" Compounding: -1 Basis: 0 Dates: [10x1 datetime] Rates: [10x1 double] Settle: 01-Jan-2019 InterpMethod: "linear" ShortExtrapMethod: "next" LongExtrapMethod: "previous"
Create Swap
Instrument Object
Use fininstrument
to create an amortizing Swap
instrument object.
Maturity = datetime(2024,1,1); ADates = datetime([2020,1,1 ; 2024,1,1]); APrincipal = [100; 85]; Notional = timetable(ADates,APrincipal); Swap = fininstrument("Swap",'Maturity',Maturity,'LegRate',[0.035,0.01],'Reset',[1 1],'Notional',Notional,'Name',"swap_instrument")
Swap = Swap with properties: LegRate: [0.0350 0.0100] LegType: ["fixed" "float"] Reset: [1 1] Basis: [0 0] Notional: [2x1 timetable] LatestFloatingRate: [NaN NaN] ResetOffset: [0 0] DaycountAdjustedCashFlow: [0 0] ProjectionCurve: [0x0 ratecurve] BusinessDayConvention: ["actual" "actual"] Holidays: NaT EndMonthRule: [1 1] StartDate: NaT Maturity: 01-Jan-2024 Name: "swap_instrument"
Create Discount
Pricer Object
Use finpricer
to create a Discount
pricer object and use the ratecurve
object for the 'DiscountCurve'
name-value pair argument.
outPricer = finpricer("Discount", 'DiscountCurve',myRC)
outPricer = Discount with properties: DiscountCurve: [1x1 ratecurve]
Price Swap
Instrument
Use price
to compute the price and sensitivities for the amortizing Swap
instrument.
[Price, outPR] = price(outPricer, Swap,["all"])
Price = 5.7183
outPR = priceresult with properties: Results: [1x2 table] PricerData: []
outPR.Results
ans=1×2 table
Price DV01
______ ________
5.7183 0.044672
Price Vanilla Swap
Instrument Using HullWhite
Model and IRTree
Pricer
This example shows the workflow to price a vanilla Swap
instrument when you use a HullWhite
model and an IRTree
pricing method.
Create ratecurve
Object
Create a ratecurve
object using ratecurve
for the underlying interest-rate curve for the Swap
instrument.
Settle = datetime(2020,1,15); Type = 'zero'; ZeroTimes = [calmonths(6) calyears([1 2 3 4 5 7 10 20 30])]'; ZeroRates = [0.0052 0.0055 0.0061 0.0073 0.0094 0.0119 0.0168 0.0222 0.0293 0.0307]'; ZeroDates = Settle + ZeroTimes; myRC = ratecurve('zero',Settle,ZeroDates,ZeroRates)
myRC = ratecurve with properties: Type: "zero" Compounding: -1 Basis: 0 Dates: [10x1 datetime] Rates: [10x1 double] Settle: 15-Jan-2020 InterpMethod: "linear" ShortExtrapMethod: "next" LongExtrapMethod: "previous"
Create Swap
Instrument Object
Use fininstrument
to create a vanilla Swap
instrument object.
LegType = ["float","fixed"]; Swap = fininstrument("Swap",'Maturity',datetime(2030,9,15),'LegRate',[0.022 0.019],'LegType',LegType,'ProjectionCurve',myRC,'Name',"swap_instrument")
Swap = Swap with properties: LegRate: [0.0220 0.0190] LegType: ["float" "fixed"] Reset: [2 2] Basis: [0 0] Notional: 100 LatestFloatingRate: [NaN NaN] ResetOffset: [0 0] DaycountAdjustedCashFlow: [0 0] ProjectionCurve: [1x2 ratecurve] BusinessDayConvention: ["actual" "actual"] Holidays: NaT EndMonthRule: [1 1] StartDate: NaT Maturity: 15-Sep-2030 Name: "swap_instrument"
Create HullWhite
Model Object
Use finmodel
to create a HullWhite
model object.
HullWhiteModel = finmodel("HullWhite",'Alpha',0.032,'Sigma',0.04)
HullWhiteModel = HullWhite with properties: Alpha: 0.0320 Sigma: 0.0400
Compute Swap
Instrument Cash Flow Dates
Use cfdates
to compute the cash flows.
CFdates = cfdates(Settle, Swap.Maturity, Swap.Reset(1), Swap.Basis(1))
CFdates = 1x22 datetime
15-Mar-2020 15-Sep-2020 15-Mar-2021 15-Sep-2021 15-Mar-2022 15-Sep-2022 15-Mar-2023 15-Sep-2023 15-Mar-2024 15-Sep-2024 15-Mar-2025 15-Sep-2025 15-Mar-2026 15-Sep-2026 15-Mar-2027 15-Sep-2027 15-Mar-2028 15-Sep-2028 15-Mar-2029 15-Sep-2029 15-Mar-2030 15-Sep-2030
Create IRTree
Pricer Object
Use finpricer
to create an IRTree
pricer object and use the ratecurve
object for the 'DiscountCurve'
name-value pair argument.
HWTreePricer = finpricer("IRTree",'Model',HullWhiteModel,'DiscountCurve',myRC,'TreeDates',CFdates')
HWTreePricer = HWBKTree with properties: Tree: [1x1 struct] TreeDates: [22x1 datetime] Model: [1x1 finmodel.HullWhite] DiscountCurve: [1x1 ratecurve]
Price Swap
Instrument
Use price
to compute the price and sensitivities for the vanilla Swap
instrument.
[Price, outPR] = price(HWTreePricer, Swap,"all")
Price = 24.3727
outPR = priceresult with properties: Results: [1x4 table] PricerData: [1x1 struct]
outPR.Results
ans=1×4 table
Price Delta Gamma Vega
______ ______ _______ __________
24.373 820.67 -8790.5 8.5265e-10
Price Vanilla Swap
Instrument Using HullWhite
Model and IRTree
Pricer and Compute Par Swap Rate
This example shows the workflow to price a vanilla Swap
instrument when you use a HullWhite
model and an IRTree
pricing method and then compute the par swap rate using parswaprate
.
Create ratecurve
Object
Create a ratecurve
object using ratecurve
for the underlying interest-rate curve for the Swap
instrument.
Settle = datetime(2020,1,15); Type = 'zero'; ZeroTimes = [calmonths(6) calyears([1 2 3 4 5 7 10 20 30])]'; ZeroRates = [0.0052 0.0055 0.0061 0.0073 0.0094 0.0119 0.0168 0.0222 0.0293 0.0307]'; ZeroDates = Settle + ZeroTimes; myRC = ratecurve('zero',Settle,ZeroDates,ZeroRates)
myRC = ratecurve with properties: Type: "zero" Compounding: -1 Basis: 0 Dates: [10x1 datetime] Rates: [10x1 double] Settle: 15-Jan-2020 InterpMethod: "linear" ShortExtrapMethod: "next" LongExtrapMethod: "previous"
Create Swap
Instrument Object
Use fininstrument
to create a vanilla Swap
instrument object.
LegType = ["float","fixed"]; Swap = fininstrument("Swap",'Maturity',datetime(2030,9,15),'LegRate',[0.022 0.019],'LegType',LegType,'ProjectionCurve',myRC,'Name',"swap_instrument")
Swap = Swap with properties: LegRate: [0.0220 0.0190] LegType: ["float" "fixed"] Reset: [2 2] Basis: [0 0] Notional: 100 LatestFloatingRate: [NaN NaN] ResetOffset: [0 0] DaycountAdjustedCashFlow: [0 0] ProjectionCurve: [1x2 ratecurve] BusinessDayConvention: ["actual" "actual"] Holidays: NaT EndMonthRule: [1 1] StartDate: NaT Maturity: 15-Sep-2030 Name: "swap_instrument"
Create HullWhite
Model Object
Use finmodel
to create a HullWhite
model object.
HullWhiteModel = finmodel("HullWhite",'Alpha',0.032,'Sigma',0.04)
HullWhiteModel = HullWhite with properties: Alpha: 0.0320 Sigma: 0.0400
Compute Swap
Instrument Cash Flow Dates
Use cfdates
to compute the cash flows.
CFdates = cfdates(Settle, Swap.Maturity, Swap.Reset(1), Swap.Basis(1))
CFdates = 1x22 datetime
15-Mar-2020 15-Sep-2020 15-Mar-2021 15-Sep-2021 15-Mar-2022 15-Sep-2022 15-Mar-2023 15-Sep-2023 15-Mar-2024 15-Sep-2024 15-Mar-2025 15-Sep-2025 15-Mar-2026 15-Sep-2026 15-Mar-2027 15-Sep-2027 15-Mar-2028 15-Sep-2028 15-Mar-2029 15-Sep-2029 15-Mar-2030 15-Sep-2030
Create IRTree
Pricer Object
Use finpricer
to create an IRTree
pricer object and use the ratecurve
object for the 'DiscountCurve'
name-value pair argument.
HWTreePricer = finpricer("IRTree",'Model',HullWhiteModel,'DiscountCurve',myRC,'TreeDates',CFdates')
HWTreePricer = HWBKTree with properties: Tree: [1x1 struct] TreeDates: [22x1 datetime] Model: [1x1 finmodel.HullWhite] DiscountCurve: [1x1 ratecurve]
Price Swap
Instrument
Use price
to compute the price and sensitivities for the vanilla Swap
instrument.
[Price, outPR] = price(HWTreePricer, Swap,"all")
Price = 24.3727
outPR = priceresult with properties: Results: [1x4 table] PricerData: [1x1 struct]
outPR.Results
ans=1×4 table
Price Delta Gamma Vega
______ ______ _______ __________
24.373 820.67 -8790.5 8.5265e-10
Compute Par Swap Rate
Use parswaprate
to compute the par swap rate for the OvernightIndexedSwap instrument. The par swap rate is the rate that renders a swap value equal to zero.
outRate = parswaprate(Swap,myRC)
outRate = 0.0434
Price Vanilla Swap
Instrument Using LinearGaussian2F
Model and IRMonteCarlo
Pricer
This example shows the workflow to price a vanilla Swap
instrument when using a LinearGaussian2F
model and an IRMonteCarlo
pricing method.
Create ratecurve
Object
Create a ratecurve
object using ratecurve
.
Settle = datetime(2020,1,15); Type = 'zero'; ZeroTimes = [calmonths(6) calyears([1 2 3 4 5 7 10 20 30])]'; ZeroRates = [0.0052 0.0055 0.0061 0.0073 0.0094 0.0119 0.0168 0.0222 0.0293 0.0307]'; ZeroDates = Settle + ZeroTimes; myRC = ratecurve('zero',Settle,ZeroDates,ZeroRates)
myRC = ratecurve with properties: Type: "zero" Compounding: -1 Basis: 0 Dates: [10x1 datetime] Rates: [10x1 double] Settle: 15-Jan-2020 InterpMethod: "linear" ShortExtrapMethod: "next" LongExtrapMethod: "previous"
Create Swap
Instrument Object
Use fininstrument
to create a Swap
instrument object.
LegType = ["float","fixed"]; Swap = fininstrument("Swap",'Maturity',datetime(2030,9,15),'LegRate',[0.022 0.019],'LegType',LegType,'ProjectionCurve',myRC,'Name',"swap_instrument")
Swap = Swap with properties: LegRate: [0.0220 0.0190] LegType: ["float" "fixed"] Reset: [2 2] Basis: [0 0] Notional: 100 LatestFloatingRate: [NaN NaN] ResetOffset: [0 0] DaycountAdjustedCashFlow: [0 0] ProjectionCurve: [1x2 ratecurve] BusinessDayConvention: ["actual" "actual"] Holidays: NaT EndMonthRule: [1 1] StartDate: NaT Maturity: 15-Sep-2030 Name: "swap_instrument"
Create LinearGaussian2F
Model Object
Use finmodel
to create a LinearGaussian2F
model object.
LinearGaussian2FModel = finmodel("LinearGaussian2F",'Alpha1',0.07,'Sigma1',0.01,'Alpha2',0.5,'Sigma2',0.006,'Correlation',-0.7)
LinearGaussian2FModel = LinearGaussian2F with properties: Alpha1: 0.0700 Sigma1: 0.0100 Alpha2: 0.5000 Sigma2: 0.0060 Correlation: -0.7000
Create IRMonteCarlo
Pricer Object
Use finpricer
to create an IRMonteCarlo
pricer object and use the ratecurve
object for the 'DiscountCurve'
name-value pair argument.
outPricer = finpricer("IRMonteCarlo",'Model',LinearGaussian2FModel,'DiscountCurve',myRC,'SimulationDates',ZeroDates)
outPricer = G2PPMonteCarlo with properties: NumTrials: 1000 RandomNumbers: [] DiscountCurve: [1x1 ratecurve] SimulationDates: [15-Jul-2020 15-Jan-2021 15-Jan-2022 15-Jan-2023 15-Jan-2024 15-Jan-2025 15-Jan-2027 15-Jan-2030 15-Jan-2040 15-Jan-2050] Model: [1x1 finmodel.LinearGaussian2F]
Price Swap
Instrument
Use price
to compute the price and sensitivities for the Swap
instrument.
[Price,outPR] = price(outPricer,Swap,["all"])
Price = 23.6657
outPR = priceresult with properties: Results: [1x4 table] PricerData: [1x1 struct]
outPR.Results
ans=1×4 table
Price Delta Gamma Vega
______ ______ _______ ______
23.666 819.11 -8748.9 0 0
More About
Vanilla Swap
A vanilla swap is a contract obligating two parties, typically the fixed-rate payer and the floating-rate payer, to exchange future cash flows based on a predetermined notional amount.
In a vanilla swap, one party pays a fixed interest rate, while the other pays a floating rate based on a reference rate like LIBOR. Cash flows are exchanged on predetermined dates, typically quarterly, semiannually, or annually, until the contract's specified maturity date, which can range from a few months to several years.
Swap with Amortization
A swap with an amortization schedule repays part of the principal (face value) along with the coupon payments.
A swap with an amortization schedule is used to manage interest-rate risk and
serve as a cash flow management tool. For this particular type of swap, the notional
amount decreases over time. This means that interest payments decrease not only on
the floating leg but also on the fixed leg. Use the Notional
name-value pair argument to support an amortization schedule.
Forward Swap
In a forward interest-rate swap, a fixed interest-rate loan is exchanged for a floating interest-rate loan at a future specified date.
The StartDate
name-value pair argument supports the future
date for the forward swap.
Version History
Introduced in R2020aR2023b: Support for Pricing Swap
Instruments Using CoxIngersollRoss
Model and IRTree
Pricer
You can price Swap
instruments using a CoxIngersollRoss
model object
and an IRTree
pricing
method.
R2022b: Serial date numbers not recommended
Although Swap
supports serial date numbers,
datetime
values are recommended instead. The
datetime
data type provides flexible date and time
formats, storage out to nanosecond precision, and properties to account for time
zones and daylight saving time.
To convert serial date numbers or text to datetime
values, use the datetime
function. For example:
t = datetime(738427.656845093,"ConvertFrom","datenum"); y = year(t)
y = 2021
There are no plans to remove support for serial date number inputs.
See Also
Functions
MATLAB Command
You clicked a link that corresponds to this MATLAB command:
Run the command by entering it in the MATLAB Command Window. Web browsers do not support MATLAB commands.
Select a Web Site
Choose a web site to get translated content where available and see local events and offers. Based on your location, we recommend that you select: .
You can also select a web site from the following list:
How to Get Best Site Performance
Select the China site (in Chinese or English) for best site performance. Other MathWorks country sites are not optimized for visits from your location.
Americas
- América Latina (Español)
- Canada (English)
- United States (English)
Europe
- Belgium (English)
- Denmark (English)
- Deutschland (Deutsch)
- España (Español)
- Finland (English)
- France (Français)
- Ireland (English)
- Italia (Italiano)
- Luxembourg (English)
- Netherlands (English)
- Norway (English)
- Österreich (Deutsch)
- Portugal (English)
- Sweden (English)
- Switzerland
- United Kingdom (English)