Common Model Functions

Abstract Model Types

DiffFusion.Model — Type

abstract type Model end

An abstract base model type. This type covers component models and hybrid composite models.

DiffFusion.ComponentModel — Type

abstract type ComponentModel <: Model end

An abstract component model type. This type implements the common interface of all component models.

State Variable

A model allows to simulate a stochastic process $\left(X_t\right)$. For a given $t$ the vector $X_t$ is represented by a ModelState.

DiffFusion.ModelState — Type

struct ModelState
    X::AbstractMatrix
    idx::Dict{String,Int}
end

A ModelState is a matrix of state variables decorated by a dictionary of alias strings and optional additional parameters.

It allows to decouple simulation of state variables and usage of state variables.

X is of size (n, p) where n represents the number of state aliases and p represents the number of paths. A matrix with a large number of paths is typically used when calling model functions for payoff evaluation.

A single realisation of risk factors is represented by an (n, 1) matrix. We use (n,1) matrix instead of (n,) vector to avoid size-dependent switches.

idx is a dictionary with n entries. Keys represent state state alias entries and values represent the corresponding positions in X.

params is a struct or dictionary that holds additional pre-calculated state-independent data which is used in subsequent Theta and Sigma calculations. This aims at avoiding duplicate calculations for state-dependent Theta and Sigma calculations. The params is supposed to be calculated by method simulation_parameters(...).

DiffFusion.model_state — Function

model_state(X::AbstractMatrix, idx::Dict{String,Int})

Create a ModelState object and make sure it is consistent.

model_state(X::AbstractMatrix, m::Model, params = nothing)

Create a model state for a given model.

DiffFusion.alias_dictionary — Function

alias_dictionary(alias_list)

Create an alias dictionary

Auxilliary Methods

DiffFusion.alias — Method

alias(m::Model)

Return the model's own alias. This is the default implementation.

DiffFusion.model_alias — Function

model_alias(m::Model)

Return the aliases modelled by a model.

Typically, this coincides with the model's own alias. For composite models this is a list of component model aliases.

model_alias(m::CompositeModel)

Return the aliases modelled by a model.

Typical this coincides with the model's own alias. For composite models this is a list of component model aliases.

DiffFusion.state_alias — Function

state_alias(m::Model)

Return a list of state alias strings that represent the model components.

DiffFusion.factor_alias — Function

factor_alias(m::Model)

Return a list of risk factor alias strings that represent the components of the multi-variate Brownian motion risk factors.

DiffFusion.parameter_grid — Function

parameter_grid(m::Model)

Return a list of times representing the (joint) grid points of piece-wise constant model parameters.

This method is intended to be used in conjunction with time-integration mehods that require smooth integrand functions.

parameter_grid(models::AbstractVector)

Return a list of times representing the (joint) grid points of piece-wise constant model parameters.

This method is intended to be used in conjunction with time-integration mehods that require smooth integrand functions.

parameter_grid(m::CevAssetModel)

Return a list of times representing the (joint) grid points of piece-wise constant model parameters.

This method is intended to be used in conjunction with time-integration mehods that require smooth integrand functions.

parameter_grid(m::LognormalAssetModel)

Return a list of times representing the (joint) grid points of piece-wise constant model parameters.

This method is intended to be used in conjunction with time-integration mehods that require smooth integrand functions.

parameter_grid(m::CompositeModel)

Return a list of times representing the (joint) grid points of piece-wise constant model parameters.

This method is intended to be used in conjunction with time-integration mehods that require smooth integrand functions.

parameter_grid(m::GaussianHjmModel)

Return a list of times representing the (joint) grid points of piece-wise constant model parameters.

This method is intended to be used in conjunction with time-integration mehods that require smooth integrand functions.

parameter_grid(m::MarkovFutureModel)

Return a list of times representing the (joint) grid points of piece-wise constant model parameters.

This method is intended to be used in conjunction with time-integration mehods that require smooth integrand functions.

Model Functions for Simulation

DiffFusion.Theta — Function

Theta(
    m::Model,
    s::ModelTime,
    t::ModelTime,
    X::Union{ModelState, Nothing} = nothing,
    )

Return the deterministic drift component for simulation over the time period [s, t]. If Theta is state-dependent a state vector X must be supplied. The method returns a vector of length(state_alias).

Theta(
    m::CevAssetModel,
    s::ModelTime,
    t::ModelTime,
    X::Union{ModelState, Nothing} = nothing,
    )

Return the deterministic drift component for simulation over the time period [s, t].

Theta(
    m::LognormalAssetModel,
    s::ModelTime,
    t::ModelTime,
    X::Union{ModelState, Nothing} = nothing,
    )

Return the deterministic drift component for simulation over the time period [s, t].

Theta(
    m::CoxIngersollRossModel,
    s::ModelTime,
    t::ModelTime,
    X::Union{ModelState, Nothing} = nothing,
    )

Return the deterministic drift component for simulation over the time period [s, t].

Theta(
    m::SimpleModel,
    s::ModelTime,
    t::ModelTime,
    X::Union{ModelState, Nothing} = nothing,
    )

Return the deterministic drift component for simulation over the time period [s, t].

Theta(
    m::DiagonalModel,
    s::ModelTime,
    t::ModelTime,
    X::ModelState,
    )

Return the deterministic drift component for simulation over the time period [s, t].

Theta(
    m::GaussianHjmModel,
    s::ModelTime,
    t::ModelTime,
    X::Union{ModelState, Nothing} = nothing,
    )

Return the deterministic drift component for simulation over the time period [s, t]. If Theta is state-dependent a state vector X must be supplied. The method returns a vector of length(state_alias).

Theta(
    m::MarkovFutureModel,
    s::ModelTime,
    t::ModelTime,
    X::Union{ModelState, Nothing} = nothing,
    )

Return the deterministic drift component for simulation over the time period [s, t]. If Theta is state-dependent a state vector X must be supplied. The method returns a vector of length(state_alias).

DiffFusion.H_T — Function

H_T(
    m::Model,
    s::ModelTime,
    t::ModelTime,
    X::Union{ModelState, Nothing} = nothing,
    )

Return the transposed of the convection matrix H for simulation over the time period [s, t]. If H is state-dependent a state vector X must be supplied. We use the transposed of H to

allow for efficient sparse CSC matrix insertion and
allow for efficient multiplication X' * H' = (H * X)'.

The state vector X may effectively be a subset of all states. To accommodate this, we use a dedicated list of state aliases state_alias_H for the result matrix. The method returns a (sparse) matrix of size (length(state_alias_H), length(state_alias)).

H_T(
    m::CevAssetModel,
    s::ModelTime,
    t::ModelTime,
    X::Union{ModelState, Nothing} = nothing,
    )

Return the transposed of the convection matrix H for simulation over the time period [s, t].

H_T(
    m::LognormalAssetModel,
    s::ModelTime,
    t::ModelTime,
    X::Union{ModelState, Nothing} = nothing,
    )

Return the transposed of the convection matrix H for simulation over the time period [s, t].

H_T(
    m::CoxIngersollRossModel,
    s::ModelTime,
    t::ModelTime,
    X::Union{ModelState, Nothing} = nothing,
    )

Return the transposed of the convection matrix H for simulation over the time period [s, t].

There is no benefit in allowing HT to be state-dependent. If HT would need to be state-dependent then it should be incorporated into Theta.

H_T(
    m::SimpleModel,
    s::ModelTime,
    t::ModelTime,
    X::Union{ModelState, Nothing} = nothing,
    )

Return the transposed of the convection matrix H for simulation over the time period [s, t].

H_T(
    m::DiagonalModel,
    s::ModelTime,
    t::ModelTime,
    X::Union{ModelState, Nothing} = nothing,
    )

Return the transposed of the convection matrix H for simulation over the time period [s, t].

H_T(
    m::GaussianHjmModel,
    s::ModelTime,
    t::ModelTime,
    X::Union{ModelState, Nothing} = nothing,
    )

Return the transposed of the convection matrix H for simulation over the time period [s, t].

H_T(
    m::MarkovFutureModel,
    s::ModelTime,
    t::ModelTime,
    X::Union{ModelState, Nothing} = nothing,
    )

Return the transposed of the convection matrix H for simulation over the time period [s, t].

DiffFusion.Sigma_T — Function

Sigma_T(
    m::Model,
    s::ModelTime,
    t::ModelTime,
    X::Union{ModelState, Nothing} = nothing,
    )

Return a matrix-valued function representing the volatility matrix function.

The signature of the resulting function is (u::ModelTime). Here, u represents the observation time.

The state vector is required if Sigma(u) depends on X_s.

The result of an evaluation of Sigma_T(...)(u) is a matrix of size (length(state_alias), length(factor_alias_Sigma)).

The Brownian motion relevant for a model may effectively be a subset of all Brownian motions. To accommodate this, we use a dedicated list of factor aliases factor_alias_Sigma for the size of the result matrix of a function evaluation.

The transposed '_T' is convention to simplify notation for covariance calculation.

