CommoditySwaptionEngine Class Reference

Commodity Swaption Analytical Engine. More...

#include <qle/pricingengines/commodityswaptionengine.hpp>

Inheritance diagram for CommoditySwaptionEngine:

Collaboration diagram for CommoditySwaptionEngine:

Public Member Functions
	CommoditySwaptionEngine (const Handle< YieldTermStructure > &discountCurve, const Handle< QuantLib::BlackVolTermStructure > &vol, Real beta=0.0)
void	calculate () const override
Public Member Functions inherited from CommoditySwaptionBaseEngine
	CommoditySwaptionBaseEngine (const Handle< YieldTermStructure > &discountCurve, const Handle< QuantLib::BlackVolTermStructure > &vol, Real beta=0.0)

Private Member Functions
QuantLib::Real	expA (QuantLib::Size floatLegIndex, QuantLib::Real normFactor) const
QuantLib::Real	expASquared (QuantLib::Size floatLegIndex, QuantLib::Real strike, QuantLib::Real normFactor) const
QuantLib::Real	crossTerms (const QuantLib::ext::shared_ptr< QuantLib::CashFlow > &cf_1, const QuantLib::ext::shared_ptr< QuantLib::CashFlow > &cf_2, bool isAveraging, QuantLib::Real strike, QuantLib::Real normFactor) const
QuantLib::Real	maxQuantity (QuantLib::Size floatLegIndex) const

Additional Inherited Members
Protected Member Functions inherited from CommoditySwaptionBaseEngine
QuantLib::Size	fixedLegIndex () const
QuantLib::Real	fixedLegValue (QuantLib::Size fixedLegIndex) const
	Give back the fixed leg price at the swaption expiry time. More...
QuantLib::Real	strike (QuantLib::Size fixedLegIndex) const
QuantLib::Real	rho (const QuantLib::Date &ed_1, const QuantLib::Date &ed_2) const
bool	averaging (QuantLib::Size floatLegIndex) const
Protected Attributes inherited from CommoditySwaptionBaseEngine
Handle< YieldTermStructure >	discountCurve_
Handle< QuantLib::BlackVolTermStructure >	volStructure_
Real	beta_

Detailed Description

Commodity Swaption Analytical Engine.

Analytical pricing based on the two-moment Turnbull-Wakeman approximation similar to APO pricing. Reference: Iain Clark, Commodity Option Pricing, Wiley, section 2.8 See also the documentation in the ORE+ product catalogue.

Definition at line 79 of file commodityswaptionengine.hpp.

Constructor & Destructor Documentation

CommoditySwaptionEngine()

CommoditySwaptionEngine	(	const Handle< YieldTermStructure > &	discountCurve,
		const Handle< QuantLib::BlackVolTermStructure > &	vol,
		Real	beta = 0.0
	)

Definition at line 81 of file commodityswaptionengine.hpp.

        : CommoditySwaptionBaseEngine(discountCurve, vol, beta) {}

Member Function Documentation

calculate()

void calculate ( ) const

override

Definition at line 167 of file commodityswaptionengine.cpp.

                                              {
 
    // Get the index of the fixed and floating leg
    Size idxFixed = fixedLegIndex();
    Size idxFloat = idxFixed == 0 ? 1 : 0;
 
    // Fixed leg value is the strike
    Real kStar = fixedLegValue(idxFixed);
 
    // Max quantity is used as a normalisation factor
    Real normFactor = maxQuantity(idxFloat);
 
    // E[A(t_e)] from the ORE+ Product Catalogue
    Real EA = expA(idxFloat, normFactor);
 
    // Fixed leg strike price. This determines the strike at which we query the volatility surface in the
    // calculations. The implementation here just looks at the fixed price in the first period of the fixed leg. If
    // we have an underlying swap where the fixed price varies a lot over different calculation periods, this may
    // lead to a mispricing.
    Real strikePrice = strike(idxFixed);
 
    // E[A^2(t_e)] from the ORE+ Product Catalogue
    Real EAA = expASquared(idxFloat, strikePrice, normFactor);
 
    // Discount factor to the exercise date, P(0, t_e) from the ORE+ Product Catalogue
    Date exercise = arguments_.exercise->dateAt(0);
    Real discountExercise = discountCurve_->discount(exercise);
 
    // Time to swaption expiry, t_e from the ORE+ Product Catalogue
    Time t_e = volStructure_->timeFromReference(exercise);
 
    // sigma_X from the ORE+ Product Catalogue
    Real sigmaX = sqrt(log(EAA / (EA * EA)) / t_e);
 
    // We have used EA to get sigmaX so we can modify EA again now to remove the normalisation factor.
    EA *= normFactor;
 
    // If fixed leg payer flag value is -1 => payer swaption. In this case, we want \omega = 1 in black formula
    // so we need type = Call.
    Option::Type type = arguments_.payer[idxFixed] < 0 ? Option::Call : Option::Put;
 
    // Populate the value using Black-76 formula as documented in ORE+ Product Catalogue
    results_.value = blackFormula(type, kStar, EA, sigmaX * sqrt(t_e), discountExercise);
 
    // Populate some additional results
    results_.additionalResults["Sigma"] = sigmaX;
    results_.additionalResults["Forward"] = EA;
    results_.additionalResults["Strike"] = kStar;
    results_.additionalResults["StrikePrice"] = strikePrice;
    results_.additionalResults["Expiry"] = t_e;
}

