Swaptions

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

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

Calculate the list of future undiscounted payoffs in numeraire currency.

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

Calculate the list of future discounted payoffs in numeraire currency.

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.

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.