RangeAccrualNote

RangeAccrualNote instrument object

Since R2026a

expand all in page

Description

Create and price a RangeAccrualNote instrument object for one or more Range Accrual Note instruments using this workflow:

  1. Use fininstrument to create a RangeAccrualNote instrument object for one or more Range Accrual Note instruments.

  2. Use finmodel to specify a HullWhite or LinearGaussian2F model for the RangeAccrualNote instrument object.

  3. When using a HullWhite or LinearGaussian2F model, use finpricer to specify an IRMonteCarlo pricing method for one or more RangeAccrualNote 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 RangeAccrualNote instrument, see Choose Instruments, Models, and Pricers.

Creation

Syntax

RangeAccrualNoteObj = fininstrument(InstrumentType,Maturity=maturity_value,ReferenceType=reference_type,ReferenceTenor=reference_tenor_value,CouponRate=couponrate_value,TargetRange=targetrange_value)
RangeAccrualNoteObj = fininstrument(___,Name=Value)

Description

RangeAccrualNoteObj = fininstrument(InstrumentType,Maturity=maturity_value,ReferenceType=reference_type,ReferenceTenor=reference_tenor_value,CouponRate=couponrate_value,TargetRange=targetrange_value) creates a RangeAccrualNote object for one or more Range Accrual Note instruments by specifying InstrumentType and sets the properties for the required name-value arguments Maturity, ReferenceType, ReferenceTenor, CouponRate, and TargetRange.

For more information on range accrual notes, see More About.

example

RangeAccrualNoteObj = fininstrument(___,Name=Value) sets optional properties using additional name-value pairs in addition to the required arguments in the previous syntax. For example, RangeAccrualNoteObj = fininstrument("RangeAccrualNote",Maturity=datetime(2026,9,15),ReferenceType="spot",ReferenceTenor=10,CouponRate=0.04,TargetRange=[0 0.0325],Period=2,Basis=4,Principal=500,CMSReferenceReset=4,Name="RangeAccrualNote_option") creates a RangeAccrualNote instrument. You can specify multiple name-value pair arguments.

example

Input Arguments

expand all

Instrument type, specified as a string with the value of "RangeAccrualNote", a character vector with the value of 'RangeAccrualNote', an NINST-by-1 string array with values of "RangeAccrualNote", or an NINST-by-1 cell array of character vectors with values of 'RangeAccrualNote'.

Data Types: char | cell | string

Name-Value Arguments

expand all

Specify 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: RangeAccrualNoteObj = fininstrument("RangeAccrualNote",Maturity=datetime(2026,9,15),ReferenceType="spot",ReferenceTenor=10,CouponRate=0.04,TargetRange=[0 0.0325],Period=2,Basis=4,Principal=500,CMSReferenceReset=4,Name="RangeAccrualNote_option")

Required RangeAccrualNote Name-Value Arguments

expand all

RangeAccrualNote maturity date, specified as a scalar datetime value or an NINST-by-1 vector using a datetime array, string array, or date character vectors.

If you use date character vectors or strings, the format must be recognizable by datetime because the Maturity property is stored as a datetime.

Data Types: char | cell | string

Type of underlying reference rate, specified as a scalar string or character vector or an NINST-by-1 cell array of character vectors or string array.

  • "cms" — Refers to the Constant Maturity Swap rate, a common choice for instruments linked to long-term interest rate expectations.

  • "spot" — Represents the spot rate, which is typically an interbank rate or an overnight rate.

In a range accrual note, the reference rate is crucial as it dictates whether the note accrues interest and the rate at which it does so. Common reference rates include:

  • Overnight Rates — Such as the Secured Overnight Financing Rate (SOFR)

  • Interbank Rates —Such as the Euro Interbank Offered Rate (EURIBOR)

  • Swap Rates — Such as the Constant Maturity Swap (CMS) rate

Data Types: char | cell | string

Tenor, in years, for the underlying reference rate , specified as a scalar numeric or an NINST-by-1 numeric array.

The underlying reference rate specific to using ReferenceType can be a Constant Maturity Swap (CMS) rate or a spot rate.

You can specify multiple tenors to create RangeAccrualNote instruments with more than one reference rate. For instance, to create a dual CMS range accrual note, specify [10,30] with ReferenceType as "cms" to use both the 10-year and 30-year CMS rates.

