ApoFutureSurface Class Reference

Average future price option (APO) surface derived from a future option surface. More...

#include <qle/termstructures/aposurface.hpp>

Inheritance diagram for ApoFutureSurface:

Collaboration diagram for ApoFutureSurface:

Public Member Functions
	ApoFutureSurface (const QuantLib::Date &referenceDate, const std::vector< QuantLib::Real > &moneynessLevels, const QuantLib::ext::shared_ptr< CommodityIndex > &index, const QuantLib::Handle< PriceTermStructure > &pts, const QuantLib::Handle< QuantLib::YieldTermStructure > &yts, const QuantLib::ext::shared_ptr< FutureExpiryCalculator > &expCalc, const QuantLib::Handle< QuantLib::BlackVolTermStructure > &baseVts, const QuantLib::ext::shared_ptr< FutureExpiryCalculator > &baseExpCalc, QuantLib::Real beta=0.0, bool flatStrikeExtrapolation=true, const boost::optional< QuantLib::Period > &maxTenor=boost::none)
TermStructure interface
QuantLib::Date	maxDate () const override
VolatilityTermStructure interface
QuantLib::Real	minStrike () const override
QuantLib::Real	maxStrike () const override
Visitability
void	accept (QuantLib::AcyclicVisitor &v) override
Observer interface
void	update () override
LazyObject interface
void	performCalculations () const override
Inspectors
const QuantLib::ext::shared_ptr< BlackVarianceSurfaceMoneyness > &	vts () const

BlackVolatilityTermStructure
QuantLib::ext::shared_ptr< CommodityIndex >	index_
QuantLib::ext::shared_ptr< FutureExpiryCalculator >	baseExpCalc_
std::vector< QuantLib::Date >	apoDates_
	The APO schedule dates. More...
std::vector< std::vector< QuantLib::ext::shared_ptr< QuantLib::SimpleQuote > > >	vols_
	This will keep a handle on the APO vol quotes that are calculated. More...
QuantLib::ext::shared_ptr< BlackVarianceSurfaceMoneyness >	vts_
	The surface that is created to do the work. More...
QuantLib::ext::shared_ptr< CommodityAveragePriceOptionBaseEngine >	apoEngine_
	The engine for valuing the APOs. More...
QuantLib::Volatility	blackVolImpl (QuantLib::Time t, QuantLib::Real strike) const override

Detailed Description

Average future price option (APO) surface derived from a future option surface.

Definition at line 40 of file aposurface.hpp.

Constructor & Destructor Documentation

ApoFutureSurface()

ApoFutureSurface	(	const QuantLib::Date &	referenceDate,
		const std::vector< QuantLib::Real > &	moneynessLevels,
		const QuantLib::ext::shared_ptr< CommodityIndex > &	index,
		const QuantLib::Handle< PriceTermStructure > &	pts,
		const QuantLib::Handle< QuantLib::YieldTermStructure > &	yts,
		const QuantLib::ext::shared_ptr< FutureExpiryCalculator > &	expCalc,
		const QuantLib::Handle< QuantLib::BlackVolTermStructure > &	baseVts,
		const QuantLib::ext::shared_ptr< FutureExpiryCalculator > &	baseExpCalc,
		QuantLib::Real	beta = 0.0,
		bool	flatStrikeExtrapolation = true,
		const boost::optional< QuantLib::Period > &	maxTenor = boost::none
	)

