Commodity digital option trade representation as call spread. More...

#include <ored/portfolio/commoditydigitaloption.hpp>

Inheritance diagram for CommodityDigitalOption:

Collaboration diagram for CommodityDigitalOption:

Public Member Functions
	CommodityDigitalOption ()
	Default constructor. More...

	CommodityDigitalOption (const Envelope &env, const OptionData &optionData, const std::string &commodityName, const std::string &currency, QuantLib::Real strike, QuantLib::Real payoff, const boost::optional< bool > &isFuturePrice=boost::none, const QuantLib::Date &futureExpiryDate=QuantLib::Date())
	Detailed constructor. More...

void	build (const QuantLib::ext::shared_ptr< EngineFactory > &engineFactory) override
	Build underlying instrument and link pricing engine. More...

std::map< AssetClass, std::set< std::string > >	underlyingIndices (const QuantLib::ext::shared_ptr< ReferenceDataManager > &referenceDataManager=nullptr) const override
	Add underlying Commodity names. More...

Serialisation
virtual void	fromXML (XMLNode *node) override

virtual XMLNode *	toXML (XMLDocument &doc) const override

Trade
bool	hasCashflows () const override

Public Member Functions inherited from Trade
	Trade ()
	Default constructor. More...

	Trade (const string &tradeType, const Envelope &env=Envelope(), const TradeActions &ta=TradeActions())
	Base class constructor. More...

virtual	~Trade ()
	Default destructor. More...

virtual void	build (const QuantLib::ext::shared_ptr< EngineFactory > &)=0

virtual std::map< std::string, RequiredFixings::FixingDates >	fixings (const QuantLib::Date &settlementDate=QuantLib::Date()) const

const RequiredFixings &	requiredFixings () const

virtual std::map< AssetClass, std::set< std::string > >	underlyingIndices (const QuantLib::ext::shared_ptr< ReferenceDataManager > &referenceDataManager=nullptr) const

void	reset ()
	Reset trade, clear all base class data. This does not reset accumulated timings for this trade. More...

void	resetPricingStats (const std::size_t numberOfPricings=0, const boost::timer::nanosecond_type cumulativePricingTime=0)
	Reset accumulated timings to given values. More...

string &	id ()
	Set the trade id. More...

void	setEnvelope (const Envelope &envelope)
	Set the envelope with counterparty and portfolio info. More...

void	setAdditionalData (const std::map< std::string, boost::any > &additionalData)

TradeActions &	tradeActions ()
	Set the trade actions. More...

const string &	id () const

const string &	tradeType () const

const Envelope &	envelope () const

const set< string > &	portfolioIds () const

const TradeActions &	tradeActions () const

const QuantLib::ext::shared_ptr< InstrumentWrapper > &	instrument () const

const std::vector< QuantLib::Leg > &	legs () const

const std::vector< string > &	legCurrencies () const

const std::vector< bool > &	legPayers () const

const string &	npvCurrency () const

virtual QuantLib::Real	notional () const
	Return the current notional in npvCurrency. See individual sub-classes for the precise definition. More...

virtual string	notionalCurrency () const

const Date &	maturity () const

virtual bool	isExpired (const Date &d)

const string &	issuer () const

template<typename T >
T	additionalDatum (const std::string &tag) const
	returns any additional datum. More...

virtual const std::map< std::string, boost::any > &	additionalData () const
	returns all additional data returned by the trade once built More...

const std::string &	sensitivityTemplate () const

void	validate () const
	Utility to validate that everything that needs to be set in this base class is actually set. More...

boost::timer::nanosecond_type	getCumulativePricingTime () const
	Get cumulative timing spent on pricing. More...

std::size_t	getNumberOfPricings () const
	Get number of pricings. More...

Public Member Functions inherited from XMLSerializable
virtual	~XMLSerializable ()

virtual void	fromXML (XMLNode *node)=0

