Builder for a COM model component. More...

#include <ored/model/commodityschwartzmodelbuilder.hpp>

Inheritance diagram for CommoditySchwartzModelBuilder:

Collaboration diagram for CommoditySchwartzModelBuilder:

Public Member Functions
	CommoditySchwartzModelBuilder (const QuantLib::ext::shared_ptr< ore::data::Market > &market, const QuantLib::ext::shared_ptr< CommoditySchwartzData > &data, const QuantLib::Currency &baseCcy, const std::string &configuration=Market::defaultConfiguration, const std::string &referenceCalibrationGrid="")
	Constructor. More...

Real	error () const
	Return calibration error. More...

Inspectors
std::string	name ()

QuantLib::ext::shared_ptr< QuantExt::CommoditySchwartzParametrization >	parametrization () const

QuantLib::ext::shared_ptr< QuantExt::CommoditySchwartzModel >	model () const

std::vector< QuantLib::ext::shared_ptr< BlackCalibrationHelper > >	optionBasket () const

Public Member Functions inherited from ModelBuilder
void	recalibrate () const

virtual void	forceRecalculate ()

virtual bool	requiresRecalibration () const=0

ModelBuilder interface
const QuantLib::ext::shared_ptr< ore::data::Market >	market_

const std::string	configuration_

const QuantLib::ext::shared_ptr< CommoditySchwartzData >	data_

const std::string	referenceCalibrationGrid_

const QuantLib::Currency	baseCcy_

Real	error_

QuantLib::ext::shared_ptr< QuantExt::CommoditySchwartzParametrization >	parametrization_

QuantLib::ext::shared_ptr< QuantExt::CommoditySchwartzModel >	model_

std::vector< bool >	optionActive_

std::vector< QuantLib::ext::shared_ptr< BlackCalibrationHelper > >	optionBasket_

Array	optionExpiries_

Handle< Quote >	fxSpot_

Handle< QuantExt::PriceTermStructure >	curve_

Handle< BlackVolTermStructure >	vol_

std::vector< QuantLib::Real >	volCache_

bool	forceCalibration_ = false

QuantLib::ext::shared_ptr< QuantExt::MarketObserver >	marketObserver_

std::vector< Real >	calibrationErrors_

Array	params_

void	forceRecalculate () override

bool	requiresRecalibration () const override

void	performCalculations () const override

Real	optionStrike (const Size j) const

Date	optionExpiry (const Size j) const

void	buildOptionBasket () const

bool	volSurfaceChanged (const bool updateCache) const

Detailed Description

Builder for a COM model component.

This class is a utility to turn a COM model component's description into a COM model parametrization which can be used to ultimately instantiate a CrossAssetModel. h

Definition at line 49 of file commodityschwartzmodelbuilder.hpp.

Constructor & Destructor Documentation

◆ CommoditySchwartzModelBuilder()

CommoditySchwartzModelBuilder	(	const QuantLib::ext::shared_ptr< ore::data::Market > &	market,
		const QuantLib::ext::shared_ptr< CommoditySchwartzData > &	data,
		const QuantLib::Currency &	baseCcy,
		const std::string &	configuration = `Market::defaultConfiguration`,
		const std::string &	referenceCalibrationGrid = `""`
	)

Constructor.

Parameters

market	Market object
data	EQ model parameters/description
baseCcy	base currency for calibration
configuration	Market configuration to use
referenceCalibrationGrid	the reference calibration grid

Definition at line 40 of file commodityschwartzmodelbuilder.cpp.

    : market_(market), configuration_(configuration), data_(data), referenceCalibrationGrid_(referenceCalibrationGrid),
      baseCcy_(baseCcy) {
 
    optionActive_ = std::vector<bool>(data_->optionExpiries().size(), false);
    marketObserver_ = QuantLib::ext::make_shared<MarketObserver>();
    QuantLib::Currency ccy = ore::data::parseCurrency(data->currency());
    string name = data->name();
 
    LOG("Start building CommoditySchwartz model for " << name);
 
    // get market data
    std::string fxCcyPair = ccy.code() + baseCcy_.code();
    fxSpot_ = market_->fxRate(fxCcyPair, configuration_);
    curve_ = market_->commodityPriceCurve(name, configuration_);
    vol_ = market_->commodityVolatility(name, configuration_);
 
    // register with market observables except vols
    marketObserver_->registerWith(fxSpot_);
    marketObserver_->registerWith(curve_);
 
    // register the builder with the vol and the market observer
    registerWith(vol_);
    registerWith(marketObserver_);
 
    // notify observers of all market data changes, not only when not calculated
    alwaysForwardNotifications();
 
    // build option basket and derive parametrization from it
    if (data->calibrateSigma() || data->calibrateKappa())
        buildOptionBasket();
 
    parametrization_ = QuantLib::ext::make_shared<QuantExt::CommoditySchwartzParametrization>(ccy, name, curve_, fxSpot_,
                                                                                      data->sigmaValue(), data->kappaValue(),
                                                                                      data->driftFreeState());
    model_ = QuantLib::ext::make_shared<QuantExt::CommoditySchwartzModel>(parametrization_);
    params_ = model_->params();
}

