EqBsBuilder Class Reference

Builder for a Lognormal EQ model component. More...

#include <ored/model/eqbsbuilder.hpp>

Inheritance diagram for EqBsBuilder:

Collaboration diagram for EqBsBuilder:

Public Member Functions
	EqBsBuilder (const QuantLib::ext::shared_ptr< ore::data::Market > &market, const QuantLib::ext::shared_ptr< EqBsData > &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	eqName ()
QuantLib::ext::shared_ptr< QuantExt::EqBsParametrization >	parametrization () 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< EqBsData >	data_
const std::string	referenceCalibrationGrid_
const QuantLib::Currency	baseCcy_
Real	error_
QuantLib::ext::shared_ptr< QuantExt::EqBsParametrization >	parametrization_
std::vector< bool >	optionActive_
std::vector< QuantLib::ext::shared_ptr< BlackCalibrationHelper > >	optionBasket_
Array	optionExpiries_
Handle< Quote >	eqSpot_
Handle< Quote >	fxSpot_
Handle< YieldTermStructure >	ytsRate_
Handle< YieldTermStructure >	ytsDiv_
Handle< BlackVolTermStructure >	eqVol_
std::vector< QuantLib::Real >	eqVolCache_
bool	forceCalibration_ = false
QuantLib::ext::shared_ptr< QuantExt::MarketObserver >	marketObserver_
void	forceRecalculate () override
bool	requiresRecalibration () const override
void	setCalibrationDone () const
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 Lognormal EQ model component.

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

Definition at line 48 of file eqbsbuilder.hpp.

Constructor & Destructor Documentation

EqBsBuilder()

EqBsBuilder	(	const QuantLib::ext::shared_ptr< ore::data::Market > &	market,
		const QuantLib::ext::shared_ptr< EqBsData > &	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 39 of file eqbsbuilder.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 eqName = data->eqName();
 
    LOG("Start building EqBs model for " << eqName);
 
    // get market data
    std::string fxCcyPair = ccy.code() + baseCcy_.code();
    eqSpot_ = market_->equitySpot(eqName, configuration_);
    fxSpot_ = market_->fxRate(fxCcyPair, configuration_);
    // FIXME using the "discount curve" here instead of the equityReferenceRateCurve?
    ytsRate_ = market_->discountCurve(ccy.code(), configuration_);
    ytsDiv_ = market_->equityDividendCurve(eqName, configuration_);
    eqVol_ = market_->equityVol(eqName, configuration_);
 
    // register with market observables except vols
    marketObserver_->registerWith(eqSpot_);
    marketObserver_->registerWith(fxSpot_);
    marketObserver_->registerWith(ytsRate_);
    marketObserver_->registerWith(ytsDiv_);
 
    // register the builder with the vol and the market observer
    registerWith(eqVol_);
    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())
        buildOptionBasket();
 
    Array sigmaTimes, sigma;
    if (data->sigmaParamType() == ParamType::Constant) {
        QL_REQUIRE(data->sigmaTimes().size() == 0, "empty sigma time grid expected");
        QL_REQUIRE(data->sigmaValues().size() == 1, "initial sigma grid size 1 expected");
        sigmaTimes = Array(0);
        sigma = Array(data_->sigmaValues().begin(), data_->sigmaValues().end());
    } else {
        if (data->calibrateSigma()) { // override
            QL_REQUIRE(optionExpiries_.size() > 0, "optionExpiries is empty");
            sigmaTimes = Array(optionExpiries_.begin(), optionExpiries_.end() - 1);
            sigma = Array(sigmaTimes.size() + 1, data->sigmaValues()[0]);
        } else {
            // use input time grid and input alpha array otherwise
            sigmaTimes = Array(data_->sigmaTimes().begin(), data_->sigmaTimes().end());
            sigma = Array(data_->sigmaValues().begin(), data_->sigmaValues().end());
            QL_REQUIRE(sigma.size() == sigmaTimes.size() + 1, "sigma grids do not match");
        }
    }
 
    // Quotation needs to be consistent with FX spot quotation in the FX calibration basket
    if (data->sigmaParamType() == ParamType::Piecewise)
        parametrization_ = QuantLib::ext::make_shared<QuantExt::EqBsPiecewiseConstantParametrization>(
            ccy, eqName, eqSpot_, fxSpot_, sigmaTimes, sigma, ytsRate_, ytsDiv_);
    else if (data->sigmaParamType() == ParamType::Constant)
        parametrization_ = QuantLib::ext::make_shared<QuantExt::EqBsConstantParametrization>(ccy, eqName, eqSpot_, fxSpot_,
                                                                                     sigma[0], ytsRate_, ytsDiv_);
    else
        QL_FAIL("interpolation type not supported for Equity");
}

