# Payoffs Functions

In this section we document the payoff scripting framework.

DiffFusion.PayoffType
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.

DiffFusion.obs_timeMethod
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.

DiffFusion.obs_timesMethod
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.

DiffFusion.atMethod
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)

## Leafs

DiffFusion.LeafType
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.

DiffFusion.NumeraireType
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.

DiffFusion.BankAccountType
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.

DiffFusion.ZeroBondType
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.

DiffFusion.AssetType
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.

DiffFusion.ForwardAssetType
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.

DiffFusion.AssetConvexityAdjustmentType
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.

DiffFusion.ForwardIndexType
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.

DiffFusion.IndexConvexityAdjustmentType
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.

DiffFusion.FutureIndexType
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.

DiffFusion.FixingType
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.

## Unary Nodes

DiffFusion.UnaryNodeType
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.

DiffFusion.ExpType
struct Exp <: UnaryNode
x::Payoff
end

Function exp() applied to payoff.

DiffFusion.LogType
struct Log <: UnaryNode
x::Payoff
end

Function log() applied to payoff.

DiffFusion.PayType
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.

DiffFusion.CacheType
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.

## Binary Nodes

DiffFusion.BinaryNodeType
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.

DiffFusion.AddType
struct Add <: BinaryNode
x::Payoff
y::Payoff
end

DiffFusion.SubType
struct Sub <: BinaryNode
x::Payoff
y::Payoff
end

Subtraction of payoffs.

DiffFusion.MulType
struct Mul <: BinaryNode
x::Payoff
y::Payoff
end

Multiplication of payoffs.

DiffFusion.DivType
struct Div <: BinaryNode
x::Payoff
y::Payoff
end

Division of payoffs.

## Rates Payoffs

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

A simple compounded forward Libor rate.

DiffFusion.LiborRateMethod
LiborRate(
obs_time::ModelTime,
start_time::ModelTime,
end_time::ModelTime,
key::String,
)

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

DiffFusion.CompoundedRateType
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.

DiffFusion.CompoundedRateMethod
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.

DiffFusion.OptionletType
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)]^+.

DiffFusion.OptionletType
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.

DiffFusion.SwaptionType
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
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.

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

Create a Swaption payoff.

## Asset Option Payoffs

DiffFusion.VanillaAssetOptionType
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.

## American Monte Carlo Payoffs

DiffFusion.AmcPayoffType
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.

DiffFusion.AmcPayoffLinksType
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.

DiffFusion.AmcPayoffRegressionType
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.

DiffFusion.AmcMaxType
struct AmcMax <: AmcPayoff
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.

DiffFusion.AmcMaxMethod
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.

DiffFusion.AmcMinType
struct AmcMin <: AmcPayoff
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.

DiffFusion.AmcMinMethod
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.

DiffFusion.AmcOneType
struct AmcOne <: AmcPayoff
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.

DiffFusion.AmcOneMethod
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.

DiffFusion.AmcSumType
struct AmcSum <: AmcPayoff
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.

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

Create an AmcSum payoff.

DiffFusion.reset_regression!Function
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.

DiffFusion.has_amc_payoffFunction
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.

## Common Methods Overview

DiffFusion.obs_timeFunction
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.

DiffFusion.obs_timesFunction
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.

DiffFusion.atFunction
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.

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

Base.stringFunction
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 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.