ConvertibleBond Class Reference

Serializable Convertible Bond. More...

#include <ored/portfolio/convertiblebond.hpp>

Inheritance diagram for ConvertibleBond:

Collaboration diagram for ConvertibleBond:

Public Member Functions
	ConvertibleBond ()
	Default constructor. More...
	ConvertibleBond (const Envelope &env, const ConvertibleBondData &data)
	Constructor for coupon bonds. More...
void	build (const QuantLib::ext::shared_ptr< ore::data::EngineFactory > &) override
void	fromXML (XMLNode *node) override
XMLNode *	toXML (XMLDocument &doc) const override
std::map< AssetClass, std::set< std::string > >	underlyingIndices (const QuantLib::ext::shared_ptr< ReferenceDataManager > &referenceDataManager=nullptr) const override
	Add underlying Bond names. More...
const ConvertibleBondData &	data () const
const BondData &	bondData () 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...
virtual bool	hasCashflows () const
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...

Private Attributes
ConvertibleBondData	originalData_
ConvertibleBondData	data_

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

Serializable Convertible Bond.

Definition at line 34 of file convertiblebond.hpp.

Constructor & Destructor Documentation

ConvertibleBond() [1/2]

ConvertibleBond

(

)

Default constructor.

Definition at line 37 of file convertiblebond.hpp.

: Trade("ConvertibleBond") {}

ConvertibleBond() [2/2]

ConvertibleBond	(	const Envelope &	env,
		const ConvertibleBondData &	data
	)

Constructor for coupon bonds.

Definition at line 40 of file convertiblebond.hpp.

        : Trade("ConvertibleBond", env), originalData_(data), data_(data) {}

Member Function Documentation

build()

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

override