Here is the call graph for this function:

expA()

Real expA ( QuantLib::Size  floatLegIndex, QuantLib::Real  normFactor  ) const

private

Calculate the expected value of the floating leg at the swaption expiry date i.e. the expected value of the quantity A(t_e) from the ORE+ Product Catalogue. Quantities in the calculation are divided by the normFactor to guard against numerical blow up.

Definition at line 219 of file commodityswaptionengine.cpp.

                                                                            {
 
    // This is the quantity E[A(t_e)] in the ORE+ Product Catalogue.
    Real value = 0.0;
 
    for (const QuantLib::ext::shared_ptr<CashFlow>& cf : arguments_.legs[floatLegIndex]) {
        value += cf->amount() * discountCurve_->discount(cf->date()) / normFactor;
    }
 
    Date exercise = arguments_.exercise->dateAt(0);
    Real discountExercise = discountCurve_->discount(exercise);
    value /= discountExercise;
 
    return value;
}

Here is the caller graph for this function:

expASquared()

Real expASquared ( QuantLib::Size  floatLegIndex, QuantLib::Real  strike, QuantLib::Real  normFactor  ) const

private

Calculate the expected value of the floating leg squared at the swaption expiry date i.e. the expected value of the quantity A^2(t_e) from the ORE+ Product Catalogue. Quantities in the calculation are divided by the normFactor to guard against numerical blow up.

Definition at line 235 of file commodityswaptionengine.cpp.

                                                                                                {
 
    // This is the quantity E[A^2(t_e)] in the ORE+ Product Catalogue.
    Real value = 0.0;
 
    // Is the floating leg averaging.
    bool isAveraging = averaging(floatLegIndex);
 
    // Calculate E[A^2(t_e)]
    Size numPeriods = arguments_.legs[floatLegIndex].size();
    for (Size i = 0; i < numPeriods; i++) {
        for (Size j = 0; j <= i; j++) {
            Real factor = i == j ? 1.0 : 2.0;
            value += factor * crossTerms(arguments_.legs[floatLegIndex][i], arguments_.legs[floatLegIndex][j],
                                         isAveraging, strike, normFactor);
        }
    }
 
    // Divide through by P^2(0, t_e) to get quantity E[A^2(t_e)] in the ORE+ Product Catalogue.
    Date exercise = arguments_.exercise->dateAt(0);
    Real discountExercise = discountCurve_->discount(exercise);
    value /= (discountExercise * discountExercise);
 
    return value;
}

Here is the call graph for this function:

Here is the caller graph for this function:

crossTerms()

Real crossTerms ( const QuantLib::ext::shared_ptr< QuantLib::CashFlow > &  cf_1, const QuantLib::ext::shared_ptr< QuantLib::CashFlow > &  cf_2, bool  isAveraging, QuantLib::Real  strike, QuantLib::Real  normFactor  ) const

private

Calculate the cross terms involved in expASquared. Quantities in the calculation are divided by the normFactor to guard against numerical blow up.

