# Products Functions

In this section we document product objects and methods.

## Cash Flow and Coupon Types

`DiffFusion.CashFlow`

— Type`abstract type CashFlow end`

A CashFlow represents a general payment in an unspecified currency.

In a simulation, we calculate discounted expected cash flows in a consistent numeraire currency.

The `CashFlow`

object is inspired by QuantLib's CashFlow interface.

We apply the convention that cash flows are formulated for unit notionals. Actual notionals are applied at the level of legs. This design aims at simplifying MTM cross currency swap legs with notional exchange.

`DiffFusion.CombinedCashFlow`

— Type```
struct CombinedCashFlow <: CashFlow
first::CashFlow
second::CashFlow
op::Function
end
```

A composition of two cash flows in a single cash flow.

This `CashFlow`

type is intended e.g. for spreads and caplets/floorlets.

`DiffFusion.combined_cashflow`

— Function```
combined_cashflow(
first::CashFlow,
second::CashFlow,
op::Function,
)
```

Create a CombinedCashFlow object.

`DiffFusion.Coupon`

— Type`abstract type Coupon <: CashFlow end`

A Coupon is a payment that is composed of an (effective) coupon rate and a year fraction.

`DiffFusion.FixedCashFlow`

— Type```
struct FixedCashFlow <: CashFlow
pay_time::ModelTime
amount::ModelValue
end
```

A simple deterministic cash flow (normalised to one unit notional)

`DiffFusion.FixedRateCoupon`

— Type```
struct FixedRateCoupon <: Coupon
pay_time::ModelTime
fixed_rate::ModelValue
year_fraction::ModelValue
end
```

A fixed rate coupon.

`DiffFusion.SimpleRateCoupon`

— Type```
struct SimpleRateCoupon <: Coupon
fixing_time::ModelTime
start_time::ModelTime
end_time::ModelTime
pay_time::ModelTime
year_fraction::ModelValue
curve_key::String
fixing_key::Union{String, Nothing}
spread_rate::Union{ModelValue, Nothing}
end
```

A (legacy) Libor or Euribor rate coupon.

`DiffFusion.CompoundedRateCoupon`

— Type```
struct CompoundedRateCoupon <: Coupon
period_times::AbstractVector
period_year_fractions::AbstractVector
pay_time::ModelTime
curve_key::String
fixing_key::Union{String, Nothing}
spread_rate::Union{ModelValue, Nothing}
end
```

A backward-looking compounded RFR coupon.

`DiffFusion.OptionletCoupon`

— Type```
struct OptionletCoupon <: Coupon
expiry_time::ModelTime
coupon::Union{SimpleRateCoupon, CompoundedRateCoupon}
strike_rate::ModelValue
call_put::ModelValue
coupon_type::DataType # distinguish constructors
end
```

A caplet or floorlet coupon on a forward-looking or backward-looking rate.

`DiffFusion.OptionletCoupon`

— Method```
OptionletCoupon(
expiry_time::ModelTime,
coupon::Union{SimpleRateCoupon, CompoundedRateCoupon},
strike_rate::ModelValue,
call_put::ModelValue,
)
```

Create an `OptionletCoupon`

object from an underlying `SimpleRateCoupon`

or `CompoundedRateCoupon`

.

Option `expiry_time`

is specified by user.

`DiffFusion.OptionletCoupon`

— Method```
OptionletCoupon(
expiry_time::ModelTime,
coupon::Union{SimpleRateCoupon, CompoundedRateCoupon},
strike_rate::ModelValue,
call_put::ModelValue,
)
```

Create an `OptionletCoupon`

object from an underlying `SimpleRateCoupon`

or `CompoundedRateCoupon`

.

Option `expiry_time`

is determined from underlying coupon.

## Cash Flow and Coupon Methods

`DiffFusion.pay_time`

— Method`pay_time(cf::CashFlow)`

Return the payment time for a CashFlow.

This represents a default implementation

This method is used to calculate discounted expected values.

`DiffFusion.pay_time`

— Method`pay_time(cf::CombinedCashFlow)`

Return the payment time for a CombinedCashFlow.

`DiffFusion.pay_time`

— Method`pay_time(cf::OptionletCoupon)`

Return the payment time for a OptionletCoupon.

This coincides with the payment time of the underlying coupon.

`DiffFusion.first_time`

— Function`first_time(cf::Coupon)`

Derive the first event time of the `Coupon`

.

This time is used in conjunction with call rights to determine whether a coupon period is already broken.

`first_time(cf::FixedRateCoupon)`

Derive the first event time of the `FixedRateCoupon`

