BlackBondOptionEngine Class Reference

Black-formula bond option engine. More...

#include <qle/pricingengines/blackbondoptionengine.hpp>

Inheritance diagram for BlackBondOptionEngine:

Collaboration diagram for BlackBondOptionEngine:

Public Member Functions
	BlackBondOptionEngine (const Handle< YieldTermStructure > &discountCurve, const Handle< SwaptionVolatilityStructure > &volatility, const Handle< YieldTermStructure > &underlyingReferenceCurve, const Handle< DefaultProbabilityTermStructure > &defaultCurve=Handle< DefaultProbabilityTermStructure >(), const Handle< Quote > &recoveryRate=Handle< Quote >(), const Handle< Quote > &securitySpread=Handle< Quote >(), Period timestepPeriod=1 *Months)
	volatility is the quoted fwd yield volatility, not price vol More...
void	calculate () const override

Private Attributes
Handle< YieldTermStructure >	discountCurve_
Handle< SwaptionVolatilityStructure >	volatility_
Handle< YieldTermStructure >	underlyingReferenceCurve_
Handle< DefaultProbabilityTermStructure >	defaultCurve_
Handle< Quote >	recoveryRate_
Handle< Quote >	securitySpread_
Period	timestepPeriod_

Detailed Description

Black-formula bond option engine.

Definition at line 36 of file blackbondoptionengine.hpp.

Constructor & Destructor Documentation

BlackBondOptionEngine()

BlackBondOptionEngine	(	const Handle< YieldTermStructure > &	discountCurve,
		const Handle< SwaptionVolatilityStructure > &	volatility,
		const Handle< YieldTermStructure > &	underlyingReferenceCurve,
		const Handle< DefaultProbabilityTermStructure > &	defaultCurve = Handle<DefaultProbabilityTermStructure>(),
		const Handle< Quote > &	recoveryRate = Handle<Quote>(),
		const Handle< Quote > &	securitySpread = Handle<Quote>(),
		Period	timestepPeriod = 1 * Months
	)

volatility is the quoted fwd yield volatility, not price vol

Definition at line 33 of file blackbondoptionengine.cpp.

    : discountCurve_(discountCurve), volatility_(volatility), underlyingReferenceCurve_(underlyingReferenceCurve),
      defaultCurve_(defaultCurve), recoveryRate_(recoveryRate), securitySpread_(securitySpread),
      timestepPeriod_(timestepPeriod) {
    registerWith(discountCurve_);
    registerWith(volatility_);
    registerWith(underlyingReferenceCurve_);
    registerWith(defaultCurve_);
    registerWith(recoveryRate_);
    registerWith(securitySpread_);
}

Member Function Documentation

calculate()

void calculate ( ) const

override

