IRMonteCarlo

Create IRMonteCarlo pricer object for interest-rate instruments using HullWhite, BraceGatarekMusiela, BlackKarasinski, or LinearGaussian2F model

Since R2021b

Description

Create and price a Cap, Floor, Swap, Swaption, FloatBond, FixedBond, FixedBondOption, FloatBondOption, OptionEmbeddedFixedBond, or OptionEmbeddedFloatBond instrument object with a HullWhite, BraceGatarekMusiela, SABRBraceGatarekMusiela, BlackKarasinski, or LinearGaussian2F model and a IRMonteCarlo pricing method using this workflow:

1. Use fininstrument to create a FixedBond, FloatBond, Cap, Floor, Swap, Swaption, FixedBondOption, FloatBondOption, OptionEmbeddedFixedBond, or OptionEmbeddedFloatBond instrument object.

2. Use finmodel to specify a HullWhite, BlackKarasinski, or LinearGaussian2F model for the Cap, Floor, Swap, Swaption, FloatBond, FixedBond, FixedBondOption, FloatBondOption, OptionEmbeddedFixedBond, or OptionEmbeddedFloatBond instrument object.

   Use finmodel to specify a BraceGatarekMusiela or SABRBraceGatarekMusiela model for the Cap, Floor, FloatBond, FixedBond, FixedBondOption, FloatBondOption, OptionEmbeddedFixedBond, or OptionEmbeddedFloatBond instrument object.

3. When using a HullWhite, BlackKarasinski, or LinearGaussian2F model, use finpricer to specify an IRMonteCarlo pricer object for the Cap, Floor, Swap, Swaption, FloatBond, FixedBond, FixedBondOption, FloatBondOption, OptionEmbeddedFixedBond, or OptionEmbeddedFloatBond instrument object.

   When using a BraceGatarekMusiela or SABRBraceGatarekMusiela model, use finpricer to specify an IRMonteCarlo pricer object for the Cap, Floor, FloatBond, FixedBond, FixedBondOption, FloatBondOption, OptionEmbeddedFixedBond, or OptionEmbeddedFloatBond instrument object.

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 instruments, models, and pricing methods for Cap, Floor, Swap, Swaption, FloatBond, FixedBond, FixedBondOption, FloatBondOption, OptionEmbeddedFixedBond, or OptionEmbeddedFloatBond instruments, see Choose Instruments, Models, and Pricers.

Creation

Syntax

IRMonteCarloPricerObj = finpricer(PricerType,Model=model,DiscountCurve=ratecurve_obj,SimulationDates=simulation_dates)

IRMonteCarloPricerObj = finpricer(___,Name=Value)

Description

IRMonteCarloPricerObj = finpricer(PricerType,Model=model,DiscountCurve=ratecurve_obj,SimulationDates=simulation_dates) creates an IRMonteCarlo pricer object by specifying PricerType and sets the properties using the required name-value arguments Model, DiscountCurve, and SimulationDates.

IRMonteCarloPricerObj = finpricer(___,Name=Value) sets optional properties using additional name-value arguments in addition to the required arguments in the previous syntax. For example, IRMonteCarloPricerObj = finpricer("irmontecarlo",Model=HWModel,DiscountCurve=ratecurve_obj,SimulationDates=[datetime(2018,1,30); datetime(2019,1,30)],NumTrials=500) creates an IRMonteCarlo pricer object using a HullWhite model. You can specify multiple name-value arguments.

Input Arguments

PricerType — Pricer type

string with value "IRMonteCarlo" | character vector with value 'IRMonteCarlo'

Pricer type, specified as a string with the value "IRMonteCarlo" or a character vector with the value 'IRMonteCarlo'.

Data Types: char | 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.

Example: IRMonteCarloPricerObj = finpricer("irmontecarlo",Model=HWModel,DiscountCurve=ratecurve_obj,SimulationDates=[datetime(2018,1,30); datetime(2019,1,30)],NumTrials=500)

Required IRMonteCarlo Name-Value Arguments

Model — Model object

HullWhite object | BlackKarasinski object | LinearGaussian2F object | BraceGatarekMusiela object | SABRBraceGatarekMusiela object

