CommoditySwaptionMonteCarloEngine Class Reference

Commodity Swaption Monte Carlo Engine. More...

#include <qle/pricingengines/commodityswaptionengine.hpp>

Inheritance diagram for CommoditySwaptionMonteCarloEngine:

Collaboration diagram for CommoditySwaptionMonteCarloEngine:

Public Member Functions
	CommoditySwaptionMonteCarloEngine (const Handle< YieldTermStructure > &discountCurve, const Handle< QuantLib::BlackVolTermStructure > &vol, Size samples, Real beta=0.0, const Size seed=42)
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
void	calculateSpot (QuantLib::Size idxFixed, QuantLib::Size idxFloat, QuantLib::Real strike) const
	Calculations when underlying swap references a commodity spot price. More...
void	calculateFuture (QuantLib::Size idxFixed, QuantLib::Size idxFloat, QuantLib::Real strike) const
	Calculations when underlying swap references a commodity spot price. More...
QuantLib::Real	spotFloatLegFactor (QuantLib::Size idxFloat, QuantLib::Real discountExercise) const
void	futureFloatLegFactors (QuantLib::Size idxFloat, QuantLib::Real discountExercise, const std::vector< QuantLib::Date > &expiries, QuantLib::Matrix &floatLegFactors, QuantLib::Array &discounts, QuantLib::Array &amounts) const
std::map< QuantLib::Date, QuantLib::Real >	futureExpiries (QuantLib::Size idxFloat, QuantLib::Matrix &outSqrtCorr, QuantLib::Real strike) const

Private Attributes
Size	samples_
long	seed_

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 Monte Carlo Engine.

Monte Carlo implementation of the Swaption payoff for as documented in ORE+ Product Catalogue. Reference: Iain Clark, Commodity Option Pricing, Wiley, section 2.8

Definition at line 116 of file commodityswaptionengine.hpp.

Constructor & Destructor Documentation

CommoditySwaptionMonteCarloEngine()

CommoditySwaptionMonteCarloEngine	(	const Handle< YieldTermStructure > &	discountCurve,
		const Handle< QuantLib::BlackVolTermStructure > &	vol,
		Size	samples,
		Real	beta = 0.0,
		const Size	seed = 42
	)

Definition at line 118 of file commodityswaptionengine.hpp.

        : CommoditySwaptionBaseEngine(discountCurve, vol, beta), samples_(samples), seed_(seed) {}

Member Function Documentation

calculate()

void calculate ( ) const

override

Definition at line 424 of file commodityswaptionengine.cpp.

                                                        {
 
    // Get the index of the fixed and floating leg
    Size idxFixed = fixedLegIndex();
    Size idxFloat = idxFixed == 0 ? 1 : 0;
 
    // Determines the strike at which we read values from the vol surface.
    Real strikePrice = strike(idxFixed);
 
    // Switch implementation depending on whether underlying swap references a spot or future price
    if (referencesFuturePrice(arguments_.legs[idxFloat])) {
        calculateFuture(idxFixed, idxFloat, strikePrice);
    } else {
        calculateSpot(idxFixed, idxFloat, strikePrice);
    }
}

Here is the call graph for this function:

calculateSpot()

void calculateSpot ( QuantLib::Size  idxFixed, QuantLib::Size  idxFloat, QuantLib::Real  strike  ) const

private

Calculations when underlying swap references a commodity spot price.