Sigma_T(
    m::CevAssetModel,
    s::ModelTime,
    t::ModelTime,
    X::Union{ModelState, Nothing} = nothing,
    )

Return a matrix-valued function representing the volatility matrix function.

The signature of the resulting function is (u::ModelTime). Here, u represents the observation time.

Sigma_T(
    m::LognormalAssetModel,
    s::ModelTime,
    t::ModelTime,
    X::Union{ModelState, Nothing} = nothing,
    )

Return a matrix-valued function representing the volatility matrix function.

The signature of the resulting function is (u::ModelTime). Here, u represents the observation time.

Sigma_T(
    m::CoxIngersollRossModel,
    s::ModelTime,
    t::ModelTime,
    X::Union{ModelState, Nothing} = nothing,
    )

Return a matrix-valued function representing the volatility matrix function.

Sigma_T(
    m::SimpleModel,
    s::ModelTime,
    t::ModelTime,
    X::Union{ModelState, Nothing} = nothing,
    )

Return a matrix-valued function representing the volatility matrix function.

The signature of the resulting function is (u::ModelTime). Here, u represents the observation time.

Sigma_T(
    m::DiagonalModel,
    s::ModelTime,
    t::ModelTime,
    X::ModelState,
    )

Return a matrix-valued function representing the volatility matrix function.

The signature of the resulting function is (u::ModelTime). Here, u represents the observation time.

Sigma_T(
    m::GaussianHjmModel,
    s::ModelTime,
    t::ModelTime,
    X::Union{ModelState, Nothing} = nothing,
    )

Return a matrix-valued function representing the volatility matrix function.

Sigma_T(
    m::MarkovFutureModel,
    s::ModelTime,
    t::ModelTime,
    X::Union{ModelState, Nothing} = nothing,
    )

Return a matrix-valued function representing the volatility matrix function.

DiffFusion.state_dependent_Theta — Function

state_dependent_Theta(m::Model)

Return whether Theta requires a state vector input X.

state_dependent_Theta(m::CevAssetModel)

Return whether Theta requires a state vector input X.

state_dependent_Theta(m::LognormalAssetModel)

Return whether Theta requires a state vector input X.

state_dependent_Theta(m::CompositeModel)

Return whether Theta requires a state vector input X.

state_dependent_Theta(m::GaussianHjmModel)

Return whether Theta requires a state vector input X.

state_dependent_Theta(m::MarkovFutureModel)

Return whether Theta requires a state vector input X.

DiffFusion.state_dependent_H — Function

state_dependent_H(m::Model)

Return whether H requires a state vector input X.

state_dependent_H(m::CevAssetModel)

Return whether H requires a state vector input X.

state_dependent_H(m::LognormalAssetModel)

Return whether H requires a state vector input X.

state_dependent_H(m::CompositeModel)

Return whether H requires a state vector input X.

state_dependent_H(m::GaussianHjmModel)

Return whether H requires a state vector input X.

state_dependent_H(m::MarkovFutureModel)

Return whether H requires a state vector input X.

DiffFusion.state_dependent_Sigma — Function

state_dependent_Sigma(m::Model)

Return whether Sigma requires a state vector input X.

state_dependent_Sigma(m::CevAssetModel)

Return whether Sigma requires a state vector input X.

state_dependent_Sigma(m::LognormalAssetModel)

Return whether Sigma requires a state vector input X.

state_dependent_Sigma(m::CompositeModel)

Return whether Sigma requires a state vector input X.

state_dependent_Sigma(m::GaussianHjmModel)

Return whether Sigma requires a state vector input X.

state_dependent_Sigma(m::MarkovFutureModel)

Return whether Sigma requires a state vector input X.

DiffFusion.state_alias_H — Function

state_alias_H(m::Model)

Return a list of state alias strings required for (H * X) calculation.

state_alias_H(m::CevAssetModel)

Return a list of state alias strings required for (H * X) calculation.

state_alias_H(m::LognormalAssetModel)

Return a list of state alias strings required for (H * X) calculation.

state_alias_H(m::CompositeModel)

Return a list of state alias strings required for (H * X) calculation.

state_alias_H(m::GaussianHjmModel)

Return a list of state alias strings required for (H * X) calculation.

state_alias_H(m::MarkovFutureModel)

Return a list of state alias strings required for (H * X) calculation.

DiffFusion.factor_alias_Sigma — Function

factor_alias_Sigma(m::Model)