.

`first_time(cf::SimpleRateCoupon)`

Derive the first event time of the `SimpleRateCoupon`

.

`first_time(cf::CompoundedRateCoupon)`

Derive the first event time of the `CompoundedRateCoupon`

.

`DiffFusion.amount`

— Method`amount(cf::CashFlow)`

Return the payoff representing the simulated cash flow amount of the payment.

This method is intended to be used for general payoffs in conjunction with AMC.

`DiffFusion.expected_amount`

— Method`expected_amount(cf::CashFlow, obs_time::ModelTime)`

Return the payoff representing the simulated expected amount of the payment.

Expectation is calculated in $T$-forward measure of cash flow currency with $T$ being the payment time and conditioning on observation time.

This method is intended to be used for analytical pricers.

`DiffFusion.year_fraction`

— Method`year_fraction(cf::Coupon)`

Derive the year fraction for a Coupon.

`DiffFusion.coupon_rate`

— Method`coupon_rate(cf::Coupon)`

Return a payoff for the realised simulated effective coupon rate.

`DiffFusion.forward_rate`

— Method`forward_rate(cf::Coupon, obs_time::ModelTime)`

Return a payoff for the effective forward rate of the coupon.

Expectation is calculated in T-forward measure of cash flow currency with T being the payment time and conditioning on observation time.

This method is intended to be used for analytical pricers.

## Cash Flow Legs

`DiffFusion.CashFlowLeg`

— Type`abstract type CashFlowLeg end`

A `CashFlowLeg`

combines `CashFlow`

objects in a single currency and adds notional and payer/receiver information and discounting.

We apply the convention that notionals are non-negative and cash flows are modelled from the receiving counter party perspective. This does include the exceptions of negative spread cash flows or negative notional exchange cash flows.

`DiffFusion.DeterministicCashFlowLeg`

— Type```
struct DeterministicCashFlowLeg <: CashFlowLeg
alias::String
cashflows::AbstractVector
notionals::AbstractVector
curve_key::String
fx_key::Union{String, Nothing}
payer_receiver::ModelValue
end
```

A DeterministicCashFlowLeg models legs with deterministic notionals.

`DiffFusion.cashflow_leg`

— Function```
cashflow_leg(
alias::String,
cashflows::AbstractVector,
notionals::AbstractVector,
curve_key::Union{String, Nothing} = nothing,
fx_key::Union{String, Nothing} = nothing,
payer_receiver = 1.0,
)
```

Create a DeterministicCashFlowLeg.

```
cashflow_leg(
alias::String,
cashflows::AbstractVector,
notional::ModelValue,
curve_key::Union{String, Nothing} = nothing,
fx_key::Union{String, Nothing} = nothing,
payer_receiver = 1.0,
)
```

Create a constant notional CashFlowLeg.

`DiffFusion.MtMCashFlowLeg`

— Type```
struct MtMCashFlowLeg <: CashFlowLeg
alias::String
cashflows::AbstractVector
intitial_notional::ModelValue
curve_key_dom::String
curve_key_for::String
fx_key_dom::Union{String, Nothing}
fx_key_for::Union{String, Nothing}
fx_reset_times::AbstractVector
fx_pay_times::AbstractVector
payer_receiver::ModelValue
end
```

A mark-to-market (MtM) cross currency cash flow leg adds notional resets to the cash flow payments.

Notional resets are calculated from FX rates at reset times.

We consider a setting with numeraire currency, domestic currency and foreign currency.

Cash flows are denominated in domestic currency. Initial notional is expressed in foreign currency and simulation is modelled in numeraire currency.

We denote `fx_key_for`

the FOR-NUM asset key and `fx_key_dom`

the DOM-NUM asset key.

FX rates for notional exchange are fixed at `fx_reset_times`

and notional cash flows are exchanged at `fx_pay_times`

. The very first notional exchange is not modelled because it is either in the past or foreign and domestic notional exchange offset each other.

As a consequence, we have one `fx_reset_time`

and one `fx_pay_time`

per cash flow. The `fx_reset_time`

is at (or before) the start of the coupon period and `fx_pay_time`

is at (or after) the end of the coupon period.

`DiffFusion.mtm_cashflow_leg`

— Function```
mtm_cashflow_leg(
alias::String,
cashflows::AbstractVector,
intitial_notional::ModelValue,
curve_key_dom::String,
curve_key_for::String,
fx_key_dom::Union{String, Nothing},
fx_key_for::Union{String, Nothing},
fx_reset_times::AbstractVector,
fx_pay_times::AbstractVector,
payer_receiver::ModelValue,
)
```

