Payoffs Functions

abstract type Payoff end

A Payoff is a random variable X in our stochastic model.

It represents a market object that can be evaluated in conjunction with a given path.

We are interested in realisations of a payoff at a given path, i.e. X(omega). Moreover, for risk-neutral valuation we are also interested in discounted payoffs at a given path.

We implement a Payoff as a root of a computational graph. The nodes of the computational graph are itself Payoff objects which represent mathematical operations or use the path omega to determine its realisations.

obs_time(p::Payoff)

A Payoff is typically observed at a particular time. In that sense, a Payoff is an $F_t$-measurable random variable.

The observation time represents the time, after which the payoff is known.

obs_times(p::Payoff)

A payoff is typically linked to other payoffs and forms a DAG. This function returns all observation times associated with a given payoff.

This functionality is required to determine relevant simulation grid points.

at(p::Payoff, path::AbstractPath)

Evaluate a Payoff at a given path, X(omega).

Depending on the functionality associated with the path, this function typically returns a vector of realisations.

This function is invoked when using call operator on a Payoff,

(p::Payoff)(path::AbstractPath) = at(p::Payoff, path::AbstractPath)

abstract type Leaf <: Payoff end

A Leaf is a particular Payoff which has no outgoing links to other Payoff objects. A Leaf typically uses the path to determine its realisations.

We assume that a Leaf has a field obs_time.

struct Numeraire <: Leaf
    obs_time::ModelTime
    curve_key::String
end

The price of our numeraire asset price N(t) at observation time t.

Typically, this coincides with the bank account price in numeraire (i.e. domestic) currency.

struct BankAccount <: Leaf
    obs_time::ModelTime
    key::String
end

The price of a continuous compounded bank account B(t) at observation time t and with unit notional at inception.

struct ZeroBond <: Leaf
    obs_time::ModelTime
    maturity_time::ModelTime
    key::String
end

The price of a zero coupon bond P(t,T) with observation time t and bond maturity time T.

struct Asset <: Leaf
    obs_time::ModelTime
    key::String
end

The price of a tradeable asset S(t) at observation time t.

A tradeable asset is typically an FX rate, equity/index price or spot inflation index.

struct ForwardAsset <: Leaf
    obs_time::ModelTime
    maturity_time::ModelTime
    key::String
end

The forward price E_t[S(T)] of a tradeable asset S at observation time t and with maturity time T. Expectation is calculated in T-forward measure.

struct AssetConvexityAdjustment <: Leaf
    obs_time::ModelTime
    first_time::ModelTime
    second_time::ModelTime
    pay_time::ModelTime
    key::String
end

Convexity adjustment factor for YoY asset payoffs.

struct ForwardIndex <: Leaf
    obs_time::ModelTime
    maturity_time::ModelTime
    key::String
end

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

This is used in particular for inflation modelling.

struct IndexConvexityAdjustment <: Leaf
    obs_time::ModelTime
    first_time::ModelTime
    second_time::ModelTime
    pay_time::ModelTime
    key::String
end

Convexity adjustment factor for YoY index payoffs.

struct FutureIndex <: Leaf
    obs_time::ModelTime
    maturity_time::ModelTime
    key::String
end

Risk-neutral expectation Et^T[ST] of a price index.

This is used in particular for Future modelling.

struct Fixing <: Leaf
    obs_time::ModelTime
    key::String
end

The value of an index fixing Idx(t) at observation time t.

The value is obtained from a term structure linked to the path.

struct Fixed <: Leaf
    value::ModelValue
end

A deterministic quantity.

struct ScalarValue <: Leaf
    value::ModelValue
end

A scalar deterministic quantity.

abstract type UnaryNode <: Payoff end

A UnaryNode is a particular Payoff which has exactly one outgoing link to another Payoff object.

We assume that the reference to the outgoing Payoff object is a field denoted x.

A UnaryNode is typically a decorator of the linked Payoff.

struct Exp <: UnaryNode
    x::Payoff
end

Function exp() applied to payoff.

struct Log <: UnaryNode
    x::Payoff
