# Payoffs

In this section we document the payoff scripting framework.

## Interface

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

## Basic Payoffs

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

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

## Mathematical Operations

The following payoffs are created by operator overloading of `+`

, `-`

, `*`

, `/`

and logical operators.

`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.Logical`

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

Logical operations

## Mathematical Functions

`DiffFusion.Exp`

— Type```
struct Exp <: UnaryNode
x::Payoff
end
```

Function exp() applied to payoff.

`DiffFusion.Log`

— Type```
struct Log <: UnaryNode
x::Payoff
end
```

Function log() applied to payoff.

`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

## Common Payoff 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

`obs_time(p::VanillaAssetOption)`

Return VanillaAssetOption 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.

`obs_times(p::VanillaAssetOption)`

Return all VanillaAssetOption observation times.

`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::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)*.

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