Definition at line 50 of file blackbondoptionengine.cpp.

                                            {
 
    QL_REQUIRE(!discountCurve_.empty(), "BlackBondOptionEngine::calculate(): empty discount curve");
 
    QL_REQUIRE(arguments_.putCallSchedule.size() == 1, "BlackBondOptionEngine: can only handle European options");
    Date exerciseDate = arguments_.putCallSchedule.front()->date();
 
    QL_REQUIRE(!underlyingReferenceCurve_.empty(), "BlackBondOptionEngine::calculate(): empty reference curve");
 
    auto fwdBondEngine = QuantLib::ext::make_shared<DiscountingRiskyBondEngine>(
        underlyingReferenceCurve_, defaultCurve_, recoveryRate_, securitySpread_, timestepPeriod_);
    auto bondNpvResults = fwdBondEngine->calculateNpv(exerciseDate, arguments_.underlying->settlementDate(exerciseDate),
                                              arguments_.underlying->cashflows());
    
    for (auto& cfRes : bondNpvResults.cashflowResults) {
        cfRes.legNumber = 0;
        cfRes.type = "Underlying_Bond__" + cfRes.type;
    }
    
    Real fwdNpv = bondNpvResults.npv;
 
   
    Real knockOutProbability = defaultCurve_.empty() ? 0.0 : 1.0 - defaultCurve_->survivalProbability(exerciseDate);
 
    // adjust forward if option does not knock out (option is on the recovery value if bond defaults before expiry)
    if (!arguments_.knocksOutOnDefault) {
        fwdNpv = (1.0 - knockOutProbability) * fwdNpv + knockOutProbability *
                                                            (recoveryRate_.empty() ? 0.0 : recoveryRate_->value()) *
                                                            arguments_.underlying->notional(exerciseDate);
    }
 
    // hard code yield compounding convention to annual
    Rate fwdYtm = CashFlows::yield(arguments_.underlying->cashflows(), fwdNpv, volatility_->dayCounter(), Compounded,
                                   Annual, false, exerciseDate, exerciseDate);
    InterestRate fwdRate(fwdYtm, volatility_->dayCounter(), Compounded, Annual);
    Time fwdDur = CashFlows::duration(arguments_.underlying->cashflows(), fwdRate, Duration::Modified, false,
                                      exerciseDate, exerciseDate);
 
    QL_REQUIRE(arguments_.putCallSchedule.size() == 1, "BlackBondOptionEngine: only European bond options allowed");
 
    // read atm yield vol
    Real underlyingLength = volatility_->swapLength(exerciseDate, arguments_.underlying->cashflows().back()->date());
    Volatility yieldVol = volatility_->volatility(exerciseDate, underlyingLength, fwdYtm);
 
    // compute price vol from yield vol
    Volatility fwdPriceVol;
    Real shift = 0.0;
    if (volatility_->volatilityType() == VolatilityType::Normal)
        fwdPriceVol = yieldVol * fwdDur;
    else {
        if (close_enough(volatility_->shift(exerciseDate, underlyingLength), 0.0)) {
            QL_REQUIRE(fwdYtm > 0, "BlackBondOptionEngine: input yield vols are lognormal, but yield is not positive ("
                                       << fwdYtm << ")");
            fwdPriceVol = yieldVol * fwdDur * fwdYtm;
        } else {
            shift = volatility_->shift(exerciseDate, underlyingLength);
            QL_REQUIRE(fwdYtm > -shift, "BlackBondOptionEngine: input yield vols are shifted lognormal "
                                            << shift << ", but yield (" << fwdYtm << ") is not greater than -shift ("
                                            << -shift);
            fwdPriceVol = yieldVol * fwdDur * (fwdYtm + shift);
        }
    }
 
    QL_REQUIRE(fwdPriceVol >= 0.0, "BlackBondOptionEngine: negative forward price vol ("
                                       << fwdPriceVol << "), yieldVol=" << yieldVol << ", fwdDur=" << fwdDur
                                       << ", fwdYtm=" << fwdYtm << ", shift="
                                       << (volatility_->volatilityType() == VolatilityType::Normal
                                               ? 0.0
                                               : volatility_->shift(exerciseDate, underlyingLength)));
 
    // strike could be a price or yield
    Real cashStrike;
    if (arguments_.putCallSchedule.front()->isBondPrice()) {
        // adjust cashCashStrike if given as clean
        // note that the accruedAmount is on the basis of notional 100, as cleanPrice and dirtyPrice
        cashStrike = arguments_.putCallSchedule.front()->price().amount();
        if (arguments_.putCallSchedule.front()->price().type() == QuantLib::Bond::Price::Clean)
            cashStrike += arguments_.underlying->accruedAmount(exerciseDate) / 100;
    } else {
        // for a yield get the strike using npv calculation, yield should always be dirty price
        // so no adjustment needed
        InterestRate yield = arguments_.putCallSchedule.front()->yield();
        cashStrike = CashFlows::npv(arguments_.underlying->cashflows(), yield, false, exerciseDate, exerciseDate);
    }
 
    Real optionValue = blackFormula(
        arguments_.putCallSchedule[0]->type() == Callability::Call ? Option::Call : Option::Put, cashStrike, fwdNpv,
        fwdPriceVol * std::sqrt(volatility_->timeFromReference(exerciseDate)), discountCurve_->discount(exerciseDate));
 
    // correct for knock out probability
    if (arguments_.knocksOutOnDefault && !defaultCurve_.empty())
        optionValue *= 1.0 - knockOutProbability;
 
    CashFlowResults optionFlow;
    optionFlow.payDate = exerciseDate;
    optionFlow.legNumber = 1;
    optionFlow.type = "ExpectedOptionPayoff";
    optionFlow.amount = optionValue / discountCurve_->discount(exerciseDate);
    optionFlow.discountFactor = discountCurve_->discount(exerciseDate);
    optionFlow.presentValue = optionValue;
 
    bondNpvResults.cashflowResults.push_back(optionFlow);
 
    results_.additionalResults["knockOutProbability"] = knockOutProbability;
    results_.additionalResults["cashFlowResults"] = bondNpvResults.cashflowResults;
    results_.additionalResults["CashStrike"] = cashStrike;
    results_.additionalResults["FwdCashPrice"] = fwdNpv;
    results_.additionalResults["PriceVol"] = fwdPriceVol;
    results_.additionalResults["timeToExpiry"] = volatility_->timeFromReference(exerciseDate);
    results_.additionalResults["optionValue"] = optionValue;
    results_.additionalResults["yieldVol"] = yieldVol;
    results_.additionalResults["yieldVolShift"] = shift;
    results_.additionalResults["fwdDuration"] = fwdDur;
    results_.additionalResults["fwdYieldToMaturity"] = fwdYtm;
 
    results_.additionalResults["AccruedAtExercise"] = arguments_.underlying->accruedAmount(exerciseDate)/100;
    // results_.additionalResults["CleanBondPrice"] = arguments_.underlying->cleanPrice();
    // results_.additionalResults["DirtyBondPrice"] = arguments_.underlying->dirtyPrice();
    if (!arguments_.knocksOutOnDefault) {
        results_.additionalResults["ExpectedBondRecovery"] = knockOutProbability *
                                                             (recoveryRate_.empty() ? 0.0 : recoveryRate_->value()) *
                                                             arguments_.underlying->notional(exerciseDate);
    }
    results_.value = optionValue;
}

Here is the call graph for this function:

Member Data Documentation

discountCurve_

Handle<YieldTermStructure> discountCurve_

private

Definition at line 48 of file blackbondoptionengine.hpp.

volatility_

Handle<SwaptionVolatilityStructure> volatility_

private

Definition at line 49 of file blackbondoptionengine.hpp.

underlyingReferenceCurve_

Handle<YieldTermStructure> underlyingReferenceCurve_

private

Definition at line 50 of file blackbondoptionengine.hpp.

defaultCurve_

Handle<DefaultProbabilityTermStructure> defaultCurve_

private

Definition at line 51 of file blackbondoptionengine.hpp.

recoveryRate_

Handle<Quote> recoveryRate_

private

Definition at line 52 of file blackbondoptionengine.hpp.

securitySpread_

Handle<Quote> securitySpread_

private

Definition at line 53 of file blackbondoptionengine.hpp.

timestepPeriod_

Period timestepPeriod_

private

Definition at line 54 of file blackbondoptionengine.hpp.