end

Function log() applied to payoff.

struct Pay <: UnaryNode
    x::Payoff
    obs_time::ModelTime
    test_times::Bool
end

A Pay payoff allows the user to modify the observation time of a given payoff. This is relevant for discounting.

Typically, we use Pay to specify the pay time for a payoff.

mutable struct Cache <: UnaryNode
    x::Payoff
    path::Union{AbstractPath, Nothing}
    value::Union{AbstractVector, Nothing}
end

A Cache payoff aims at avoiding repeated calculations of the same payoff.

If a Payoff object is referenced by several parent Payoff objects then each call of at() of the parent object triggers a call of at() of the child object that all return the same value(s).

A Cache payoff checks whether the payoff was already evaluated and if yes then returns a cached value.

abstract type BinaryNode <: Payoff end

A BinaryNode is a particular Payoff which has exactly two outgoing links to other Payoff objects.

We assume that the references to the outgoing Payoff objects are fields denoted x and y.

A BinaryNode is typically a mathematical operation.

struct Add <: BinaryNode
    x::Payoff
    y::Payoff
end

Addition of payoffs.

struct Sub <: BinaryNode
    x::Payoff
    y::Payoff
end

Subtraction of payoffs.

struct Mul <: BinaryNode
    x::Payoff
    y::Payoff
end

Multiplication of payoffs.

struct Div <: BinaryNode
    x::Payoff
    y::Payoff
end

Division of payoffs.

struct Max <: BinaryNode
    x::Payoff
    y::Payoff
end

Path-wise maximum

struct Min <: BinaryNode
    x::Payoff
    y::Payoff
end

Path-wise minimum

struct Logical <: BinaryNode
    x::Payoff
    y::Payoff
    op::String
end

Logical operations

struct LiborRate <: Leaf
    obs_time::ModelTime
    start_time::ModelTime
    end_time::ModelTime
    year_fraction::ModelValue
    key::String
end

A simple compounded forward Libor rate.

LiborRate(
   obs_time::ModelTime,
   start_time::ModelTime,
   end_time::ModelTime,
   key::String,
   )

A simple compounded forward Libor rate with year fraction from model time.

struct CompoundedRate <: Payoff
    obs_time::ModelTime
    start_time::ModelTime
    end_time::ModelTime
    year_fraction::ModelValue
    fixed_compounding::Union{Payoff, Nothing}
    key::String
    fixed_type::DataType  # distinguish from constructors
end

A continuously compounded backward looking rate.

This is a proxy for daily compounded RFR coupon rates.

For obstime less starttime it is equivalent to a Libor rate.

CompoundedRate(
    obs_time::ModelTime,
    start_time::ModelTime,
    end_time::ModelTime,
    key::String,
    fixed_compounding::Union{Payoff, Nothing} = nothing,
    )

A continuously compounded backward looking rate with year fraction from model time.

struct Optionlet <: Payoff
    obs_time::ModelTime
    expiry_time::ModelTime
    gearing_factor::Payoff
    forward_rate::Union{LiborRate, CompoundedRate}
    strike_rate::Payoff
    call_put::ModelValue
end

The time-t forward price of an option paying [ϕ(R-K)]^+. Rate R is determined at expiry_time. The rate R can be forward-looking or backward-looking.

forward price is calculated as expectation in T-forward measure where T corresponds to the period end time. Conditioning (for time-t price) is on information at obs_time.

The rate R is written in terms of a compounding factor C and R = [G C - 1]/τ. Here, G is an additional gearing factor to capture past OIS fixings.

Then, option payoff becomes G/τ [ϕ(C - (1 + τK)/G)]^+.

Optionlet(
    obs_time_::ModelTime,
    expiry_time::ModelTime,
    forward_rate::Union{LiborRate, CompoundedRate},
    strike_rate::Payoff,
    call_put::ModelValue,
    gearing_factor::Payoff = ScalarValue(1.0),
    )

Create an Optionlet payoff.