Model object, specified as Model and the name of a previously created HullWhite, BlackKarasinski, LinearGaussian2F, BraceGatarekMusiela, or SABRBraceGatarekMusiela model object. Create the model object using finmodel.

Data Types: object

DiscountCurve — ratecurve object for discounting cash flows

ratecurve object

ratecurve object for discounting cash flows, specified as DiscountCurve and the name of a previously created ratecurve object.

Note

Specify a flat ratecurve object for DiscountCurve. If you use a nonflat ratecurve object, the software uses the rate in the ratecurve object at Maturity and assumes that the value is constant for the life of the interest-rate option.

Data Types: object

SimulationDates — Simulation dates

datetime array | string array | date character vector

Simulation dates, specified as SimulationDates and a scalar or a vector using a datetime array, string array, or date character vectors.

To support existing code, IRMonteCarlo also accepts serial date numbers as inputs, but they are not recommended.

Optional IRMonteCarlo Name-Value Arguments

NumTrials — Simulation trials

1000 (default) | scalar

Simulation trials, specified as NumTrials and a scalar number of independent sample paths.

Data Types: double

RandomNumbers — Dependent random variates

[ ] (default) | structure

Dependent random variates, specified as RandomNumbers and an NSimulationDates-by-NBrownians-by-NTrials 3D time series array. The 3D time series array has the following field:

• Z — NSimulationDates-by-NBrownians-by-NTrials 3D time series array of dependent random variates used to generate the Brownian motion vector (that is, Wiener processes) that drive the simulation.

Data Types: struct

Output Arguments

IRMonteCarloPricerObj — IRMonteCarlo pricer

IRMonteCarlo object

IRMonteCarlo pricer, returned as a IRMonteCarlo object.

Properties

Model — Model object

Read-only: object

This property is read-only.

Model object, returned as an object.

Data Types: object

DiscountCurve — ratecurve object for discounting cash flows

ratecurve object

ratecurve object for discounting cash flows, returned as a ratecurve object.

Data Types: object

SimulationDates — Simulation dates

datetime

Simulation dates, returned as a datetime array.

Data Types: datetime

NumTrials — Simulation trials

1000 (default) | scalar

Simulation trials, returned as a scalar number of independent sample paths.

Data Types: double

RandomNumbers — Dependent random variates

[ ] (default) | structure

Dependent random variates, returned as an NSimulationDates-by-NBrownians-by-NTrials 3D time series array.

Data Types: struct

Object Functions

price

Compute price for interest-rate instrument with IRMonteCarlo pricer

Examples

Use IRMonteCarlo Pricer and HullWhite Model to Price FixedBond Instrument

This example shows the workflow to price a FixedBond instrument when using a HullWhite model and an IRMonteCarlo pricing method.

Create FixedBond Instrument Object

Use fininstrument to create a FixedBond instrument object.

FixB = fininstrument("FixedBond",Maturity=datetime(2022,9,15),CouponRate=0.05,Name="fixed_bond")

FixB = 
  FixedBond with properties:

                  CouponRate: 0.0500
                      Period: 2
                       Basis: 0
                EndMonthRule: 1
                   Principal: 100
    DaycountAdjustedCashFlow: 0
       BusinessDayConvention: "actual"
                    Holidays: NaT
                   IssueDate: NaT
             FirstCouponDate: NaT
              LastCouponDate: NaT
                   StartDate: NaT
                    Maturity: 15-Sep-2022
                        Name: "fixed_bond"

Create HullWhite Model Object

Use finmodel to create a HullWhite model object.

HullWhiteModel = finmodel("HullWhite",Alpha=0.32,Sigma=0.49)

HullWhiteModel = 
  HullWhite with properties:

    Alpha: 0.3200
    Sigma: 0.4900

Create ratecurve Object

Create a ratecurve object using ratecurve.

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 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=HullWhiteModel,DiscountCurve=myRC,SimulationDates=ZeroDates)

outPricer = 
  HWMonteCarlo with properties:

          NumTrials: 1000
      RandomNumbers: []
      DiscountCurve: [1×1 ratecurve]
    SimulationDates: [01-Jul-2019    01-Jan-2020    01-Jan-2021    01-Jan-2022    01-Jan-2023    01-Jan-2024    01-Jan-2026    01-Jan-2029    01-Jan-2039    01-Jan-2049]
              Model: [1×1 finmodel.HullWhite]