Definition at line 441 of file commodityswaptionengine.cpp.

                                                                                                     {
 
    // Fixed leg value
    Real valueFixedLeg = fixedLegValue(idxFixed);
 
    // If float leg payer flag is 1 (-1) => rec (pay) float and pay (rec) fixed => omega = 1 (-1) for payer (receiver).
    Real omega = arguments_.payer[idxFloat];
 
    // Time to swaption expiry
    Date exercise = arguments_.exercise->dateAt(0);
    Time t_e = volStructure_->timeFromReference(exercise);
 
    // Discount to exercise
    Real discountExercise = discountCurve_->discount(exercise);
 
    // Variance of spot process to expiry
    Real var = volStructure_->blackVariance(t_e, strike);
    Real stdDev = sqrt(var);
 
    // Sample spot is S_i(t_e) = F(0, t_e) exp(-var / 2) exp(stdDev z_i). factor is second two term here.
    Real factor = exp(-var / 2.0);
 
    // Populate these values below
    Real optionValue = 0.0;
    Real swapValue = 0.0;
    Real floatLegValue = 0.0;
 
    // Create the standard normal RNG
    LowDiscrepancy::rsg_type rsg = LowDiscrepancy::make_sequence_generator(1, seed_);
 
    // Get the value that when multiplied by the sample value gives the float leg value
    Real floatFactor = spotFloatLegFactor(idxFloat, discountExercise);
 
    // Value swap at swaption exercise date over a number, i = 1, ..., N of samples i.e. \hat{V}_i(t_e) from ORE+
    // Product Catalogue. Value of the swaption at time 0 is then P(0, t_e) \sum_{i=1}^{N} \hat{V}^{+}_i(t_e) / N
    for (Size i = 0; i < samples_; i++) {
 
        // Sample value is S_i(t_e) / F(0, t_e) = exp(-var / 2) exp(stdDev z_i).
        Real sample = factor * exp(stdDev * rsg.nextSequence().value[0]);
 
        // Calculate float leg value and swap value given sample
        Real sampleFloatLegValue = floatFactor * sample;
        Real sampleSwapValue = omega * (sampleFloatLegValue - valueFixedLeg);
 
        // Update values dividing by samples each time to guard against blow up.
        optionValue += max(sampleSwapValue, 0.0) / samples_;
        swapValue += sampleSwapValue / samples_;
        floatLegValue += sampleFloatLegValue / samples_;
    }
 
    // Populate the results remembering to multiply by P(0, t_e)
    results_.value = discountExercise * optionValue;
    results_.additionalResults["SwapNPV"] = discountExercise * swapValue;
    results_.additionalResults["FixedLegNPV"] = discountExercise * valueFixedLeg;
    results_.additionalResults["FloatingLegNPV"] = discountExercise * floatLegValue;
}

Here is the call graph for this function:

Here is the caller graph for this function:

calculateFuture()

void calculateFuture ( QuantLib::Size  idxFixed, QuantLib::Size  idxFloat, QuantLib::Real  strike  ) const

private

Calculations when underlying swap references a commodity spot price.

Definition at line 498 of file commodityswaptionengine.cpp.

                                                                                                       {
 
    // Fixed leg value
    Real valueFixedLeg = fixedLegValue(idxFixed);
 
    // Unique expiry dates
    Matrix sqrtCorr;
    map<Date, Real> expiries = futureExpiries(idxFloat, sqrtCorr, strike);
 
    // Generate n _independent_ standard normal variables {Z_{i,1}, ..., Z_{i,n}} where n is the number of future
    // contracts that we are modelling and i = 1, ..., N is the number of samples. It is a speed-up to set n = 1 if
    // correlation between all the future contracts is 1.0 i.e. beta_ = 0.0. We don't do this and prefer code clarity.
    LowDiscrepancy::rsg_type rsg = LowDiscrepancy::make_sequence_generator(expiries.size(), seed_);
 
    // If float leg payer flag is 1 (-1) => rec (pay) float and pay (rec) fixed => omega = 1 (-1) for payer (receiver).
    Real omega = arguments_.payer[idxFloat];
 
    // Time to swaption expiry
    Date exercise = arguments_.exercise->dateAt(0);
    Time t_e = volStructure_->timeFromReference(exercise);
 
    // Discount to exercise
    Real discountExercise = discountCurve_->discount(exercise);
 
    // Precalculate exp{-var_j / 2} and stdDev_j mentioned in comment above
    vector<Real> expVar;
    vector<Real> stdDev;
    vector<Date> expiryDates;
    for (const auto& p : expiries) {
        Real var = p.second * p.second * t_e;
        expVar.push_back(exp(-var / 2.0));
        stdDev.push_back(sqrt(var));
        expiryDates.push_back(p.first);
    }
 
    // Populate these values below
    Real optionValue = 0.0;
    Real swapValue = 0.0;
    Real floatLegValue = 0.0;
 
    // Values that will be used to calculate floating leg value on each iteration. We precalculate as much as
    // possible here to avoid calculation on each iteration.
    Size numCfs = arguments_.legs[idxFloat].size();
    Matrix factors(numCfs, expiries.size(), 0.0);
    Array discounts(numCfs, 0.0);
    Array amounts(numCfs, 0.0);
    futureFloatLegFactors(idxFloat, discountExercise, expiryDates, factors, discounts, amounts);
    Array factor = (discounts * amounts) * factors;
 
    // Value swap at swaption exercise date over a number, i = 1, ..., N of samples i.e. \hat{V}_i(t_e) from ORE+
    // Product Catalogue. Value of the swaption at time 0 is then P(0, t_e) \sum_{i=1}^{N} \hat{V}^{+}_i(t_e) / N
    for (Size i = 0; i < samples_; i++) {
 
        // sequence is n independent standard normal random variables
        vector<Real> sequence = rsg.nextSequence().value;
 
        // w holds n correlated standard normal variables
        Array w = sqrtCorr * Array(sequence.begin(), sequence.end());
 
        // Update w to hold the sample value that we want i.e.
        //   F_{i,j}(t_e) / F_{i,j}(0) = exp{-var_j / 2} exp{stdDev_j w_{i,j}}
        // where j = 1,..., n indexes the futures (i.e. date keys in the map)
        // and i = 1,..., N indexes the number of Monte Carlo samples.
        for (Size i = 0; i < w.size(); i++) {
            w[i] = exp(stdDev[i] * w[i]) * expVar[i];
        }
 
        // Calculate float leg value on this iteration
        Real sampleFloatLegValue = DotProduct(factor, w);
 
        // Calculate the swap leg value on this iteration
        Real sampleSwapValue = omega * (sampleFloatLegValue - valueFixedLeg);
 
        // Update values dividing by samples each time to guard against blow up.
        optionValue += max(sampleSwapValue, 0.0) / samples_;
        swapValue += sampleSwapValue / samples_;
        floatLegValue += sampleFloatLegValue / samples_;
    }
 
    // Populate the results remembering to multiply by P(0, t_e)
    results_.value = discountExercise * optionValue;
    results_.additionalResults["SwapNPV"] = discountExercise * swapValue;
    results_.additionalResults["FixedLegNPV"] = discountExercise * valueFixedLeg;
    results_.additionalResults["FloatingLegNPV"] = discountExercise * floatLegValue;
}

