# AssetMonteCarlo

Create `AssetMonteCarlo` pricer object for equity instruments using `BlackScholes`, `Merton`, `Heston`, or `Bates` model

## Description

Create and price a `Vanilla`, `Barrier`, `Lookback`, `PartialLookback`, `Asian`, `Spread`, `DoubleBarrier`, `Cliquet`, `Touch`, `DoubleTouch`, `Binary` instrument object with a `BlackScholes`, `Bachelier`, `Merton`, `Heston`, or `Bates` model and a `AssetMonteCarlo` pricing method using this workflow:

1. Use `finmodel` to specify a `BlackScholes` model for the `Vanilla`, `Barrier`, `Lookback`, `PartialLookback`, `Asian`, `Spread`, `DoubleBarrier`, `Cliquet`, `Touch`, `DoubleTouch`, or `Binary` instrument object.

Use `finmodel` to specify a `Bachelier` model for the `Vanilla`, `Spread` or `Binary` instrument object.

Use `finmodel` to specify a `Merton`, `Bates`, or `Heston` model for the `Vanilla`, `Barrier`, `Lookback`, `PartialLookback`, `Asian`, `DoubleBarrier`, `Touch`, `DoubleTouch`, `Cliquet`, or `Binary` instrument object.

2. Use `finpricer` to specify an `AssetMonteCarlo` pricer object for the `Vanilla`, `Barrier`, `Lookback`, `PartialLookback`, `Asian`, `Spread`, `DoubleBarrier`, `Cliquet`, `Touch`, `DoubleTouch`, or `Binary` 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 instruments, models, and pricing methods for `Vanilla`, `Barrier`, `Lookback`, `PartialLookback`, `Asian`, `Spread`, `DoubleBarrier`, `Cliquet`, `Touch`, `DoubleTouch`, or `Binary` instruments, see Choose Instruments, Models, and Pricers.

## Creation

### Syntax

``AssetMonteCarloPricerObj = finpricer(PricerType,'Model',model,'DiscountCurve',ratecurve_obj,'SpotPrice',spotprice_value,'SimulationDates',simulation_dates)``
``AssetMonteCarloPricerObj = finpricer(___,Name,Value)``

### Description

example

````AssetMonteCarloPricerObj = finpricer(PricerType,'Model',model,'DiscountCurve',ratecurve_obj,'SpotPrice',spotprice_value,'SimulationDates',simulation_dates)` creates a `AssetMonteCarlo` pricer object by specifying `PricerType` and sets the properties using the required name-value pair arguments `Model`, `DiscountCurve`, `SpotPrice`, and `SimulationDates`.```

example

````AssetMonteCarloPricerObj = finpricer(___,Name,Value)` sets optional properties using additional name-value pairs in addition to the required arguments in the previous syntax. For example, ```AssetMonteCarloPricerObj = finpricer("assetmontecarlo",'Model',BSModel,'DiscountCurve',ratecurve_obj,'SpotPrice',1000,'SimulationDates',[datetime(2018,1,30); datetime(2019,1,30)],'NumTrials',500,'DividendType','continuous','DividendValue',0.3)``` creates an `AssetMonteCarlo` pricer object using a `BlackScholes` model. You can specify multiple name-value pair arguments.```

### Input Arguments

expand all

Pricer type, specified as a string with the value `"AssetMonteCarlo"` or a character vector with the value `'AssetMonteCarlo'`.

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: ```AssetMonteCarloPricerObj = finpricer("assetmontecarlo",'Model',BSModel,'DiscountCurve',ratecurve_obj,'SpotPrice',1000,'SimulationDates',[datetime(2018,1,30); datetime(2019,1,30)],'NumTrials',500,'DividendType','continuous','DividendValue',0.3)```

Required `AssetMonteCarlo` Name-Value Pair Arguments

expand all

Model, specified as the comma-separated pair consisting of `'Model'` and the name of a previously created `BlackScholes`, `Merton`, `Bates`, or `Heston` model object. Create the model object using `finmodel`.

Data Types: `object`

`ratecurve` object for discounting cash flows, specified as the comma-separated pair consisting of `'DiscountCurve'` and the name of a previously created `ratecurve` object.

Note

