Products Functions

In this section we document product objects and methods.

Cash Flow and Coupon Types

DiffFusion.CashFlowType
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.CombinedCashFlowType
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_cashflowFunction
combined_cashflow(
    first::CashFlow,
    second::CashFlow,
    op::Function,
    )

Create a CombinedCashFlow object.

DiffFusion.CouponType
abstract type Coupon <: CashFlow end

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

DiffFusion.FixedCashFlowType
struct FixedCashFlow <: CashFlow
    pay_time::ModelTime
    amount::ModelValue
end

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

DiffFusion.FixedRateCouponType
struct FixedRateCoupon <: Coupon
    pay_time::ModelTime
    fixed_rate::ModelValue
    year_fraction::ModelValue
end

A fixed rate coupon.

DiffFusion.SimpleRateCouponType
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.CompoundedRateCouponType
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.OptionletCouponType
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.OptionletCouponMethod
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.OptionletCouponMethod
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_timeMethod
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_timeMethod
pay_time(cf::CombinedCashFlow)

Return the payment time for a CombinedCashFlow.

DiffFusion.pay_timeMethod
pay_time(cf::OptionletCoupon)

Return the payment time for a OptionletCoupon.

This coincides with the payment time of the underlying coupon.

DiffFusion.first_timeFunction
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.amountMethod
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_amountMethod
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.coupon_rateMethod
coupon_rate(cf::Coupon)

Return a payoff for the realised simulated effective coupon rate.

DiffFusion.forward_rateMethod
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.CashFlowLegType
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.DeterministicCashFlowLegType
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_legFunction
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.MtMCashFlowLegType
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_legFunction
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.CashBalanceLegType
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_legFunction
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.AssetLegType

An 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_cashflowsMethod
future_cashflows(leg::CashFlowLeg, obs_time::ModelTime)

Calculate the list of future undiscounted payoffs in numeraire currency.

DiffFusion.discounted_cashflowsMethod
discounted_cashflows(leg::CashFlowLeg, obs_time::ModelTime)

Calculate the list of future discounted payoffs in numeraire currency.

Swaption Cash Flow Legs

DiffFusion.SwaptionSettlementType
@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.SwaptionLegType
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.SwaptionLegType
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.BermudanExerciseType
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 CashFlowLegs.

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_exerciseMethod
bermudan_exercise(
    exercise_time::ModelTime,
    cashflow_legs::AbstractVector,
    make_regression_variables::Function,
    )

Create a BermudanExercise and check for valid inputs.

DiffFusion.make_bermudan_exercisesFunction
make_bermudan_exercises(
    fixed_leg::DeterministicCashFlowLeg,
    float_leg::DeterministicCashFlowLeg,
    exercise_time::AbstractVector,
    )

Create a list of BermudanExercises from Vanilla swap legs.

DiffFusion.BermudanSwaptionLegType

A Bermudan swaption implemented as a CashFlowLeg.

alias is the leg alias.

bermudan_exercises is a list of BermudanExercises 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 AmcPayoffs.

hold_values is a list of Payoffs per BermudanExercise that represent the option prices if not exercised.

exercise_triggers is a list of Payoffs 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_legFunction
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 AmcPayoffs. 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.amountFunction
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_rateFunction
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_cashflowsFunction
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_amountFunction
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_rateFunction
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_cashflowsFunction
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_fractionFunction
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.