Price FixedBond Instrument

Use price to compute the price for the FixedBond instrument.

[Price,outPR] = price(outPricer,FixB,["all"])

Price = 
115.0303

outPR = 
  priceresult with properties:

       Results: [1×4 table]
    PricerData: [1×1 struct]

outPR.Results

ans=1×4 table
    Price      Delta     Gamma     Vega
    ______    _______    ______    ____

    115.03    -397.13    1430.4     0  

Use IRMonteCarlo Pricer and LinearGaussian2F Model to Price Cap Instrument

This example shows the workflow to price a Cap instrument when using a LinearGaussian2F model and an IRMonteCarlo pricing method.

Create Cap Instrument Object

Use fininstrument to create a Cap instrument object.

CapOpt = fininstrument("Cap",Maturity=datetime(2022,9,15),Strike=0.01,Reset=2,Name="cap_option")

CapOpt = 
  Cap with properties:

                      Strike: 0.0100
                    Maturity: 15-Sep-2022
                 ResetOffset: 0
                       Reset: 2
                       Basis: 0
                   Principal: 100
             ProjectionCurve: [0×0 ratecurve]
    DaycountAdjustedCashFlow: 0
       BusinessDayConvention: "actual"
                    Holidays: NaT
                        Name: "cap_option"

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

Create a ratecurve object using ratecurve.

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 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: [01-Jul-2019    01-Jan-2020    01-Jan-2021    01-Jan-2022    01-Jan-2023    01-Jan-2024    01-Jan-2026    01-Jan-2029    01-Jan-2039    01-Jan-2049]
              Model: [1×1 finmodel.LinearGaussian2F]

Price Cap Instrument

Use price to compute the price and sensitivities for the Cap instrument.

[Price,outPR] = price(outPricer,CapOpt,["all"])

Price = 
1.2156

outPR = 
  priceresult with properties:

       Results: [1×4 table]
    PricerData: [1×1 struct]

outPR.Results

ans=1×4 table
    Price     Delta     Gamma          Vega      
    ______    ______    _____    ________________

    1.2156    131.37    11048    126.5    -157.38

Use IRMonteCarlo Pricer and BraceGatarekMusiela Model to Price Floor Instrument

This example shows the workflow to price a Floor instrument when using a BraceGatarekMusiela model and an IRMonteCarlo pricing method.

Create Floor Instrument Object

Use fininstrument to create a Floor instrument object.

FloorOpt = fininstrument("Floor",Maturity=datetime(2022,9,15),Strike=0.05,Reset=1,Name="floor_option")

FloorOpt = 
  Floor with properties:

                      Strike: 0.0500
                    Maturity: 15-Sep-2022
                 ResetOffset: 0
                       Reset: 1
                       Basis: 0
                   Principal: 100
             ProjectionCurve: [0×0 ratecurve]
    DaycountAdjustedCashFlow: 0
       BusinessDayConvention: "actual"
                    Holidays: NaT
                        Name: "floor_option"

Create BraceGatarekMusiela Model Object

Use finmodel to create a BraceGatarekMusiela model object.

BGMVolFunc = @(a,t) (a(1)*t + a(2)).*exp(-a(3)*t) + a(4);
BGMVolParams = [.3 -.02 .7 .14];
numRates = 20;
VolFunc(1:numRates-1) = {@(t) BGMVolFunc(BGMVolParams,t)};
Beta = .08;
CorrFunc = @(i,j,Beta) exp(-Beta*abs(i-j));
Correlation = CorrFunc(meshgrid(1:numRates-1)',meshgrid(1:numRates-1),Beta);
BGM = finmodel("BraceGatarekMusiela",Volatility=VolFunc,Correlation=Correlation,Period=1);

Create ratecurve Object

Create a ratecurve object using ratecurve.

Settle = datetime(2019,1,1);
Type = 'zero';
ZeroTimes = [calmonths(6) calyears([1 2 3 4 5 7 10 20])]';
ZeroRates = [0.0052 0.0055 0.0061 0.0073 0.0094 0.0119 0.0168 0.0222 0.0293]';
ZeroDates = Settle + ZeroTimes;
 
myRC = ratecurve('zero',Settle,ZeroDates,ZeroRates)

myRC = 
  ratecurve with properties:

                 Type: "zero"
          Compounding: -1
                Basis: 0
                Dates: [9×1 datetime]
                Rates: [9×1 double]
               Settle: 01-Jan-2019
         InterpMethod: "linear"
    ShortExtrapMethod: "next"
     LongExtrapMethod: "previous"

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=BGM,DiscountCurve=myRC,SimulationDates=ZeroDates)

