# Black

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

## Description

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`, or`Swaption` 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.

## Creation

### Syntax

``BlackModelObj = finmodel(ModelType,'Volatility',volatility_value)``
``BlackModelObj = finmodel(___,Name,Value)``

### Description

example

````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.```

### 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`

`Black` Name-Value Pair Arguments

Specify required and optional comma-separated pairs of `Name,Value` arguments. `Name` is the argument name and `Value` is the corresponding value. `Name` must appear inside quotes. You can specify several name and value pair arguments in any order as `Name1,Value1,...,NameN,ValueN`.

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`

## Properties

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`

## Examples

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 ```

expand all

expand all