virtual XMLNode *	toXML (XMLDocument &doc) const =0

void	fromFile (const std::string &filename)

void	toFile (const std::string &filename) const

void	fromXMLString (const std::string &xml)
	Parse from XML string. More...

std::string	toXMLString () const
	Parse from XML string. More...

Inspectors
OptionData	optionData_

std::string	name_

string	currency_

Real	strike_

Real	payoff_

boost::optional< bool >	isFuturePrice_

QuantLib::Date	futureExpiryDate_

QuantLib::ext::shared_ptr< QuantLib::Index >	index_
	An index is needed if the option is to be automatically exercised on expiry. More...

std::string	indexName_
	Hold the external index name if needed e.g. in the case of an FX index. More...

QuantLib::Date	expiryDate_
	Store the option expiry date. More...

Date	forwardDate_

const boost::optional< bool > &	isFuturePrice () const

const QuantLib::Date &	futureExpiryDate () const

Additional Inherited Members
Protected Member Functions inherited from Trade
Date	addPremiums (std::vector< QuantLib::ext::shared_ptr< Instrument > > &instruments, std::vector< Real > &multipliers, const Real tradeMultiplier, const PremiumData &premiumData, const Real premiumMultiplier, const Currency &tradeCurrency, const QuantLib::ext::shared_ptr< EngineFactory > &factory, const string &configuration)

void	setLegBasedAdditionalData (const Size legNo, Size resultLegId=Null< Size >()) const

void	setSensitivityTemplate (const EngineBuilder &builder)

void	setSensitivityTemplate (const std::string &id)

Protected Attributes inherited from Trade
string	tradeType_

QuantLib::ext::shared_ptr< InstrumentWrapper >	instrument_

std::vector< QuantLib::Leg >	legs_

std::vector< string >	legCurrencies_

std::vector< bool >	legPayers_

string	npvCurrency_

QuantLib::Real	notional_

string	notionalCurrency_

Date	maturity_

string	issuer_

string	sensitivityTemplate_

bool	sensitivityTemplateSet_ = false

std::size_t	savedNumberOfPricings_ = 0

boost::timer::nanosecond_type	savedCumulativePricingTime_ = 0

RequiredFixings	requiredFixings_

std::map< std::string, boost::any >	additionalData_

Detailed Description

Commodity digital option trade representation as call spread.

Definition at line 35 of file commoditydigitaloption.hpp.

Constructor & Destructor Documentation

◆ CommodityDigitalOption() [1/2]

CommodityDigitalOption ( )

Default constructor.

Definition at line 41 of file commoditydigitaloption.cpp.

41{ tradeType_ = "CommodityDigitalOption"; }

ore::data::Trade::tradeType_

string tradeType_

Definition: trade.hpp:196

◆ CommodityDigitalOption() [2/2]

CommodityDigitalOption	(	const Envelope &	env,
		const OptionData &	optionData,
		const std::string &	commodityName,
		const std::string &	currency,
		QuantLib::Real	strike,
		QuantLib::Real	payoff,
		const boost::optional< bool > &	isFuturePrice = `boost::none`,
		const QuantLib::Date &	futureExpiryDate = `QuantLib::Date()`
	)

Detailed constructor.

Member Function Documentation

◆ build()

void build ( const QuantLib::ext::shared_ptr< EngineFactory > & engineFactory )

overridevirtual

Build underlying instrument and link pricing engine.

Implements Trade.