Create a MTM cash flow leg.

```
mtm_cashflow_leg(
alias::String,
leg::DeterministicCashFlowLeg,
intitial_notional::ModelValue, # in foreign currency
initial_reset_time::ModelValue,
curve_key_for::String,
fx_key_for::Union{String, Nothing},
)
```

Create a MtM cash flow leg from a deterministic leg.

`DiffFusion.CashBalanceLeg`

— Type```
struct CashBalance <: CashFlowLeg
alias::String
notional::ModelValue
fx_key::Union{String, Nothing}
payer_receiver::ModelValue
maturity_time::Union{Nothing, ModelTime}
end
```

A CashLeg represents a constant cash balance in domestic or foreign corrency.

`DiffFusion.cash_balance_leg`

— Function```
cash_balance_leg(
alias::String,
notional::ModelValue,
fx_key::Union{String, Nothing} = nothing,
payer_receiver::ModelValue = +1.0,
maturity_time::Union{Nothing, ModelTime} = nothing
)
```

Create a CashBalance object.

`DiffFusion.AssetLeg`

— TypeAn AssetLeg represents a position in a tradeable asset. Such tradeable asset can be, e.g., a share price, index price or an (FOR-DOM) FX rate where DOM currency differs from numeraire currency.

`DiffFusion.future_cashflows`

— Method`future_cashflows(leg::CashFlowLeg, obs_time::ModelTime)`

Calculate the list of future undiscounted payoffs in numeraire currency.

`DiffFusion.discounted_cashflows`

— Method`discounted_cashflows(leg::CashFlowLeg, obs_time::ModelTime)`

Calculate the list of future discounted payoffs in numeraire currency.

## Swaption Cash Flow Legs

`DiffFusion.SwaptionSettlement`

— Type```
@enum(
SwaptionSettlement,
SwaptionCashSettlement,
SwaptionPhysicalSettlement,
)
```

SwaptionSettlement specifies whether swaption terminates at settlement time or whether it is converted into a physicl swap.

For `SwaptionCashSettlement`

the cash price is calculated as model price, i.e. physical price at expiry.

`DiffFusion.SwaptionLeg`

— Type```
struct SwaptionLeg <: CashFlowLeg
alias::String
#
expiry_time::ModelTime
settlement_time::ModelTime
float_coupons::AbstractVector
fixed_coupons::AbstractVector
payer_receiver::ModelValue
swap_disc_curve_key::String
settlement_type::SwaptionSettlement
#
notional::ModelValue
swpt_disc_curve_key::String
swpt_fx_key::Union{String, Nothing}
swpt_long_short::ModelValue
#
fixed_times::AbstractVector
fixed_weights::AbstractVector
fixed_rate::ModelValue
exercise_indicator::Payoff
end
```

A European swaption referencing a Vanilla swap with forward looking or backward looking rates.

`DiffFusion.SwaptionLeg`

— Type```
SwaptionLeg(
alias::String,
#
expiry_time::ModelTime,
settlement_time::ModelTime,
float_coupons::AbstractVector,
fixed_coupons::AbstractVector,
payer_receiver::ModelValue,
swap_disc_curve_key::String,
settlement_type::SwaptionSettlement,
#
notional::ModelValue,
swpt_disc_curve_key::String = swap_disc_curve_key,
swpt_fx_key::Union{String, Nothing} = nothing,
swpt_long_short::ModelValue = +1.0,
)
```

Create a swaption object.

`DiffFusion.BermudanExercise`

— Type```
struct BermudanExercise
exercise_time::ModelTime
cashflow_legs::AbstractVector
make_regression_variables::Function
end
```

A container holding the information about an exercise event of a `BermudanSwaptionLeg`

.

Here, `exercise_time`

is the individual option exercise time and `cashflow_legs`

is a list of `CashFlowLeg`

s.

The cash flows in the cash flow legs are supposed to start after `exercise_time`

. That is, the `BermudanExercise`

manages the lag between option exercise and option settlement.

`make_regression_variables`

is a function with signature

`(exercise_time) -> [ regr_payoff_1, ..., regr_payoff_N ].`

The function takes observation time as input to allow for re-usable fuctions. It returns a list of regression payoffs used for this particular exercise.

The result of the function is passed on to the `AmcPayoff`

creation.

`DiffFusion.bermudan_exercise`

— Method```
bermudan_exercise(
exercise_time::ModelTime,
cashflow_legs::AbstractVector,
make_regression_variables::Function,
)
```

Create a `BermudanExercise`

and check for valid inputs.

`DiffFusion.make_bermudan_exercises`

