# Payoffs Functions

In this section we document the payoff scripting framework.

`DiffFusion.Payoff`

— Type`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_time`

— Method`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_times`

— Method`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.at`

— Method`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.Leaf`

— Type`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.Numeraire`

— Type```
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.BankAccount`

— Type```
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.ZeroBond`

— Type```
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.Asset`

— Type```
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.ForwardAsset`

— Type```
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.Fixing`

— Type```
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.

`DiffFusion.Fixed`

— Type```
struct Fixed <: Leaf
value::ModelValue
end
```

A deterministic quantity.

`DiffFusion.ScalarValue`

— Type```
struct ScalarValue <: Leaf
value::ModelValue
end
```

A scalar deterministic quantity.

## Unary Nodes

`DiffFusion.UnaryNode`

— Type`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.Pay`

— Type```
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.Cache`

— Type```
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.BinaryNode`

— Type`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.Add`

— Type```
struct Add <: BinaryNode
x::Payoff
y::Payoff
end
```

Addition of payoffs.

`DiffFusion.Sub`

— Type```
struct Sub <: BinaryNode
x::Payoff
y::Payoff
end
```

Subtraction of payoffs.

`DiffFusion.Mul`

— Type```
struct Mul <: BinaryNode
x::Payoff
y::Payoff
end
```

Multiplication of payoffs.

`DiffFusion.Div`

— Type```
struct Div <: BinaryNode
x::Payoff
y::Payoff
end
```

Division of payoffs.

`DiffFusion.Max`

— Type```
struct Max <: BinaryNode
x::Payoff
y::Payoff
end
```

Path-wise maximum

`DiffFusion.Min`

— Type```
struct Min <: BinaryNode
x::Payoff
y::Payoff
end
```

Path-wise minimum

`DiffFusion.Logical`

— Type```
struct Logical <: BinaryNode
x::Payoff
y::Payoff
op::String
end
```

Logical operations

## Rates Payoffs

`DiffFusion.LiborRate`

— Type```
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.LiborRate`

— Method```
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.CompoundedRate`

— Type```
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 obs*time less start*time it is equivalent to a Libor rate.

`DiffFusion.CompoundedRate`

— Method```
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.Optionlet`

— Type```
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.Optionlet`

— Type```
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.Swaption`

— Type```
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`

.

`DiffFusion.Swaption`

— Method```
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.

## American Monte Carlo Payoffs

`DiffFusion.AmcPayoff`

— Type`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.AmcPayoffLinks`

— Type```
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.AmcPayoffRegression`

— Type```
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.AmcMax`

— Type```
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`

.

`DiffFusion.AmcMax`

— Method```
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.AmcMin`

— Type```
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`

.

`DiffFusion.AmcMin`

— Method```
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.AmcOne`

— Type```
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`

.

`DiffFusion.AmcOne`

— Method```
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.AmcSum`

— Type```
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.

`DiffFusion.AmcSum`

— Method```
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.calibrate_regression`

— Function`calibrate_regression(links::AmcPayoffLinks, regr::AmcPayoffRegression)`

Calibrate the regression for an AMC payoff.

`DiffFusion.has_amc_payoff`

— Function`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_time`

— Function`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

`DiffFusion.obs_times`

— Function`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.

`DiffFusion.at`

— Function`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::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.

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.

`Base.string`

— Function`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::Pay)`

Formatted (and shortened) output for Pay payoff.

`string(p::Cache)`

Formatted (and shortened) output for Cache 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.