LinearGaussian2F

Create LinearGaussian2F model object for Cap, Floor, Swaption, Swap, FixedBond, FloatBond, RangeAccrualNote, FloatBondOption, FixedBondOption, OptionEmbeddedFixedBond, OptionEmbeddedFloatBond, or OptionEmbeddedRangeAccrualNote instrument

Since R2021b

Description

Create and price a Cap, Floor, Swaption, Swap, FloatBond, FloatBondOption, FixedBond, RangeAccrualNote, FixedBondOption, OptionEmbeddedFixedBond, OptionEmbeddedFloatBond, or OptionEmbeddedRangeAccrualNote instrument object with a LinearGaussian2F model using this workflow:

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

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

3. Use finpricer to specify an IRMonteCarlo pricing method for a Cap, Floor, Swaption, Swap, FixedBond, FloatBond, RangeAccrualNote, FloatBondOption, FixedBondOption, OptionEmbeddedFixedBond, OptionEmbeddedFloatBond, or OptionEmbeddedRangeAccrualNote 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 pricing methods for a Cap, Floor, Swaption, Swap, FixedBond, FloatBond, RangeAccrualNote, FloatBondOption, FixedBondOption, OptionEmbeddedFixedBond, OptionEmbeddedFloatBond, or OptionEmbeddedRangeAccrualNote instrument, see Choose Instruments, Models, and Pricers.

Creation

Syntax

LinearGaussian2FModelObj = finmodel(ModelType,Alpha1=alpha1_value,Sigma1=sigma1_value,Alpha2=alpha2_value,Sigma2=sigma2_value,Correlation=correlation_value)

Description

LinearGaussian2FModelObj = finmodel(ModelType,Alpha1=alpha1_value,Sigma1=sigma1_value,Alpha2=alpha2_value,Sigma2=sigma2_value,Correlation=correlation_value) creates a LinearGaussian2F model object by specifying ModelType and the required name-value arguments for Alpha1, Sigma1, Alpha2, Sigma2 and Correlation to set properties using name-value pair arguments. For example, LinearGaussian2FModelObj = finmodel("LinearGaussian2F",Alpha1=0.07,Sigma1=0.01,Alpha2=0.5,Sigma2=0.006,Correlation=-0.7) creates a LinearGaussian2F model object.

Input Arguments

ModelType — Model type

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

Model type, specified as a string with the value of "LinearGaussian2F" or a character vector with the value of 'LinearGaussian2F'.

Data Types: char | string

Name-Value Arguments

Specify required 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: LinearGaussian2FModelObj = finmodel("LinearGaussian2F",Alpha1=0.07,Sigma1=0.01,Alpha2=0.5,Sigma2=0.006,Correlation=-0.7)

Alpha1 — Positive mean reversion value for first factor

scalar numeric | timetable

Positive mean reversion value for first factor, specified as Alpha1 and a scalar numeric or timetable.

Data Types: double | timetable

Sigma1 — Positive volatility for first factor

scalar numeric | timetable

Positive volatility for first factor, specified as Sigma1 and a scalar numeric or timetable.

Data Types: double | timetable

Alpha2 — Positive mean reversion value for second factor

numeric | timetable

Positive mean reversion value for the second factor, specified as Alpha2 and a scalar numeric or timetable.

Data Types: double | timetable

Sigma2 — Positive volatility for second factor

numeric | timetable

Positive volatility for second factor, specified as Sigma2 and a scalar numeric or timetable.

Data Types: double | timetable

Correlation — Scalar correlation of factors

numeric

Scalar correlation of factors, specified as Correlation and a scalar numeric.

Data Types: double

Output Arguments

LinearGaussian2FModelObj — LinearGaussian2F model

LinearGaussian2F object

LinearGaussian2F model, returned as a LinearGaussian2F object.

Properties

Alpha1 — Positive mean reversion for first factor

numeric | timetable

Positive mean reversion for first factor, returned as a scalar numeric or timetable.

Data Types: double

Sigma1 — Positive volatility for first factor

numeric | timetable

Positive volatility for first factor, returned as a scalar numeric value or timetable.

Data Types: double

Alpha2 — Positive mean reversion value for second factor

numeric | timetable

Positive mean reversion value for second factor, returned as a scalar numeric or timetable.

Data Types: double

Sigma2 — Positive volatility for second factor

