Calculate price and sensitivities for European or American spread options using Monte Carlo simulations

## Syntax

``PriceSens = spreadsensbyls(RateSpec,StockSpec1,StockSpec2,Settle,Maturity,OptSpec,Strike,Corr)``
``PriceSens = spreadsensbyls(___,Name,Value)``
``````[PriceSens,Paths,Times,Z] = spreadsensbyls(RateSpec,StockSpec1,StockSpec2,Settle,Maturity,OptSpec,Strike,Corr)``````
``````[PriceSens,Paths,Times,Z] = spreadsensbyls(___,Name,Value)``````

## Description

example

````PriceSens = spreadsensbyls(RateSpec,StockSpec1,StockSpec2,Settle,Maturity,OptSpec,Strike,Corr)` returns the price of a European or American call or put spread option using Monte Carlo simulations.For American options, the Longstaff-Schwartz least squares method is used to calculate the early exercise premium. NoteAlternatively, you can use the `Spread` object to calculate price or sensitivities for spread options. For more information, see Get Started with Workflows Using Object-Based Framework for Pricing Financial Instruments. ```
````PriceSens = spreadsensbyls(___,Name,Value)` adds optional name-value pair arguments.```
``````[PriceSens,Paths,Times,Z] = spreadsensbyls(RateSpec,StockSpec1,StockSpec2,Settle,Maturity,OptSpec,Strike,Corr)``` returns the `PriceSens`, `Paths`, `Times`, and `Z` of a European or American call or put spread option using Monte Carlo simulations.```
``````[PriceSens,Paths,Times,Z] = spreadsensbyls(___,Name,Value)``` returns the `PriceSens`, `Paths`, `Times`, and `Z` and adds optional name-value pair arguments.```

## Examples

collapse all

```Settle = datetime(2012,6,1); Maturity = datetime(2012,9,1);```

Define asset 1. Price and volatility of RBOB gasoline

``` Price1gallon = 2.85; % \$/gallon Price1 = Price1gallon * 42; % \$/barrel Vol1 = 0.29;```

Define asset 2. Price and volatility of WTI crude oil

``` Price2 = 93.20; % \$/barrel Vol2 = 0.36;```

Define the correlation between the underlying asset prices of asset 1 and asset 2.

`Corr = 0.42;`

```OptSpec = 'call'; Strike = 20;```

Define the `RateSpec`.

```rates = 0.05; Compounding = -1; Basis = 1; RateSpec = intenvset('ValuationDate', Settle, 'StartDates', Settle, ... 'EndDates', Maturity, 'Rates', rates, ... 'Compounding', Compounding, 'Basis', Basis)```
```RateSpec = struct with fields: FinObj: 'RateSpec' Compounding: -1 Disc: 0.9876 Rates: 0.0500 EndTimes: 0.2500 StartTimes: 0 EndDates: 735113 StartDates: 735021 ValuationDate: 735021 Basis: 1 EndMonthRule: 1 ```

Define the `StockSpec` for the two assets.

`StockSpec1 = stockspec(Vol1, Price1)`
```StockSpec1 = struct with fields: FinObj: 'StockSpec' Sigma: 0.2900 AssetPrice: 119.7000 DividendType: [] DividendAmounts: 0 ExDividendDates: [] ```
`StockSpec2 = stockspec(Vol2, Price2)`
```StockSpec2 = struct with fields: FinObj: 'StockSpec' Sigma: 0.3600 AssetPrice: 93.2000 DividendType: [] DividendAmounts: 0 ExDividendDates: [] ```

Compute the spread option price and sensitivities using Monte Carlo simulation based on the Longstaff-Schwartz model.

```OutSpec = {'Price', 'Delta', 'Gamma'}; [Price, Delta, Gamma] = spreadsensbyls(RateSpec, StockSpec1, StockSpec2, ... Settle, Maturity, OptSpec, Strike, Corr, 'OutSpec', OutSpec)```
```Price = 11.0799 ```
```Delta = 1×2 0.6626 -0.5972 ```
```Gamma = 1×2 0.0209 0.0240 ```

## Input Arguments

collapse all

Interest-rate term structure (annualized and continuously compounded), specified by the `RateSpec` obtained from `intenvset`. For information on the interest-rate specification, see `intenvset`.

Data Types: `struct`

Stock specification for underlying asset 1. For information on the stock specification, see `stockspec`.

