Main Content


Create Black model object for Cap, Floor, or Swaption instrument

Since R2020a


Create and price a Cap, Floor, or Swaption instrument object with a Black model using this workflow:

  1. Use fininstrument to create a Cap, Floor, orSwaption instrument object.

  2. Use finmodel to specify a Black model object for the Cap, Floor, or Swaption instrument object.

  3. Use finpricer to specify a Black pricing method for the Cap, Floor, or Swaption 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, or Swaption instrument when using a Black model, see Choose Instruments, Models, and Pricers.




BlackModelObj = finmodel(ModelType,'Volatility',volatility_value) creates a Black model object by specifying ModelType and sets the properties for the required name-value pair argument Volatility. For more information on a Black model, see More About and Algorithms.


BlackModelObj = finmodel(___,Name,Value) sets optional properties using additional name-value pairs in addition to the required arguments in the previous syntax. For example, BlackModelObj = finmodel("Black",'Volatility',0.032,'Shift',0.002) creates a Black model object. You can specify multiple name-value pair arguments.

Input Arguments

expand all

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

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: BlackModelObj = finmodel("Black",'Volatility',0.032,'Shift',0.002)

Required Black Name-Value Pair Arguments

expand all

Volatility value for the underlying asset, specified as the comma-separated pair consisting of 'Volatility' and a scalar nonnegative numeric.

Data Types: double

Optional Black Name-Value Pair Argument

expand all

Shift in decimals for the shifted Black model, specified as the comma-separated pair consisting of 'Shift' and a scalar rate shift in positive decimals. Set this parameter to a positive rate shift in decimals to add a positive shift to the forward rate and strike, which effectively sets a negative lower bound for the forward rate. For example, a Shift value of 0.01 is equal to a 1% shift.

Data Types: double


expand all

Volatility value, returned as a scalar nonnegative numeric.

Data Types: double

Shift in decimals for the shifted Black model, returned as a scalar rate shift in a positive decimal.

Data Types: double


collapse all

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

Create Cap Instrument Object

Use fininstrument to create a Cap instrument object.

CapOpt = fininstrument("Cap",'Strike',.001,'Maturity',datetime(2019,1,30),'Reset',4,'Principal',100,'Basis',8,'Name',"cap_option")
CapOpt = 
  Cap with properties:

                      Strike: 1.0000e-03
                    Maturity: 30-Jan-2019
                 ResetOffset: 0
                       Reset: 4
                       Basis: 8
                   Principal: 100
             ProjectionCurve: [0x0 ratecurve]
    DaycountAdjustedCashFlow: 0
       BusinessDayConvention: "actual"
                    Holidays: NaT
                        Name: "cap_option"

Create Black Model Object

Use finmodel to create a Black model object.

BlackModel = finmodel("Black",'Volatility',0.032,'Shift',0.002)
BlackModel = 
  Black with properties:

    Volatility: 0.0320
         Shift: 0.0020

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: [10x1 datetime]
                Rates: [10x1 double]
               Settle: 15-Sep-2018
         InterpMethod: "linear"
    ShortExtrapMethod: "next"
     LongExtrapMethod: "previous"

Create Black Pricer Object

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

outPricer = finpricer("analytic",'Model',BlackModel,'DiscountCurve',myRC)
outPricer = 
  Black with properties:

            Model: [1x1 finmodel.Black]
    DiscountCurve: [1x1 ratecurve]

Price Cap Instrument

Use price to compute the price for the Cap instrument.

Price = price(outPricer,CapOpt)
Price = 0.1575

More About

expand all


expand all

Version History

Introduced in R2020a