Definition at line 30 of file aposurface.cpp.

    : BlackVolatilityTermStructure(referenceDate, baseVts->calendar(), baseVts->businessDayConvention(),
                                   baseVts->dayCounter()),
      index_(index), baseExpCalc_(baseExpCalc), vols_(moneynessLevels.size()) {
 
    // Checks.
    QL_REQUIRE(!pts.empty(), "The price term structure should not be empty.");
    QL_REQUIRE(!yts.empty(), "The yield term structure should not be empty.");
    QL_REQUIRE(expCalc, "The expiry calculator should not be null.");
    QL_REQUIRE(!baseVts.empty(), "The base volatility term structure should not be empty.");
    QL_REQUIRE(!index_->priceCurve().empty(), "The commodity index should have a base price curve.");
    QL_REQUIRE(baseExpCalc_, "The base expiry calculator should not be null.");
 
    // Register with dependent term structures.
    registerWith(pts);
    registerWith(yts);
    registerWith(baseVts);
 
    // Determine the maximum expiry of the APO surface that we will build
    Date maxDate;
    if (maxTenor) {
        // If maxTenor is provided, use it.
        maxDate = referenceDate + *maxTenor;
    } else {
        maxDate = baseVts->maxDate();
        if (maxDate == Date::maxDate() || maxDate == Date()) {
            maxDate = pts->maxDate();
            QL_REQUIRE(maxDate != Date::maxDate() && maxDate != Date(),
                       "Could not determine a maximum date for the ApoFutureSurface");
        }
    }
    QL_REQUIRE(maxDate > referenceDate, "Expected the max date, " << io::iso_date(maxDate)
                                                                  << ", to be greater than the reference date, "
                                                                  << io::iso_date(referenceDate) << ".");
 
    // Get the start and end dates of each APO that will be used to create the APO surface in the expiry direction.
    // Here, we use the expiry calculator, expCalc. This expiry calculator will generally be from the corresponding
    // averaging future contracts. We will be using this APO surface to price these averaging futures as standard
    // non-averaging commodity options. The averaging future contract expiry will equal the APO expiry.
    apoDates_ = { expCalc->priorExpiry(true, referenceDate) };
    vector<Time> apoTimes;
    while (apoDates_.back() < maxDate) {
        apoDates_.push_back(expCalc->nextExpiry(false, apoDates_.back()));
        apoTimes.push_back(timeFromReference(apoDates_.back()));
    }
 
    // Spot quote based on the price curve and adapted yield term structure
    Handle<Quote> spot(QuantLib::ext::make_shared<DerivedPriceQuote>(pts));
    Handle<YieldTermStructure> pyts =
        Handle<YieldTermStructure>(QuantLib::ext::make_shared<PriceTermStructureAdapter>(*pts, *yts));
    pyts->enableExtrapolation();
 
    // Hard-code this to false.
    bool stickyStrike = false;
 
    // Initialise the matrix of quotes for use in vts_. These will be populated/updated in performCalculations by
    // pricing all of the APOs and extracting the volatility from each of them. Rows are moneyness levels and columns
    // are expiry times in the matrix of quotes that are fed to vts_'s ctor.
    vector<vector<Handle<Quote> > > vols(moneynessLevels.size());
    for (Size i = 0; i < moneynessLevels.size(); i++) {
        for (Size j = 0; j < apoTimes.size(); j++) {
            vols_[i].push_back(QuantLib::ext::make_shared<SimpleQuote>(0.0));
            vols[i].push_back(Handle<Quote>(vols_[i].back()));
        }
    }
 
    // Initialise the underlying helping volatility structure.
    vts_ = QuantLib::ext::make_shared<BlackVarianceSurfaceMoneynessForward>(calendar_, spot, apoTimes, moneynessLevels, vols,
                                                                    baseVts->dayCounter(), pyts, yts, stickyStrike,
                                                                    flatStrikeExtrapolation);
 
    vts_->enableExtrapolation();
 
    // Initialise the engine for performing the APO valuations.
    apoEngine_ = QuantLib::ext::make_shared<CommodityAveragePriceOptionAnalyticalEngine>(yts, baseVts, beta);
}

Here is the call graph for this function:

Member Function Documentation

maxDate()

Date maxDate ( ) const

override

Definition at line 113 of file aposurface.cpp.

{ return vts_->maxDate(); }

Here is the caller graph for this function:

minStrike()

Real minStrike ( ) const

override

Definition at line 115 of file aposurface.cpp.

{ return vts_->minStrike(); }

maxStrike()

Real maxStrike ( ) const

override

Definition at line 117 of file aposurface.cpp.

{ return vts_->maxStrike(); }

accept()

void accept ( QuantLib::AcyclicVisitor &  v )

override

Definition at line 119 of file aposurface.cpp.

                                               {
    if (auto v1 = dynamic_cast<Visitor<ApoFutureSurface>*>(&v))
        v1->visit(*this);
    else
        QL_FAIL("Not an ApoFutureSurface visitor");
}