— Function```
make_bermudan_exercises(
fixed_leg::DeterministicCashFlowLeg,
float_leg::DeterministicCashFlowLeg,
exercise_time::AbstractVector,
)
```

Create a list of `BermudanExercise`

s from Vanilla swap legs.

`DiffFusion.BermudanSwaptionLeg`

— TypeA Bermudan swaption implemented as a `CashFlowLeg`

.

`alias`

is the leg alias.

`bermudan_exercises`

is a list of `BermudanExercise`

s in ascending order.

`option_long_short`

is `+1`

for a long option position (buy) and `-1`

for a short option position (sell).

`numeraire_curve_key`

is a discount curve key used for numeraie calculation in `AmcPayoff`

s.

`hold_values`

is a list of `Payoff`

s per `BermudanExercise`

that represent the option prices if not exercised.

`exercise_triggers`

is a list of `Payoff`

s per `BermudanExercise`

that represent the indicator whether option was not exercised at respective exercise time.

`make_regression_variables`

is a function with signature

`(obs_time) -> [ regr_payoff_1, ..., regr_payoff_N ].`

The function takes observation time as input to allow for re-usable fuctions. It returns a list of regression payoffs used for regression to current observation time.

The result of the function `make_regression_variables`

is passed on to the `AmcPayoff`

creation.

`regression_data`

holds function to create a regression and a `Path`

to calibrate the regression. Details are passed on to `AmcPayoff`

at creation. The elements are supposed to be updated subsequent to `BermudanSwaptionLeg`

creation. This should allow decoupling of leg creation and usage.

`DiffFusion.bermudan_swaption_leg`

— Function```
bermudan_swaption_leg(
alias::String,
bermudan_exercises::AbstractVector,
option_long_short::ModelValue,
numeraire_curve_key::String,
make_regression_variables::Function,
path::Union{AbstractPath, Nothing},
make_regression::Union{Function, Nothing},
)
```

Create a `BermudanSwaptionLeg`

.

Calculate hold value payoffs and exercise trigger payoffs and setup the `BermudanSwaptionLeg`

object.

`alias`

, `bermudan_exercises`

, `option_long_short`

, `numeraire_curve_key`

, and `make_regression_variables`

are passed on to `BermudanSwaptionLeg`

.

`path`

and `make_regression`

are used to create an `AmcPayoffRegression`

object for `AmcPayoff`

s. This data is supposed to be updated subsequent to leg cretion.

`regression_on_exercise_trigger = true`

specifies AMC regression strategy. If `regression_on_exercise_trigger = then`

then regression on regression is used. `regression_on_exercise_trigger = true`

is recommended for accurate sensitivity calculation.

```
bermudan_swaption_leg(
alias::String,
fixed_leg::DeterministicCashFlowLeg,
float_leg::DeterministicCashFlowLeg,
exercise_times::AbstractVector,
option_long_short::ModelValue,
regression_on_exercise_trigger = false,
)
```

Create a `BermudanSwaptionLeg`

using simplified interface.

`regression_on_exercise_trigger = true`

specifies AMC regression strategy. If `regression_on_exercise_trigger = then`

then regression on regression is used. `regression_on_exercise_trigger = true`

is recommended for accurate sensitivity calculation.

`DiffFusion.reset_regression!`

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

## Common Methods Overview

`DiffFusion.amount`

— Function`amount(cf::CashFlow)`

Return the payoff representing the simulated cash flow amount of the payment.

This method is intended to be used for general payoffs in conjunction with AMC.

`amount(cf::Coupon)`

Calculate payment amount for a Coupon.

`amount(cf::FixedCashFlow)`

Return FixedCashFlow amount.

`amount(cf::CombinedCashFlow)`

Return the payoff representing the simulated cash flow amount of the payment.

`DiffFusion.coupon_rate`

— Function`coupon_rate(cf::Coupon)`

Return a payoff for the realised simulated effective coupon rate.

`coupon_rate(cf::FixedRateCoupon)`

Return FixedRateCoupon rate.

`coupon_rate(cf::SimpleRateCoupon)`

Return SimpleRateCoupon rate.

`coupon_rate(cf::CompoundedRateCoupon)`

Return CompoundedRateCoupon rate.

`coupon_rate(cf::OptionletCoupon)`

Return OptionletCoupon rate.

`DiffFusion.discounted_cashflows`

— Function`discounted_cashflows(leg::CashFlowLeg, obs_time::ModelTime)`

Calculate the list of future discounted payoffs in numeraire currency.

`discounted_cashflows(leg::DeterministicCashFlowLeg, obs_time::ModelTime)`