Specify a flat `ratecurve` object for `DiscountCurve`. If you use a nonflat `ratecurve` object, the software uses the rate in the `ratecurve` object at `Maturity` and assumes that the value is constant for the life of the equity option.

Data Types: `object`

Current price of the underlying asset, specified as the comma-separated pair consisting of `'SpotPrice'` and a scalar nonnegative numeric or scalar positive or negative numeric when using `Bachelier` model.

Note

If you use a `Vanilla`, `Binary`, or `Spread` instrument with a `Bachelier` model, the `SpotPrice` can be a negative numeric value.

Data Types: `double`

Simulation dates, specified as the comma-separated pair consisting of `'SimulationDates'` and a scalar serial date number, date character vector, or datetime or a vector of serial date numbers, cell array of character vectors, string array, or datetime array.

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

Optional `AssetMonteCarlo` Name-Value Pair Arguments

expand all

Simulation trials, specified as the comma-separated pair consisting of `'NumTrials'` and a scalar number of independent sample paths.

Data Types: `double`

Dependent random variates, specified as the comma-separated pair consisting of `'RandomNumbers'` and an `NSimulationDates`-by-`NBrownians`-by-`NTrials` 3D time series array. The 3D time series array has the following fields:

• `Z``NSimulationDates`-by-`NBrownians`-by-`NTrials` 3D time series array of dependent random variates used to generate the Brownian motion vector (that is, Wiener processes) that drive the simulation.

• `N``NSimulationDates`-by-`NBrownians`-by-`NTrials` 3D time series array of dependent random variates used as the number of jumps.

• `SizeJ``NSimulationDates`-by-`NBrownians`-by-`NTrials` 3D time series array of dependent random variates used as the jump sizes.

Note

`BlackScholes` and `Heston` models only require `Z` field.

Data Types: `struct`

Stock dividend type, specified as the comma-separated pair consisting of `'DividendType'` and a character vector or string. `DividendType` must be either `"cash"` for actual dollar dividends or `"continuous"` for a continuous dividend yield.

Data Types: `char` | `string`

Dividend yield for the underlying stock, specified as the comma-separated pair consisting of `'DividendValue'` and a scalar numeric for a dividend yield or a timetable for a dividend schedule.

Note

Specify a scalar if `DividendType` is `"continuous"` and a timetable if `DividendType` is `"cash"`.

Data Types: `double` | `timetable`

## Properties

expand all

Model, returned as an object.

Data Types: `object`

`ratecurve` object for discounting cash flows, returned as a `ratecurve` object.

Data Types: `object`

Current price of underlying asset, returned as a scalar nonnegative numeric or a scalar positive or negative numeric when using `Bachelier` model.

Data Types: `double`

Simulation dates, returned as a datetime array.

Data Types: `datetime`

Simulation trials, returned as a scalar number of independent sample paths.

Data Types: `double`

Dependent random variates, returned as an `NSimulationDates`-by-`NBrownians`-by-`NTrials` 3D time series array.

Data Types: `struct`

Calculation for the early exercise premium, returned as a scalar function handle. The default `@longstaffschwartz_cubic` uses the Longstaff-Schwartz least squares method.

Data Types: `function_handle`

Dividend type, returned as a string. `DividendType` is either `"cash"` for actual dollar dividends or `"continuous"` for a continuous dividend yield.

Data Types: `string`

Dividend yield or dividend schedule for the underlying stock, returned as a scalar numeric for a dividend yield or a timetable for a dividend schedule.

Data Types: `double` | `timetable`

## Object Functions

 `price` Compute price for equity instrument with `AssetMonteCarlo` pricer

## Examples

collapse all

This example shows the workflow to price a `DoubleBarrier` instrument when you use a `BlackScholes` model and an `AssetMonteCarlo` pricing method.

Create `DoubleBarrier` Instrument Object

Use `fininstrument` to create a `DoubleBarrier` instrument object.

`DoubleBarrierOpt = fininstrument("DoubleBarrier",'Strike',100,'ExerciseDate',datetime(2020,8,15),'OptionType',"call",'ExerciseStyle',"american",'BarrierType',"DKO",'BarrierValue',[110 80],'Name',"doublebarrier_option")`
```DoubleBarrierOpt = DoubleBarrier with properties: OptionType: "call" Strike: 100 BarrierValue: [110 80] ExerciseStyle: "american" ExerciseDate: 15-Aug-2020 BarrierType: "dko" Rebate: [0 0] Name: "doublebarrier_option" ```