`stockspec` can handle other types of underlying assets. For example, for physical commodities the price is represented by `StockSpec.Asset`, the volatility is represented by `StockSpec.Sigma`, and the convenience yield is represented by `StockSpec.DividendAmounts`.

Data Types: `struct`

Stock specification for underlying asset 2. For information on the stock specification, see `stockspec`.

`stockspec` can handle other types of underlying assets. For example, for physical commodities the price is represented by `StockSpec.Asset`, the volatility is represented by `StockSpec.Sigma`, and the convenience yield is represented by `StockSpec.DividendAmounts`.

Data Types: `struct`

Settlement date for the spread option, specified as a scalar datetime, string, or date character vector.

To support existing code, `spreadsensbyls` also accepts serial date numbers as inputs, but they are not recommended.

Maturity date for spread option, specified as a scalar datetime, string, or date character vector.

To support existing code, `spreadsensbyls` also accepts serial date numbers as inputs, but they are not recommended.

Definition of option as `'call'` or `'put'`, specified as a character vector.

Data Types: `char`

Option strike price value, specified as a scalar integer.

Data Types: `single` | `double`

Correlation between underlying asset prices, specified as a scalar integer.

Data Types: `single` | `double`

### Name-Value Arguments

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.

Before R2021a, use commas to separate each name and value, and enclose `Name` in quotes.

Example: ```PriceSens = spreadbyls(RateSpec,StockSpec1,StockSpec2,Settle,Maturity,OptSpec,Strike,Corr,'AmericanOpt',1)```

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

• `0` — European

• `1` — American

Note

For American options, the Longstaff-Schwartz least squares method is used to calculate the early exercise premium. For more information on the least squares method, see https://people.math.ethz.ch/%7Ehjfurrer/teaching/LongstaffSchwartzAmericanOptionsLeastSquareMonteCarlo.pdf.

Data Types: `single` | `double`

Number of independent sample paths (simulation trials), specified as the comma-separated pair consisting of `'NumTrials'` and a nonnegative scalar integer.

Data Types: `single` | `double`

Number of simulation periods per trial, specified as the comma-separated pair consisting of `'NumPeriods'` and a nonnegative scalar integer. `NumPeriods` is considered only when pricing European basket options. For American spread options, `NumPeriods` is equal to the number of exercise days during the life of the option.

Data Types: `single` | `double`

Time series array of dependent random variates, specified as the comma-separated pair consisting of `'Z'` and a `NumPeriods`-by-`2`-by-`NumTrials` 3-D array. The `Z` value generates the Brownian motion vector (that is, Wiener processes) that drives the simulation.

Data Types: `single` | `double`

Indicator for antithetic sampling, specified as the comma-separated pair consisting of `'Antithetic'` and a value of `true` or `false`.

Data Types: `logical`

Define outputs, specified as the comma-separated pair consisting of `'OutSpec'`and a `NOUT`- by-`1` or `1`-by-`NOUT` cell array of character vectors with possible values of `'Price'`, `'Delta'`, `'Gamma'`, `'Vega'`, `'Lambda'`, `'Rho'`, `'Theta'`, and `'All'`.

`OutSpec = {'All'}` specifies that the output should be `Delta`, `Gamma`, `Vega`, `Lambda`, `Rho`, `Theta`, and `Price`, in that order. This is the same as specifying `OutSpec` to include each sensitivity:

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

Data Types: `char` | `cell`

## Output Arguments

collapse all

Expected price or sensitivities of the spread option, returned as a `1`-by-`1` array as defined by `OutSpec`.

Simulated paths of correlated state variables, returned as a ```NumPeriods + 1```-by-`2`-by-`NumTrials` 3-D time series array. Each row of `Paths` is the transpose of the state vector X(t) at time t for a given trial.

Observation times associated with simulated paths, returned as a ```NumPeriods + 1```-by-`1` column vector of observation times associated with the simulated paths. Each element of `Times` is associated with the corresponding row of `Paths`.

Time series array of dependent random variates, returned as a `NumPeriods`-by-`2`-by-`NumTrials` 3-D array when `Z` is specified as an input argument. If the `Z` input argument is not specified, then the `Z` output argument contains the random variates generated internally.

collapse all

A spread option is an option written on the difference of two underlying assets.

For example, a European call on the difference of two assets X1 and X2 would have the following pay off at maturity:

`$\mathrm{max}\left(X1-X2-K,0\right)$`

where:

K is the strike price.