Monte Carlo Contracts

A Python library to compose complex fincancial products from elementary contracts.

This is what it looks like (see Minimal.ipynb for the full example):

ko_option = Until(
    Stock("ABC Eqty") > 70,
    When(
        At(np.datetime64("2024-06-01")),
        Or(Stock("ABC Eqty") * One("USD") - 55 * One("USD"), Zero()),
    ),
)

evaluate(model, ko_option)
# 3.2316051920219797

This library employs ideas from How to Write a Financial Contract by S. L. Peyton Jones and J-M. Eber. However, the implementation is not based on functional programming but rather using an object oriented approach. Also, this implementation is tailored towards Monte Carlo based cashflow generation whereas the paper favours more general methods.

For an introduction to the concepts of composable contracts and usage instructions of this library, see the Introduction notebook.

Features

• Composition of financial contracts using elementary contracts Zero, One, Give, Scale, And, When, Cond, Anytime, Until, Delay and Exchange.
• Boolean and real valued observables (stochastic processes) to be referenced by contracts.
• Cashflow generation for composed contracts given simulation models on fixed dategrids.

Non-Features

• Financial products description language. This library provides classes to describe financial contracts at a low level; a high level description language could be translated into this low level language, but not the other way round.
• Lifecycle management. Capturing past lifecycle events of financial products such as call rights, knockouts or even fixings is left to a high level description. Doing it here would be very hard due to the nature of the acquisition date free variable and the lack of mandatory start / end dates in particular. Just think about a simple contract such as When(Stock("ABC") > 100, One("EUR")). Which fixings would you require? Up to which point would you perform model simulation?
• Pricing methods other than Monte Carlo Simulation. While composable contract representations do not force Monte Carlo methods, this library is designed exclusively for them. Supporting other methods would likely require a separation of contracts and the operations defined on them, e.g. by means of the visitor pattern. In How to Write a Financial Contract, Peyton Jones and Eber favour implementation in functional programming languages where this separation is achieved more naturally.

Examples

• Introduction
• Minimal
• Equity Options
• FX Options
• Working with Observables
• Cashflow types

Install

With Python 3.8+ on your machine, you can install monte-carlo-contracts using pip by running (ideally in a virtual environment)

pip install monte-carlo-contracts

which will automatically install the hard dependencies numpy and pandas.

For development or running the examples, you may instead want to run

pip install -e .

and then

pip install -r requirements_dev.txt

from the root directory of this repository.

Available Contracts and Observables

History

See HISTORY.md.

Credits

Main developer is luphord luphord@protonmail.com.

cookiecutter-pyscript was used as project template, but the repository structure has evolved considerably.

History

Some future version (not yet)

• ToDo: Observables Sum, Product, Maximum, Minimum, AndObservable and OrObservable accept more than two contracts to be combined
• ToDo: Add JSON (de)serialization for contracts and observables
• ToDo: Add Jupyter based treeview for contracts and observables
• ToDo: Implement cashflow generation for Or contract with future payment dates
• ToDo: Implement cashflow generation for Anytime contract (using Longstaff-Schwartz approach)
• ToDo: Implement get_model_requirements for all observables and contracts
• ToDo: Add a "test model" working for arbitrary underlyings to analyze contracts
• ToDO: fix Ho-Lee-Model
• ToDo: Use instances of a Currency class instead of strings to describe currencies
• ToDo: Add documentation about the concepts of contracts, observables and acquisition dates
• ToDo: Document financial products lifecycle aspects and their relationship to composable contracts
• ToDo: Add labels to contracts which are forwarded to simulated cashflows
• ToDo: Add documentation about models in Introduction notebook

0.10.0 (2022-04-03)

• Add new Exchange(currency, contract) contract
• Modify FX options examples to use Exchange for cash settlement
• Add observables and contracts overview to package doc, as well as to Introduction notebook

0.9.0 (2023-03-26)