Create `BlackScholes` Model Object

Use `finmodel` to create a `BlackScholes` model object.

`BlackScholesModel = finmodel("BlackScholes","Volatility",0.3)`
```BlackScholesModel = BlackScholes with properties: Volatility: 0.3000 Correlation: 1 ```

Create `ratecurve` Object

Create a flat `ratecurve` object using `ratecurve`.

```Settle = datetime(2017,9,15); Maturity = datetime(2023,9,15); Rate = 0.035; myRC = ratecurve('zero',Settle,Maturity,Rate,'Basis',12)```
```myRC = ratecurve with properties: Type: "zero" Compounding: -1 Basis: 12 Dates: 15-Sep-2023 Rates: 0.0350 Settle: 15-Sep-2017 InterpMethod: "linear" ShortExtrapMethod: "next" LongExtrapMethod: "previous" ```

Create `AssetMonteCarlo` Pricer Object

Use `finpricer` to create an `AssetMonteCarlo` pricer object and use the `ratecurve` object for the `'DiscountCurve'` name-value pair argument.

```ExerciseDate = datetime(2020,08,15); Settle = datetime(2017,9,15); outPricer = finpricer("AssetMonteCarlo","DiscountCurve",myRC,"Model",BlackScholesModel,'SpotPrice',100,'simulationDates', Settle+days(1):days(1):ExerciseDate);```

Price `DoubleBarrier` Instrument

Use `price` to compute the price and sensitivities for the `DoubleBarrier` instrument.

`[Price, outPR] = price(outPricer,DoubleBarrierOpt,"all")`
```Price = 6.9667 ```
```outPR = priceresult with properties: Results: [1x7 table] PricerData: [1x1 struct] ```
`outPR.Results `
```ans=1×7 table Price Delta Gamma Lambda Rho Theta Vega ______ _______ _________ ______ _______ ______ _______ 6.9667 0.26875 -0.096337 3.8576 0.39855 9.5406 -1.2907 ```

This example shows the workflow to price a fixed-strike `Asian` instrument when you use a `Heston` model and an `AssetMonteCarlo` pricing method.

Create `Asian` Instrument Object

Use `fininstrument` to create an `Asian` instrument object.

`AsianOpt = fininstrument("Asian",'ExerciseDate',datetime(2022,9,15),'Strike',100,'OptionType',"put",'Name',"asian_option")`
```AsianOpt = Asian with properties: OptionType: "put" Strike: 100 AverageType: "arithmetic" AveragePrice: 0 AverageStartDate: NaT ExerciseStyle: "european" ExerciseDate: 15-Sep-2022 Name: "asian_option" ```

Create `Heston` Model Object

Use `finmodel` to create a `Heston` model object.

`HestonModel = finmodel("Heston",'V0',0.032,'ThetaV',0.1,'Kappa',0.003,'SigmaV',0.02,'RhoSV',0.9)`
```HestonModel = Heston with properties: V0: 0.0320 ThetaV: 0.1000 Kappa: 0.0030 SigmaV: 0.0200 RhoSV: 0.9000 ```

Create `ratecurve` Object

Create a flat `ratecurve` object using `ratecurve`.

```Settle = datetime(2018,9,15); Maturity = datetime(2023,9,15); Rate = 0.035; myRC = ratecurve('zero',Settle,Maturity,Rate,'Basis',12)```
```myRC = ratecurve with properties: Type: "zero" Compounding: -1 Basis: 12 Dates: 15-Sep-2023 Rates: 0.0350 Settle: 15-Sep-2018 InterpMethod: "linear" ShortExtrapMethod: "next" LongExtrapMethod: "previous" ```

Create `AssetMonteCarlo` Pricer Object

Use `finpricer` to create an `AssetMonteCarlo` pricer object and use the `ratecurve` object for the `'DiscountCurve'` name-value pair argument.