Data Types: double

RangeAccrualNote coupon rate, specified as a scalar decimal for an annual rate or a timetable where the first column is dates and the second column is associated rates. The date indicates the last day that the coupon rate is valid.

Note

If you are creating one or more RangeAccrualNote instruments and use a timetable, the timetable specification applies to all of the RangeAccrualNote instruments. CouponRate does not accept an NINST-by-1 cell array of timetables as input.

Data Types: double | timetable

RangeAccrualNote target range for the reference rate, specified as numeric vector, timetable, or function handle.

  • Numeric Vector

    When using a numeric vector for TargetRange, you define a [lowerBarrier, upperBarrier] target range (inclusive) for the reference rate. Specify this value as a 1-by-2 vector that is applied to all reference rates. For example:

    • [0, 3.25/100]

    • [0, inf]

    • [-inf, 4/100]

  • Timetable Format

    For more complex range settings, a timetable can specify different ranges for distinct periods. When you use a timetable for TargetRange, the columns represent the corresponding [lowerBarrier, upperBarrier] target ranges for each reference rate. Each date in the timetable indicates the last day that the target range is valid. The dimension in the timetable representing the reference rates must be arranged according to the tenors outlined in ReferenceTenor.

    For more complex range settings, a timetable can specify different ranges for distinct periods. For example,

           Time             Var1     
    ___________    ______________

    01-Jan-2021       0    0.0325
    01-Jan-2025       0    0.0375
    01-Jan-2026       0.01 Inf
    where

    • Year 1 is 0.00% – 3.25%

    • Year 2 to year 5 is 0.00% – 3.75%

    • Year 6 is >= 0.01%

    For an example of TargetRange using a timetable format, see Price RangeAccrualNote Instrument with Multiple Target Ranges Using HullWhite Model and IRMonteCarlo Pricer.

    Note

    If you are creating one or more RangeAccrualNote instruments and use a timetable, the timetable specification applies to all of the RangeAccrualNote instruments. TargetRange does not accept an NINST-by-1 cell array of timetables as input.

  • Function Handle

    If a RangeAccrualNote instrument involves using multiple reference rates with different ranges for each reference rate, you can specify TargetRange as a function handle. By using a function handle, you can dynamically define and manage complex relationships and conditions, ensuring that each reference rate is accurately evaluated against its corresponding range.

    When using a function handle for TargetRange, the function should accept input parameters in the form (refRates, rateDates), where refRates is an NRateDates-by-NTrials-by-NRefRates 3-D matrix containing reference rates. Each page (third dimension) of this matrix corresponds to a specific tenor as defined in the ReferenceTenor parameter. The rateDates is a vector containing the dates associated with the reference rates within a single coupon period. The function handle must return a fractional value between 0 and 1 that represents how interest accrues for each day the reference rates remain within the specified range. For instance, the function handle fractional return value can be the ratio of the number of days the rates remain within the range to the total number of coupon dates in that period.

    For an example of TargetRange using a function handle, see Price RangeAccrualNote Instrument with a Custom Target Range Using HullWhite Model and IRMonteCarlo Pricer.

Data Types: double | timetable | function_handle

Optional RangeAccrualNote Name-Value Arguments

expand all

Frequency of actual coupon payments per year, specified as a scalar integer or an NINST-by-1 vector of integers. Values for Period are 1, 2, 3, 4, 6, or 12.

Data Types: double

Day-count basis, specified as a scalar integer or an NINST-by-1 vector of integers using the following values:

  • 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

Principal amount, specified as a scalar numeric or an NINST-by-1 numeric vector.

Data Types: double

Frequency of actual payments per year for underlying reference swap of CMS, specified as a scalar or an NINST-by-1 vector.

Note

CMSReferenceReset applies only when you specify ReferenceType as "cms".

Data Types: double

Flag indicating whether the cash flow is adjusted by day count convention, specified as a scalar logical or an NINST-by-1 vector of logicals with values of true or false.

Data Types: logical

Business day conventions for cash flow dates, specified as a scalar string or character vector or an NINST-by-1 cell array of character vectors or string array. 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 nonbusiness 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 an NINST-by-1 vector of a datetime array, string array, or date character vectors. For example:

