HullWhite

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

Description

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

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

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

3. Choose a pricing method.

   • Use finpricer to specify a HullWhite pricing method for a Cap, Floor, or Swaption instrument object and use an IRTree or IRMonteCarlo pricing method for the Cap, Floor, Swaption, Swap, FixedBond, FloatBond, FloatBondOption, FixedBondOption, OptionEmbeddedFixedBond, or OptionEmbeddedFloatBond instrument object.

   • When using an RangeAccrualNote or OptionEmbeddedRangeAccrualNote, with a HullWhite model, you can use finpricer to specify an IRMonteCarlo pricing method.

4. Optionally, when using an OptionEmbeddedFixedBond with an IRTree pricing method and a HullWhite model, you can calculate the option adjusted spread (OAS) using oas.

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

HullWhiteModelObj = finmodel(ModelType,'Alpha'alpha_value,'Sigma',sigma_value)

Description

HullWhiteModelObj = finmodel(ModelType,'Alpha'alpha_value,'Sigma',sigma_value) creates a HullWhite model object by specifying ModelType and the required name-value pair argumentsAlpha and Sigma to set properties using name-value pair arguments. For example, HullWhiteModelObj = finmodel("HullWhite",'Alpha',0.052,'Sigma',0.34) creates a HullWhite model object.

Input Arguments

ModelType — Model type

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

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

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.

Before R2021a, use commas to separate each name and value, and enclose Name in quotes.

Example: HullWhiteModelObj = finmodel("HullWhite",'Alpha',0.052,'Sigma',0.34)

Alpha — Mean reversion speed

numeric

Mean reversion speed, specified as the comma-separated pair consisting of 'Alpha' and a scalar numeric or timetable.

Alpha accepts a timetable, where the first column is dates and the second column is the associated Alpha value.

Data Types: double | timetable

Sigma — Volatility

numeric | timetable

Volatility, specified as the comma-separated pair consisting of 'Sigma' and a scalar numeric or timetable.

Sigma accepts a timetable, where the first column is dates and the second column is the associated Sigma value.

Data Types: double | timetable

Output Arguments

HullWhiteModelObj — Hull-White model

HullWhite object

Hull-White model, returned as a HullWhite object.

Properties

Alpha — Mean reversion speed

numeric

Mean reversion speed, returned as a scalar numeric or timetable.

Data Types: double | timetable

Sigma — Volatility

numeric | timetable

Volatility, returned as a scalar numeric value or timetable.

Data Types: double | timetable

Examples

Use HullWhite Model and HullWhite Pricer to Price Floor Instrument

This example shows the workflow to price a Floor instrument when you use a HullWhite model and a HullWhite pricing method.

Create Floor Instrument Object

Use fininstrument to create a Floor instrument object.

FloorOpt = fininstrument("Floor",'Strike',0.045,'Maturity',datetime(2019,1,30),'Reset',4,'Principal',100,'Basis',1,'Name',"floor_option")

FloorOpt = 
  Floor with properties:

                      Strike: 0.0450
                    Maturity: 30-Jan-2019
                 ResetOffset: 0
                       Reset: 4
                       Basis: 1
                   Principal: 100
             ProjectionCurve: [0×0 ratecurve]
    DaycountAdjustedCashFlow: 0
       BusinessDayConvention: "actual"
                    Holidays: NaT
                        Name: "floor_option"

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

Create ratecurve Object

Create a ratecurve object using ratecurve.

Settle = datetime(2018,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-2018
         InterpMethod: "linear"
    ShortExtrapMethod: "next"
     LongExtrapMethod: "previous"

Create HullWhite Pricer Object

Use finpricer to create a HullWhite pricer object and use the ratecurve object for the 'DiscountCurve' name-value pair argument.

outPricer = finpricer("analytic",'Model',HullWhiteModel,'DiscountCurve',myRC) 

outPricer = 
  HullWhite with properties:

    DiscountCurve: [1×1 ratecurve]
            Model: [1×1 finmodel.HullWhite]

Price Floor Instrument

Use price to compute the price for the Floor instrument.

Price = price(outPricer,FloorOpt)

Price = 
1.4917

Use HullWhite Model and IRMonteCarlo Pricer to Price RangeAccrualNote Instrument

This example shows the workflow to price a RangeAccrualNote instrument when you use a HullWhite 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="cms",ReferenceTenor=10,CouponRate=0.4,TargetRange=[0,3.25/100],Principal=1000,Name="rangeaccrualnote_instrument")

RangeAccrualNoteInstrument = 
  RangeAccrualNote 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-2026
                  CouponRate: 0.4000
                 TargetRange: [0 0.0325]
                   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 a HullWhite Model Object

Use finmodel to create a HullWhite model object.

HullWhiteModel = finmodel("HullWhite",Alpha=0.02,Sigma=0.03)

HullWhiteModel = 
  HullWhite with properties:

    Alpha: 0.0200
    Sigma: 0.0300

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

outPricer = 
  HWMonteCarlo 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.HullWhite]

Price RangeAccrualNote Instrument

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

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

Price = 
1.5111e+03

outPR = 
  priceresult with properties:

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

outPR.Results

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

    1511.1    8244.1    5.9468e+06    -4760.4

More About

Hull-White Model

The Hull-White (HW) model is a mathematical model used to describe the behavior of interest rates over time.

The HW model uses stochastic calculus to model the evolution of interest rates as a function of time and random factors. This is a one-factor short-rate model, which means that it assumes that the short-term interest rate is determined by a single underlying factor.

The HW model assumes that the short-term interest rate follows a stochastic process. The stochastic process is typically modeled as a mean-reverting process driven by a random shock or factor.

The HW model is defined as:

$$d{r}_t=[{\theta }_t-\alpha r_t]dt+\sigma d{W}_t$$

where

r_t is the short-term interest rate at time t.

dr_t is the change in the short-term interest rate over a small time interval dt.

Θ_t is the time-varying mean reversion level of the interest rate.

α is the constant mean reversion speed.

σ is the constant volatility of the interest rate.

dW_t is a standard Wiener process or Brownian motion, representing the randomness or uncertainty in the evolution of the interest rate.

Version History

Introduced in R2020a

R2026a: Support for RangeAccrualNote and OptionEmbeddedRangeAccrualNote Instruments

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