struct Swaption <: Payoff
    obs_time::ModelTime
    expiry_time::ModelTime
    settlement_time::ModelTime
    forward_rates::AbstractVector
    forward_rate_pay_times::AbstractVector
    fixed_times::AbstractVector
    fixed_weights::AbstractVector
    fixed_rate::ModelValue
    payer_receiver::ModelValue
    disc_key::String
    zcb_pay_times::AbstractVector
    rate_type::DataType  # to distinguish from functions
end

Time-t forward price of an option paying An⋅[ϕ(S-K)]^+. Swap rate S is determined at expiry_time. Floating rates in S can be forward looking of backward looking rates.

Forward price is calculated in T-forward measure where T corresponds to settlement_time. Conditioning (for time-t price) is on information at obs_time.

Swaption(
    obs_time_::ModelTime,
    expiry_time::ModelTime,
    settlement_time::ModelTime,
    forward_rates::AbstractVector,
    fixed_times::AbstractVector,
    fixed_weights::AbstractVector,
    fixed_rate::ModelValue,
    payer_receiver::ModelValue,
    disc_key::String,
    )

Create a Swaption payoff.

struct VanillaAssetOption <: Payoff
    obs_time::ModelTime
    expiry_time::ModelTime
    forward_price::ForwardAsset
    strike_price::Payoff
    call_put::ModelValue
end

The time-t forward price of an option paying [ϕ(F-K)]^+. Forward asset price F is determined at expiry_time.

Option forward price is calculated as expectation in T-forward measure where T corresponds to the expiry time. Conditioning (for time-t price) is on information at obs_time.

abstract type AmcPayoff <: Payoff end

AmcPayoff is used to implement common methods for AMC payoffs. Concrete AMC payoffs are assumed to hold a fields links::AmcPayoffLinks and regr::AmcPayoffRegression.

An AMC payoff is special and does not fit into the structure of unary/binary nodes. Instead, we have several edges to other payoffs with observation times before (x and y) and after (z) its own observation time.

struct AmcPayoffLinks
    obs_time::ModelTime
    x::AbstractVector
    y::AbstractVector
    z::AbstractVector
    curve_key::String
end

An AmcPayoffLinks object holds common data fields for an American Monte Carlo (AMC) payoff.

Here, obs_time is the observation time of the AMC payoff and x, y, z are related Payoff vectors. The elements of x and y represent random variables with observation times after obs_time. The elements of z represent random variables with observation time (at or) before obs_time. z is the vector of regression variables.

The parameter curve_key is used to specify a discount curve for numeraire price calculation.

We calculate $X$ as the sum of discounted payoff values of x and $Y$ as the sum of discounted payoff values of y. $Z = [ Z_1, Z_2, ... ]$ represent the (undiscounted) values of the regression variables from the payoff vector z.

Then we estimate the trigger variable

$T = E[ X - Y | Z_1, Z_2, ... ]$

An actual AMC payoff uses $X$, $Y$, and $T$ to calculate its values.

mutable struct AmcPayoffRegression
    path::Union{AbstractPath, Nothing}
    make_regression::Union{Function, Nothing}
    regression::Any
end

AmcPayoffRegression holds the common data fields to regression and regression calibration for AMC payoffs. These data fields are supposed to be updated subsequent creation of the object. As a consequence, AmcPayoffRegression is declared mutable.

The element path is a Monte Carlo path. This element is typically linked to a simulation and a context mapping.

make_regression is a function/functor with signature

make_regression(C::AbstractMatrix, O::AbstractVector) -> obj.

This function is typically a lambda for polynomial_regression (or similar) where parameters like maximum polynomial degree are fixed.

The result of make_regression is stored in the regression field. For the result object regression we assume that a method

predict(regression, C)

is defined. The method predict is supposed to return a prediction for a matrix of controls C. See PolynomialRegression as an example.

struct AmcMax <: AmcPayoff
    links::AmcPayoffLinks
    regr::AmcPayoffRegression
end

An AmcMax payoff is used to model long call rights.

It calculates the expectation of maximum of (sum of) discounted payoffs x and (sum of) discounted payoffs y. Expectation is calculated conditional on information at obs_time. This is approximated by regression variable payoffs z.