update()

void update ( )

override

Definition at line 126 of file aposurface.cpp.

                              {
    TermStructure::update();
    LazyObject::update();
}

performCalculations()

void performCalculations ( ) const

override

Definition at line 131 of file aposurface.cpp.

                                                 {
 
    // Quantity is 1.0 everywhere below.
    Real quantity = 1.0;
 
    for (Size j = 1; j < apoDates_.size(); j++) {
 
        // Set up the APO cashflow with from apoDates_[j-1] to apoDates_[j]
        auto cf =
            QuantLib::ext::make_shared<CommodityIndexedAverageCashFlow>(quantity, apoDates_[j - 1], apoDates_[j], apoDates_[j],
                                                                index_, Calendar(), 0.0, 1.0, true, 0, 0, baseExpCalc_);
 
        // The APO cashflow forward rate is the amount
        Real forward = cf->amount();
 
        // Some of the sigmas will be Null<Real>() in the first APO period if the accrued is already greater than the
        // strike. So store the sigmas in a vector in the first step and then update the quotes as a second step.
        // idx will point to the first element in sigmas not equal to Null<Real>().
        vector<Real> sigmas(vts_->moneyness().size());
        for (Size i = 0; i < vts_->moneyness().size(); i++) {
 
            // "exercise date" is just the last date of the APO cashflow.
            auto exercise = QuantLib::ext::make_shared<EuropeanExercise>(apoDates_[j]);
 
            // Apply moneyness to forward rate to get current strike
            Real strike = vts_->moneyness()[i] * forward;
 
            // Create the APO and call NPV() to trigger population of results.
            CommodityAveragePriceOption apo(cf, exercise, 1.0, strike, Option::Call);
            apo.setPricingEngine(apoEngine_);
            apo.NPV();
 
            auto it = apo.additionalResults().find("sigma");
            if (it != apo.additionalResults().end())
                sigmas[i] = boost::any_cast<Real>(it->second);
            else
                sigmas[i] = Null<Real>();
        }
 
        QL_REQUIRE(sigmas.back() != Null<Real>(), "All of the sigmas are null.");
 
        for (Size i = vts_->moneyness().size(); i > 0; i--) {
 
            // Know already that the last sigma is not null.
            if (sigmas[i - 1] == Null<Real>())
                sigmas[i - 1] = sigmas[i];
 
            // Update the quote
            vols_[i - 1][j - 1]->setValue(sigmas[i - 1]);
        }
    }
}

vts()

const QuantLib::ext::shared_ptr< BlackVarianceSurfaceMoneyness > & vts

(

)

const

Definition at line 184 of file aposurface.cpp.

{ return vts_; }

blackVolImpl()

Volatility blackVolImpl ( QuantLib::Time  t, QuantLib::Real  strike  ) const

overrideprotected

Definition at line 186 of file aposurface.cpp.

                                                                   {
    calculate();
    return vts_->blackVol(t, strike, true);
}

Member Data Documentation

index_

QuantLib::ext::shared_ptr<CommodityIndex> index_

private

Definition at line 90 of file aposurface.hpp.

baseExpCalc_

QuantLib::ext::shared_ptr<FutureExpiryCalculator> baseExpCalc_

private

Definition at line 91 of file aposurface.hpp.

apoDates_

std::vector<QuantLib::Date> apoDates_

private

The APO schedule dates.

Definition at line 94 of file aposurface.hpp.

vols_

std::vector<std::vector<QuantLib::ext::shared_ptr<QuantLib::SimpleQuote> > > vols_

private

This will keep a handle on the APO vol quotes that are calculated.

Definition at line 97 of file aposurface.hpp.

vts_

QuantLib::ext::shared_ptr<BlackVarianceSurfaceMoneyness> vts_

private

The surface that is created to do the work.

Definition at line 100 of file aposurface.hpp.

apoEngine_

QuantLib::ext::shared_ptr<CommodityAveragePriceOptionBaseEngine> apoEngine_

private

The engine for valuing the APOs.

Definition at line 103 of file aposurface.hpp.