Monte Carlo Paths Functions

In this section we document data structures and methods for path setup.

Simulation Context

DiffFusion.ContextType
struct Context
    alias::String
    numeraire::NumeraireEntry
    rates::Dict{String, RatesEntry}
    assets::Dict{String, AssetEntry}
    forward_indices::Dict{String, ForwardIndexEntry}
    future_indices::Dict{String, FutureIndexEntry}
    fixings::Dict{String, FixingEntry}
end

A Context represents a mapping from market references (keys) to model and term structure references (aliases).

Links are represented as key/alias pairs. market references are used in the specification of payoffs and products. Model and term structure references are used to set up models and model parameters.

In simple settings there can be a one-to-one mapping between market references and model/term structure references. However, more realistic settings benefit from an additional mapping. For example, discount factors for two (or more) market reference (say EUR ESTR and EUR Euribor) can be calculated from a single model (with model reference EUR) and two (or more) yield curves (with term structure reference ESTR and Euribor).

A Context

  • adds a layer of abstraction to disentangle models and products and

  • links models and term structures according to business logic.

DiffFusion.ContextEntryType
abstract type ContextEntry end

A ContextEntry represents a mapping from a context key to model aliases and term structure aliases.

We use the convention that keys are UPPERCASE strings. This aims at helping to distinguish between keys and alias.

DiffFusion.NumeraireEntryType
struct NumeraireEntry <: ContextEntry
    context_key::String
    model_alias::Union{String, Nothing}
    termstructure_dict::Dict{String,String}
end

A NumeraireEntry represents a link to an interest rate model and yield curves used for numeraire calculation.

We opt to allow for different yield curves in numeraire application. This should allow e.g. AMC methods wih trade-specific discounting.

An empty model alias (nothing) represents a deterministic model.

The termstructure_dict maps term structure keys to term structure aliases.

We use the convention that keys are UPPERCASE strings. This aims at helping to distinguish between keys and alias.

DiffFusion.numeraire_entryFunction
numeraire_entry(
    context_key::String,
    model_alias::Union{String, Nothing} = nothing,
    termstructure_dict::Union{AbstractDict, Nothing} = nothing,
    )

Simplify NumeraireEntry setup.

numeraire_entry(
    context_key::String,
    model_alias::Union{String, Nothing},
    termstructure_alias::String,
    )

Simplify NumeraireEntry setup.

DiffFusion.RatesEntryType
struct RatesEntry <: ContextEntry
    context_key::String
    model_alias::Union{String, Nothing}
    termstructure_dict::Dict{String,String}
end

A RatesEntry represents a link to an interest rate model and yield curves used for zero coupon bond calculation.

An empty model alias (nothing) represents a deterministic model.

The termstructure_dict maps term structure keys to term structure aliases.

We use the convention that keys are UPPERCASE strings. This aims at helping to distinguish between keys and alias.

DiffFusion.rates_entryFunction
rates_entry(
    context_key::String,
    model_alias::Union{String, Nothing} = nothing,
    termstructure_dict::Union{AbstractDict, Nothing} = nothing,
    )

Simplify RatesEntry setup.

ratesentry( contextkey::String, modelalias::Union{String, Nothing}, termstructurealias::String, )

Simplify RatesEntry setup.

DiffFusion.AssetEntryType
struct AssetEntry <: ContextEntry
    context_key::String
    asset_model_alias::Union{String, Nothing}
    domestic_model_alias::Union{String, Nothing}
    foreign_model_alias::Union{String, Nothing}
    asset_spot_alias::String
    domestic_termstructure_dict::Dict{String,String}
    foreign_termstructure_dict::Dict{String,String}
end

An AssetEntry represents a link to an asset model, two interest rate models and yield curves. This entry is used to calculate future simulated asset values.

We use the foreign currency analogy to represent tradeable assets.

An empty model alias (nothing) represents a deterministic model.

domestic_termstructure_dict and foreign_termstructure_dict map term structure keys to term structure aliases.

We use the convention that keys are UPPERCASE strings. This aims at helping to distinguish between keys and alias.

DiffFusion.asset_entryFunction
asset_entry(
    context_key::String,
    asset_model_alias::Union{String, Nothing} = nothing,
    domestic_model_alias::Union{String, Nothing} = nothing,
    foreign_model_alias::Union{String, Nothing} = nothing,
    asset_spot_alias::Union{String, Nothing} = nothing,
    domestic_termstructure_dict::Union{AbstractDict, Nothing} = nothing,
    foreign_termstructure_dict::Union{AbstractDict, Nothing} = nothing,
    )

Simplify AssetEntry setup.

asset_entry(
    context_key::String,
    asset_model_alias::Union{String, Nothing} = nothing,
    domestic_model_alias::Union{String, Nothing} = nothing,
    foreign_model_alias::Union{String, Nothing} = nothing,
    asset_spot_alias::Union{String, Nothing} = nothing,
    domestic_termstructure_alias::String,
    foreign_termstructure_alias::String,
    )

Simplify AssetEntry setup.