AmcMax(
    obs_time::ModelTime,
    x::AbstractVector,
    y::AbstractVector,
    z::AbstractVector,
    path::Union{AbstractPath, Nothing},
    make_regression::Union{Function, Nothing},
    curve_key::String,
    )

Create an AmcMax payoff.

struct AmcMin <: AmcPayoff
    links::AmcPayoffLinks
    regr::AmcPayoffRegression
end

An AmcMin payoff is used to model short call rights.

It calculates the expectation of minimum of (sum of) discounted payoffs x and (sum of) discounted payoffs y. Expectation is calculated conditional on information at obs_time. This is approximated by regression variable payoffs z.

AmcMin(
    obs_time::ModelTime,
    x::AbstractVector,
    y::AbstractVector,
    z::AbstractVector,
    path::Union{AbstractPath, Nothing},
    make_regression::Union{Function, Nothing},
    curve_key::String,
    )

Create an AmcMin payoff.

struct AmcOne <: AmcPayoff
    links::AmcPayoffLinks
    regr::AmcPayoffRegression
end

An AmcOne payoff is used to model the indicator variable $1_{(X > Y)}$.

It calculates the expectation of maximum of (sum of) discounted payoffs x and (sum of) discounted payoffs y. Expectation is calculated conditional on information at obs_time. This is approximated by regression variable payoffs z.

AmcOne(
    obs_time::ModelTime,
    x::AbstractVector,
    y::AbstractVector,
    z::AbstractVector,
    path::Union{AbstractPath, Nothing},
    make_regression::Union{Function, Nothing},
    curve_key::String,
    )

Create an AmcOne payoff.

struct AmcSum <: AmcPayoff
    links::AmcPayoffLinks
    regr::AmcPayoffRegression
end

An AmcSum payoff is used to model general conditional expectations

$B(t) E[ X(T)/B(T) | Z(t) ]$

AmcSum payoffs are typically used to calculate future model prices in exposure simulation applications.

AmcSum(
    obs_time::ModelTime,
    x::AbstractVector,
    z::AbstractVector,
    path::Union{AbstractPath, Nothing},
    make_regression::Union{Function, Nothing},
    curve_key::String,
    )

Create an AmcSum payoff.

reset_regression!(
    p::AmcPayoff,
    path::Union{AbstractPath, Nothing} = nothing,
    make_regression::Union{Function, Nothing}  = nothing,
    )

Reset the regression properties for an AMC payoffs.

This method is used to allow setting and updating AMC regression after payoff creation.

reset_regression!(
    p::UnaryNode,
    path::Union{AbstractPath, Nothing} = nothing,
    make_regression::Union{Function, Nothing}  = nothing,
    )

Delegate resetting the regression properties to child payoff.

reset_regression!(
    p::BinaryNode,
    path::Union{AbstractPath, Nothing} = nothing,
    make_regression::Union{Function, Nothing}  = nothing,
    )

Delegate resetting the regression properties to child payoffs.

reset_regression!(
    p::Union{Leaf, CompoundedRate, Optionlet, Swaption},
    path::Union{AbstractPath, Nothing} = nothing,
    make_regression::Union{Function, Nothing}  = nothing,
    )

Ignore resetting the regression properties for Leaf and similar payoffs.

Note that some rates payoffs and rates options are no Leafs.

reset_regression!(
    p::Payoff,
    path::Union{AbstractPath, Nothing} = nothing,
    make_regression::Union{Function, Nothing}  = nothing,
    )

Throw an error if reset_regression! is not implemented for concrete payoff.

reset_regression!(
    leg::BermudanSwaptionLeg,
    path::Union{AbstractPath, Nothing} = nothing,
    make_regression::Union{Function, Nothing}  = nothing,
    )

Reset the regression properties for the AMC payoffs of the BermudanSwaptionLeg.

This method is used to allow setting and updating AMC regression after leg creation.

calibrate_regression(links::AmcPayoffLinks, regr::AmcPayoffRegression)

