Documentation

# optSensByHestonFD

Option price and sensitivities by Heston model using finite differences

## Syntax

``[PriceSens,PriceGrid,AssetPrices,Variances,Times] = optByHestonFD(Rate,AssetPrice,Settle,ExerciseDates,OptSpec,Strike,V0,ThetaV,Kappa,SigmaV,RhoSV)``
``[PriceSens,PriceGrid,AssetPrices,Variances,Times] = optByHestonFD(___,Name,Value)``

## Description

example

````[PriceSens,PriceGrid,AssetPrices,Variances,Times] = optByHestonFD(Rate,AssetPrice,Settle,ExerciseDates,OptSpec,Strike,V0,ThetaV,Kappa,SigmaV,RhoSV)` computes a vanilla European or American option price and sensitivities by the Heston model, using the alternating direction implicit (ADI) method.```

example

````[PriceSens,PriceGrid,AssetPrices,Variances,Times] = optByHestonFD(___,Name,Value)` specifies options using one or more name-value pair arguments in addition to the input arguments in the previous syntax.```

## Examples

collapse all

Define the option variables and Heston model parameters.

```AssetPrice = 10; Strike = 10; Rate = 0.1; Settle = '01-Jan-2017'; ExerciseDates = '02-Apr-2017'; V0 = 0.0625; ThetaV = 0.16; Kappa = 5.0; SigmaV = 0.9; RhoSV = 0.1;```

Compute the American put option price and sensitivities.

```OptSpec = 'Put'; [Price,Delta,Gamma,Rho,Theta,Vega,VegaLT] = optSensByHestonFD(Rate, AssetPrice, Settle, ExerciseDates, ... OptSpec, Strike, V0, ThetaV, Kappa, SigmaV, RhoSV, 'AmericanOpt', 1, ... 'OutSpec', ["Price" "Delta" "Gamma" "Rho" "Theta" "Vega" "VegaLT"])```
```Price = 0.5188 ```
```Delta = -0.4472 ```
```Gamma = 0.2822 ```
```Rho = -0.9234 ```
```Theta = -1.1614 ```
```Vega = 0.8998 ```
```VegaLT = 1.0921 ```

## Input Arguments

collapse all

Continuously compounded risk-free interest rate, specified as a scalar decimal.

Data Types: `double`

Current underlying asset price, specified as a scalar numeric.

Data Types: `double`

Option settlement date, specified as a scalar using serial date numbers, date character vectors, datetime arrays, or string arrays.

Data Types: `double` | `char` | `datetime` | `string`

Option exercise dates, specified as a serial date number, date character vector, string array, or datetime array:

• For a European option, there is only one `ExerciseDates` value and this is the option expiry date.

• For an American option, use a `1`-by-`2` vector of exercise date boundaries. The option can be exercised on any tree date between or including the pair of dates on that row. If only one non-`NaN` date is listed, the option can be exercised between the `Settle` date and the single listed `ExerciseDate`.

Data Types: `double` | `char` | `string` | `datetime`

Definition of the option, specified as a scalar using a cell array of character vectors or string arrays with values `'call'` or `'put'`.

Data Types: `cell` | `string`

Option strike price value, specified as a scalar numeric.

Data Types: `double`

Initial variance of the underlying asset, specified as a scalar numeric.

Data Types: `double`

Long-term variance of the underlying asset, specified as a scalar numeric.

Data Types: `double`

Mean revision speed for the variance of the underlying asset, specified as a scalar numeric.

Data Types: `double`

Volatility of the variance of the underlying asset, specified as a scalar numeric.

Data Types: `double`

Correlation between the Weiner processes for the underlying asset and its variance, specified as a scalar numeric.

Data Types: `double`

### Name-Value Pair Arguments

Specify 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: ```[PriceSens,PriceGrid,AssetPrices,Variances,Times] = optSensByHestonFD(Rate,AssetPrice,Settle,ExerciseDates,OptSpec,Strike,V0,ThetaV,Kappa,SigmaV,RhoSV,'Basis',7)```

Day-count basis of the instrument, specified as the comma-separated pair consisting of `'Basis'` and a scalar using a supported value:

• 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

Data Types: `double`

Continuously compounded underlying asset yield, specified as the comma-separated pair consisting of `'DividendYield'` and a scalar numeric.

### Note

If you enter a value for `DividendYield`, then set `DividendAmounts` and `ExDividendDates` = `[ ]` or do not enter them. If you enter values for `DividendAmounts` and `ExDividendDates`, then set `DividendYield` = `0`.

Data Types: `double`

