# Monte Carlo Paths Functions

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

## Simulation Context

`DiffFusion.Context`

— Type```
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.ContextEntry`

— Type`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.NumeraireEntry`

— Type```
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_entry`

— Function```
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.RatesEntry`

— Type```
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_entry`

— Function```
rates_entry(
context_key::String,
model_alias::Union{String, Nothing} = nothing,
termstructure_dict::Union{AbstractDict, Nothing} = nothing,
)
```

Simplify `RatesEntry`

setup.

rates*entry( context*key::String, model*alias::Union{String, Nothing}, termstructure*alias::String, )

Simplify `RatesEntry`

setup.

`DiffFusion.AssetEntry`

— Type```
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.

`DiffFusion.asset_entry`

— Function```
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.ForwardIndexEntry`

— Type```
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.

`DiffFusion.forward_index_entry`

— Function```
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.FutureIndexEntry`

— Type```
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.

`DiffFusion.future_index_entry`

— Function```
future_index_entry(
context_key::String,
future_model_alias::Union{String, Nothing} = nothing,
future_index_alias::String = nothing,
)
```

Simplify `FutureIndexEntry`

setup.

`DiffFusion.FixingEntry`

— Type```
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_entry`

— Function```
fixing_entry(
context_key::String,
termstructure_alias::Union{String, Nothing} = nothing,
)
```

Simplify `FixingEntry`

setup.

`DiffFusion.key`

— Method`key(ce::ContextEntry)`

Return the context key of a context entry.

`DiffFusion.context`

— Function```
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_context`

— Function`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_context`

— Function`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_keys`

— Function`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 empty*context*key 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.AbstractPath`

— Type`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.Path`

— Type```
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.path`

— Function```
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.PathInterpolation`

— Type```
@enum(
PathInterpolation,
NoPathInterpolation,
LinearPathInterpolation,
)
```

PathInterpolation encodes how simulated states can be interpolates.

`Base.length`

— Function`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.numeraire`

— Function`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_account`

— Function`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_bond`

— Function`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_bonds`

— Function```
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_factor`

— Function`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.asset`

— Function`asset(p::AbstractPath, t::ModelTime, key::String)`

Calculate asset price.

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

Calculate asset price.

`DiffFusion.forward_asset`

— Function`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.fixing`

— Function`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_adjustment`

— Function```
asset_convexity_adjustment(
p::AbstractPath,
t::ModelTime,
T0::ModelTime,
T1::ModelTime,
T2::ModelTime,
key::String
)
```

Return the convexity adjustment for a YoY asset payoff.

```
asset_convexity_adjustment(
p::Path,
t::ModelTime,
T0::ModelTime,
T1::ModelTime,
T2::ModelTime,
key::String
)
```

Return the convexity adjustment for a YoY asset payoff.

`DiffFusion.forward_index`

— Function`forward_index(p::AbstractPath, t::ModelTime, T::ModelTime, key::String)`

Expectation E*t^T[S*T] of a tradeable asset.

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

Expectation E*t^T[S*T] of a tradeable asset.

`DiffFusion.index_convexity_adjustment`

— Function```
index_convexity_adjustment(
p::AbstractPath,
t::ModelTime,
T0::ModelTime,
T1::ModelTime,
T2::ModelTime,
key::String
)
```

Return the convexity adjustment for a YoY index payoff.

```
index_convexity_adjustment(
p::Path,
t::ModelTime,
T0::ModelTime,
T1::ModelTime,
T2::ModelTime,
key::String
)
```

Return the convexity adjustment for a YoY index payoff.

`DiffFusion.future_index`

— Function`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_variable`

— Function`state_variable(sim::Simulation, t::ModelTime, ip::PathInterpolation)`

Derive a state variable for a given observation time.

`DiffFusion.discount`

— Function```
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.