Calibrate the regression for an AMC payoff.

has_amc_payoff(p::AmcPayoff)

Determine whether a payoff is or contains an AMC payoff.

AMC payoffs require special treatment e.g. for sensitivity calculation.

has_amc_payoff(p::UnaryNode)

Determine whether a payoff is or contains an AMC payoff.

has_amc_payoff(p::BinaryNode)

Determine whether a payoff is or contains an AMC payoff.

has_amc_payoff(p::Union{Leaf, CompoundedRate, Optionlet, Swaption})

Determine whether a payoff is or contains an AMC payoff.

has_amc_payoff(p::Payoff)

Determine whether a payoff is or contains an AMC payoff.

has_amc_payoff(payoffs::AbstractVector)

Determine whether any payoff is or contains an AMC payoff.

obs_time(p::Payoff)

A Payoff is typically observed at a particular time. In that sense, a Payoff is an $F_t$-measurable random variable.

The observation time represents the time, after which the payoff is known.

obs_time(p::Leaf)

Return the observation time for a Leaf object.

obs_time(p::UnaryNode)

Return the observation time of the linked payoff.

obs_time(p::BinaryNode)

Derive the observation time from linked payoffs.

obs_time(p::Fixed)

Observation time for Fixed payoffs is zero because they are deterministic.

obs_time(p::ScalarValue)

Observation time for ScalarValue payoffs is zero because they are deterministic.

obs_time(p::Pay)

Return decorating observation time.

obs_time(p::CompoundedRate)

Calculate observation time for CompoundedRate payoff.

obs_time(p::Optionlet)

Return Optionlet observation time.

obs_time(p::Swaption)

Return Swaption observation time.

obs_time(p::AmcPayoff)

Return the AMC payoff observation time

obs_time(p::VanillaAssetOption)

Return VanillaAssetOption observation time.

obs_times(p::Payoff)

A payoff is typically linked to other payoffs and forms a DAG. This function returns all observation times associated with a given payoff.

This functionality is required to determine relevant simulation grid points.

obs_times(p::Leaf)

Derive the set of observation times from the single observation time of the Leaf object.

obs_times(p::UnaryNode)

Return all observation times of the linked payoff.

obs_times(p::BinaryNode)

Derive all observation times from linked payoff.

obs_times(p::Pay)

Return all observation times of the linked payoff.

obs_times(p::CompoundedRate)

Calculate all observation times (i.e. event times) for CompoundedRate payoff.

obs_times(p::Optionlet)

Return all Optionlet observation times.

obs_times(p::Swaption)

Return all Swaption observation times.

obs_times(p::AmcPayoff)

Return observation times of all referenced payoffs.

obs_times(p::VanillaAssetOption)

Return all VanillaAssetOption observation times.

at(p::Payoff, path::AbstractPath)

Evaluate a Payoff at a given path, X(omega).

Depending on the functionality associated with the path, this function typically returns a vector of realisations.

This function is invoked when using call operator on a Payoff,

(p::Payoff)(path::AbstractPath) = at(p::Payoff, path::AbstractPath)

at(p::Numeraire, path::AbstractPath)

Derive the numeraire price at a given path.

at(p::BankAccount, path::AbstractPath)

Derive the bank account price at a given path.

at(p::ZeroBond, path::AbstractPath)

Derive the zero bond price at a given path.

at(p::Asset, path::AbstractPath)

Derive the asset price at a given path.

at(p::ForwardAsset, path::AbstractPath)

Derive the asset price at a given path.

at(p::Fixing, path::AbstractPath)

Derive the fixing value at a given path.

at(p::Fixed, path::AbstractPath)

Return the deterministic value broadcasted to the length of the path.

at(p::ScalarValue, path::AbstractPath)

Return the deterministic scalar value.

This aims at avoiding some unnecessary allocations.

at(p::AssetConvexityAdjustment, path::AbstractPath)

Derive the YoY payoff convexity adjustment at a given path.

at(p::ForwardIndex, path::AbstractPath)

Derive forward index value at a given path.