Definition at line 417 of file convertiblebond.cpp.

                                                                                            {
    DLOG("ConvertibleBond::build() called for trade " << id());
 
    // ISDA taxonomy: not a derivative, but define the asset class at least
    // so that we can determine a TRS asset class that has Convertible Bond underlyings
    additionalData_["isdaAssetClass"] = string("Credit");
    additionalData_["isdaBaseProduct"] = string("");
    additionalData_["isdaSubProduct"] = string("");
    additionalData_["isdaTransaction"] = string("");
 
    auto builder = QuantLib::ext::dynamic_pointer_cast<ConvertibleBondEngineBuilder>(engineFactory->builder("ConvertibleBond"));
    QL_REQUIRE(builder, "ConvertibleBond::build(): could not cast to ConvertibleBondBuilder, this is unexpected");
 
    data_ = originalData_;
    data_.populateFromBondReferenceData(engineFactory->referenceData());
 
    // build converible underlying bond, add to required fixings
 
    ore::data::Bond underlyingBond(Envelope(), data_.bondData());
    underlyingBond.build(engineFactory);
    requiredFixings_.addData(underlyingBond.requiredFixings());
    auto qlUnderlyingBond = QuantLib::ext::dynamic_pointer_cast<QuantLib::Bond>(underlyingBond.instrument()->qlInstrument());
    QL_REQUIRE(qlUnderlyingBond,
               "ConvertibleBond::build(): internal error, could not cast underlying bond to QuantLib::Bond");
    auto qlUnderlyingBondCoupons = qlUnderlyingBond->cashflows();
    qlUnderlyingBondCoupons.erase(
        std::remove_if(qlUnderlyingBondCoupons.begin(), qlUnderlyingBondCoupons.end(),
                       [](QuantLib::ext::shared_ptr<CashFlow> c) { return QuantLib::ext::dynamic_pointer_cast<Coupon>(c) == nullptr; }),
        qlUnderlyingBondCoupons.end());
 
    // get open end date replacement from vanilla builder to handle perpetuals
 
    QuantLib::ext::shared_ptr<EngineBuilder> vanillaBuilder = engineFactory->builder("Bond");
    QL_REQUIRE(builder, "ConvertibleBond::build(): internal error, vanilla builder is null");
    std::string openEndDateStr = vanillaBuilder->modelParameter("OpenEndDateReplacement", {}, false, "");
    Date openEndDateReplacement = getOpenEndDateReplacement(openEndDateStr, parseCalendar(data_.bondData().calendar()));
 
    // check whether the underlying bond is set up as perpetual (i.e. without maturity date)
 
    bool isPerpetual = false;
    for (auto const& d : data_.bondData().coupons()) {
        for (auto const& r : d.schedule().rules()) {
            isPerpetual = isPerpetual || r.endDate().empty();
        }
    }
 
    DLOG("isPerpetual=" << std::boolalpha << isPerpetual << ", openEndDateReplacement=" << openEndDateReplacement);
 
    // get equity index and fx index
 
    auto config = builder->configuration(MarketContext::pricing);
 
    QuantLib::ext::shared_ptr<EquityIndex2> equity;
    if (!data_.conversionData().equityUnderlying().name().empty()) {
        equity = *engineFactory->market()->equityCurve(data_.conversionData().equityUnderlying().name(), config);
    }
 
    QL_REQUIRE((equity == nullptr && data_.conversionData().fixedAmountConversionData().initialised()) ||
                   (equity != nullptr && !data_.conversionData().fixedAmountConversionData().initialised()),
               "ConvertibleBondEngineBuilder::build(): exactly one of equity underlying or fixed amount conversion "
               "must be specified");
 
    QuantLib::ext::shared_ptr<FxIndex> fx;
    if (equity != nullptr && !equity->currency().empty()) {
        if (equity->currency().code() != data_.bondData().currency()) {
            QL_REQUIRE(!data_.conversionData().fxIndex().empty(),
                       "ConvertibleBondEngineBuilder::build(): FXIndex required in conversion data, since eq ccy ("
                           << equity->currency().code() << ") not equal bond ccy (" << data_.bondData().currency()
                           << ")");
            fx = buildFxIndex(data_.conversionData().fxIndex(), data_.bondData().currency(), equity->currency().code(),
                              engineFactory->market(), config);
        }
    } else if (equity == nullptr && data_.conversionData().fixedAmountConversionData().initialised()) {
        if (data_.conversionData().fixedAmountConversionData().currency() != data_.bondData().currency()) {
            QL_REQUIRE(!data_.conversionData().fxIndex().empty(),
                       "ConvertibleBondEngineBuilder::build(): FXIndex required in conversion data, since fixed amount "
                       "conversion  ccy ("
                           << data_.conversionData().fixedAmountConversionData().currency() << ") not equal bond ccy ("
                           << data_.bondData().currency() << ")");
            fx = buildFxIndex(data_.conversionData().fxIndex(), data_.bondData().currency(),
                              data_.conversionData().fixedAmountConversionData().currency(), engineFactory->market(),
                              config);
        }
    }
 
    // for cross currency, add required FX fixings for conversion and dividend history
 
    if (fx != nullptr) {
 
        Date d0 = qlUnderlyingBond->startDate();
        Date d1 = qlUnderlyingBond->maturityDate();
 
        // FIXME, the following only works, if we have the dividends loaded at this point...
        if (equity != nullptr) {
            auto div = equity->dividendFixings();
            for (auto const& d : div) {
                if (d.exDate >= d0) {
                    requiredFixings_.addFixingDate(fx->fixingCalendar().adjust(d.exDate, Preceding),
                                                   data_.conversionData().fxIndex());
                }
            }
        }
 
        Date today = Settings::instance().evaluationDate();
        d0 = std::min(d0, today);
 
        // ...as a workaround, we add all fx fixings from min(today, bond start date) to maturity
        // -> this also covers the required fx fixings for conversion, so we don't have to add them separately
        for (Date d = d0; d <= d1; ++d) {
            requiredFixings_.addFixingDate(fx->fixingCalendar().adjust(d, Preceding), data_.conversionData().fxIndex(),
                                           Date::maxDate(), false, false);
        }
    }
 
    // the multiplier, basically the number of bonds and a sign for long / short positions
 
    Real multiplier = data_.bondData().bondNotional() * (data_.bondData().isPayer() ? -1.0 : 1.0);
 
    // build convertible data
 
    ConvertibleBond2::ExchangeableData exchangeableData = buildExchangeableData(data_.conversionData());
    std::vector<ConvertibleBond2::CallabilityData> callData =
        buildCallabilityData(data_.callData(), openEndDateReplacement);
    ConvertibleBond2::MakeWholeData makeWholeCrIncreaseData = buildMakeWholeData(data_.callData());
    std::vector<ConvertibleBond2::CallabilityData> putData =
        buildCallabilityData(data_.putData(), openEndDateReplacement);
    // for fixed amounts the model will provide an equity with constant unit spot rate, so that
    // we can treat the amount as a ratio
    std::vector<ConvertibleBond2::ConversionRatioData> conversionRatioData =
        equity != nullptr ? buildConversionRatioData(data_.conversionData())
                          : buildConversionFixedAmountData(data_.conversionData());
    std::vector<ConvertibleBond2::ConversionData> conversionData = buildConversionData(
        data_.conversionData(), requiredFixings_, equity, fx, data_.conversionData().fxIndex(), openEndDateReplacement);
    std::vector<ConvertibleBond2::MandatoryConversionData> mandatoryConversionData =
        buildMandatoryConversionData(data_.conversionData());
    std::vector<ConvertibleBond2::ConversionResetData> conversionResetData = buildConversionResetData(
        data_.conversionData(), requiredFixings_, equity, fx, data_.conversionData().fxIndex(), openEndDateReplacement);
    std::vector<ConvertibleBond2::DividendProtectionData> dividendProtectionData =
        buildDividendProtectionData(data_.dividendProtectionData(), requiredFixings_, equity, fx,
                                    data_.conversionData().fxIndex(), openEndDateReplacement);
 
    // build convertible bond instrument and attach pricing engine
 
    // get the last relevant date of the convertible bond, this is used as the last calibration date for the model
    Date lastDate = qlUnderlyingBond->maturityDate();
    if (!dividendProtectionData.empty()) {
        lastDate = std::max(lastDate, dividendProtectionData.back().protectionDate);
    }
 
    QL_REQUIRE(data_.conversionData().initialised(), "ConvertibleBond::build(): conversion data required");
    auto qlConvertible = QuantLib::ext::make_shared<ConvertibleBond2>(
        qlUnderlyingBond->settlementDays(), qlUnderlyingBond->calendar(), qlUnderlyingBond->issueDate(),
        qlUnderlyingBondCoupons, exchangeableData, callData, makeWholeCrIncreaseData, putData, conversionRatioData,
        conversionData, mandatoryConversionData, conversionResetData, dividendProtectionData,
        data_.detachable().empty() ? false : parseBool(data_.detachable()), isPerpetual);
    qlConvertible->setPricingEngine(builder->engine(
        id(), data_.bondData().currency(), data_.bondData().creditCurveId(), data_.bondData().hasCreditRisk(),
        data_.bondData().securityId(), data_.bondData().referenceCurveId(), exchangeableData.isExchangeable, equity, fx,
        data_.conversionData().exchangeableData().equityCreditCurve(), qlUnderlyingBond->startDate(), lastDate));
    setSensitivityTemplate(*builder);
 
    // set up other trade member variables
 
    instrument_ = QuantLib::ext::make_shared<VanillaInstrument>(qlConvertible, multiplier);
    npvCurrency_ = notionalCurrency_ = data_.bondData().currency();
    maturity_ = qlUnderlyingBond->maturityDate();
    notional_ = qlUnderlyingBond->notional();
    legs_ = {qlUnderlyingBond->cashflows()};
    legCurrencies_ = {npvCurrency_};
    legPayers_ = {data_.bondData().isPayer()};
}