outPricer = 
  BGMMonteCarlo with properties:

          NumTrials: 1000
      RandomNumbers: []
      DiscountCurve: [1×1 ratecurve]
    SimulationDates: [01-Jul-2019    01-Jan-2020    01-Jan-2021    01-Jan-2022    01-Jan-2023    01-Jan-2024    01-Jan-2026    01-Jan-2029    01-Jan-2039]
              Model: [1×1 finmodel.BraceGatarekMusiela]

Price Floor Instrument

Use price to compute the price and sensitivities for the Floor instrument.

[Price,outPR] = price(outPricer,FloorOpt,["all"])

Price = 
14.7975

outPR = 
  priceresult with properties:

       Results: [1×3 table]
    PricerData: [1×1 struct]

outPR.Results

ans=1×3 table
    Price      Delta     Gamma 
    ______    _______    ______

    14.797    -398.43    1399.5

Use IRMonteCarlo Pricer and Black-Karasinski Model to Price Fixed Bond Instrument

This example shows the workflow to price a FixedBond instrument when using a BlackKarasinski model and an IRMonteCarlo pricing method.

Create FixedBond Instrument Object

Use fininstrument to create a FixedBond instrument object.

FixB = fininstrument("FixedBond",Maturity=datetime(2022,9,15),CouponRate=0.05,Name="fixed_bond")

FixB = 
  FixedBond with properties:

                  CouponRate: 0.0500
                      Period: 2
                       Basis: 0
                EndMonthRule: 1
                   Principal: 100
    DaycountAdjustedCashFlow: 0
       BusinessDayConvention: "actual"
                    Holidays: NaT
                   IssueDate: NaT
             FirstCouponDate: NaT
              LastCouponDate: NaT
                   StartDate: NaT
                    Maturity: 15-Sep-2022
                        Name: "fixed_bond"

Create BlackKarasinski Model Object

Use finmodel to create a BlackKarasinski model object.

BlackKarasinskiModel = finmodel("BlackKarasinski",'Alpha',0.02,'Sigma',0.34)

BlackKarasinskiModel = 
  BlackKarasinski with properties:

    Alpha: 0.0200
    Sigma: 0.3400

Create ratecurve Object

Create a ratecurve object using ratecurve.

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 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=BlackKarasinskiModel,DiscountCurve=myRC,SimulationDates=datetime(2019,3,15)+calmonths(0:6:48)')

outPricer = 
  BKMonteCarlo with properties:

          NumTrials: 1000
      RandomNumbers: []
      DiscountCurve: [1×1 ratecurve]
    SimulationDates: [15-Mar-2019    15-Sep-2019    15-Mar-2020    15-Sep-2020    15-Mar-2021    15-Sep-2021    15-Mar-2022    15-Sep-2022    15-Mar-2023]
              Model: [1×1 finmodel.BlackKarasinski]

Price FixedBond Instrument

Use price to compute the price for the FixedBond instrument.

[Price,outPR] = price(outPricer,FixB,["all"])

Price = 113.3046

outPR = 
  priceresult with properties:

       Results: [1×4 table]
    PricerData: [1×1 struct]

outPR.Results

ans=1×4 table
    Price     Delta     Gamma      Vega 
    _____    _______    ______    ______

    113.3    -310.39    -26724    2.0305

Version History

Introduced in R2021b

R2022b: Serial date numbers not recommended

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

R2022b: Support for Black-Karasinski model

The name-value argument option for Model supports a "BlackKarasinski" binomial tree model.