at(p::IndexConvexityAdjustment, path::AbstractPath)

Derive the YoY payoff convexity adjustment at a given path.

at(p::FutureIndex, path::AbstractPath)

Derive forward index value at a given path.

at(p::Pay, path::AbstractPath)

Derive payoff of the child payoff.

at(p::Cache, path::AbstractPath)

Derive payoff of the child payoff only if not yet calculated.

at(p::Exp, path::AbstractPath)

Evaluate exp-function.

at(p::Log, path::AbstractPath)

Evaluate log-function.

Addition.

Subtraction.

Multiplication.

Division.

Maximum

Minimum

Logical

at(p::LiborRate, path::AbstractPath)

Derive the forward Libor rate at a given path.

at(p::CompoundedRate, path::AbstractPath)

Derive the compounded backward looking rate at a given path.

at(p::Optionlet, path::AbstractPath)

Evaluate a Optionlet at a given path, X(omega).

at(p::Swaption, path::AbstractPath)

Evaluate a Swaption at a given path, X(omega).

at(links::AmcPayoffLinks, regr::AmcPayoffRegression, path::AbstractPath)

Calculate the common components of AMC payoffs for a given valuation path.

at(p::AmcMax, path::AbstractPath)

Evaluate an AmcMax payoff at a given path.

at(p::AmcMin, path::AbstractPath)

Evaluate an AmcMin payoff at a given path.

at(p::AmcOne, path::AbstractPath)

Evaluate an AmcOne payoff at a given path.

at(p::AmcSum, path::AbstractPath)

Evaluate an AmcSum payoff at a given path.

at(p::VanillaAssetOption, path::AbstractPath)

Evaluate a VanillaAssetOption at a given path, X(omega).

string(p::Numeraire)

Formatted (and shortened) output for Numeraire payoff.

string(p::BankAccount)

Formatted (and shortened) output for BankAccount payoff.

string(p::ZeroBond)

Formatted (and shortened) output for ZeroBond payoff.

string(p::Asset)

Formatted (and shortened) output for Asset payoff.

string(p::ForwardAsset)

Formatted (and shortened) output for ForwardAsset payoff.

string(p::Fixing)

Formatted (and shortened) output for Fixing payoff.

string(p::Fixed)

Formatted (and shortened) output for deterministic payoff.

string(p::ScalarValue)

Formatted (and shortened) output for deterministic payoff.

string(p::AssetConvexityAdjustment)

Formatted (and shortened) output for AssetConvexityAdjustment payoff.

string(p::ForwardIndex)

Formatted (and shortened) output for ForwardIndex payoff.

string(p::IndexConvexityAdjustment)

Formatted (and shortened) output for IndexConvexityAdjustment payoff.

string(p::FutureIndex)

Formatted (and shortened) output for FutureIndex payoff.

string(p::Pay)

Formatted (and shortened) output for Pay payoff.

string(p::Cache)

Formatted (and shortened) output for Cache payoff.

string(p::Exp)

Formatted output for Exp payoff.

string(p::Log)

Formatted output for Log payoff.

Formatted addition.

Formatted subtraction.

Formatted multiplication.

Formatted division.

Formatted maximum.

Formatted minimum.

Formatted logical.

string(p::LiborRate)

Formatted (and shortened) output for LiborRate payoff.

string(p::CompoundedRate)

Formatted (and shortened) output for CompoundedRate payoff.

string(p::Optionlet)

Formatted (and shortened) output for Optionlet payoff.

string(p::Swaption)

Formatted (and shortened) output for Swaption payoff.

string(links::AmcPayoffLinks)

Formatted (and shortened) output for AMC payoff links.

string(p::AmcMax)

Formatted (and shortened) output for AmcMax payoff.

string(p::AmcMin)

Formatted (and shortened) output for AmcMin payoff.

string(p::AmcOne)

Formatted (and shortened) output for AmcOne payoff.

string(p::AmcSum)

Formatted (and shortened) output for AmcSum payoff.

string(p::VanillaAssetOption)

Formatted (and shortened) output for VanillaAssetOption payoff.