Swap

Swap instrument object

Description

Create and price a Swap instrument object for one or more Swap instruments using this workflow:

1. Use fininstrument to create a Swap instrument object for one or more Swap instruments.

2. Use ratecurve to specify a curve model for the Swap instrument object or use finmodel to specify a HullWhite, BlackKarasinski, BlackDermanToy, CoxIngersollRoss, or LinearGaussian2F model.

3. Choose a pricing method.

   • When using a ratecurve, use finpricer to specify a Discount pricing method

   • When using a HullWhite, BlackKarasinski, CoxIngersollRoss, or BlackDermanToy model , use an IRTree pricing method for one or more Swap instruments.

   • When using a HullWhite, BlackKarasinski, or LinearGaussian2F model, use finpricer to specify an IRMonteCarlo pricing method for one or more Swap 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

SwapInstrument = fininstrument(InstrumentType,'Maturity',maturity_date,'LegRate',leg_rate)

SwapInstrument = fininstrument(___,Name,Value)

Description

SwapInstrument = fininstrument(InstrumentType,'Maturity',maturity_date,'LegRate',leg_rate) creates a 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.

SwapInstrument = fininstrument(___,Name,Value) sets optional properties using additional name-value pairs in addition to the required arguments in the previous syntax. For 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") 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

Name-Value Arguments

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")

Required Swap Name-Value Pair Arguments

Maturity — 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

Optional Swap Name-Value Pair Arguments

LegType — 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 to false, the software ignores the rule, meaning that a payment date is always the same numerical day of the month.

• If you set EndMonthRule to true, 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

Output Arguments

SwapInstrument — Swap instrument

Swap object

Swap instrument, returned as a Swap object.

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: [10×1 datetime]
                Rates: [10×1 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: [1×2 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: [1×1 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: [1×2 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: [0×0 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: [1×1 struct]
        TreeDates: [4×1 datetime]
            Model: [1×1 finmodel.CoxIngersollRoss]
    DiscountCurve: [1×1 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: [1×4 table]
    PricerData: [1×1 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: [10×1 datetime]
                Rates: [10×1 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: [1×1 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: [10×1 datetime]
                Rates: [10×1 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: [2×1 timetable]
          LatestFloatingRate: [NaN NaN]
                 ResetOffset: [0 0]
    DaycountAdjustedCashFlow: [0 0]
             ProjectionCurve: [0×0 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: [1×1 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: [1×2 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: [10×1 datetime]
                Rates: [10×1 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: [1×2 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 = 1×22 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: [1×1 struct]
        TreeDates: [22×1 datetime]
            Model: [1×1 finmodel.HullWhite]
    DiscountCurve: [1×1 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: [1×4 table]
    PricerData: [1×1 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: [10×1 datetime]
                Rates: [10×1 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: [1×2 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 = 1×22 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: [1×1 struct]
        TreeDates: [22×1 datetime]
            Model: [1×1 finmodel.HullWhite]
    DiscountCurve: [1×1 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: [1×4 table]
    PricerData: [1×1 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: [10×1 datetime]
                Rates: [10×1 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: [1×2 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: [1×1 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: [1×1 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: [1×4 table]
    PricerData: [1×1 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 R2020a

R2023b: 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.