Definition at line 51 of file commoditydigitaloption.cpp.

                                                                                            {
 
    // ISDA taxonomy, assuming Commodity follows the Equity template
    additionalData_["isdaAssetClass"] = std::string("Commodity");
    additionalData_["isdaBaseProduct"] = std::string("Option");
    additionalData_["isdaSubProduct"] = std::string("Price Return Basic Performance");
    // skip the transaction level mapping for now
    additionalData_["isdaTransaction"] = std::string("");
 
    // Checks
    QL_REQUIRE((strike_ > 0 || close_enough(strike_, 0.0)), "Commodity digital option requires a positive strike");
    QL_REQUIRE(optionData_.exerciseDates().size() == 1, "Invalid number of exercise dates");
 
    expiryDate_ = parseDate(optionData_.exerciseDates().front());
 
    // Populate the index_ in case the option is automatic exercise.
    // Intentionally use null calendar because we will ask for index value on the expiry date without adjustment.
    const QuantLib::ext::shared_ptr<Market>& market = engineFactory->market();
    index_ = *market->commodityIndex(name_, engineFactory->configuration(MarketContext::pricing));
    if (!isFuturePrice_ || *isFuturePrice_) {
 
        // Assume future price if isFuturePrice_ is not explicitly set or if it is and true.
        auto index = *market->commodityIndex(name_, engineFactory->configuration(MarketContext::pricing));
 
        // If we are given an explicit future contract expiry date, use it, otherwise use option's expiry.
        Date expiryDate;
        if (futureExpiryDate_ != Date()) {
            expiryDate = futureExpiryDate_;
        } else {
            // Get the expiry date of the option. This is the expiry date of the commodity future index.
            const vector<string>& expiryDates = optionData_.exerciseDates();
            QL_REQUIRE(expiryDates.size() == 1,
                       "Expected exactly one expiry date for CommodityDigitalOption but got " << expiryDates.size() << ".");
            expiryDate = parseDate(expiryDates[0]);
        }
 
        // Clone the index with the relevant expiry date.
        index_ = index->clone(expiryDate);
 
        // Set the VanillaOptionTrade forwardDate_ if the index is a CommodityFuturesIndex - we possibly still have a 
        // CommoditySpotIndex at this point so check. Also, will only work for European exercise.
        auto et = parseExerciseType(optionData_.style());
    QL_REQUIRE(et == Exercise::European, "European style expected for CommodityDigitalOption");
        if (et == Exercise::European && QuantLib::ext::dynamic_pointer_cast<CommodityFuturesIndex>(index_)) {
            forwardDate_ = expiryDate;
        }
    }
 
    // Build digital as call or put spread 
    Real strikeSpread = strike_ * 0.01; // FIXME, what is a usual spread here, and where should we put it?
    Real strike1 = strike_ - strikeSpread/2;
    Real strike2 = strike_ + strikeSpread/2;
    CommodityOption opt1(envelope(), optionData_, name_, currency_, 1.0, TradeStrike(strike1, currency_), isFuturePrice_, futureExpiryDate_);
    CommodityOption opt2(envelope(), optionData_, name_, currency_, 1.0, TradeStrike(strike2, currency_),
                         isFuturePrice_, futureExpiryDate_);
    opt1.build(engineFactory);
    opt2.build(engineFactory);
    QuantLib::ext::shared_ptr<Instrument> inst1 = opt1.instrument()->qlInstrument();
    QuantLib::ext::shared_ptr<Instrument> inst2 = opt2.instrument()->qlInstrument();
 
    setSensitivityTemplate(opt1.sensitivityTemplate());
 
    QuantLib::ext::shared_ptr<CompositeInstrument> composite = QuantLib::ext::make_shared<CompositeInstrument>();
    // add and subtract such that the long call spread and long put spread have positive values
    if (optionData_.callPut() == "Call") {
        composite->add(inst1);
        composite->subtract(inst2);
    }
    else if (optionData_.callPut() == "Put") {
        composite->add(inst2);
        composite->subtract(inst1);
    }
    else {
        QL_FAIL("OptionType Call or Put required in CommodityDigitalOption " << id());
    }
 
    Position::Type positionType = parsePositionType(optionData_.longShort());
    Real bsIndicator = (positionType == QuantLib::Position::Long ? 1.0 : -1.0);
    Real multiplier = payoff_ * bsIndicator / strikeSpread;
    std::vector<QuantLib::ext::shared_ptr<Instrument>> additionalInstruments;
    std::vector<Real> additionalMultipliers;
    // FIXME: Do we need to retrieve the engine builder's configuration
    string configuration = Market::defaultConfiguration; 
    Currency ccy = parseCurrencyWithMinors(currency_);
    maturity_ = std::max(expiryDate_, addPremiums(additionalInstruments, additionalMultipliers, multiplier,
                          optionData_.premiumData(), -bsIndicator, ccy, engineFactory, configuration));
 
    instrument_ = QuantLib::ext::shared_ptr<InstrumentWrapper>(
        new VanillaInstrument(composite, multiplier, additionalInstruments, additionalMultipliers));
 
    npvCurrency_ = currency_;
    notional_ = payoff_;
    notionalCurrency_ = currency_;
    
    // LOG the volatility if the trade expiry date is in the future.
    if (expiryDate_ > Settings::instance().evaluationDate()) {
        DLOG("Implied vol for " << tradeType_ << " on " << name_ << " with expiry " << expiryDate_
                                << " and strike " << strike_ << " is "
                                << market->commodityVolatility(name_)->blackVol(expiryDate_, strike_));
    }
 
    additionalData_["payoff"] = payoff_;
    additionalData_["strike"] = strike_;
    additionalData_["optionType"] = optionData_.callPut();
    additionalData_["strikeCurrency"] = currency_;    
}