Here is the call graph for this function:

Member Function Documentation

◆ error()

Real error ( ) const

Return calibration error.

Definition at line 87 of file commodityschwartzmodelbuilder.cpp.

                                                {
    calculate();
    return error_;
}

◆ name()

std::string name ( )

Definition at line 68 of file commodityschwartzmodelbuilder.hpp.

68{ return data_->name(); }

Here is the caller graph for this function:

◆ parametrization()

QuantLib::ext::shared_ptr< QuantExt::CommoditySchwartzParametrization > parametrization ( ) const

Definition at line 92 of file commodityschwartzmodelbuilder.cpp.

                                                                                                                     {
    calculate();
    return parametrization_;
}

◆ model()

QuantLib::ext::shared_ptr< QuantExt::CommoditySchwartzModel > model ( ) const

Definition at line 82 of file commodityschwartzmodelbuilder.cpp.

                                                                                                 {
    calculate();
    return model_;
}

◆ optionBasket()

std::vector< QuantLib::ext::shared_ptr< BlackCalibrationHelper > > optionBasket ( ) const

Definition at line 96 of file commodityschwartzmodelbuilder.cpp.

                                                                                                           {
    calculate();
    return optionBasket_;
}

◆ forceRecalculate()

void forceRecalculate ( )

overridevirtual

Reimplemented from ModelBuilder.

Definition at line 269 of file commodityschwartzmodelbuilder.cpp.

                                                     {
    forceCalibration_ = true;
    ModelBuilder::forceRecalculate();
    forceCalibration_ = false;
}

Here is the call graph for this function:

◆ requiresRecalibration()

bool requiresRecalibration ( ) const

overridevirtual

Implements ModelBuilder.

Definition at line 101 of file commodityschwartzmodelbuilder.cpp.

                                                                {
    return (data_->calibrateSigma() || data_->calibrateKappa()) &&
           (volSurfaceChanged(false) || marketObserver_->hasUpdated(false) || forceCalibration_);
}

Here is the call graph for this function:

Here is the caller graph for this function:

◆ performCalculations()

void performCalculations ( ) const

overrideprivate

Definition at line 106 of file commodityschwartzmodelbuilder.cpp.

                                                              {
    if (requiresRecalibration()) {
        DLOG("COM model requires recalibration");
 
        // reset market observer updated flag
        marketObserver_->hasUpdated(true);
        // build option basket
        buildOptionBasket();
        // update vol cache
        volSurfaceChanged(true);
 
        // attach pricing engine to helpers
        QuantLib::ext::shared_ptr<QuantExt::CommoditySchwartzFutureOptionEngine> engine =
            QuantLib::ext::make_shared<QuantExt::CommoditySchwartzFutureOptionEngine>(model_);
        for (Size j = 0; j < optionBasket_.size(); j++)
            optionBasket_[j]->setPricingEngine(engine);
 
        QL_REQUIRE(data_->calibrationType() != CalibrationType::Bootstrap, "Bootstrap COM calibration not supported yet");
 
        if (data_->calibrationType() == CalibrationType::None ||
            (data_->calibrateSigma() == false && data_->calibrateKappa() == false)) {
            LOG("COM calibration is deactivated in the CommoditySchwartzModelData for name " << data_->name());
            return;
        }
 
        // check which parameters are kept fixed
        std::vector<bool> fix(model_->parametrization()->numberOfParameters(), true);
        std::vector<Real> weights;
        Size freeParams = 0;
        if (data_->calibrateSigma()) {
            fix[0] = false;
            freeParams++;
            LOG("CommoditySchwartzModel: calibrate sigma for name " << data_->name());
        }
        if (data_->calibrateKappa()) {
            fix[1] = false;
            freeParams++;
            LOG("CommoditySchwartzModel: calibrate kappa for name " << data_->name());
        }
        if (freeParams == 0) {
            WLOG("CommoditySchwartzModel: skip calibration for name " << data_->name() << ", no free parameters");
            error_ = 0.0;
            return;
        }
 
        // use identical start values for each calibration to ensure identical results for identical baskets
        model_->setParams(params_);
 
        LOG("CommoditySchwartzModel for name " << data_->name() << " before calibration:"
            << " sigma=" << parametrization_->sigmaParameter()
            << " kappa=" << parametrization_->kappaParameter());
 
        model_->calibrate(optionBasket_, *data_->optimizationMethod(), data_->endCriteria(), data_->constraint(), weights, fix);
 
        LOG("CommoditySchwartzModel for name " << data_->name() << " after calibration:"
            << " sigma=" << parametrization_->sigmaParameter()
            << " kappa=" << parametrization_->kappaParameter());
 
        error_ = getCalibrationError(optionBasket_);
        LOG("CommoditySchwartzModel calibration rmse error " << error_ << " for name " << data_->name());
        try {
            auto d = getCalibrationDetails(optionBasket_, parametrization_);
            DLOG(d);
        } catch (const std::exception& e) {
            WLOG("An error occurred: " << e.what());
        }
    }
}

