Interest Rates Models

abstract type SeparableHjmModel <: ComponentModel end

An abstract type for separable HJM models.

This type covers common functions for Gaussian and Quasi-Gaussian models.

The SeparableHjmModel is supposed to hold a constant vector-valued ParameterTermstructure for mean reversion chi and benchmark rate times delta.

struct GaussianHjmModel <: SeparableHjmModel
    alias::String
    delta::ParameterTermstructure
    chi::ParameterTermstructure
    sigma_T::GaussianHjmModelVolatility
    y::AbstractArray
    state_alias::AbstractVector
    factor_alias::AbstractVector
    correlation_holder::Union{CorrelationHolder, Nothing}
    quanto_model::Union{AssetModel, Nothing}
    scaling_type::BenchmarkTimesScaling
end

A Gaussian HJM model with piece-wise constant benchmark rate volatility and constant mean reversion.

gaussian_hjm_model(
    alias::String,
    delta::ParameterTermstructure,
    chi::ParameterTermstructure,
    sigma_f::BackwardFlatVolatility,
    correlation_holder::Union{CorrelationHolder, Nothing},
    quanto_model::Union{AssetModel, Nothing},
    scaling_type::BenchmarkTimesScaling = ForwardRateScaling,
    )

Create a Gausian HJM model.

func_y(
    y0::AbstractMatrix,
    chi::AbstractVector,
    sigmaT::AbstractMatrix,
    s::ModelTime,
    t::ModelTime,
    )

Calculate variance/auxiliary state variable $y(t)$ given $y(s)=y_0$.

In this function we assume that sigma is constant over the time interval $(s,t)$.

func_y(m::GaussianHjmModel, t::ModelTime)

Calculate variance/auxiliary state variable y(t).

chi_hjm(m::SeparableHjmModel)

Return vector of constant mean reversion rates.

chi_hjm(m::MarkovFutureModel)

Return vector of constant mean reversion rates.

benchmark_times(m::SeparableHjmModel)

Return vector of reference/benchmark times

benchmark_times(m::MarkovFutureModel)

Return vector of reference/benchmark times

H_hjm(chi::AbstractVector, s::ModelTime, t::ModelTime)

Diagonal entries of $H(s,t)$.

H_hjm(m::SeparableHjmModel, s::ModelTime, t::ModelTime)

Diagonal entries of $H(s,t)$.

G_hjm(chi::AbstractVector, s::ModelTime, t::ModelTime)

Vector function $G(s,t)$.

G_hjm(m::SeparableHjmModel, s::ModelTime, t::ModelTime)

Vector function $G(s,t)$.

G_hjm(chi::AbstractVector, s::ModelTime, T::AbstractVector)

Vector function $G(s,t)$ as matrix of size (d,k) where k = length(T)

G_hjm(m::SeparableHjmModel, s::ModelTime, T::AbstractVector)

Vector function $G(s,t)$.

@enum(
    BenchmarkTimesScaling,
    ForwardRateScaling,
    ZeroRateScaling,
    DiagonalScaling,
)

Specify scaling methods to be used for state variable x volatility function.

ForwardRateScaling (default) uses forward rates as benchmark rates. For refrence, see Andersen/Piterbarg, Interest Rate Modeling, 2010, Prop. 13.3.2.

ZeroRateScaling uses continous compounded zero rates as benchmark rates. See https://ssrn.com/abstract=4638188 for details.

DiagonalScaling uses identity matrix (i.e. no scaling).

benchmark_times_scaling(
    chi::AbstractVector,
    delta::AbstractVector,
    scaling_type::BenchmarkTimesScaling = ForwardRate::BenchmarkTimesScaling
    )

Calculate volatility scaling matrix depending on the scaling type.

benchmark_times_scaling_forward_rate(chi::AbstractVector, delta::AbstractVector)

Benchmark times volatility scaling matrix $H [H^f]^{-1} = [H^f H^{-1}]^{-1}$.

benchmark_times_scaling_zero_rate(chi::AbstractVector, delta::AbstractVector)

Benchmark times volatility scaling matrix based on zero rates.