`outPricer = finpricer("AssetMonteCarlo",'DiscountCurve',myRC,"Model",HestonModel,'SpotPrice',80,'simulationDates',Settle+calmonths(1):calmonths(1):datetime(2022,9,15))`
```outPricer = HestonMonteCarlo with properties: DiscountCurve: [1x1 ratecurve] SpotPrice: 80 SimulationDates: [15-Oct-2018 15-Nov-2018 15-Dec-2018 ... ] NumTrials: 1000 RandomNumbers: [] Model: [1x1 finmodel.Heston] DividendType: "continuous" DividendValue: 0 ```

Price `Asian` Instrument

Use `price` to compute the price and sensitivities for the `Asian` instrument.

`[Price, outPR] = price(outPricer,AsianOpt,"all")`
```Price = 14.7999 ```
```outPR = priceresult with properties: Results: [1x8 table] PricerData: [1x1 struct] ```
`outPR.Results `
```ans=1×8 table Price Delta Gamma Lambda Rho Theta Vega VegaLT _____ ________ ________ _______ _______ _______ ______ _______ 14.8 -0.71073 0.023453 -3.8418 -173.12 0.61794 27.992 0.15319 ```

This example shows the workflow to price an American option for a `Vanilla` instrument when you use a `Bachelier` model and an `AssetMonteCarlo` pricing method.

Create `Vanilla` Instrument Object

Use `fininstrument` to create a `Vanilla` instrument object.

`VanillaOpt = fininstrument("Vanilla",'Strike',105,'ExerciseDate',datetime(2022,9,15),'OptionType',"call",'ExerciseStyle',"american",'Name',"vanilla_option")`
```VanillaOpt = Vanilla with properties: OptionType: "call" ExerciseStyle: "american" ExerciseDate: 15-Sep-2022 Strike: 105 Name: "vanilla_option" ```

Create `Bachelier` Model Object

Use `finmodel` to create a `Bachelier` model object.

`BachelierModel = finmodel("Bachelier","Volatility",0.2)`
```BachelierModel = Bachelier with properties: Volatility: 0.2000 Correlation: 1 ```

Create `ratecurve` Object

Create a flat `ratecurve` object using `ratecurve`.

```Settle = datetime(2018,9,15); Maturity = datetime(2023,9,15); Rate = 0.035; myRC = ratecurve('zero',Settle,Maturity,Rate,'Basis',12)```
```myRC = ratecurve with properties: Type: "zero" Compounding: -1 Basis: 12 Dates: 15-Sep-2023 Rates: 0.0350 Settle: 15-Sep-2018 InterpMethod: "linear" ShortExtrapMethod: "next" LongExtrapMethod: "previous" ```

Create `AssetMonteCarlo` Pricer Object

Use `finpricer` to create an `AssetMonteCarlo` pricer object and use the `ratecurve` object for the `'DiscountCurve'` name-value pair argument.

`outPricer = finpricer("AssetMonteCarlo",'DiscountCurve',myRC,"Model",BachelierModel,'SpotPrice',150,'simulationDates',datetime(2022,9,15))`
```outPricer = BachelierMonteCarlo with properties: DiscountCurve: [1x1 ratecurve] SpotPrice: 150 SimulationDates: 15-Sep-2022 NumTrials: 1000 RandomNumbers: [] Model: [1x1 finmodel.Bachelier] DividendType: "continuous" DividendValue: 0 ```

Price `Vanilla` Instrument

Use `price` to compute the price and sensitivities for the `Vanilla` instrument.

`[Price, outPR] = price(outPricer,VanillaOpt,["all"])`
```Price = 57.3776 ```
```outPR = priceresult with properties: Results: [1x7 table] PricerData: [1x1 struct] ```
`outPR.Results`
```ans=1×7 table Price Delta Gamma Lambda Rho Theta Vega ______ _______ __________ ______ ______ _______ ___________ 57.378 0.99107 -1.579e-14 2.5909 291.94 -2.5576 -2.1316e-10 ```

This example shows the workflow to price a `Binary` instrument with an underlying negatively valued asset when you use a `Bachelier` model and an `AssetMonteCarlo` pricing method.

Create `Binary` Instrument Object

Use `fininstrument` to create a `Binary` instrument object.

`BinaryOpt = fininstrument("Binary",'ExerciseDate',datetime(2022,9,15),'Strike',15,'PayoffValue',13,'OptionType',"put",'Name',"binary_option")`
```BinaryOpt = Binary with properties: OptionType: "put" ExerciseDate: 15-Sep-2022 Strike: 15 PayoffValue: 13 ExerciseStyle: "european" Name: "binary_option" ```