DiffFusion.ForwardIndexEntryType
struct ForwardIndexEntry <: ContextEntry
    context_key::String
    asset_model_alias::Union{String, Nothing}
    domestic_model_alias::Union{String, Nothing}
    foreign_model_alias::Union{String, Nothing}
    forward_index_alias::String
end

A ForwardIndexEntry represents a link to an asset model, two interest rate models and a forward index curves. This entry is used to calculate future simulated forward asset prices.

We use the foreign currency analogy to represent tradeable assets.

An empty model alias (nothing) represents a deterministic model.

forward_index_alias represents the link to the forward index curve.

We use the convention that keys are UPPERCASE strings. This aims at helping to distinguish between keys and alias.

DiffFusion.forward_index_entryFunction
forward_index_entry(
    context_key::String,
    asset_model_alias::Union{String, Nothing} = nothing,
    domestic_model_alias::Union{String, Nothing} = nothing,
    foreign_model_alias::Union{String, Nothing} = nothing,
    forward_index_alias::Union{String, Nothing} = nothing,
    )

Simplify ForwardIndexEntry setup.

DiffFusion.FutureIndexEntryType
struct FutureIndexEntry <: ContextEntry
    context_key::String
    future_model_alias::Union{String, Nothing}
    future_index_alias::String
end

A FutureIndexEntry represents a link to a Futures model and a future index curve. This entry is used to calculate future simulated Future prices.

Key proposition is that the Future price is a martingale in the corresponding domestic risk-neutral measure.

An empty model alias (nothing) represents a deterministic model.

future_index_alias represents the link to the Future index curve.

We use the convention that keys are UPPERCASE strings. This aims at helping to distinguish between keys and alias.

DiffFusion.future_index_entryFunction
future_index_entry(
    context_key::String,
    future_model_alias::Union{String, Nothing} = nothing,
    future_index_alias::String = nothing,
    )

Simplify FutureIndexEntry setup.

DiffFusion.FixingEntryType
struct FixingEntry <: ContextEntry
    context_key::String
    termstructure_alias::String
end

A FixingEntry represents a link to a parameter term structure used to obtain fixings for indices etc.

DiffFusion.fixing_entryFunction
fixing_entry(
    context_key::String,
    termstructure_alias::Union{String, Nothing} = nothing,
    )

Simplify FixingEntry setup.

DiffFusion.keyMethod
key(ce::ContextEntry)

Return the context key of a context entry.

DiffFusion.contextFunction
context(
    alias::String,
    num_entry::NumeraireEntry,
    rates_entries::Union{AbstractVector, Nothing} = nothing,
    asset_entries::Union{AbstractVector, Nothing} = nothing,
    forward_index_entries::Union{AbstractVector, Nothing} = nothing,
    future_index_entries::Union{AbstractVector, Nothing} = nothing,
    fixing_entries::Union{AbstractVector, Nothing} = nothing,
    )

Simplify Context setup.

DiffFusion.simple_contextFunction
simple_context(alias::String, alias_list::AbstractVector)

Generate a simple Context based on a list of currency aliases.

User must ensure that aliases can be referenced as normalised keys.

DiffFusion.deterministic_model_contextFunction
deterministic_model_context(alias::String, alias_list::AbstractVector)

Generate a simple Context for fully deterministic modelling based on a list of currency aliases.

User must ensure that aliases can be referenced as normalised keys.

DiffFusion.context_keysFunction
context_keys(key::String)

Parse the context entry key and term structure keys from an input key string.

We implement a simple syntax for input key strings:

context_key:[ts_key_1][-,+][ts_key_2]

Result is a tuple of the form

(context_key, ts_key_1, ts_key_2, [-,+])

Elements that are not found are returned as emptycontextkey value.

We apply normalisation of keys to mitigate risk of key errors by the user.

Simulated Paths

The concept of a path adds a layer of abstraction. On the one-hand side we have models and simulations. These objects are specified by the mathematical details of stochastic processes. On the other hand-side we have payoffs and products. These objects are specified by the business context.

A path is used to link business context and payoff evaluation to models and simulations.

DiffFusion.AbstractPathType
abstract type AbstractPath end

An AbstractPath specifies the interface for path implementations.

This aims at providing the flexibility to add other types of paths in the future.

DiffFusion.PathType
struct Path <: AbstractPath
    sim::Simulation
    ts_dict::Dict{String,<:Termstructure}
    state_alias_dict::Dict{String,Int}
    context::Context
    interpolation::PathInterpolation
end

A Path combines a model, simulated model states and term structures. The interface to market references is established by a valuation context.

Paths are used by payoffs to calculate simulated zero bonds, asset prices and further building blocks of financial instrument payoffs.

DiffFusion.pathFunction
path(
    sim::Simulation,
    ts_dict::Dict{String,<:Termstructure},
    cxt::Context,
    ip::PathInterpolation = NoPathInterpolation
    )

Create a Path object.

path(
    sim::Simulation,
    ts::Vector{Termstructure},
    cxt::Context,
    ip::PathInterpolation = NoPathInterpolation
    )