func_Theta_x(
    chi::AbstractVector,
    y::Function,       # (u) -> Matrix
    sigmaT::Function,  # (u) -> Matrix
    alpha::Function,   # (u) -> Vector
    s::ModelTime,
    t::ModelTime,
    param_grid::Union{AbstractVector, Nothing},
    )

Calculate Theta function for state variable x.

In this function we assume for the interval $(s,t)$ that - variance $y(s)$ is known, - volatility $σ$ is state-independent and - quanto adjustment alpha is state-independent.

func_Theta_x_integrate_y(
    chi::AbstractVector,
    y::Function,       # (u) -> Matrix
    sigmaT::Function,  # (u) -> Matrix
    alpha::Function,   # (u) -> Vector
    s::ModelTime,
    t::ModelTime,
    param_grid::Union{AbstractVector, Nothing},
    )

Calculate Theta function for state variable $x$.

Avoidance of explicit $σ^\top σ$ dependence may help with integrating over jumps in piece-wise constant volatility.

In this function we assume for the interval $(s,t)$ that - variance $y$ is state-independent, - volatility $σ$ is state-independent and - quanto adjustment $α$ is state-independent.

func_Theta_s(
    chi::AbstractVector,
    y::Function,       # (u) -> Matrix
    sigmaT::Function,  # (u) -> Matrix
    alpha::Function,   # (u) -> Vector
    s::ModelTime,
    t::ModelTime,
    param_grid::Union{AbstractVector, Nothing},
    )

Calculate Theta function for integrated state variable $s$.

In this function we assume for the interval $(s,t)$ that - variance $y$ state-independent, - volatility $σ$ is state-independent and - quanto adjustment $α$ is state-independent.

func_Theta(
    chi::AbstractVector,
    y::Function,       # (u) -> Matrix
    sigmaT::Function,  # (u) -> Matrix
    alpha::Function,   # (u) -> Vector
    s::ModelTime,
    t::ModelTime,
    param_grid::Union{AbstractVector, Nothing},
    )

Calculate Theta function for component model state variable $X$.

In this function we assume for the interval $(s,t)$ that - variance $y$ state-independent, - volatility $σ$ is state-independent and - quanto adjustment $α$ is state-independent.

func_H_T(chi::AbstractVector, s::ModelTime, t::ModelTime)

Calculate $H$ function for component model.

func_H_T_dense(chi::AbstractVector, s::ModelTime, t::ModelTime)

Alternative $H$ function implementation for debugging.

func_Sigma_T(
    chi::AbstractVector,
    sigmaT::Function,
    s::ModelTime,
    t::ModelTime
    )

Calculate $Σ(u)^\top$ function for component model.

In this function we assume for the interval $(s,t)$ that - volatility $σ$ is state-independent.

log_bank_account(m::Model, alias::String, t::ModelTime, X::ModelState)

Retrieve the integral over sum of state variables s(t) from interest rate model.

Returns a vector of size (p,) for X with size (n,p).

log_bank_account(m::CompositeModel, alias::String, t::ModelTime, X::ModelState)

Retrieve the integral over sum of state variables s(t) from interest rate model.

log_bank_account(m::GaussianHjmModel, model_alias::String, t::ModelTime, X::ModelState)

Retrieve the integral over sum of state variables s(t) from interest rate model.

log_zero_bond(m::Model, alias::String, t::ModelTime, T::ModelTime, X::ModelState)

Calculate the zero bond term [G(t,T)' x(t) + 0.5 G(t,T)' y(t) G(t,T)]' from rates model.

Returns a vector of size (p,) for X with size (n,p).

log_zero_bond(m::CompositeModel, alias::String, t::ModelTime, T::ModelTime, X::ModelState)

Calculate the zero bond term [G(t,T)' x(t) + 0.5 G(t,T)' y(t) G(t,T)]' from rates model.

log_zero_bond(m::GaussianHjmModel, model_alias::String, t::ModelTime, T::ModelTime, X::ModelState)

Calculate the zero bond term [G(t,T)' x(t) + 0.5 G(t,T)' y(t) G(t,T)]' from rates model.

log_zero_bonds(m::Model, alias::String, t::ModelTime, T::AbstractVector, X::ModelState)