H = holidays(datetime('today'),datetime(2025,12,15));
RangeAccuralNoteObj = fininstrument("RangeAccuralNote",Maturity=datetime(2026,9,15),ReferenceType="spot", ...
ReferenceTenor=10,CouponRate=0.04,TargetRange=[0 0.0325],Period=2,Basis=4,Principal=500,CMSReferenceReset=4,Holidays=H)

Data Types: char | datetime | string

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 a scalar logical value or an NINST-by-1 vector of logicals with values of true or false.

  • 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 applies the rule, meaning that a payment date is always the last actual day of the month.

Data Types: logical

Forward starting date of payments, specified as a scalar character vector, string, or datetime or an NINST-by-1 vector using a datetime array, string array, or date character vectors.

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: char | datetime | string

User-defined name for one of more instruments, specified as a scalar string or character vector or an NINST-by-1 cell array of character vectors or string array.

Data Types: char | cell | string

Output Arguments

expand all

Range Accrual Note instrument, returned as a RangeAccrualNote object.

Properties

expand all

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

Data Types: datetime

Type of underlying reference rate, returned as a scalar string or an NINST-by-1 string array.

Data Types: string

Tenor, in years, for underlying reference rate, returned as a scalar numeric or an NINST-by-1 vector.

Data Types: double

RangeAccrualNote coupon annual rate, returned as a scalar decimal or a timetable.

Data Types: double | timetable

Target range ([lowerBarrier,upperBarrier]) for the reference rate, returned as a scalar numeric vector, timetable, or a function handle.

Data Types: double | timetable | function_handle

Frequency of payments per year, returned as a scalar integer or an NINST-by-1 vector of integers.

Data Types: double

Day count basis, returned as a scalar integer or an NINST-by-1 vector of integers.

Data Types: double

Principal amount, returned as a scalar numeric or an NINST-by-1 numeric vector.

Data Types: double

Frequency of actual payments per year for underlying reference swap of CMS, returned as a scalar or an NINST-by-1 vector.

Note

CMSReferenceReset applies only when you specify ReferenceType as "cms".

Data Types: double

Flag indicating whether cash flow adjusts for day count convention, returned as a scalar logical or an NINST-by-1 vector of logicals with values of true or false.

Data Types: logical

Business day conventions, returned as a scalar string or an NINST-by-1 string array.

Data Types: 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 having 30 or fewer days, returned as a scalar logical or an NINST-by-1 vector of logical values.

Data Types: logical

Forward starting date of payments, 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

Examples

collapse all

Open Live Script

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

This example shows the workflow to price a RangeAccrualNote instrument with multiple target ranges (using TargetRange) when you use a HullWhite model and an IRMonteCarlo pricing method.

Create RangeAccrualNote Instrument Object

Use fininstrument to create a RangeAccrualNote instrument object with multiple target ranges by the TargetRange name-value argument with a timetable. 