Cash dividend amounts, specified as the comma-separated pair consisting of `'DividendAmounts'` and a `NDIV`-by-`1` vector.

### Note

Each dividend amount must have a corresponding ex-dividend date. If you enter values for `DividendAmounts` and `ExDividendDates`, then set `DividendYield` = `0`.

Data Types: `double`

Ex-dividend dates, specified as the comma-separated pair consisting of `'ExDividendDates'` and a `NDIV`-by-`1` vector of serial date numbers, character vectors, string arrays, or datetime arrays.

Data Types: `double` | `char` | `string` | `datetime`

Maximum price for price grid boundary, specified as the comma-separated pair consisting of `'AssetPriceMax'` and a positive scalar.

Data Types: `single` | `double`

Maximum variance to use for variance grid boundary, specified as the comma-separated pair consisting of `'VarianceMax'` as a scalar numeric.

Data Types: `double`

Size of the asset grid for finite difference grid, specified as the comma-separated pair consisting of `'AssetGridSize'` and a scalar numeric.

Data Types: `double`

Number of nodes for the variance grid for finite difference grid, specified as the comma-separated pair consisting of `'VarianceGridSize'` and a scalar numeric.

Data Types: `double`

Number of nodes of the time grid for finite difference grid, specified as the comma-separated pair consisting of `'TimeGridSize'` and a positive numeric scalar.

Data Types: `double`

Option type, specified as the comma-separated pair consisting of `'AmericanOpt'` and a scalar flag with one of these values:

• `0` — European

• `1` — American

Data Types: `double`

Define outputs, specified as the comma-separated pair consisting of `'OutSpec'` and an `NOUT`- by-`1` or a `1`-by-`NOUT` string array or cell array of character vectors with the supported values.

### Note

`'vega'` is the sensitivity with respect to the initial volatility sqrt(`V0`). In contrast, `'vegalt'` is the sensitivity with respect to the long-term volatility sqrt(`ThetaV`).

Example: ```OutSpec = {'price','delta','gamma','vega','rho','theta','vegalt'}```

Data Types: `string` | `cell`

## Output Arguments

collapse all

Option price and sensitivities, returned as a scalar numeric. `OutSpec` determines the types and order of the outputs.

Grid containing prices calculated by the finite difference method, returned as a three-dimensional grid with size `AssetGridSize``VarianceGridSize``TimeGridSize`. The depth is not necessarily equal to the `TimeGridSize`, because exercise and ex-dividend dates are added to the time grid. `PriceGrid(:, :, end)` contains the price for t = `0`.

Prices of the asset corresponding to the first dimension of `PriceGrid`, returned as a vector.

Variances corresponding to the second dimension of `PriceGrid`, returned as a vector.

Times corresponding to the third dimension of `PriceGrid`, returned as a vector.

collapse all

### Vanilla Option

A vanilla option is a category of options that includes only the most standard components.

A vanilla option has an expiration date and straightforward strike price. American-style options and European-style options are both categorized as vanilla options.

The payoff for a vanilla option is as follows:

• For a call: $\mathrm{max}\left(St-K,0\right)$

• For a put: $\mathrm{max}\left(K-St,0\right)$

where:

St is the price of the underlying asset at time t.

K is the strike price.

### Heston Stochastic Volatility Model

The Heston model is an extension of the Black-Scholes model, where the volatility (square root of variance) is no longer assumed to be constant, and the variance now follows a stochastic (CIR) process. This allows modeling the implied volatility smiles observed in the market.

The stochastic differential equation is:

`$\begin{array}{l}d{S}_{t}=\left(r-q\right){S}_{t}dt+\sqrt{{v}_{t}}{S}_{t}d{W}_{t}\\ d{v}_{t}=\kappa \left(\theta -{v}_{t}\right)dt+{\sigma }_{v}\sqrt{{v}_{t}}d{W}_{t}^{v}\\ \text{E}\left[d{W}_{t}d{W}_{t}^{v}\right]=pdt\end{array}$`

where

r is the continuous risk-free rate.

q is the continuous dividend yield.

St is the asset price at time t.

vt is the asset price variance at time t

v0 is the initial variance of the asset price at t = 0 for (v0 > 0).

θ is the long-term variance level for (θ > 0).

κ is the mean reversion speed for the variance for (κ > 0).

σv is the volatility of the variance for (σv > 0).

p is the correlation between the Weiner processes Wt and Wvt for (-1 ≤ p ≤ 1).

 Heston, S. L. “A Closed-Form Solution for Options with Stochastic Volatility with Applications to Bond and Currency Options.” The Review of Financial Studies. Vol 6, Number 2, 1993.