Create a Path object from a list of term structures.

DiffFusion.PathInterpolationType
@enum(
    PathInterpolation,
    NoPathInterpolation,
    LinearPathInterpolation,
)

PathInterpolation encodes how simulated states can be interpolates.

Base.lengthFunction
length(p::AbstractPath)

Return the number of realisations represented by the AbstractPath object.

We assume that model functions applied to an AbstractPath return a vector of length(p) where p is the number realisations.

length(p::Path)

Derive the number of realisations from the linked simulation.

DiffFusion.numeraireFunction
numeraire(p::AbstractPath, t::ModelTime, curve_key::String)

Calculate the numeraire in the domestic currency.

We allow for curve-specific numeraire calculation e.g. to allow for trade-specific discounting in AMC valuation.

numeraire(p::Path, t::ModelTime, curve_key::String)

Calculate the numeraire in the domestic currency.

We allow for curve-specific numeraire calculation e.g. to allow for trade-specific discounting in AMC valuation.

DiffFusion.bank_accountFunction
bank_account(p::AbstractPath, t::ModelTime, key::String)

Calculate a continuous compounded bank account value.

bank_account(p::Path, t::ModelTime, key::String)

Calculate a continuous compounded bank account value.

DiffFusion.zero_bondFunction
zero_bond(p::AbstractPath, t::ModelTime, T::ModelTime, key::String)

Calculate a zero coupon bond price.

zero_bond(p::Path, t::ModelTime, T::ModelTime, key::String)

Calculate a zero coupon bond price.

DiffFusion.zero_bondsFunction
zero_bonds(
    yts::YieldTermstructure,
    m::GaussianHjmModel,
    t::ModelTime,
    T::AbstractVector,
    SX::ModelState,
    )

Zero bond price reconstruction.

Returns a vector of length p where p is the number of paths in SX.

zero_bond(p::AbstractPath, t::ModelTime, T::ModelTime, key::String)

Calculate a zero coupon bond prices.

zero_bonds(p::Path, t::ModelTime, T::AbstractVector, key::String)

Calculate zero coupon bond prices.

DiffFusion.compounding_factorFunction
compounding_factor(p::AbstractPath, t::ModelTime, T1::ModelTime, T2::ModelTime, key::String)

Calculate a compounding factor P(t,T1) / P(t,T2).

compounding_factor(p::Path, t::ModelTime, T1::ModelTime, T2::ModelTime, key::String)

Calculate a compounding factor P(t,T1) / P(t,T2).

DiffFusion.assetFunction
asset(p::AbstractPath, t::ModelTime, key::String)

Calculate asset price.

asset(p::Path, t::ModelTime, key::String)

Calculate asset price.

DiffFusion.forward_assetFunction
forward_asset(p::AbstractPath, t::ModelTime, T::ModelTime, key::String)

Calculate forward asset price as expectation in T-forward measure.

forward_asset(p::Path, t::ModelTime, T::ModelTime, key::String)

Calculate forward asset price as expectation in T-forward measure, conditional on time-t.

DiffFusion.fixingFunction
fixing(p::AbstractPath, t::ModelTime, key::String)

Return a fixing from a term structure.

This is used to handle fixings for indices etc.

fixing(p::Path, t::ModelTime, key::String)

Return a fixing from a term structure.

DiffFusion.asset_convexity_adjustmentFunction
asset_convexity_adjustment(
    p::AbstractPath,
    t::ModelTime,
    T0::ModelTime,
    T1::ModelTime,
    T2::ModelTime,
    key::String
    )

Return the convexity adjustment for a YoY asset payoff.

DiffFusion.forward_indexFunction
forward_index(p::AbstractPath, t::ModelTime, T::ModelTime, key::String)

Expectation Et^T[ST] of a tradeable asset.

forward_index(p::Path, t::ModelTime, T::ModelTime, key::String)

Expectation Et^T[ST] of a tradeable asset.

DiffFusion.index_convexity_adjustmentFunction
index_convexity_adjustment(
    p::AbstractPath,
    t::ModelTime,
    T0::ModelTime,
    T1::ModelTime,
    T2::ModelTime,
    key::String
    )

Return the convexity adjustment for a YoY index payoff.

DiffFusion.future_indexFunction
future_index(p::AbstractPath, t::ModelTime, T::ModelTime, key::String)

Expectation E_t^Q[F(T,T)] of a Future index/price.

future_index(p::Path, t::ModelTime, T::ModelTime, key::String)

Expectation E_t^Q[F(T,T)] of a Future index/price.

Auxiliary methods:

DiffFusion.state_variableFunction
state_variable(sim::Simulation, t::ModelTime, ip::PathInterpolation)

Derive a state variable for a given observation time.

DiffFusion.discountFunction
discount(
    t::ModelTime,
    ts_dict::Dict{String,Termstructure},
    first_alias::String,
    second_alias::Union{String,Nothing} = nothing,
    operation::Union{String,Nothing} = nothing,
    )

Derive the discount factor for one or two of curve alias and a curve operation.