Here is the call graph for this function:

Member Function Documentation

error()

Real error

(

)

const

Return calibration error.

Definition at line 108 of file eqbsbuilder.cpp.

                              {
    calculate();
    return error_;
}

eqName()

std::string eqName

(

)

Definition at line 67 of file eqbsbuilder.hpp.

{ return data_->eqName(); }

Here is the caller graph for this function:

parametrization()

QuantLib::ext::shared_ptr< QuantExt::EqBsParametrization > parametrization

(

)

const

Definition at line 113 of file eqbsbuilder.cpp.

                                                                                      {
    calculate();
    return parametrization_;
}

optionBasket()

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

(

)

const

Definition at line 117 of file eqbsbuilder.cpp.

                                                                                         {
    calculate();
    return optionBasket_;
}

forceRecalculate()

void forceRecalculate ( )

overridevirtual

Reimplemented from ModelBuilder.

Definition at line 234 of file eqbsbuilder.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 122 of file eqbsbuilder.cpp.

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

Here is the call graph for this function:

Here is the caller graph for this function:

setCalibrationDone()

void setCalibrationDone

(

)

const

Definition at line 134 of file eqbsbuilder.cpp.

                                           {
    // reset market observer updated flag
    marketObserver_->hasUpdated(true);
    // update vol cache
    volSurfaceChanged(true);
}

Here is the call graph for this function:

performCalculations()

void performCalculations ( ) const

overrideprivate

Definition at line 127 of file eqbsbuilder.cpp.

                                            {
    if (requiresRecalibration()) {
        // build option basket
        buildOptionBasket();
    }
}

Here is the call graph for this function:

optionStrike()

Real optionStrike ( const Size  j ) const

private

Definition at line 141 of file eqbsbuilder.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 154 of file eqbsbuilder.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 187 of file eqbsbuilder.cpp.

                                          {
    QL_REQUIRE(data_->optionExpiries().size() == data_->optionStrikes().size(), "Eq 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>(eqVol_->blackVol(expiryDate, strikeValue)));
            QuantLib::ext::shared_ptr<QuantExt::FxEqOptionHelper> helper = QuantLib::ext::make_shared<QuantExt::FxEqOptionHelper>(
                expiryDate, strikeValue, eqSpot_, volQuote, ytsRate_, ytsDiv_);
            optionBasket_.push_back(helper);
            helper->performCalculations();
            expiryTimes.push_back(ytsRate_->timeFromReference(helper->option()->exercise()->date(0)));
            DLOG("Added EquityOptionHelper " << data_->eqName() << " " << 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 165 of file eqbsbuilder.cpp.

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

Here is the call graph for this function:

Here is the caller graph for this function:

Member Data Documentation

market_

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

private

Definition at line 89 of file eqbsbuilder.hpp.

configuration_

const std::string configuration_

private

Definition at line 90 of file eqbsbuilder.hpp.

data_

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

private

Definition at line 91 of file eqbsbuilder.hpp.

referenceCalibrationGrid_

const std::string referenceCalibrationGrid_

private

Definition at line 92 of file eqbsbuilder.hpp.

baseCcy_

const QuantLib::Currency baseCcy_

private

Definition at line 93 of file eqbsbuilder.hpp.

error_

Real error_

private

Definition at line 96 of file eqbsbuilder.hpp.

parametrization_

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

mutableprivate

Definition at line 97 of file eqbsbuilder.hpp.

optionActive_

std::vector<bool> optionActive_

mutableprivate

Definition at line 100 of file eqbsbuilder.hpp.

optionBasket_

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

mutableprivate

Definition at line 101 of file eqbsbuilder.hpp.

optionExpiries_

Array optionExpiries_

mutableprivate

Definition at line 102 of file eqbsbuilder.hpp.

eqSpot_

Handle<Quote> eqSpot_

private

Definition at line 105 of file eqbsbuilder.hpp.

fxSpot_

Handle<Quote> fxSpot_

private

Definition at line 105 of file eqbsbuilder.hpp.

ytsRate_

Handle<YieldTermStructure> ytsRate_

private

Definition at line 106 of file eqbsbuilder.hpp.

ytsDiv_

Handle<YieldTermStructure> ytsDiv_

private

Definition at line 106 of file eqbsbuilder.hpp.

eqVol_

Handle<BlackVolTermStructure> eqVol_

private

Definition at line 107 of file eqbsbuilder.hpp.

eqVolCache_

std::vector<QuantLib::Real> eqVolCache_

mutableprivate

Definition at line 110 of file eqbsbuilder.hpp.

forceCalibration_

bool forceCalibration_ = false

private

Definition at line 113 of file eqbsbuilder.hpp.

marketObserver_

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

private

Definition at line 116 of file eqbsbuilder.hpp.