Maturity = datetime(2026,9,15);
RangeAccrualNoteInstrument = fininstrument("RangeAccrualNote",Maturity=Maturity,ReferenceType="cms",ReferenceTenor=10,CouponRate=0.4,TargetRange=timetable([datetime(2021,10,1);datetime(2025,10,1);datetime(2026,10,1)],[0,0.0325;0,0.0375;0.01,inf]),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: [3×1 timetable]
                   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 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.4373e+03

outPR = 
  priceresult with properties:

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


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

    1437.3    10014    9.946e+06    1288.4
Open Live Script

This example shows the workflow to price a RangeAccrualNote instrument with a custom TargetRange (specified using a function handle) and uses a HullWhite model and an IRMonteCarlo pricing method.

Create RangeAccrualNote Instrument Object

Use fininstrument to create a RangeAccrualNote instrument object. The TargetRange name-value argument specifies a function handle for checkValidCoupon. This function handle supports a custom calculation for a triple CMS RangeAccrualNote instrument. This RangeAccrualNote instrument object uses "cms" as the ReferenceType value with tenors [5, 10, 20]. The Period argument is set to 12, meaning each coupon period spans one month. The checkValidCoupon function collects simulated reference rates are collected for each coupon period.

Maturity = datetime(2026,1,1);
RangeAccrualNoteInstrument = fininstrument("RangeAccrualNote",Maturity=Maturity,ReferenceType="cms",ReferenceTenor=[5,10,20],Period=12,CouponRate=0.4,TargetRange=@checkValidCoupon,Principal=1000,Name="rangeaccrualnote_instrument")
RangeAccrualNoteInstrument = 
  RangeAccrualNote with properties:

               ReferenceType: "cms"
                      Period: 12
                       Basis: 0
                   Principal: 1000
           CMSReferenceReset: 2
    DaycountAdjustedCashFlow: 0
       BusinessDayConvention: "actual"
                    Holidays: NaT
                EndMonthRule: 1
              ReferenceTenor: [5 10 20]
                    Maturity: 01-Jan-2026
                  CouponRate: 0.4000
                 TargetRange: @checkValidCoupon
                   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 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 pair 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×340 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.3367e+03

outPR = 
  priceresult with properties:

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


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

    1336.7    9606.6    -2.2465e+06    -2803.4

Local Function

function ratio = checkValidCoupon(refRates, rateDates)
%%%%%%%%%% Information %%%%%%%%%%%%%%
% refRates: 3D matrix, NumSimulateDays-by-NumTrials-by-NumRefRates
% rateDates: vector, NumSimulateDays

% Reference rates are ordered as per ReferenceTenor and cover one coupon period.
% refRate1 = refRates(:,:,1): 5-year CMS for the period in rateDates
% refRate2 = refRates(:,:,2): 10-year CMS for the period in rateDates
% refRate3 = refRates(:,:,3): 20-year CMS for the period in rateDates

% Output ratio must be a 1 x NumTrials vector.
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%

% Define target range based on strategy.
Settle = datetime(2021,1,1);
Maturity = datetime(2026,1,1);
targetDates = Settle+calyears(1):calyears(1):Maturity;
targetRates = [.0325 .035 .0375 .04 .0425];

UpperRate = targetRates(find(rateDates(end) <= targetDates,1));
LowerRate = 0;

refRate1 = refRates(:,:,1);
refRate2 = refRates(:,:,2);
refRate3 = refRates(:,:,3);

% Calculate valid days based on custom logic.
validDays = sum((refRate3-refRate2) >= UpperRate | refRate1 >= LowerRate & refRate1 <= UpperRate,1); % 1 x NumTrials vector
totalDays = numel(rateDates);

% Compute accrued interest fraction based on custom logic.
AccruedCouponFraction = (2 * validDays - totalDays) / totalDays;

% Output ratio for pricer to compute accrued interest.
% AccruedCouponForThisPeriod = ratio * CouponRate*Principal/Period;
ratio = AccruedCouponFraction; % 1 x NumTrials vector

end
Open Live Script

This example shows the workflow to price a RangeAccrualNote instrument object for three RangeAccrualNote instruments when you use a HullWhite model and an IRMonteCarlo pricing method.

Create RangeAccrualNote Instrument Object

Use fininstrument to create a RangeAccrualNote instrument object for three RangeAccrualNote instruments. 

Maturity = datetime([2026,9,15; 2027,10,15 ; 2028,11,15]);
RangeAccrualNoteInstrument = fininstrument("RangeAccrualNote",Maturity=Maturity,ReferenceType="cms",ReferenceTenor=10,CouponRate=0.4,TargetRange=[0,3.25/100],Principal=1000,Name="rangeaccrualnote_instrument")
RangeAccrualNoteInstrument=3×1 RangeAccrualNote array with properties:
    ReferenceType
    Period
    Basis
    Principal
    CMSReferenceReset
    DaycountAdjustedCashFlow
    BusinessDayConvention
    Holidays
    EndMonthRule
    ReferenceTenor
    Maturity
    CouponRate
    TargetRange
    StartDate
    Name

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 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(end);
SimulationDates = busdate(SimulationDates,"follow");
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    …    ] (1×1049 datetime)
              Model: [1×1 finmodel.HullWhite]

Price RangeAccrualNote Instruments

Use price to compute the price and sensitivities for the three RangeAccrualNote instruments.

[Price,outPR] = price(outPricer,RangeAccrualNoteInstrument,"all")
Price = 3×1
103 ×

    1.5076
    1.8737
    2.0297


outPR=3×1 priceresult array with properties:
    Results
    PricerData


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

    1507.6    7839.9    -7.033e+06    -5674.5


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

    1873.7    12209    4.1283e+06    -10593


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

    2029.7    11157    2.9613e+06    -14635
Open Live Script

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

More About

expand all

Version History

Introduced in R2026a

See Also

Functions

Topics