numeric | timetable

Positive volatility for second factor, returned as a scalar numeric value or timetable.

Data Types: double | timetable

Correlation — Scalar correlation of factors

numeric

Scalar correlation of factors, returned as a scalar numeric value.

Data Types: double

Examples

Use LinearGaussian2F Model and IRMonteCarlo Pricer 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 LinearGaussian2F Model and IRMonteCarlo Pricer to Price RangeAccrualNote Instrument

Since R2026a

This example shows the workflow to price a RangeAccrualNote instrument when you use a LinearGaussian2F model and an IRMonteCarlo pricing method.

Create RangeAccrualNote Instrument Object

Use fininstrument to create a RangeAccrualNote instrument object.

Maturity = datetime(2026,9,15);
RangeAccrualNoteInstrument = fininstrument("RangeAccrualNote",Maturity=Maturity,ReferenceType="spot",ReferenceTenor=10,CouponRate=0.4,TargetRange=[0,inf],Principal=5000,Name="rangeaccrualnote_instrument")

RangeAccrualNoteInstrument = 
  RangeAccrualNote with properties:

               ReferenceType: "spot"
                      Period: 2
                       Basis: 0
                   Principal: 5000
           CMSReferenceReset: 2
    DaycountAdjustedCashFlow: 0
       BusinessDayConvention: "actual"
                    Holidays: NaT
                EndMonthRule: 1
              ReferenceTenor: 10
                    Maturity: 15-Sep-2026
                  CouponRate: 0.4000
                 TargetRange: [0 Inf]
                   StartDate: NaT
                        Name: "rangeaccrualnote_instrument"

Create ratecurve Object

Create a ratecurve object using ratecurve.

Settle = datetime(2024,9,15);
Type = 'zero';
ZeroTimes = [calyears(1:3)]';
ZeroRates = [0.0055 0.0061 0.0073]';
ZeroDates = Settle + ZeroTimes;

myRC = ratecurve('zero',Settle,ZeroDates,ZeroRates)

myRC = 
  ratecurve with properties:

                 Type: "zero"
          Compounding: -1
                Basis: 0
                Dates: [3×1 datetime]
                Rates: [3×1 double]
               Settle: 15-Sep-2024
         InterpMethod: "linear"
    ShortExtrapMethod: "next"
     LongExtrapMethod: "previous"

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 with the 'DiscountCurve' name-value argument.

SimulationDates = Settle:caldays(1):Maturity;
SimulationDates = busdate(SimulationDates,"follow",RangeAccrualNoteInstrument.Holidays);
outPricer = finpricer("IRMonteCarlo",Model=LinearGaussian2FModel,DiscountCurve=myRC,SimulationDates=SimulationDates)

outPricer = 
  G2PPMonteCarlo with properties:

          NumTrials: 1000
      RandomNumbers: []
      DiscountCurve: [1×1 ratecurve]
    SimulationDates: [16-Sep-2024    17-Sep-2024    18-Sep-2024    19-Sep-2024    20-Sep-2024    23-Sep-2024    24-Sep-2024    25-Sep-2024    26-Sep-2024    27-Sep-2024    30-Sep-2024    01-Oct-2024    02-Oct-2024    03-Oct-2024    …    ] (1×523 datetime)
              Model: [1×1 finmodel.LinearGaussian2F]

Price RangeAccrualNote Instrument

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

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

Price = 
8.5353e+03

outPR = 
  priceresult with properties:

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

outPR.Results

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

    8535.3    77108    -2.0252e+07    -70127     83218

Use LinearGaussian2F Model and IRMonteCarlo Pricer to Price OptionEmbeddedRangeAccrualNote Instrument

Since R2026a

This example shows the workflow to price a OptionEmbeddedangeAccrualNote instrument when you use a LinearGaussian2F model and an IRMonteCarlo pricing method.

Create OptionEmbeddedRangeAccrualNote Instrument Object

Use fininstrument to create a OptionEmbeddedRangeAccrualNote instrument object.

Maturity = datetime(2027,9,15);
OptionEmbeddedRangeAccrualNoteInstrument = fininstrument("OptionEmbeddedRangeAccrualNote",Maturity=Maturity,ReferenceType="cms",ReferenceTenor=10,CouponRate=0.4,TargetRange=[0,3.25/100],Principal=1000,Name="optionembedded_rangeaccrualnote_instrument")