Here is the call graph for this function:

◆ underlyingIndices()

std::map< AssetClass, std::set< std::string > > underlyingIndices ( const QuantLib::ext::shared_ptr< ReferenceDataManager > & referenceDataManager = nullptr ) const

overridevirtual

Add underlying Commodity names.

Reimplemented from Trade.

Definition at line 159 of file commoditydigitaloption.cpp.

                                                                                                                       {
    return {{AssetClass::COM, std::set<std::string>({name_})}};
}

◆ fromXML()

void fromXML ( XMLNode * node )

overridevirtual

Reimplemented from Trade.

Definition at line 163 of file commoditydigitaloption.cpp.

                                                  {
 
    Trade::fromXML(node);
 
    XMLNode* commodityNode = XMLUtils::getChildNode(node, "CommodityDigitalOptionData");
    QL_REQUIRE(commodityNode, "A commodity option needs a 'CommodityDigitalOptionData' node");
 
    optionData_.fromXML(XMLUtils::getChildNode(commodityNode, "OptionData"));
 
    name_ = XMLUtils::getChildValue(commodityNode, "Name", true);
    currency_ = XMLUtils::getChildValue(commodityNode, "Currency", true);
    strike_ = XMLUtils::getChildValueAsDouble(commodityNode, "Strike", true);
    payoff_ = XMLUtils::getChildValueAsDouble(commodityNode, "Payoff", true);
 
    isFuturePrice_ = boost::none;
    if (XMLNode* n = XMLUtils::getChildNode(commodityNode, "IsFuturePrice"))
        isFuturePrice_ = parseBool(XMLUtils::getNodeValue(n));
 
    futureExpiryDate_ = Date();
    if (XMLNode* n = XMLUtils::getChildNode(commodityNode, "FutureExpiryDate"))
        futureExpiryDate_ = parseDate(XMLUtils::getNodeValue(n));
}

Here is the call graph for this function:

◆ toXML()

XMLNode * toXML ( XMLDocument & doc ) const

overridevirtual

Reimplemented from Trade.

