Products Functions

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.

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.

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

Create a CombinedCashFlow object.

abstract type Coupon <: CashFlow end

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

struct FixedCashFlow <: CashFlow
    pay_time::ModelTime
    amount::ModelValue
end

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

struct FixedRateCoupon <: Coupon
    pay_time::ModelTime
    fixed_rate::ModelValue
    year_fraction::ModelValue
    first_time::Union{ModelTime,Nothing}
end

A fixed rate coupon.

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.

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.

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.

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.

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.

struct RelativeReturnCoupon <: Coupon
    first_time::ModelTime
    second_time::ModelTime
    pay_time::ModelTime
    year_fraction::ModelValue
    asset_key::String
    curve_key_dom::String
    curve_key_for::String
end

A RelativeReturnCoupon pays a coupon with rate (S2/S1 - 1) / dT. Here, S1 and S2 are spot asset prices.

Such a coupon is typical for year-on-year type instruments.

struct RelativeReturnIndexCoupon <: Coupon
    first_time::ModelTime
    second_time::ModelTime
    pay_time::ModelTime
    year_fraction::ModelValue
    forward_index_key::String
end

A RelativeReturnIndexCoupon pays a coupon with rate (I2/I1 - 1) / dT. Here, I1 and I2 are spot (index) prices for which a forward index curve is available.

Such a coupon is typical for year-on-year type instruments.

struct VanillaAssetOptionFlow <: CashFlow
    expiry_time::ModelTime
    pay_time::ModelTime
    strike_price::ModelValue
    call_put::ModelValue
    asset_key::String
end

A CashFlow representing a Call or Put option on an Asset.

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.

pay_time(cf::CombinedCashFlow)

Return the payment time for a CombinedCashFlow.

pay_time(cf::OptionletCoupon)

Return the payment time for a OptionletCoupon.

This coincides with the payment time of the underlying coupon.

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.

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.

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.

year_fraction(cf::Coupon)

Derive the year fraction for a Coupon.

coupon_rate(cf::Coupon)

Return a payoff for the realised simulated effective coupon rate.

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.

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.

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.

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.

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.

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.

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.

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.

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.

future_cashflows(leg::CashFlowLeg, obs_time::ModelTime)

Calculate the list of future undiscounted payoffs in numeraire currency.

discounted_cashflows(leg::CashFlowLeg, obs_time::ModelTime)

Calculate the list of future discounted payoffs in numeraire currency.

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

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.

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.

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.

bermudan_exercise(
    exercise_time::ModelTime,
    cashflow_legs::AbstractVector,
    make_regression_variables::Function,
    )

Create a BermudanExercise and check for valid inputs.

make_bermudan_exercises(
    fixed_leg::DeterministicCashFlowLeg,
    float_leg::DeterministicCashFlowLeg,
    exercise_time::AbstractVector,
    )

Create a list of BermudanExercises from Vanilla swap legs.

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.

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,
    numeraire_curve_key::String,
    regression_on_exercise_trigger = true,
    )

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.

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.

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.

amount(cf::VanillaAssetOptionFlow)

Return the payoff of the VanillaAssetOptionFlow.

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.

coupon_rate(cf::RelativeReturnCoupon)

Return RelativeReturnCoupon rate.

coupon_rate(cf::RelativeReturnIndexCoupon)

Return RelativeReturnIndexCoupon rate.

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.

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.

expected_amount(cf::VanillaAssetOptionFlow, obs_time::ModelTime)

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

This implementation is an approximation and does not capture convexity adjustments.

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.

forward_rate(cf::RelativeReturnCoupon, obs_time::ModelTime)

Return RelativeReturnCoupon forward rate.

forward_rate(cf::RelativeReturnIndexCoupon, obs_time::ModelTime)

Return RelativeReturnIndexCoupon forward rate.

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.

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.

year_fraction(cf::RelativeReturnCoupon)

Return RelativeReturnCoupon year_fraction.

year_fraction(cf::RelativeReturnIndexCoupon)

Return RelativeReturnIndexCoupon year_fraction.