Calculate the zero bond terms [G(t,T)' x(t) + 0.5 G(t,T)' y(t) G(t,T)]' from rates model.

log_zero_bonds(m::CompositeModel, alias::String, t::ModelTime, T::AbstractVector, X::ModelState)

Calculate the zero bond terms [G(t,T)' x(t) + 0.5 G(t,T)' y(t) G(t,T)]' from rates model.

log_zero_bonds(m::GaussianHjmModel, model_alias::String, t::ModelTime, T::AbstractVector, X::ModelState)

Calculate the zero bond terms [G(t,T)' x(t) + 0.5 G(t,T)' y(t) G(t,T)]' from rates model.

log_compounding_factor(
    m::Model,
    model_alias::String,
    t::ModelTime,
    T1::ModelTime,
    T2::ModelTime,
    X::ModelState,
    )

Calculate the forward compounding factor term [G(t,T2) - G(t,T1)]' x(t) + 0.5 * [G(t,T2)' y(t) G(t,T2) - G(t,T1)' y(t) G(t,T1)].

This is used for Libor forward rate calculation.

Returns a vector of size (p,) for X with size (n,p).

log_compounding_factor(
    m::CompositeModel,
    alias::String,
    t::ModelTime,
    T1::ModelTime,
    T2::ModelTime,
    X::ModelState,
    )

Calculate the forward compounding factor term [G(t,T2) - G(t,T1)]' x(t) + 0.5 * [G(t,T2)' y(t) G(t,T2) - G(t,T1)' y(t) G(t,T1)].

This is used for Libor forward rate calculation.

Returns a vector of size (p,) for X with size (n,p).

log_compounding_factor(
    m::GaussianHjmModel,
    model_alias::String,
    t::ModelTime,
    T1::ModelTime,
    T2::ModelTime,
    X::ModelState,
    )

Calculate the forward compounding factor term [G(t,T2) - G(t,T1)]' x(t) + 0.5 * [G(t,T2)' y(t) G(t,T2) - G(t,T1)' y(t) G(t,T1)].

This is used for Libor forward rate calculation.

forward_rate_variance(
    m::Model,
    alias::String,
    t::ModelTime,
    T::ModelTime,
    T0::ModelTime,
    T1::ModelTime,
    )

Calculate the lognormal variance for a compounding factor of a forward-looking or backward-looking forward rate.

forward_rate_variance(
    m::CompositeModel,
    alias::String,
    t::ModelTime,
    T::ModelTime,
    T0::ModelTime,
    T1::ModelTime,
    )

Calculate the lognormal variance for a compounding factor of a forward-looking or backward-looking forward rate.

forward_rate_variance(
    m::GaussianHjmModel,
    t::ModelTime,
    T::ModelTime,
    T0::ModelTime,
    T1::ModelTime,
    )

Calculate the lognormal variance for a compounding factor of a forward-looking or backward-looking forward rate.

Time t is the observation time, T is the rate fixing time or option exercise time, T0 is the rate period start time, and T1 is the rate period end time.

If t ≤ T0 then we calculate the variance for a forward-looking rate. If t = T1 then we calculate the variance for a backward-looking rate.

forward_rate_variance(
    m::GaussianHjmModel,
    alias::String,
    t::ModelTime,
    T::ModelTime,
    T0::ModelTime,
    T1::ModelTime,
    )

Calculate the lognormal variance for a compounding factor of a forward-looking or backward-looking forward rate.

This function implements the Model interface function.

forward_rate_variance(
p::AbstractPath,
t::ModelTime,
T::ModelTime,
T0::ModelTime,
T1::ModelTime,
key::String,
)

Calculate the lognormal variance for a compounding factor of a forward-looking or backward-looking forward rate.

forward_rate_variance(
p::Path,
t::ModelTime,
T::ModelTime,
T0::ModelTime,
T1::ModelTime,
key::String,
)

Calculate the lognormal variance for a compounding factor of a forward-looking or backward-looking forward rate.

swap_rate_variance(
    m::Model,
    alias::String,
    yts::YieldTermstructure,
    t::ModelTime,
    T::ModelTime,
    swap_times::AbstractVector,
    yf_weights::AbstractVector,
    X::ModelState,
    )

