## Overview
Storage valuation and optimisation model implemented using the Longstaff Schwartz Least Squares
Monte Carlo technique.
[A multi-factor model](https://github.com/cmdty/core/blob/master/docs/multifactor_price_process/multifactor_price_process.pdf)
is used to for the commodity price dynamics. This allows for a complex
volatility and correlations structure between forward rates as well as calibration to option implied volatilities. Users can also provide their
own spot price simulations to the model, should another model of price dynamics be desired.
The models can be used for any commodity, although are most suitable for natural gas
storage valuation and optimisation.
Calculations take into account many of the complex features of physical storage including:
* Inventory dependent injection and withdrawal rates, otherwise known as ratchets. For physical storage it is often the case that maximum withdrawal rates will increase, and injection rates will decrease as the storage inventory increases. For natural gas, this due to the increased pressure within the storage cavern.
* Time dependent injection and withdrawal rates, including the ability to add outages when no injection or withdrawal is allowed.
* Forced injection/withdrawal, as can be enforced by regulatory or physical constraints.
* Commodity consumed on injection/withdrawal, for example where natural gas is consumed by the motors that power injection into storage.
* Time dependent minimum and maximum inventory, necessary if different notional volumes of a storage facility are leased for different consecutive years.
* Optional time and inventory dependent loss of commodity in storage. For example this assumption is necessary for electricity storage which isn't 100% efficient.
* Ability to constrain the storage to be empty at the end of it's life, or specify a value of commodity inventory left in storage.
## Examples
### Creating the Storage Object
The first step is to create an instance of the class CmdtyStorage which
represents the storage facility. See below for two examples of this. The first example creates
a simple storage object with constant constraints. The second examples creates a storage
object with inventory-varying injection and withdrawal rates, commonly known as "ratchets".
For full details on how to create CmdtyStorage instances see the Jupyter notebook
[creating_storage_instances.ipynb](https://github.com/cmdty/storage/blob/master/samples/python/creating_storage_instances.ipynb).
```python
from cmdty_storage import CmdtyStorage, RatchetInterp
import pandas as pd
storage_simple = CmdtyStorage(
freq='D',
storage_start = '2021-04-01',
storage_end = '2022-04-01',
injection_cost = 0.01,
withdrawal_cost = 0.025,
min_inventory = 0.0,
max_inventory = 1500.0,
max_injection_rate = 25.5,
max_withdrawal_rate = 30.9
)
storage_with_ratchets = CmdtyStorage(
freq='D',
storage_start = '2021-04-01',
storage_end = '2022-04-01',
injection_cost = 0.01,
withdrawal_cost = 0.025,
ratchets= [
('2021-04-01', # For days after 2021-04-01 (inclusive) until 2022-10-01 (exclusive):
[
(0.0, -150.0, 250.0), # At min inventory of zero, max withdrawal of 150, max injection 250
(2000.0, -200.0, 175.0), # At inventory of 2000, max withdrawal of 200, max injection 175
(5000.0, -260.0, 155.0), # At inventory of 5000, max withdrawal of 260, max injection 155
(7000.0, -275.0, 132.0), # At max inventory of 7000, max withdrawal of 275, max injection 132
]),
('2022-10-01', # For days after 2022-10-01 (inclusive):
[
(0.0, -130.0, 260.0), # At min inventory of zero, max withdrawal of 130, max injection 260
(2000.0, -190.0, 190.0), # At inventory of 2000, max withdrawal of 190, max injection 190
(5000.0, -230.0, 165.0), # At inventory of 5000, max withdrawal of 230, max injection 165
(7000.0, -245.0, 148.0), # At max inventory of 7000, max withdrawal of 245, max injection 148
]),
],
ratchet_interp = RatchetInterp.LINEAR
)
```
### Storage Optimisation Using LSMC
The following is an example of valuing the storage using LSMC and a [three-factor seasonal model](https://github.com/cmdty/core/blob/master/docs/three_factor_seasonal_model/three_factor_seasonal_model.pdf) of price dynamics.
```python
from cmdty_storage import three_factor_seasonal_value
# Creating the Inputs
monthly_index = pd.period_range(start='2021-04-25', periods=25, freq='M')
monthly_fwd_prices = [16.61, 15.68, 15.42, 15.31, 15.27, 15.13, 15.96, 17.22, 17.32, 17.66,
17.59, 16.81, 15.36, 14.49, 14.28, 14.25, 14.32, 14.33, 15.30, 16.58,
16.64, 16.79, 16.64, 15.90, 14.63]
fwd_curve = pd.Series(data=monthly_fwd_prices, index=monthly_index).resample('D').fillna('pad')
rates = [0.005, 0.006, 0.0072, 0.0087, 0.0101, 0.0115, 0.0126]
rates_pillars = pd.PeriodIndex(freq='D', data=['2021-04-25', '2021-06-01', '2021-08-01', '2021-12-01', '2022-04-01',
'2022-12-01', '2023-12-01'])
ir_curve = pd.Series(data=rates, index=rates_pillars).resample('D').asfreq('D').interpolate(method='linear')
def settlement_rule(delivery_date):
return delivery_date.asfreq('M').asfreq('D', 'end') + 20
# Call the three-factor seasonal model
three_factor_results = three_factor_seasonal_value(
cmdty_storage = storage_with_ratchets,
val_date = '2021-04-25',
inventory = 1500.0,
fwd_curve = fwd_curve,
interest_rates = ir_curve,
settlement_rule = settlement_rule,
num_sims = 2000,
seed = 12,
spot_mean_reversion = 91.0,
spot_vol = 0.85,
long_term_vol = 0.30,
seasonal_vol = 0.19,
basis_funcs = '1 + x_st + x_sw + x_lt + s + x_st**2 + x_sw**2 + x_lt**2 + s**2 + s * x_st',
discount_deltas = True
)
# Inspect the NPV results
print('Full NPV:\t{0:,.0f}'.format(three_factor_results.npv))
print('Intrinsic NPV: \t{0:,.0f}'.format(three_factor_results.intrinsic_npv))
print('Extrinsic NPV: \t{0:,.0f}'.format(three_factor_results.extrinsic_npv))
```
Prints the following.
```
Full NPV: 78,175
Intrinsic NPV: 40,976
Extrinsic NPV: 37,199
```
For comprehensive documentation of invoking the LSMC model, using both the
three-factor price model, a more general multi-factor model, or using
externally provided simulations, see the notebook
[multifactor_storage.ipynb](https://github.com/cmdty/storage/blob/master/samples/python/multifactor_storage.ipynb).
### Inspecting Valuation Results
The object returned from the calling `three_factor_seasonal_value` has many properties containing useful information. The code below give examples of a
few of these. See the **Valuation Results** section of [multifactor_storage.ipynb](https://github.com/cmdty/storage/blob/master/samples/python/multifactor_storage.ipynb) for more details.
Plotting the daily Deltas and projected inventory:
```python
%matplotlib inline
ax_deltas = three_factor_results.deltas.plot(title='Daily Deltas vs Projected Inventory', legend=True, label='Delta')
ax_deltas.set_ylabel('Delta')
inventory_projection = three_factor_results.expected_profile['inventory']
ax_inventory = inventory_projection.plot(secondary_y=True, legend=True, ax=ax_deltas, label='Expected Inventory')
h1, l1 = ax_deltas.get_legend_handles_labels()
h2, l2 = ax_inventory.get_legend_handles_labels()
ax_inventory.set_ylabel('Inventory')
ax_deltas.legend(h1+h2, l1+l2, loc=1)
```
The **trigger_prices** property contains information on "trigger prices" which are approximate spot price levels at which the exercise decision changes.
* The withdraw trigger price is the spot price level, at time of nomination, above which the optimal decision will change to withdraw.
* The inject trigger price is the spot price level, at time of nomination, below which the optimal decision will change to inject.
Plotting the trigger prices versus the forward curve:
```python
%matplotlib inline
ax_triggers = three_factor_results.trigger_prices['inject_trigger_price'].plot(
title='Trigger Prices vs Forward Curve', legend=True)
three_factor_results.trigger_prices['withdraw_trigger_price'].plot(legend=True)
fwd_curve['2021-04-25' : '2022-04-01'].plot(legend=True)
ax_triggers.legend(['Inject Trigger Price', 'Withdraw Trigger', 'Forward Curve'])
```
## Example GUI
An example GUI notebook created using Jupyter Widgets can be found
[here](https://github.com/cmdty/storage/blob/master/samples/python/multi_factor_gui.ipynb).
## .NET Dependency For non-Windows OS
As Cmdty.Storage is mostly written in C# it requires the .NET runtime to be installed to execute.
The dlls are targetting [.NET Standard 2.0](https://learn.microsoft.com/en-us/dotnet/standard/net-standard?tabs=net-standard-2-0) which is compatible with .NET Framework versions 4.6.1
upwards. A version of .NET Framework meeting this restriction should be installed on most
Windows computers, so nothing extra is required.
If running on a non-Windows OS then the runtime of a cross-platform type of .NET will be
required. .NET Standard is compatible with .NET and Mono, with the former being recommended.
For the Python package, by default it will try to use .NET, and if this isn't installed it will
try Mono. See the Microsoft documentation on installing the .NET runtime on [Linux](https://learn.microsoft.com/en-us/dotnet/core/install/linux)
and on [macOS](https://learn.microsoft.com/en-us/dotnet/core/install/macos).
## Workaround for Crashing Python Interpreter
In some environments the valuation calculations have been observed to crash the Python
interpretter. This is due to the use of Intel MKL, which itself loads libiomp5md.dll, the OpenMP threading library.
The crash occurs during the initialisation of libiomp5md.dll, due to this dll already having
been initialised, presumably by Intel MKL usage from NumPy. The below code is a workaround to fix to fix this by setting the KMP_DUPLICATE_LIB_OK environment variable to true.
```python
import os
os.environ['KMP_DUPLICATE_LIB_OK']='True'
```
The code should be run at the start of any notebook or program.
## Curve Construction Package
To construct the storage model forward curve inputs see the [curves package](https://pypi.org/project/curves/)
which provides tools for building commodity forward, swaps, and futures curves.
Raw data
{
"_id": null,
"home_page": "https://github.com/cmdty/storage",
"name": "cmdty-storage",
"maintainer": null,
"docs_url": null,
"requires_python": "<3.13,>=3.7",
"maintainer_email": null,
"keywords": "commodities trading storage oil gas power quantitative finance",
"author": "Jake Fowler",
"author_email": "jake@cmdty.co.uk",
"download_url": null,
"platform": null,
"description": "## Overview\r\nStorage valuation and optimisation model implemented using the Longstaff Schwartz Least Squares \r\nMonte Carlo technique.\r\n[A multi-factor model](https://github.com/cmdty/core/blob/master/docs/multifactor_price_process/multifactor_price_process.pdf) \r\nis used to for the commodity price dynamics. This allows for a complex \r\nvolatility and correlations structure between forward rates as well as calibration to option implied volatilities. Users can also provide their\r\nown spot price simulations to the model, should another model of price dynamics be desired.\r\n\r\nThe models can be used for any commodity, although are most suitable for natural gas \r\nstorage valuation and optimisation.\r\n\r\nCalculations take into account many of the complex features of physical storage including:\r\n* Inventory dependent injection and withdrawal rates, otherwise known as ratchets. For physical storage it is often the case that maximum withdrawal rates will increase, and injection rates will decrease as the storage inventory increases. For natural gas, this due to the increased pressure within the storage cavern.\r\n* Time dependent injection and withdrawal rates, including the ability to add outages when no injection or withdrawal is allowed.\r\n* Forced injection/withdrawal, as can be enforced by regulatory or physical constraints.\r\n* Commodity consumed on injection/withdrawal, for example where natural gas is consumed by the motors that power injection into storage.\r\n* Time dependent minimum and maximum inventory, necessary if different notional volumes of a storage facility are leased for different consecutive years.\r\n* Optional time and inventory dependent loss of commodity in storage. For example this assumption is necessary for electricity storage which isn't 100% efficient.\r\n* Ability to constrain the storage to be empty at the end of it's life, or specify a value of commodity inventory left in storage.\r\n\r\n\r\n## Examples\r\n### Creating the Storage Object\r\nThe first step is to create an instance of the class CmdtyStorage which\r\nrepresents the storage facility. See below for two examples of this. The first example creates\r\na simple storage object with constant constraints. The second examples creates a storage\r\nobject with inventory-varying injection and withdrawal rates, commonly known as \"ratchets\".\r\n\r\nFor full details on how to create CmdtyStorage instances see the Jupyter notebook \r\n[creating_storage_instances.ipynb](https://github.com/cmdty/storage/blob/master/samples/python/creating_storage_instances.ipynb).\r\n\r\n```python\r\nfrom cmdty_storage import CmdtyStorage, RatchetInterp\r\nimport pandas as pd\r\nstorage_simple = CmdtyStorage(\r\n freq='D',\r\n storage_start = '2021-04-01',\r\n storage_end = '2022-04-01',\r\n injection_cost = 0.01,\r\n withdrawal_cost = 0.025,\r\n min_inventory = 0.0,\r\n max_inventory = 1500.0,\r\n max_injection_rate = 25.5,\r\n max_withdrawal_rate = 30.9\r\n)\r\n\r\nstorage_with_ratchets = CmdtyStorage(\r\n freq='D',\r\n storage_start = '2021-04-01',\r\n storage_end = '2022-04-01',\r\n injection_cost = 0.01,\r\n withdrawal_cost = 0.025,\r\n ratchets= [\r\n ('2021-04-01', # For days after 2021-04-01 (inclusive) until 2022-10-01 (exclusive):\r\n [\r\n (0.0, -150.0, 250.0), # At min inventory of zero, max withdrawal of 150, max injection 250\r\n (2000.0, -200.0, 175.0), # At inventory of 2000, max withdrawal of 200, max injection 175\r\n (5000.0, -260.0, 155.0), # At inventory of 5000, max withdrawal of 260, max injection 155\r\n (7000.0, -275.0, 132.0), # At max inventory of 7000, max withdrawal of 275, max injection 132\r\n ]),\r\n ('2022-10-01', # For days after 2022-10-01 (inclusive):\r\n [\r\n (0.0, -130.0, 260.0), # At min inventory of zero, max withdrawal of 130, max injection 260\r\n (2000.0, -190.0, 190.0), # At inventory of 2000, max withdrawal of 190, max injection 190\r\n (5000.0, -230.0, 165.0), # At inventory of 5000, max withdrawal of 230, max injection 165\r\n (7000.0, -245.0, 148.0), # At max inventory of 7000, max withdrawal of 245, max injection 148\r\n ]),\r\n ],\r\n ratchet_interp = RatchetInterp.LINEAR\r\n)\r\n\r\n```\r\n\r\n### Storage Optimisation Using LSMC\r\nThe following is an example of valuing the storage using LSMC and a [three-factor seasonal model](https://github.com/cmdty/core/blob/master/docs/three_factor_seasonal_model/three_factor_seasonal_model.pdf) of price dynamics.\r\n\r\n```python\r\nfrom cmdty_storage import three_factor_seasonal_value\r\n\r\n# Creating the Inputs\r\nmonthly_index = pd.period_range(start='2021-04-25', periods=25, freq='M')\r\nmonthly_fwd_prices = [16.61, 15.68, 15.42, 15.31, 15.27, 15.13, 15.96, 17.22, 17.32, 17.66, \r\n 17.59, 16.81, 15.36, 14.49, 14.28, 14.25, 14.32, 14.33, 15.30, 16.58, \r\n 16.64, 16.79, 16.64, 15.90, 14.63]\r\nfwd_curve = pd.Series(data=monthly_fwd_prices, index=monthly_index).resample('D').fillna('pad')\r\n\r\nrates = [0.005, 0.006, 0.0072, 0.0087, 0.0101, 0.0115, 0.0126]\r\nrates_pillars = pd.PeriodIndex(freq='D', data=['2021-04-25', '2021-06-01', '2021-08-01', '2021-12-01', '2022-04-01', \r\n '2022-12-01', '2023-12-01'])\r\nir_curve = pd.Series(data=rates, index=rates_pillars).resample('D').asfreq('D').interpolate(method='linear')\r\n\r\ndef settlement_rule(delivery_date):\r\n return delivery_date.asfreq('M').asfreq('D', 'end') + 20\r\n\r\n# Call the three-factor seasonal model\r\nthree_factor_results = three_factor_seasonal_value(\r\n cmdty_storage = storage_with_ratchets,\r\n val_date = '2021-04-25',\r\n inventory = 1500.0,\r\n fwd_curve = fwd_curve,\r\n interest_rates = ir_curve,\r\n settlement_rule = settlement_rule,\r\n num_sims = 2000,\r\n seed = 12,\r\n spot_mean_reversion = 91.0,\r\n spot_vol = 0.85,\r\n long_term_vol = 0.30,\r\n seasonal_vol = 0.19,\r\n basis_funcs = '1 + x_st + x_sw + x_lt + s + x_st**2 + x_sw**2 + x_lt**2 + s**2 + s * x_st',\r\n discount_deltas = True\r\n)\r\n\r\n# Inspect the NPV results\r\nprint('Full NPV:\\t{0:,.0f}'.format(three_factor_results.npv))\r\nprint('Intrinsic NPV: \\t{0:,.0f}'.format(three_factor_results.intrinsic_npv))\r\nprint('Extrinsic NPV: \\t{0:,.0f}'.format(three_factor_results.extrinsic_npv))\r\n```\r\nPrints the following.\r\n\r\n```\r\nFull NPV:\t78,175\r\nIntrinsic NPV: \t40,976\r\nExtrinsic NPV: \t37,199\r\n```\r\nFor comprehensive documentation of invoking the LSMC model, using both the \r\nthree-factor price model, a more general multi-factor model, or using \r\nexternally provided simulations, see the notebook \r\n[multifactor_storage.ipynb](https://github.com/cmdty/storage/blob/master/samples/python/multifactor_storage.ipynb).\r\n\r\n### Inspecting Valuation Results\r\nThe object returned from the calling `three_factor_seasonal_value` has many properties containing useful information. The code below give examples of a\r\nfew of these. See the **Valuation Results** section of [multifactor_storage.ipynb](https://github.com/cmdty/storage/blob/master/samples/python/multifactor_storage.ipynb) for more details.\r\n\r\nPlotting the daily Deltas and projected inventory:\r\n```python\r\n%matplotlib inline\r\nax_deltas = three_factor_results.deltas.plot(title='Daily Deltas vs Projected Inventory', legend=True, label='Delta')\r\nax_deltas.set_ylabel('Delta')\r\ninventory_projection = three_factor_results.expected_profile['inventory']\r\nax_inventory = inventory_projection.plot(secondary_y=True, legend=True, ax=ax_deltas, label='Expected Inventory')\r\nh1, l1 = ax_deltas.get_legend_handles_labels()\r\nh2, l2 = ax_inventory.get_legend_handles_labels()\r\nax_inventory.set_ylabel('Inventory')\r\nax_deltas.legend(h1+h2, l1+l2, loc=1)\r\n```\r\n\r\n\r\n\r\nThe **trigger_prices** property contains information on \"trigger prices\" which are approximate spot price levels at which the exercise decision changes.\r\n* The withdraw trigger price is the spot price level, at time of nomination, above which the optimal decision will change to withdraw.\r\n* The inject trigger price is the spot price level, at time of nomination, below which the optimal decision will change to inject.\r\n\r\nPlotting the trigger prices versus the forward curve:\r\n```python\r\n%matplotlib inline\r\nax_triggers = three_factor_results.trigger_prices['inject_trigger_price'].plot(\r\n title='Trigger Prices vs Forward Curve', legend=True)\r\nthree_factor_results.trigger_prices['withdraw_trigger_price'].plot(legend=True)\r\nfwd_curve['2021-04-25' : '2022-04-01'].plot(legend=True)\r\nax_triggers.legend(['Inject Trigger Price', 'Withdraw Trigger', 'Forward Curve'])\r\n```\r\n\r\n\r\n## Example GUI\r\nAn example GUI notebook created using Jupyter Widgets can be found \r\n[here](https://github.com/cmdty/storage/blob/master/samples/python/multi_factor_gui.ipynb).\r\n\r\n\r\n\r\n## .NET Dependency For non-Windows OS\r\nAs Cmdty.Storage is mostly written in C# it requires the .NET runtime to be installed to execute.\r\nThe dlls are targetting [.NET Standard 2.0](https://learn.microsoft.com/en-us/dotnet/standard/net-standard?tabs=net-standard-2-0) which is compatible with .NET Framework versions 4.6.1\r\nupwards. A version of .NET Framework meeting this restriction should be installed on most\r\nWindows computers, so nothing extra is required.\r\n\r\nIf running on a non-Windows OS then the runtime of a cross-platform type of .NET will be \r\nrequired. .NET Standard is compatible with .NET and Mono, with the former being recommended.\r\nFor the Python package, by default it will try to use .NET, and if this isn't installed it will\r\ntry Mono. See the Microsoft documentation on installing the .NET runtime on [Linux](https://learn.microsoft.com/en-us/dotnet/core/install/linux)\r\nand on [macOS](https://learn.microsoft.com/en-us/dotnet/core/install/macos).\r\n\r\n## Workaround for Crashing Python Interpreter\r\nIn some environments the valuation calculations have been observed to crash the Python \r\ninterpretter. This is due to the use of Intel MKL, which itself loads libiomp5md.dll, the OpenMP threading library.\r\nThe crash occurs during the initialisation of libiomp5md.dll, due to this dll already having\r\nbeen initialised, presumably by Intel MKL usage from NumPy. The below code is a workaround to fix to fix this by setting the KMP_DUPLICATE_LIB_OK environment variable to true.\r\n\r\n```python\r\nimport os\r\nos.environ['KMP_DUPLICATE_LIB_OK']='True'\r\n```\r\n\r\nThe code should be run at the start of any notebook or program.\r\n\r\n## Curve Construction Package\r\nTo construct the storage model forward curve inputs see the [curves package](https://pypi.org/project/curves/)\r\nwhich provides tools for building commodity forward, swaps, and futures curves.\r\n\r\n",
"bugtrack_url": null,
"license": null,
"summary": "Multi-Factor Least Squares Monte Carlo energy storage valuation model.",
"version": "1.6.0",
"project_urls": {
"Homepage": "https://github.com/cmdty/storage"
},
"split_keywords": [
"commodities",
"trading",
"storage",
"oil",
"gas",
"power",
"quantitative",
"finance"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "25f1378420cfe3ee7af7e8751e94dca5c1b6bd2e13d2230585fbf5f8ea187ac5",
"md5": "1dc6d1376fa21ae994dc5991f7c0552e",
"sha256": "0d03d70ebe8a211f02d95425ea7d6d68b1a8a78eb7fb256eca13098f338ed3ca"
},
"downloads": -1,
"filename": "cmdty_storage-1.6.0-py3-none-any.whl",
"has_sig": false,
"md5_digest": "1dc6d1376fa21ae994dc5991f7c0552e",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": "<3.13,>=3.7",
"size": 62236123,
"upload_time": "2024-06-16T21:32:41",
"upload_time_iso_8601": "2024-06-16T21:32:41.357327Z",
"url": "https://files.pythonhosted.org/packages/25/f1/378420cfe3ee7af7e8751e94dca5c1b6bd2e13d2230585fbf5f8ea187ac5/cmdty_storage-1.6.0-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2024-06-16 21:32:41",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "cmdty",
"github_project": "storage",
"travis_ci": false,
"coveralls": false,
"github_actions": false,
"lcname": "cmdty-storage"
}
JSON