Here is the call graph for this function:

fromXML()

void fromXML ( XMLNode *  node )

overridevirtual

Reimplemented from Trade.

Definition at line 589 of file convertiblebond.cpp.

                                           {
    Trade::fromXML(node);
    originalData_.fromXML(XMLUtils::getChildNode(node, "ConvertibleBondData"));
    data_ = originalData_;
}

toXML()

XMLNode * toXML ( XMLDocument &  doc ) const

overridevirtual

Reimplemented from Trade.

Definition at line 595 of file convertiblebond.cpp.

                                                      {
    XMLNode* node = Trade::toXML(doc);
    XMLUtils::appendNode(node, originalData_.toXML(doc));
    return node;
}

underlyingIndices()

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

overridevirtual

Add underlying Bond names.

Reimplemented from Trade.

Definition at line 44 of file convertiblebond.cpp.

                                                                                                                {
    data_ = originalData_;
    data_.populateFromBondReferenceData(referenceDataManager);
    std::map<AssetClass, std::set<std::string>> result;
    result[AssetClass::BOND] = {data_.bondData().securityId()};
    if (!data_.conversionData().equityUnderlying().name().empty())
        result[AssetClass::EQ] = {data_.conversionData().equityUnderlying().name()};
    return result;
}

data()

const ConvertibleBondData & data

(

)

const

Definition at line 51 of file convertiblebond.hpp.

{ return data_; }

bondData()

const BondData & bondData

(

)

const

Definition at line 52 of file convertiblebond.hpp.

{ return data_.bondData(); }

Here is the call graph for this function:

Member Data Documentation

originalData_

ConvertibleBondData originalData_

private

Definition at line 55 of file convertiblebond.hpp.

data_

ConvertibleBondData data_

mutableprivate

Definition at line 56 of file convertiblebond.hpp.