Here is the call graph for this function:

◆ optionStrike()

Real optionStrike ( const Size j ) const

private

Definition at line 175 of file commodityschwartzmodelbuilder.cpp.

                                                                   {
    ore::data::Strike strike = ore::data::parseStrike(data_->optionStrikes()[j]);
    Real strikeValue;
    // TODO: Extend strike type coverage
    if (strike.type == ore::data::Strike::Type::ATMF)
        strikeValue = Null<Real>();
    else if (strike.type == ore::data::Strike::Type::Absolute)
        strikeValue = strike.value;
    else
        QL_FAIL("strike type ATMF or Absolute expected");
    return strikeValue;
}

Here is the call graph for this function:

Here is the caller graph for this function:

◆ optionExpiry()

Date optionExpiry ( const Size j ) const

private

Definition at line 188 of file commodityschwartzmodelbuilder.cpp.

                                                                   {
    Date today = Settings::instance().evaluationDate();
    std::string expiryString = data_->optionExpiries()[j];
    bool expiryDateBased;
    Period expiryPb;
    Date expiryDb;
    parseDateOrPeriod(expiryString, expiryDb, expiryPb, expiryDateBased);
    Date expiryDate = expiryDateBased ? expiryDb : today + expiryPb;
    return expiryDate;
}

Here is the call graph for this function:

Here is the caller graph for this function:

◆ buildOptionBasket()

void buildOptionBasket ( ) const

private

Definition at line 221 of file commodityschwartzmodelbuilder.cpp.

                                                            {
 
    QL_REQUIRE(data_->optionExpiries().size() == data_->optionStrikes().size(), "Commodity option vector size mismatch");
 
    optionActive_ = std::vector<bool>(data_->optionExpiries().size(), false);
 
    DLOG("build reference date grid '" << referenceCalibrationGrid_ << "'");
    Date lastRefCalDate = Date::minDate();
    std::vector<Date> referenceCalibrationDates;
    if (!referenceCalibrationGrid_.empty())
        referenceCalibrationDates = DateGrid(referenceCalibrationGrid_).dates();
 
    std::vector<Time> expiryTimes;
    optionBasket_.clear();
    for (Size j = 0; j < data_->optionExpiries().size(); j++) {
        // may wish to calibrate against specific futures expiry dates...
        Date expiryDate = optionExpiry(j);
 
        // check if we want to keep the helper when a reference calibration grid is given
        auto refCalDate =
            std::lower_bound(referenceCalibrationDates.begin(), referenceCalibrationDates.end(), expiryDate);
        if (refCalDate == referenceCalibrationDates.end() || *refCalDate > lastRefCalDate) {
            optionActive_[j] = true;
            Real strikeValue = optionStrike(j);
            Handle<Quote> volQuote(QuantLib::ext::make_shared<SimpleQuote>(vol_->blackVol(expiryDate, strikeValue)));
            QuantLib::ext::shared_ptr<QuantExt::FutureOptionHelper> helper = QuantLib::ext::make_shared<QuantExt::FutureOptionHelper>(
                expiryDate, strikeValue, curve_, volQuote, data_->calibrationErrorType());
            optionBasket_.push_back(helper);
            helper->performCalculations();
            expiryTimes.push_back(curve_->timeFromReference(helper->option()->exercise()->date(0)));
            DLOG("Added FutureOptionHelper " << data_->name() << " " << QuantLib::io::iso_date(expiryDate) << " "
                                             << volQuote->value());
            if (refCalDate != referenceCalibrationDates.end())
                lastRefCalDate = *refCalDate;
        } else {
            optionActive_[j] = false;
        }
    }
 
    std::sort(expiryTimes.begin(), expiryTimes.end());
    auto itExpiryTime = unique(expiryTimes.begin(), expiryTimes.end());
    expiryTimes.resize(distance(expiryTimes.begin(), itExpiryTime));
 
    optionExpiries_ = Array(expiryTimes.size());
    for (Size j = 0; j < expiryTimes.size(); j++)
        optionExpiries_[j] = expiryTimes[j];
}

Here is the call graph for this function:

Here is the caller graph for this function:

◆ volSurfaceChanged()

bool volSurfaceChanged ( const bool updateCache ) const

private

Definition at line 199 of file commodityschwartzmodelbuilder.cpp.

                                                                                  {
    bool hasUpdated = false;
 
    // if cache doesn't exist resize vector
    if (volCache_.size() != optionBasket_.size())
        volCache_ = vector<Real>(optionBasket_.size(), Null<Real>());
 
    Size optionCounter = 0;
    for (Size j = 0; j < data_->optionExpiries().size(); j++) {
        if (!optionActive_[j])
            continue;
        Real vol = vol_->blackVol(optionExpiry(j), optionStrike(j));
        if (!close_enough(volCache_[optionCounter], vol)) {
            if (updateCache)
                volCache_[optionCounter] = vol;
            hasUpdated = true;
        }
        optionCounter++;
    }
    return hasUpdated;
}