Cash Flow and Coupons

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 FixedCashFlow <: CashFlow
    pay_time::ModelTime
    amount::ModelValue
end

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

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

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.

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.

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.

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.

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.