OptionEmbeddedRangeAccrualNoteInstrument = 
  OptionEmbeddedRangeAccrualNote with properties:

               ReferenceType: "cms"
                      Period: 2
                       Basis: 0
                   Principal: 1000
           CMSReferenceReset: 2
    DaycountAdjustedCashFlow: 0
       BusinessDayConvention: "actual"
                    Holidays: NaT
                EndMonthRule: 1
              ReferenceTenor: 10
                    Maturity: 15-Sep-2027
                  CouponRate: 0.4000
                 TargetRange: [0 0.0325]
                CallSchedule: [0×0 timetable]
                   StartDate: NaT
                        Name: "optionembedded_rangeaccrualnote_instrument"

Create ratecurve Object

Create a ratecurve object using ratecurve.

Settle = datetime(2024,9,15);
Type = 'zero';
ZeroTimes = [calyears(1:3)]';
ZeroRates = [0.0055 0.0061 0.0073]';
ZeroDates = Settle + ZeroTimes;

myRC = ratecurve('zero',Settle,ZeroDates,ZeroRates)

myRC = 
  ratecurve with properties:

                 Type: "zero"
          Compounding: -1
                Basis: 0
                Dates: [3×1 datetime]
                Rates: [3×1 double]
               Settle: 15-Sep-2024
         InterpMethod: "linear"
    ShortExtrapMethod: "next"
     LongExtrapMethod: "previous"

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

Create IRMonteCarlo Pricer Object

Use finpricer to create an IRMonteCarlo pricer object and use the ratecurve object with the 'DiscountCurve' name-value pair argument.

SimulationDates = Settle:caldays(1):Maturity;
SimulationDates = busdate(SimulationDates,"follow",OptionEmbeddedRangeAccrualNoteInstrument.Holidays);
outPricer = finpricer("IRMonteCarlo",Model=LinearGaussian2FModel,DiscountCurve=myRC,SimulationDates=SimulationDates,NumTrials=1e3)

outPricer = 
  G2PPMonteCarlo with properties:

          NumTrials: 1000
      RandomNumbers: []
      DiscountCurve: [1×1 ratecurve]
    SimulationDates: [16-Sep-2024    17-Sep-2024    18-Sep-2024    19-Sep-2024    20-Sep-2024    23-Sep-2024    24-Sep-2024    25-Sep-2024    26-Sep-2024    27-Sep-2024    30-Sep-2024    01-Oct-2024    02-Oct-2024    03-Oct-2024    …    ] (1×784 datetime)
              Model: [1×1 finmodel.LinearGaussian2F]

Price OptionEmbeddedRangeAccrualNote Instrument

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

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

Price = 
1.1936e+03

outPR = 
  priceresult with properties:

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

outPR.Results

ans=1×4 table
    Price     Delta       Gamma              Vega       
    ______    ______    __________    __________________

    1193.6    1540.1    3.0665e+06    -1456.5     2208.2

More About

LinearGaussian2F Model

The LinearGaussian2F two-factor additive Gaussian interest-rate model is a statistical framework used to model the relationship between multiple variables, particularly in the context of time series data.

In the LinearGaussian2F model, the two factors represent the main drivers of the asset price or interest-rate dynamics. These factors are typically chosen to capture different sources of risk or market influences. The model assumes that the factors follow a Gaussian distribution, which allows for a straightforward mathematical representation

Specifically, the LinearGaussian2F model is defined using the following equations:

$$r(t)=x(t)+y(t)+\varphi (t)$$

$$dx(t)=-a(t)x(t)dt+\sigma (t)d{W}_1(t),x(0)=0$$

$$dy(t)=-b(t)y(t)dt+\eta (t)d{W}_2(t),y(0)=0$$

where $$d{W}_1(t)d{W}_2(t)=\rho dt$$ is a two-dimensional Brownian motion with correlation ρ, and ϕ is a function chosen to match the initial zero curve.

Version History

Introduced in R2021b

R2026a: Support for RangeAccrualNote and OptionEmbeddedRangeAccrualNote Instruments

The LinearGaussian2F model supports the RangeAccrualNote and OptionEmbeddedRangeAccrualNote instruments with a LinearGaussian2F model when using an IRMonteCarlo pricing method.