Create `Bachelier` Model Object

Use `finmodel` to create a `Bachelier` model object.

`BachelierModel = finmodel("Bachelier","Volatility",0.2)`
```BachelierModel = Bachelier with properties: Volatility: 0.2000 Correlation: 1 ```

Create `ratecurve` Object

Create a flat `ratecurve` object using `ratecurve`.

```Settle = datetime(2018,9,15); Maturity = datetime(2023,9,15); Rate = 0.035; myRC = ratecurve('zero',Settle,Maturity,Rate,'Basis',12)```
```myRC = ratecurve with properties: Type: "zero" Compounding: -1 Basis: 12 Dates: 15-Sep-2023 Rates: 0.0350 Settle: 15-Sep-2018 InterpMethod: "linear" ShortExtrapMethod: "next" LongExtrapMethod: "previous" ```

Create `AssetMonteCarlo` Pricer Object

Use `finpricer` to create an `AssetMonteCarlo` pricer object and use the `ratecurve` object for the `'DiscountCurve'` name-value pair argument. Note that when using a Bachelier model with a Vanilla, Binary, or Spread instrument, the `SpotPrice` can be a positive or negative numeric value.

`outPricer = finpricer("AssetMonteCarlo",'DiscountCurve',myRC,"Model",BachelierModel,'SpotPrice',-6,'simulationDates',datetime(2022,9,15))`
```outPricer = BachelierMonteCarlo with properties: DiscountCurve: [1x1 ratecurve] SpotPrice: -6 SimulationDates: 15-Sep-2022 NumTrials: 1000 RandomNumbers: [] Model: [1x1 finmodel.Bachelier] DividendType: "continuous" DividendValue: 0 ```

Price `Binary` Instrument

Use `price` to compute the price and sensitivities for the `Binary` instrument.

`[Price, outPR] = price(outPricer,BinaryOpt,["all"])`
```Price = 11.3017 ```
```outPR = priceresult with properties: Results: [1x7 table] PricerData: [1x1 struct] ```
`outPR.Results`
```ans=1×7 table Price Delta Gamma Lambda Rho Theta Vega ______ _____ _____ ______ _______ _______ ____ 11.302 0 0 0 -45.198 0.39582 0 ```

## Version History

Introduced in R2020b
{"ft_lang_label":"__label__en","ft_lang_prob":0.52127725,"math_prob":0.7096805,"size":18314,"snap":"2022-27-2022-33","text_gpt3_token_len":5072,"char_repetition_ratio":0.1434735,"word_repetition_ratio":0.38112688,"special_character_ratio":0.24314731,"punctuation_ratio":0.20284697,"nsfw_num_words":0,"has_unicode_error":false,"math_prob_llama3":0.9505423,"pos_list":[0],"im_url_duplicate_count":[null],"WARC_HEADER":"{\"WARC-Type\":\"response\",\"WARC-Date\":\"2022-06-25T04:16:43Z\",\"WARC-Record-ID\":\"<urn:uuid:86130fc7-821e-4bc2-b0c6-13fdf84152ac>\",\"Content-Length\":\"172019\",\"Content-Type\":\"application/http; msgtype=response\",\"WARC-Warcinfo-ID\":\"<urn:uuid:03bba13f-78c9-4433-b9bf-d88bc5364ab6>\",\"WARC-Concurrent-To\":\"<urn:uuid:841b0c1c-f00e-4dc3-a6b6-d4d299b9225c>\",\"WARC-IP-Address\":\"23.47.146.88\",\"WARC-Target-URI\":\"https://la.mathworks.com/help/fininst/finpricer.assetmontecarlo.html\",\"WARC-Payload-Digest\":\"sha1:XFWTG66JKFM35KNNCU3QHPE2JUNO2XDS\",\"WARC-Block-Digest\":\"sha1:NUMYCVOMCSCX66XMHX3UZYJANEHVB2YF\",\"WARC-Identified-Payload-Type\":\"text/html\",\"warc_filename\":\"/cc_download/warc_2022/CC-MAIN-2022-27/CC-MAIN-2022-27_segments_1656103034170.1_warc_CC-MAIN-20220625034751-20220625064751-00426.warc.gz\"}"}