Here is the call graph for this function:

Here is the caller graph for this function:

spotFloatLegFactor()

Real spotFloatLegFactor ( QuantLib::Size  idxFloat, QuantLib::Real  discountExercise  ) const

private

Calculate the underlying spot float leg factor value at expiry time. This quantity will be multiplied by a sample value on each Monte Carlo iteration to give the swap float leg value.

Definition at line 584 of file commodityswaptionengine.cpp.

                                                                                                     {
 
    // Different float leg valuation depending on whether leg is averaging or not.
    Real floatLegValue = 0.0;
    if (averaging(idxFloat)) {
        for (const auto& cf : arguments_.legs[idxFloat]) {
            auto ccf = QuantLib::ext::dynamic_pointer_cast<CommodityIndexedAverageCashFlow>(cf);
            QL_REQUIRE(ccf, "spotSwapValue: expected a CommodityIndexedAverageCashFlow");
            Real disc = discountCurve_->discount(ccf->date());
            floatLegValue += disc * ccf->amount();
        }
    } else {
        for (const auto& cf : arguments_.legs[idxFloat]) {
            auto ccf = QuantLib::ext::dynamic_pointer_cast<CommodityIndexedCashFlow>(cf);
            QL_REQUIRE(ccf, "spotSwapValue: expected a CommodityIndexedCashFlow");
            Real disc = discountCurve_->discount(ccf->date());
            floatLegValue += disc * ccf->amount();
        }
    }
 
    // Divide floating leg value by discount to swaption expiry
    floatLegValue /= discountExercise;
 
    // Return the swap value at the expiry date t_e
    return floatLegValue;
}

Here is the call graph for this function:

Here is the caller graph for this function:

futureFloatLegFactors()

void futureFloatLegFactors ( QuantLib::Size  idxFloat, QuantLib::Real  discountExercise, const std::vector< QuantLib::Date > &  expiries, QuantLib::Matrix &  floatLegFactors, QuantLib::Array &  discounts, QuantLib::Array &  amounts  ) const

private

Populate the factors that we need to value the floating leg of a swap referencing a future contract given a Monte Carlo sample. This is to avoid recalculation of these quantities on each iteration.

