Main Content

IRMonteCarlo

Create IRMonteCarlo pricer object for equity instruments using HullWhite, BraceGatarekMusiela, or LinearGaussian2F model

Description

Create and price a Cap, Floor, Swap, Swaption, FloatBond, FixedBond, FixedBondOption, FloatBondOption, OptionEmbeddedFixedBond, or OptionEmbeddedFloatBond instrument object with a HullWhite, BraceGatarekMusiela, SABRBraceGatarekMusiela, 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 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 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

Description

example

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 pair arguments Model, DiscountCurve, and SimulationDates.

example

IRMonteCarloPricerObj = finpricer(___,Name,Value) sets optional properties using additional name-value pairs 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 pair arguments.

Input Arguments

expand all

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

Data Types: char | string

IRMonteCarlo Name-Value Pair Arguments

Specify required and optional comma-separated pairs of Name,Value arguments. Name is the argument name and Value is the corresponding value. Name must appear inside quotes. You can specify several name and value pair arguments in any order as Name1,Value1,...,NameN,ValueN.

Example: IRMonteCarloPricerObj = finpricer("irmontecarlo",'Model',HWModel,'DiscountCurve',ratecurve_obj,'SimulationDates',[datetime(2018,1,30); datetime(2019,1,30)],'NumTrials',500)
Required IRMonteCarlo Name-Value Pair Arguments

expand all

Model object, specified as the comma-separated pair consisting of 'Model' and the name of a previously created HullWhite, LinearGaussian2F, BraceGatarekMusiela, or SABRBraceGatarekMusiela model object. Create the model object using finmodel.

Data Types: object

ratecurve object for discounting cash flows, specified as the comma-separated pair consisting of '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 equity option.

Data Types: object

Simulation dates, specified as the comma-separated pair consisting of 'SimulationDates' and a scalar serial date number, date character vector, or datetime or a vector of serial date numbers, cell array of character vectors, string array, or datetime array.

Data Types: double | char | string | cell | datetime

Optional IRMonteCarlo Name-Value Pair Arguments

expand all

Simulation trials, specified as the comma-separated pair consisting of 'NumTrials' and a scalar number of independent sample paths.

Data Types: double

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

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

Properties

expand all

This property is read-only.

Model object, returned as an object.

Data Types: object

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

Data Types: object

Simulation dates, returned as a datetime array.

Data Types: datetime

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

Data Types: double

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

Data Types: struct

Object Functions

priceCompute price for interest-rate instrument with IRMonteCarlo pricer

Examples

collapse all

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: [10x1 datetime]
                Rates: [10x1 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: [1x1 ratecurve]
    SimulationDates: [01-Jul-2019    01-Jan-2020    01-Jan-2021    ...    ]
              Model: [1x1 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: [1x4 table]
    PricerData: [1x1 struct]

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

    115.03    -397.13    1430.4     0  

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: [0x0 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: [10x1 datetime]
                Rates: [10x1 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: [1x1 ratecurve]
    SimulationDates: [01-Jul-2019    01-Jan-2020    01-Jan-2021    ...    ]
              Model: [1x1 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.2389
outPR = 
  priceresult with properties:

       Results: [1x4 table]
    PricerData: [1x1 struct]

outPR.Results
ans=1×4 table
    Price     Delta     Gamma          Vega       
    ______    ______    _____    _________________

    1.2389    132.71    11038    131.63    -163.71

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: [0x0 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: [9x1 datetime]
                Rates: [9x1 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: [1x1 ratecurve]
    SimulationDates: [01-Jul-2019    01-Jan-2020    01-Jan-2021    ...    ]
              Model: [1x1 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.7882
outPR = 
  priceresult with properties:

       Results: [1x3 table]
    PricerData: [1x1 struct]

outPR.Results
ans=1×3 table
    Price     Delta     Gamma 
    ______    ______    ______

    14.788    -400.4    1280.7

Introduced in R2021b