Definition at line 186 of file commoditydigitaloption.cpp.

                                                             {
 
    XMLNode* node = Trade::toXML(doc);
 
    XMLNode* commodityNode = doc.allocNode("CommodityDigitalOptionData");
    XMLUtils::appendNode(node, commodityNode);
 
    XMLUtils::appendNode(commodityNode, optionData_.toXML(doc));
 
    XMLUtils::addChild(doc, commodityNode, "Name", name_);
    XMLUtils::addChild(doc, commodityNode, "Currency", currency_);
    XMLUtils::addChild(doc, commodityNode, "Strike", strike_);
    XMLUtils::addChild(doc, commodityNode, "Payoff", payoff_);
 
    if (isFuturePrice_)
        XMLUtils::addChild(doc, commodityNode, "IsFuturePrice", *isFuturePrice_);
 
    if (futureExpiryDate_ != Date())
        XMLUtils::addChild(doc, commodityNode, "FutureExpiryDate", to_string(futureExpiryDate_));
 
    return node;
}

Here is the call graph for this function:

◆ hasCashflows()

bool hasCashflows ( ) const

overridevirtual

Utility method indicating if the trade has cashflows for the cashflow report. The default implementation returns true so that a trade is automatically considered when cashflows are being written. To prevent a trade from being asked for its cashflows, the method can be overridden to return false.

Reimplemented from Trade.

Definition at line 61 of file commoditydigitaloption.hpp.

61{ return false; }

◆ isFuturePrice()

const boost::optional< bool > & isFuturePrice ( ) const

Definition at line 66 of file commoditydigitaloption.hpp.

66{ return isFuturePrice_; }

◆ futureExpiryDate()

const QuantLib::Date & futureExpiryDate ( ) const

Definition at line 67 of file commoditydigitaloption.hpp.

67{ return futureExpiryDate_; }

Member Data Documentation

◆ optionData_

OptionData optionData_

private

Definition at line 71 of file commoditydigitaloption.hpp.

◆ name_

std::string name_

private

Definition at line 72 of file commoditydigitaloption.hpp.

◆ currency_

string currency_

private

Definition at line 73 of file commoditydigitaloption.hpp.

◆ strike_

Real strike_

private

Definition at line 74 of file commoditydigitaloption.hpp.

◆ payoff_

Real payoff_

private

Definition at line 75 of file commoditydigitaloption.hpp.

◆ isFuturePrice_

boost::optional<bool> isFuturePrice_

private

Indicates if the option underlying is a commodity future settlement price, true, or a spot price false. If not explicitly set, it is assumed to be true.

Definition at line 80 of file commoditydigitaloption.hpp.

◆ futureExpiryDate_

QuantLib::Date futureExpiryDate_

private

An explicit expiry date for the underlying future contract. This can be used if the option trade references a future contract settlement price and the option's expiry date does not match the future contract expiry date.

Definition at line 85 of file commoditydigitaloption.hpp.

◆ index_

QuantLib::ext::shared_ptr<QuantLib::Index> index_

private

An index is needed if the option is to be automatically exercised on expiry.

Definition at line 88 of file commoditydigitaloption.hpp.

◆ indexName_

std::string indexName_

private

Hold the external index name if needed e.g. in the case of an FX index.

Definition at line 91 of file commoditydigitaloption.hpp.

◆ expiryDate_

QuantLib::Date expiryDate_

private

Store the option expiry date.

Definition at line 94 of file commoditydigitaloption.hpp.

◆ forwardDate_

Date forwardDate_

private

Definition at line 96 of file commoditydigitaloption.hpp.

Public Member Functions

Inspectors

Additional Inherited Members

Detailed Description

Constructor & Destructor Documentation

◆ CommodityDigitalOption() [1/2]

◆ CommodityDigitalOption() [2/2]

Member Function Documentation

◆ build()

◆ underlyingIndices()

◆ fromXML()

◆ toXML()

◆ hasCashflows()

◆ isFuturePrice()

◆ futureExpiryDate()

Member Data Documentation

◆ optionData_

◆ name_

◆ currency_

◆ strike_

◆ payoff_

◆ isFuturePrice_

◆ futureExpiryDate_

◆ index_

◆ indexName_

◆ expiryDate_

◆ forwardDate_