Calculate the normal model variance of a swap rate via Gaussian swap rate approximation.

swap_rate_variance(
    m::CompositeModel,
    alias::String,
    yts::YieldTermstructure,
    t::ModelTime,
    T::ModelTime,
    swap_times::AbstractVector,
    yf_weights::AbstractVector,
    X::ModelState,
    )

Calculate the normal model variance of a swap rate via Gaussian swap rate approximation.

swap_rate_variance(
    yts::YieldTermstructure,
    m::GaussianHjmModel,
    t::ModelTime,
    T::ModelTime,
    swap_times::AbstractVector,
    yf_weights::AbstractVector,
    SX::ModelState,
    )

Calculate the normal model variance of a swap rate via Gaussian swap rate approximation.

Observation time is t, Option expiry time is T.

See method swap_rate_gradient for details on further input parameters.

swap_rate_variance(
    m::GaussianHjmModel,
    alias::String,
    yts::YieldTermstructure,
    t::ModelTime,
    T::ModelTime,
    swap_times::AbstractVector,
    yf_weights::AbstractVector,
    X::ModelState,
    )

Calculate the normal model variance of a swap rate via Gaussian swap rate approximation.

This function is implements the Model interface function.

See method swap_rate_gradient for details on further input parameters.

swap_rate_variance(
    p::AbstractPath,
    t::ModelTime,
    T::ModelTime,
    swap_times::AbstractVector,
    yf_weights::AbstractVector,
    key::String,
    )

Calculate the normal model variance of a swap rate via Gaussian swap rate approximation.

swap_rate_variance(
    p::Path,
    t::ModelTime,
    T::ModelTime,
    swap_times::AbstractVector,
    yf_weights::AbstractVector,
    key::String,
    )

Calculate the normal model variance of a swap rate via Gaussian swap rate approximation.

struct GaussianHjmModelVolatility
    scaling_matrix::AbstractMatrix
    sigma_f::BackwardFlatVolatility
    DfT::AbstractMatrix
end

A dedicated matrix-valued volatility term structure for Gaussian HJM Models.

swap_rate_gradient(
    yts::YieldTermstructure,
    m::GaussianHjmModel,
    t::ModelTime,
    swap_times::AbstractVector,
    yf_weights::AbstractVector,
    SX::ModelState,
    )

The gradient dS/dx in a Gaussian HJM model.

Returns a matrix of size (p, d). Here, p is the number of paths in SX and d is the number of factors of the GHJM model, i.e., d = length(factor_alias(m)).

Observation time is t. The swap rate is specified by swap_times and yf_weights. swap_times[begin] is the start time of the first (floating rate) coupon period. swap_times[k] for k>begin represent the pay times of the fixed leg coupons. yf_weights are the year fractions of the fixed leg coupons.

The swap rate is constructed assuming single-curve setting without tenor basis. yts is the initial (discounting) yield curve.

The swap rate gradient depends on the simulated model state at t. The model state is encoded in SX.

swap_rate_instantaneous_covariance(
    yts::YieldTermstructure,
    m::GaussianHjmModel,
    t::ModelTime,
    swap_times_1::AbstractVector,
    yf_weights_1::AbstractVector,
    swap_times_2::AbstractVector,
    yf_weights_2::AbstractVector,
    SX::ModelState,
    )

Calculate the instantaneous covariance of two swap rates.

See method swap_rate_gradient for details on the input parameters.

swap_rate_volatility²(
    yts::YieldTermstructure,
    m::GaussianHjmModel,
    t::ModelTime,
    swap_times::AbstractVector,
    yf_weights::AbstractVector,
    SX::ModelState,
    )

Calculate the square of swap rate volatility (or instantaneous variance).

See method swap_rate_gradient for details on the input parameters.

swap_rate_covariance(
    yts::YieldTermstructure,
    m::GaussianHjmModel,
    t::ModelTime,
    T::ModelTime,
    swap_times_1::AbstractVector,
    yf_weights_1::AbstractVector,
    swap_times_2::AbstractVector,
    yf_weights_2::AbstractVector,
    SX::ModelState,
    )