Calculate the list of future discounted payoffs in numeraire currency.

`discounted_cashflows(leg::SwaptionLeg, obs_time::ModelTime)`

Calculate the list of future discounted payoffs in numeraire currency.

`discounted_cashflows(leg::MtMCashFlowLeg, obs_time::ModelTime)`

Calculate the list of future discounted payoffs in numeraire currency.

`discounted_cashflows(leg::CashBalanceLeg, obs_time::ModelTime)`

Calculate the list of future discounted payoffs in numeraire currency.

`discounted_cashflows(leg::AssetLeg, obs_time::ModelTime)`

Calculate the list of future discounted payoffs in numeraire currency.

`discounted_cashflows(leg::BermudanSwaptionLeg, obs_time::ModelTime)`

Calculate the list of future discounted payoffs in numeraire currency.

Critical aspect is to consider the path-dependent exercise into the option underlying.

Consider an `obs_time`

after a given `BermudanExercise`

(last exercise). For this implementation, we make the assumption that exercise at `obs_time`

will only be into the underlying of the last exercise.

Above assumption is does not pose a limitation if all underlyings are the same, i.e. standard Bermudans.

Above assumption is a limitation if the Bermudan can be exercised into different underlyings per exercise time. This corresponds to a more complex trigger option.

Above assumption can be relaxed at the expense of calculating discounted cash flows for all (earlier) underlyings.

`DiffFusion.expected_amount`

— Function`expected_amount(cf::CashFlow, obs_time::ModelTime)`

Return the payoff representing the simulated expected amount of the payment.

Expectation is calculated in $T$-forward measure of cash flow currency with $T$ being the payment time and conditioning on observation time.

This method is intended to be used for analytical pricers.

`expected_amount(cf::Coupon, obs_time::ModelTime)`

Calculate expected payment amount for a Coupon.

`expected_amount(cf::FixedCashFlow, obs_time::ModelTime)`

Return FixedCashFlow expected amount.

`expected_amount(cf::CombinedCashFlow, obs_time::ModelTime)`

Return the payoff representing the simulated expected amount of the payment.

`DiffFusion.forward_rate`

— Function`forward_rate(ts::YieldTermstructure, t::ModelTime, dt=1.0e-6)`

Return the instantaneous forward rate with observation time `t`

.

`forward_rate(cf::Coupon, obs_time::ModelTime)`

Return a payoff for the effective forward rate of the coupon.

Expectation is calculated in T-forward measure of cash flow currency with T being the payment time and conditioning on observation time.

This method is intended to be used for analytical pricers.

`forward_rate(cf::FixedRateCoupon, obs_time::ModelTime)`

Return FixedRateCoupon forward rate.

`forward_rate(cf::SimpleRateCoupon, obs_time::ModelTime)`

Return SimpleRateCoupon forward rate.

`forward_rate(cf::CompoundedRateCoupon, obs_time::ModelTime)`

Return CompoundedRateCoupon forward rate.

`forward_rate(cf::OptionletCoupon, obs_time::ModelTime)`

Return OptionletCoupon forward rate.

`DiffFusion.future_cashflows`

— Function`future_cashflows(leg::CashFlowLeg, obs_time::ModelTime)`

Calculate the list of future undiscounted payoffs in numeraire currency.

`future_cashflows(leg::DeterministicCashFlowLeg, obs_time::ModelTime)`

Calculate the list of future undiscounted payoffs in numeraire currency.

`future_cashflows(leg::SwaptionLeg, obs_time::ModelTime)`

Calculate the list of future undiscounted payoffs in numeraire currency.

`future_cashflows(leg::MtMCashFlowLeg, obs_time::ModelTime)`

Calculate the list of future undiscounted payoffs in numeraire currency.

`future_cashflows(leg::CashBalanceLeg, obs_time::ModelTime)`

Calculate the list of future undiscounted payoffs in numeraire currency.

`future_cashflows(leg::AssetLeg, obs_time::ModelTime)`

Calculate the list of future undiscounted payoffs in numeraire currency.

`DiffFusion.year_fraction`

— Function`year_fraction(cf::Coupon)`

Derive the year fraction for a Coupon.

`year_fraction(cf::FixedRateCoupon)`

Return FixedRateCoupon year_fraction.

`year_fraction(cf::SimpleRateCoupon)`

Return SimpleRateCoupon year_fraction.

`year_fraction(cf::CompoundedRateCoupon)`

Return CompoundedRateCoupon year_fraction.

`year_fraction(cf::OptionletCoupon)`

Return OptionletCoupon year_fraction.