Main Content

Swap

Swap instrument object

Since R2020a

expand all in page

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.

example

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.

example

Input Arguments

expand all

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

expand all

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.

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

expand all

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

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

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

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

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

Lag in rate setting, specified as the comma-separated pair consisting of 'ResetOffset' and a NINST-by-2 matrix.

Data Types: double

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

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

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

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

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

expand all

Maturity date, returned as a scalar datetime or an NINST-by-1 vector of datetimes.

Data Types: datetime

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

Leg type, returned as a string array with the values ["fixed","fixed"], ["fixed","float"], ["float","fixed"], or ["float","float"].

Data Types: string

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 frequency per year for each swap, returned as a scalar or an NINST-by-2 matrix.

Data Types: double

Day count basis, returned as an NINST-by-1 or an NINST-by-2 matrix.

Data Types: double

Lag in rate setting, returned as an NINST-by-2 or an NINST-by-2 matrix.

Data Types: double

Notional principal amount, returned as a scalar numeric or an NINST-by-1 numeric vector or a timetable.

Data Types: double | timetable

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

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

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 used in computing business days, returned as an NINST-by-1 vector of datetimes.

Data Types: datetime

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

Date swap starts, returned as a scalar datetime or an NINST-by-1 vector of datetimes.

Data Types: datetime

User-defined name for the instrument, returned as a scalar string or an NINST-by-1 string array.

Data Types: string

Object Functions

cashflowsCompute cash flow for FixedBond, FloatBond, Swap, FRA, STIRFuture, OISFuture, OvernightIndexedSwap, or Deposit instrument
parswaprateCompute par swap rate for Swap and OvernightIndexedSwap instrument

Examples

collapse all

Open Live Script

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
Open Live Script

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
Open Live Script

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
Open Live Script

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
Open Live Script

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
Open Live Script

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
Open Live Script

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

expand all

Version History

Introduced in R2020a

expand all

See Also

Functions

Topics