Black

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

Since R2020a

Description

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

Use fininstrument to create a Cap, Floor, or Swaption instrument object.
Use finmodel to specify a Black model object for the Cap, Floor, or Swaption instrument object.
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.

Creation

Syntax

BlackModelObj = finmodel(ModelType,'Volatility',volatility_value)

BlackModelObj = finmodel(___,Name,Value)

Description

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.

example

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.

example

Input Arguments

expand all

`ModelType` — Model type
string with value `"Black"` | character vector with value `'Black'`

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` — Volatility value for the underlying asset
nonnegative numeric

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` — Shift in decimals for shifted Black model
`0` (no shift) (default) | positive decimal

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

Properties

expand all

`Volatility` — Volatility value
nonnegative numeric

Volatility value, returned as a scalar nonnegative numeric.

Data Types: double

`Shift` — Shift in decimals for shifted Black model
`0` (no shift) (default) | positive decimal

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

Data Types: double

Examples

collapse all

Use `Black` Model and `Black` Pricer to Price `Cap` Instrument

Open Live Script

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

Shifted Black Model

The shifted Black model is the same as the Black model, except that it models the movements of (F + Shift) as the underlying asset, instead of F (which is the forward rate in the case of caplets).

This model allows negative rates, with a fixed negative lower bound defined by the amount of shift; that is, the zero lower bound of the Black model is shifted.

The shifted Black model assumes that the underlying interest rate follows a log-normal distribution. This assumption allows for the modeling of positive interest rate movements.

The shifted Black model is commonly used to price interest rate options, such as caps, floors, and swaptions. It is particularly useful when dealing with interest rates that have a non-zero floor, such as zero-coupon bonds or options on negative interest rates.

Algorithms

expand all

Black Model

$\begin{array}{l} d F = σ_{B l a c k} F d w \\ c a l l = e^{- γ T} [F N (d_{1}) - K N (d_{2})] \\ p u t = e^{- γ T} [K N (- d_{2}) - F N (- d_{1})] \\ d_{1} = \frac{\ln (\frac{F}{K}) + (\frac{σ_{B}^{2}}{2}) T}{σ_{B} \sqrt{T}}, d_{2} = d_{1} - σ_{B} \sqrt{T} \\ σ_{B} = σ_{B l a c k} \end{array}$

Here, F is the forward value and K is the strike.

Shifted Black Model

$\begin{array}{l} d F = σ_{S h i f t e d_B l a c k} (F + S h i f t) d w \\ c a l l = e^{- γ T} [(F + S h i f t) N (d_{s 1}) - (K + S h i f t) N (d_{s 2})] \\ p u t = e^{- γ T} [(K + S h i f t) N (- d_{s 2}) - (F + S h i f t) N (- d_{s 1})] \\ d_{s 1} = \frac{\ln (\frac{F + S h i f t}{K + S h i f t}) + (\frac{σ_{s B}^{2}}{2}) T}{σ_{s B} \sqrt{T}}, d_{s 2} = d_{s 1} - σ_{s B} \sqrt{T} \\ σ_{s B} = σ_{S h i f t e d_B l a c k} \end{array}$

Here, F+Shift is the forward value and K+Shift is the strike for the shifted version.

Version History

Introduced in R2020a

Black

Description

Creation

Syntax

Description

Input Arguments

`ModelType` — Model type
string with value `"Black"` | character vector with value `'Black'`

`Volatility` — Volatility value for the underlying asset
nonnegative numeric

`Shift` — Shift in decimals for shifted Black model
`0` (no shift) (default) | positive decimal

Properties

`Volatility` — Volatility value
nonnegative numeric

`Shift` — Shift in decimals for shifted Black model
`0` (no shift) (default) | positive decimal

Examples

Use `Black` Model and `Black` Pricer to Price `Cap` Instrument

More About

Shifted Black Model

Algorithms

Black Model

Shifted Black Model

Version History

See Also

Functions

Topics

Black

Description

Creation

Syntax

Description

Input Arguments

ModelType — Model type string with value "Black" | character vector with value 'Black'

Volatility — Volatility value for the underlying asset nonnegative numeric

Shift — Shift in decimals for shifted Black model 0 (no shift) (default) | positive decimal

Properties

Volatility — Volatility value nonnegative numeric

Shift — Shift in decimals for shifted Black model 0 (no shift) (default) | positive decimal

Examples

Use Black Model and Black Pricer to Price Cap Instrument

More About

Shifted Black Model

Algorithms

Black Model

Shifted Black Model

Version History

See Also

Functions

Topics

`ModelType` — Model type
string with value `"Black"` | character vector with value `'Black'`

`Volatility` — Volatility value for the underlying asset
nonnegative numeric

`Shift` — Shift in decimals for shifted Black model
`0` (no shift) (default) | positive decimal

`Volatility` — Volatility value
nonnegative numeric

`Shift` — Shift in decimals for shifted Black model
`0` (no shift) (default) | positive decimal

Use `Black` Model and `Black` Pricer to Price `Cap` Instrument