Calculate the covariance of two swap rates over the time intervall (t,T).

See method swap_rate_gradient for details on the input parameters.

swap_rate_correlation(
    yts::YieldTermstructure,
    m::GaussianHjmModel,
    t::ModelTime,
    T::ModelTime,
    swap_times_1::AbstractVector,
    yf_weights_1::AbstractVector,
    swap_times_2::AbstractVector,
    yf_weights_2::AbstractVector,
    SX::ModelState,
    )

Calculate the correlation of two swap rates via Gaussian swap rate approximation over the time intervall (t,T).

See method swap_rate_gradient for details on further input parameters.

model_implied_volatilties(
    yts::YieldTermstructure,
    m::GaussianHjmModel,
    option_times::AbstractVector,
    swap_times::AbstractMatrix,
    swap_weights::AbstractMatrix,
    SX::Union{ModelState, Nothing} = nothing
    )

Calculate model-implied swap rate volatilities in Gaussian HJM model.

option_times are the option expiry times.

swap_times is a matrix of vectors. Each element represents swap times as specified in swap_rate_gradient.

swap_weights is a matrix of vectors. Each element represents year fraction weights as specified in swap_rate_gradient.

See method swap_rate_gradient for details on further input parameters.

model_implied_volatilties(
    yts::YieldTermstructure,
    m::GaussianHjmModel,
    option_times::AbstractVector,
    swap_times::AbstractVector,
    swap_weights::AbstractVector,
    SX::Union{ModelState, Nothing} = nothing
    )

Calculate model-implied swap rate volatilities in Gaussian HJM model.

option_times are the option expiry times.

swap_times is a vector of vectors. Each element represents time offsets that are added to option_times in order to form swap_times as specified in swap_rate_gradient.

swap_weights is a vector of vectors. Each element represents year fraction weights as specified in swap_rate_gradient. swap_weights are assumed equal per expiry time.

See method swap_rate_gradient for details on further input parameters.

model_implied_volatilties(
    yts::YieldTermstructure,
    m::GaussianHjmModel,
    option_times::AbstractVector,
    swap_maturities::AbstractVector,
    SX::Union{ModelState, Nothing} = nothing
    )

Calculate model-implied swap rate volatilities in Gaussian HJM model.

option_times are the option expiry times.

swap_maturities is a list of swap tenors. Swap times and year fraction weights are calculated from swap_maturities assuming an annual schedule.

See method swap_rate_gradient for details on further input parameters.

model_implied_volatilties(
    ast_model::LognormalAssetModel,
    dom_model::Union{GaussianHjmModel, Nothing},
    for_model::Union{GaussianHjmModel, Nothing},
    ch::CorrelationHolder,
    option_times::AbstractVector,
    )

Calculate model-implied volatilities in hybrid asset model.

gaussian_hjm_model(
    alias::String,
    ch::Union{CorrelationHolder, Nothing},
    option_times::AbstractVector,
    swap_maturities::AbstractVector,
    swap_rate_volatilities::AbstractMatrix,
    yts::YieldTermstructure;
    max_iter::Integer = 5,
    volatility_regularisation::ModelValue = 0.0,
    scaling_type::BenchmarkTimesScaling = _default_benchmark_time_scaling,
    )

Calibrate a model with flat volatilities and mean reversion to strips of co-initial normal volatilities.

gaussian_hjm_model(
    alias::String,
    delta::ParameterTermstructure,
    chi::ParameterTermstructure,
    ch::Union{CorrelationHolder, Nothing},
    option_times::AbstractVector,
    swap_maturities::AbstractVector,
    swap_rate_volatilities::AbstractMatrix,
    yts::YieldTermstructure;
    max_iter::Integer = 5,
    volatility_regularisation::ModelValue = 0.0,
    scaling_type::BenchmarkTimesScaling = _default_benchmark_time_scaling,
    swap_maturity_indices::Union{AbstractVector, Nothing} = nothing,
    swap_maturity_weights::Union{AbstractVector, Nothing} = nothing,
    )

Calibrate a model with piece-wise constant volatilities to strips of co-initial normal volatilities.

Mean reversion (and correlations) are exogenously specified.