# 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.

`parameter_grid(m::CompositeModel)`

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

`parameter_grid(m::GaussianHjmModel)`

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

`parameter_grid(m::MarkovFutureModel)`

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

## 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 H*T to be state-dependent. If H*T 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.

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.

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.

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.

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.

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)`

.