Definition at line 611 of file commodityswaptionengine.cpp.

                                                                                                      {
 
    Size numCfs = arguments_.legs[idxFloat].size();
 
    QL_REQUIRE(numCfs == floatLegFactors.rows(),
               "Expected number of rows in floatLegFactors to equal number of cashflows");
    QL_REQUIRE(numCfs == discounts.size(), "Expected size of discounts to equal number of cashflows");
    QL_REQUIRE(numCfs == amounts.size(), "Expected size of amounts to equal number of cashflows");
    QL_REQUIRE(expiries.size() == floatLegFactors.columns(),
               "Expected number of columns in floatLegFactors to equal number of expiries");
 
    // Different float leg valuation depending on whether leg is averaging or not.
    if (averaging(idxFloat)) {
        for (Size i = 0; i < numCfs; i++) {
            auto ccf = QuantLib::ext::dynamic_pointer_cast<CommodityIndexedAverageCashFlow>(arguments_.legs[idxFloat][i]);
            QL_REQUIRE(ccf, "futureFloatLegFactors: expected a CommodityIndexedAverageCashFlow");
            Size numObs = ccf->indices().size();
            for (const auto& p : ccf->indices()) {
                Date expiry = p.second->expiryDate();
                auto it = find(expiries.begin(), expiries.end(), expiry);
                QL_REQUIRE(it != expiries.end(), "futureFloatLegFactors: expected to find expiry in expiries vector");
                auto idx = distance(expiries.begin(), it);
                Real fxRate{1.};
                if (ccf->fxIndex())
                    fxRate = ccf->fxIndex()->fixing(expiry);
                floatLegFactors[i][idx] += fxRate * p.second->fixing(expiry) / numObs;
            }
            discounts[i] = discountCurve_->discount(ccf->date());
            amounts[i] = ccf->periodQuantity();
        }
    } else {
        for (Size i = 0; i < numCfs; i++) {
            auto ccf = QuantLib::ext::dynamic_pointer_cast<CommodityIndexedCashFlow>(arguments_.legs[idxFloat][i]);
            QL_REQUIRE(ccf, "futureFloatLegFactors: expected a CommodityIndexedCashFlow");
 
            auto it = find(expiries.begin(), expiries.end(), ccf->index()->expiryDate());
            QL_REQUIRE(it != expiries.end(), "futureFloatLegFactors: expected to find expiry in expiries vector");
            auto idx = distance(expiries.begin(), it);
            floatLegFactors[i][idx] = 1.0;
            discounts[i] = discountCurve_->discount(ccf->date());
            amounts[i] = ccf->amount();
        }
    }
 
    // Divide discounts by discount to swaption expiry
    for (Size i = 0; i < discounts.size(); i++) {
        discounts[i] /= discountExercise;
    }
}

Here is the call graph for this function:

Here is the caller graph for this function:

futureExpiries()

map< Date, Real > futureExpiries ( QuantLib::Size  idxFloat, QuantLib::Matrix &  outSqrtCorr, QuantLib::Real  strike  ) const

private

Given the index of the floating leg idxFloat, populate a map where the keys are the unique expiry dates of the future contracts referenced in the floating leg and the values are the volatilities associated with the future contract. Also, the matrix outSqrtCorr is poulated with the square root of the correlation matrix between the expiries.

An exception is thrown if the floating leg is not referencing a commodity future price.

Definition at line 663 of file commodityswaptionengine.cpp.

                                                                                     {
 
    // Will hold the result
    map<Date, Real> result;
 
    // Populate the unique future expiry dates referenced on the floating leg
    if (averaging(idxFloat)) {
        for (const auto& cf : arguments_.legs[idxFloat]) {
            auto ccf = QuantLib::ext::dynamic_pointer_cast<CommodityIndexedAverageCashFlow>(cf);
            QL_REQUIRE(ccf, "futureExpiries: expected a CommodityIndexedAverageCashFlow");
            QL_REQUIRE(ccf->useFuturePrice(), "futureExpiries: expected the cashflow to reference a future price");
            for (const auto& p : ccf->indices()) {
                result[p.second->expiryDate()] = 0.0;
            }
        }
    } else {
        for (const auto& cf : arguments_.legs[idxFloat]) {
            auto ccf = QuantLib::ext::dynamic_pointer_cast<CommodityIndexedCashFlow>(cf);
            QL_REQUIRE(ccf, "futureExpiries: expected a CommodityIndexedCashFlow");
            QL_REQUIRE(ccf->useFuturePrice(), "futureExpiries: expected the cashflow to reference a future price");
            result[ccf->index()->expiryDate()] = 0.0;
        }
    }
 
    // Populate the map values i.e. the instantaneous volatility associated with the future contract whose expiry date
    // is the map key. Here, we make the simplifying assumption that the volatility can be read from the volatility
    // term structure at the future contract's expiry date. In most cases, if the volatility term structure is built
    // from options on futures, the option contract expiry will be a number of days before the future contract expiry
    // and we should really read off the term structure at that date. Also populate a temp vector containing the key
    // dates for use in the loop below where we populate the sqrt correlation matrix.
    vector<Date> expiryDates;
    for (auto& p : result) {
        p.second = volStructure_->blackVol(p.first, strike);
        expiryDates.push_back(p.first);
    }
 
    // Populate the outSqrtCorr matrix
    outSqrtCorr = Matrix(expiryDates.size(), expiryDates.size(), 1.0);
    for (Size i = 0; i < expiryDates.size(); i++) {
        for (Size j = 0; j < i; j++) {
            outSqrtCorr[i][j] = outSqrtCorr[j][i] = rho(expiryDates[i], expiryDates[j]);
        }
    }
    outSqrtCorr = pseudoSqrt(outSqrtCorr, SalvagingAlgorithm::None);
 
    return result;
}

Here is the call graph for this function:

Here is the caller graph for this function:

Member Data Documentation

samples_

Size samples_

private

Definition at line 153 of file commodityswaptionengine.hpp.

seed_

long seed_

private

Definition at line 154 of file commodityswaptionengine.hpp.