Return a list of factor alias strings required for (Sigma(u)' Gamma Sigma(u)) calculation.

factor_alias_Sigma(m::CevAssetModel)

Return a list of factor alias strings required for (Sigma(u)^T Gamma Sigma(u)) calculation.

factor_alias_Sigma(m::LognormalAssetModel)

Return a list of factor alias strings required for (Sigma(u)^T Gamma Sigma(u)) calculation.

factor_alias_Sigma(m::CompositeModel)

Return a list of factor alias strings required for (Sigma(u)^T Gamma Sigma(u)) calculation.

factor_alias_Sigma(m::GaussianHjmModel)

Return a list of factor alias strings required for (Sigma(u)^T Gamma Sigma(u)) calculation.

factor_alias_Sigma(m::MarkovFutureModel)

Return a list of factor alias strings required for (Sigma(u)^T Gamma Sigma(u)) calculation.

DiffFusion.covariance — Function

covariance(
    m::Model,
    ch::Union{CorrelationHolder, Nothing},
    s::ModelTime,
    t::ModelTime,
    X::Union{ModelState, Nothing} = nothing,
    )

Calculate the covariance matrix over a time interval.

DiffFusion.volatility_and_correlation — Function

volatility_and_correlation(
    m::Model,
    ch::Union{CorrelationHolder, Nothing},
    s::ModelTime,
    t::ModelTime,
    X::Union{ModelState, Nothing} = nothing,
    vol_eps::ModelValue = 1.0e-8,  # avoid division by zero
    )

Calculate the volatility vector and correlation matrix over a time interval.

DiffFusion.simulation_parameters — Function

simulation_parameters(
    m::Model,
    ch::Union{CorrelationHolder, Nothing},
    s::ModelTime,
    t::ModelTime,
    )

Pre-calculate parameters that are used in state-dependent Theta and Sigma calculation.

simulation_parameters(
    m::CevAssetModel,
    ch::Union{CorrelationHolder, Nothing},
    s::ModelTime,
    t::ModelTime,
    )

Pre-calculate parameters that are used in state-dependent Theta and Sigma calculation.

simulation_parameters(
    m::GaussianHjmModel,
    ch::Union{CorrelationHolder, Nothing},
    s::ModelTime,
    t::ModelTime,
    )

Pre-calculate parameters that are used in state-dependent Theta and Sigma calculation.

For LognormalAssetModel there are no valuations that should be cached.

simulation_parameters(
    m::CevAssetModel,
    ch::Union{CorrelationHolder, Nothing},
    s::ModelTime,
    t::ModelTime,
    )

Pre-calculate parameters that are used in state-dependent Theta and Sigma calculation.

simulation_parameters(
    m::DiagonalModel,
    ch::Union{CorrelationHolder, Nothing},
    s::ModelTime,
    t::ModelTime,
    )

Pre-calculate parameters that are used in state-dependent Theta and Sigma calculation.

simulation_parameters(
    m::GaussianHjmModel,
    ch::Union{CorrelationHolder, Nothing},
    s::ModelTime,
    t::ModelTime,
    )

Pre-calculate parameters that are used in state-dependent Theta and Sigma calculation.

For GaussianHjmModel there are no valuations that should be cached.

DiffFusion.diagonal_volatility — Function

diagonal_volatility(
    m::Model,
    s::ModelTime,
    t::ModelTime,
    X::ModelState,
    )

Calculate the path-dependent volatilities for a given model.

X is supposed to hold a state matrix of size (n, p). Here, n is length(state_alias(m)) and p is the number of paths.

The method returns a matrix of size (n, p).

diagonal_volatility(
    m::CevAssetModel,
    s::ModelTime,
    t::ModelTime,
    X::ModelState,
    )

Calculate the path-dependent volatilities for CevAssetModel.

X is supposed to hold a state matrix of size (n, p). Here, n is length(state_alias(m)) and p is the number of paths.

The method returns a matrix of size (n, p).

diagonal_volatility(
    m::CoxIngersollRossModel,
    s::ModelTime,
    t::ModelTime,
    X::ModelState,
    )

Calculate the path-dependent volatilities for CoxIngersollRossModel.

X is supposed to hold a state matrix of size (n, p). Here, n is length(state_alias(m)) and p is the number of paths.

The method returns a matrix of size (n, p).

diagonal_volatility(
    m::DiagonalModel,
    s::ModelTime,
    t::ModelTime,
    X::ModelState,
    )

Calculate the path-dependent volatilities for a given model.

X is supposed to hold a state matrix of size (n, p). Here, n is length(state_alias(m)) and p is the number of paths.

The method returns a matrix of size (n, p).