CommodityOption Class Reference

Commodity option trade representation. More...

#include <ored/portfolio/commodityoption.hpp>

Inheritance diagram for CommodityOption:

Collaboration diagram for CommodityOption:

Public Member Functions
	CommodityOption ()
	Default constructor. More...
	CommodityOption (const Envelope &env, const OptionData &optionData, const std::string &commodityName, const std::string &currency, QuantLib::Real quantity, TradeStrike strike, 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 VanillaOptionTrade
void	build (const QuantLib::ext::shared_ptr< EngineFactory > &) override
	Build QuantLib/QuantExt instrument, link pricing engine. More...
void	setNotionalAndCurrencies ()
const OptionData &	option () const
const string &	asset () const
const string &	currency () const
TradeStrike	strike () const
double	quantity () const
const QuantLib::Date	forwardDate () const
const QuantLib::Date	paymentDate () const
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
boost::optional< bool >	isFuturePrice_
QuantLib::Date	futureExpiryDate_
const boost::optional< bool > &	isFuturePrice () const
const QuantLib::Date &	futureExpiryDate () const

Additional Inherited Members
Protected Member Functions inherited from VanillaOptionTrade
	VanillaOptionTrade (AssetClass assetClassUnderlying)
	VanillaOptionTrade (const Envelope &env, AssetClass assetClassUnderlying, OptionData option, string assetName, string currency, double quantity, TradeStrike strike, const QuantLib::ext::shared_ptr< QuantLib::Index > &index=nullptr, const std::string &indexName="", QuantLib::Date forwardDate=QuantLib::Date())
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 VanillaOptionTrade
AssetClass	assetClassUnderlying_
OptionData	option_
string	assetName_
string	currency_
Currency	underlyingCurrency_
double	quantity_
TradeStrike	strike_
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...
QuantLib::Date	forwardDate_
	Store the (optional) forward date. More...
QuantLib::Date	paymentDate_
	Store the (optional) payment date. More...
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 option trade representation.

Definition at line 35 of file commodityoption.hpp.

Constructor & Destructor Documentation

CommodityOption() [1/2]

CommodityOption

(

)

Default constructor.

Definition at line 41 of file commodityoption.cpp.

: VanillaOptionTrade(AssetClass::COM) { tradeType_ = "CommodityOption"; }

CommodityOption() [2/2]

CommodityOption	(	const Envelope &	env,
		const OptionData &	optionData,
		const std::string &	commodityName,
		const std::string &	currency,
		QuantLib::Real	quantity,
		TradeStrike	strike,
		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 commodityoption.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("");
 
    additionalData_["quantity"] = quantity_;
    additionalData_["strike"] = strike_.value();
    additionalData_["strikeCurrency"] = currency_;    
 
    // Checks
    QL_REQUIRE((strike_.value() > 0) || close_enough(strike_.value(),0.0), "Commodity option requires a non-negative strike");
    if (close_enough(strike_.value(), 0.0)) {
        strike_.setValue(0.0);
    }
 
    // This is called in VanillaOptionTrade::build(), but we want to call it first here,
    // in case the build fails before it reaches VanillaOptionTrade::build()
    VanillaOptionTrade::setNotionalAndCurrencies();
 
    // 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(assetName_, 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(assetName_, 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 = option_.exerciseDates();
            QL_REQUIRE(expiryDates.size() == 1,
                       "Expected exactly one expiry date for CommodityOption 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(option_.style());
        if (et == Exercise::European && QuantLib::ext::dynamic_pointer_cast<CommodityFuturesIndex>(index_)) {
            forwardDate_ = expiryDate;
        }
 
    }
 
    VanillaOptionTrade::build(engineFactory);
 
    // LOG the volatility if the trade expiry date is in the future.
    if (expiryDate_ > Settings::instance().evaluationDate()) {
        DLOG("Implied vol for " << tradeType_ << " on " << assetName_ << " with expiry " << expiryDate_
                                << " and strike " << strike_.value() << " is "
                                << market->commodityVolatility(assetName_)->blackVol(expiryDate_, strike_.value()));
    }
}

Here is the call graph for this function:

Here is the caller 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 119 of file commodityoption.cpp.

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

fromXML()

void fromXML ( XMLNode *  node )

overridevirtual

Reimplemented from Trade.

Definition at line 123 of file commodityoption.cpp.

                                           {
 
    Trade::fromXML(node);
 
    XMLNode* commodityNode = XMLUtils::getChildNode(node, "CommodityOptionData");
    QL_REQUIRE(commodityNode, "A commodity option needs a 'CommodityOptionData' node");
 
    option_.fromXML(XMLUtils::getChildNode(commodityNode, "OptionData"));
 
    assetName_ = XMLUtils::getChildValue(commodityNode, "Name", true);
    currency_ = XMLUtils::getChildValue(commodityNode, "Currency", true);
    strike_.fromXML(commodityNode);
    quantity_ = XMLUtils::getChildValueAsDouble(commodityNode, "Quantity", 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 146 of file commodityoption.cpp.

                                                      {
 
    XMLNode* node = Trade::toXML(doc);
 
    XMLNode* eqNode = doc.allocNode("CommodityOptionData");
    XMLUtils::appendNode(node, eqNode);
 
    XMLUtils::appendNode(eqNode, option_.toXML(doc));
 
    XMLUtils::addChild(doc, eqNode, "Name", assetName_);
    XMLUtils::addChild(doc, eqNode, "Currency", currency_);
    XMLUtils::appendNode(eqNode, strike_.toXML(doc));
    XMLUtils::addChild(doc, eqNode, "Quantity", quantity_);
 
    if (isFuturePrice_)
        XMLUtils::addChild(doc, eqNode, "IsFuturePrice", *isFuturePrice_);
 
    if (futureExpiryDate_ != Date())
        XMLUtils::addChild(doc, eqNode, "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 commodityoption.hpp.

{ return false; }

isFuturePrice()

const boost::optional< bool > & isFuturePrice

(

)

const

Definition at line 66 of file commodityoption.hpp.

{ return isFuturePrice_; }

futureExpiryDate()

const QuantLib::Date & futureExpiryDate

(

)

const

Definition at line 67 of file commodityoption.hpp.

{ return futureExpiryDate_; }

Member Data Documentation

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 74 of file commodityoption.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 79 of file commodityoption.hpp.