• BREAKING CHANGE Convenvience methods generate_cashflows, generate_simple_cashflows, generate_simple_cashflows_in_currency, generate_simple_cashflows_in_numeraire_currency and evaluate that used to be defined on Model are now standalone functions that accept a model instance as first argument; i.e. instead of model.evaluate(contract) you now do evaluate(model, contract)
• BREAKING CHANGE Pricing model implementations (at the moment HoLee and simulate_equity_black_scholes_model) now need to be imported from mcc.pricing_models; stochastic processes (at the moment BrownianMotion and GeometricBrownianMotion) need to be imported from mcc.pricing_models.stochastic_processes
• Split mcc.py into multiple modules forming package mcc; imports will continue to work as before except for the exceptions listed above
• Split tests into multiple smaller modules with more specific focus
• Support Python 3.11
• Upgrade (dev) dependencies
• Development Status :: 3 - Alpha
• BREAKING CHANGE: Remove CLI stub (there was no real CLI functionality anyway)

0.8.0 (2023-03-20)

• BREAKING CHANGE: Contract now inherits from ResolvableContract instead of the other way round
• BREAKING CHANGE: And and Or contracts now accept more than two contracts to be combined; these have equivalent semantics to nested And or Or contracts and allow for flat structures to improve readability
• Add Delay(observableBool, contract) contract to delay cashflows to a later point in time (main use case is FX payment offset)
• First steps towards model requirements (yet incomplete)
• Fix cashflow generation for nested contracts

0.7.0 (2022-03-13)

• BREAKING CHANGE: ObservableFloat.simulate and ObservableBool.simulate now accept a DateIndex first_observation_idx as first argument, Contract classes will pass acquisition_idx; this allows observations to depend on the time of entering a contract, e.g. "maximum spot since acquisition"
• BREAKING CHANGE: FixedAfter fixes composed observable after (including) first_observation_idx, not from the beginning
• Add operator overloading for Contract classes, i.e. you can now do One("USD") - One("EUR") | 1.2 * One("GBP") instead of Or(And(One("USD"), Give(One("EUR"))), Scale(1.2, One("GBP")))
• Maximum and Minimum observables to observe the larger and smaller value of two observables at the same time on the same path
• RunningMax and RunningMin observables to observe running extreme values from first_observation_idx onwards
• Support Python 3.10
• Make use of type annotations added to numpy

0.6.0 (2022-03-04)

• BREAKING CHANGE: Make SimpleCashflows a pandas.DataFrame
• Run notebooks in automated tests using nbval
• Migrate from travis-ci to GitHub Actions
• Explicitly support Python 3.8 and 3.9
• Move history to HISTORY.md

0.5.0 (2020-11-08)

• BREAKING CHANGE: Add simulated_rates to Model (included in constructor); pass an empty dict for simulated_rates to adapt your code
• BREAKING CHANGE: BrownianMotion and GeometricBrownianMotion generalized to dynamic mean/drift; pass mu_t = lambda t: mu * t to adapt your code
• LinearRate observable supported by TermStructureModel
• First steps towards term structure models
• FixedAfter observable to keep an observable fixed after a condition is true
• Observables support arithmetic operations (binary +, -, *, /, ** and unary -) with other observables as well as constants (also right operators work)
• Working with Observables example notebook

0.4.0 (2020-11-04)

• Discounting (Model.discount)
• Evaluation (Model.evaluate)
• String representations for contracts and observables

0.3.0 (2020-10-23)

• Simulation of basic contract Until
• Currency conversion of IndexedCashflows
• Or contract supports multiple currencies
• ObservableFloat supports <, <=, > and >= operators with float or other ObservableFloat instances
• ObservableBool supports ~, & and | operators for combined conditions
• Equity Options and FX Options examples

0.2.0 (2020-10-11)

• Simulation of basic contracts Zero, One, Give, Scale, And, When and Cond
• Partial simulation of Or contract
• Float observables Stock and FX
• Boolean observables At
• SimulatedCashflows and model-bound IndexedCashflows to represent cashflows
• Basic Model allowing the generation of cashflows for the contracts above

0.1.0 (2020-09-22)

• Created using cookiecutter-pyscript