Definition at line 261 of file commodityswaptionengine.cpp.

                                                                {
 
    // Time to swaption expiry
    Time t_e = volStructure_->timeFromReference(arguments_.exercise->dateAt(0));
 
    // Switch depending on whether the two cashflows are averaging or not
    if (isAveraging) {
 
        // Must have CommodityIndexedAverageCashFlow if averaging
        QuantLib::ext::shared_ptr<CommodityIndexedAverageCashFlow> ccf_1 =
            QuantLib::ext::dynamic_pointer_cast<CommodityIndexedAverageCashFlow>(cf_1);
        QuantLib::ext::shared_ptr<CommodityIndexedAverageCashFlow> ccf_2 =
            QuantLib::ext::dynamic_pointer_cast<CommodityIndexedAverageCashFlow>(cf_2);
 
        // Product of quantities
        Real result = ccf_1->periodQuantity() / normFactor;
        result *= ccf_2->periodQuantity() / normFactor;
 
        // Multiply by discount factor to payment date
        result *= discountCurve_->discount(ccf_1->date());
        result *= discountCurve_->discount(ccf_2->date());
 
        // Divide by number of observations
        result /= ccf_1->indices().size();
        result /= ccf_2->indices().size();
 
        // The cross terms due to the averaging in each cashflow's period. The calculation here differs
        // depending on whether cashflows reference a future price or spot.
        Real cross = 0.0;
        if (ccf_1->useFuturePrice()) {
 
            std::vector<Real> prices1(ccf_1->indices().size()), prices2(ccf_2->indices().size()),
                vol1(ccf_1->indices().size()), vol2(ccf_2->indices().size());
            std::vector<Date> expiries1(ccf_1->indices().size()), expiries2(ccf_2->indices().size());
 
            Size i = 0;
            for (const auto& [d, p] : ccf_1->indices()) {
                expiries1[i] = p->expiryDate();
                Real fxRate{1.};
                if (ccf_1->fxIndex())
                    fxRate = ccf_1->fxIndex()->fixing(expiries1[i]);
                prices1[i] = fxRate * p->fixing(expiries1[i]);
                vol1[i] = volStructure_->blackVol(expiries1[i], strike);
                ++i;
            }
 
            i = 0;
            for (const auto& [d, p] : ccf_2->indices()) {
                expiries2[i] = p->expiryDate();
                Real fxRate{1.};
                if (ccf_2->fxIndex())
                    fxRate = ccf_2->fxIndex()->fixing(expiries2[i]);
                prices2[i] = fxRate * p->fixing(expiries2[i]);
                vol2[i] = volStructure_->blackVol(expiries2[i], strike);
                ++i;
            }
 
            for (Size i = 0; i < prices1.size(); ++i) {
                for (Size j = 0; j < prices2.size(); ++j) {
                    cross += prices1[i] * prices2[j] * exp(rho(expiries1[i], expiries2[j]) * vol1[i] * vol2[j] * t_e);
                }
            }
 
        } else {
 
            std::vector<Real> prices1(ccf_1->indices().size()), prices2(ccf_2->indices().size());
 
            Size i = 0;
            for (const auto& [d, p] : ccf_1->indices()) {
                Real fxRate{1.};
                if (ccf_1->fxIndex())
                    fxRate = ccf_1->fxIndex()->fixing(d);
                prices1[i] = fxRate * p->fixing(d);
                ++i;
            }
 
            i = 0;
            for (const auto& [d, p] : ccf_2->indices()) {
                Real fxRate{1.};
                if (ccf_2->fxIndex())
                    fxRate = ccf_2->fxIndex()->fixing(d);
                prices2[i] = fxRate * p->fixing(d);
                ++i;
            }
 
            for (Size i = 0; i < prices1.size(); ++i) {
                for (Size j = 0; j < prices2.size(); ++j) {
                    cross += prices1[i] * prices2[j];
                }
            }
 
            cross *= exp(volStructure_->blackVariance(t_e, strike));
        }
        result *= cross;
 
        return result;
 
    } else {
 
        // Must have CommodityIndexedCashFlow if not averaging
        QuantLib::ext::shared_ptr<CommodityIndexedCashFlow> ccf_1 = QuantLib::ext::dynamic_pointer_cast<CommodityIndexedCashFlow>(cf_1);
        QuantLib::ext::shared_ptr<CommodityIndexedCashFlow> ccf_2 = QuantLib::ext::dynamic_pointer_cast<CommodityIndexedCashFlow>(cf_2);
 
        // Don't support non-zero spreads or gearing != 1 so amount gives forward * quantity for commodity cashflow
        // referencing spot price or future * quantity for commodity cashflow referencing future price
        Real result = ccf_1->amount() / normFactor;
        result *= ccf_2->amount() / normFactor;
 
        // Multiply by discount factor to payment date
        result *= discountCurve_->discount(ccf_1->date());
        result *= discountCurve_->discount(ccf_2->date());
 
        // Multiply by exp{v} where the quantity v depends on whether commodity is spot or future
        Real v = 0.0;
        if (ccf_1->useFuturePrice()) {
 
            Date e_1 = ccf_1->index()->expiryDate();
            v = volStructure_->blackVol(e_1, strike);
 
            Date e_2 = ccf_2->index()->expiryDate();
            if (e_1 == e_2) {
                v *= v;
            } else {
                v *= volStructure_->blackVol(e_2, strike);
                v *= rho(e_1, e_2);
            }
 
            v *= t_e;
 
        } else {
            v = volStructure_->blackVariance(t_e, strike);
        }
        result *= exp(v);
 
        return result;
    }
}

Here is the call graph for this function:

Here is the caller graph for this function:

maxQuantity()

Real maxQuantity ( QuantLib::Size  floatLegIndex ) const

private

Return the maximum quantity over all cashflows on the commodity floating leg. This is used as a normalisation factor in the calculation of E[A(t_e)] and E[A^2(t_e)] to guard against blow up.

Definition at line 401 of file commodityswaptionengine.cpp.

                                                                  {
 
    Real result = 0.0;
 
    if (averaging(floatLegIndex)) {
        for (const auto& cf : arguments_.legs[floatLegIndex]) {
            auto ccf = QuantLib::ext::dynamic_pointer_cast<CommodityIndexedAverageCashFlow>(cf);
            QL_REQUIRE(ccf, "maxQuantity: expected a CommodityIndexedAverageCashFlow");
            result = max(result, ccf->periodQuantity());
        }
    } else {
        for (const auto& cf : arguments_.legs[floatLegIndex]) {
            auto ccf = QuantLib::ext::dynamic_pointer_cast<CommodityIndexedCashFlow>(cf);
            QL_REQUIRE(ccf, "maxQuantity: expected a CommodityIndexedCashFlow");
            result = max(result, ccf->periodQuantity());
        }
    }
 
    QL_REQUIRE(result > 0.0, "maxQuantity: quantities should be greater than 0.0");
 
    return result;
}

Here is the call graph for this function:

Here is the caller graph for this function: