Discounting Risky Bond Engine. More...

#include <qle/pricingengines/discountingriskybondengine.hpp>

Inheritance diagram for DiscountingRiskyBondEngine:

Collaboration diagram for DiscountingRiskyBondEngine:

Classes
struct	BondNPVCalculationResults

Public Member Functions
	DiscountingRiskyBondEngine (const Handle< YieldTermStructure > &discountCurve, const Handle< DefaultProbabilityTermStructure > &defaultCurve, const Handle< Quote > &recoveryRate, const Handle< Quote > &securitySpread, Period timestepPeriod, boost::optional< bool > includeSettlementDateFlows=boost::none)

	DiscountingRiskyBondEngine (const Handle< YieldTermStructure > &discountCurve, const Handle< Quote > &securitySpread, Period timestepPeriod, boost::optional< bool > includeSettlementDateFlows=boost::none)
	alternative constructor (does not require default curve or recovery rate) More...

void	calculate () const override

BondNPVCalculationResults	calculateNpv (const Date &npvDate, const Date &settlementDate, const Leg &cashflows, boost::optional< bool > includeSettlementDateFlows=boost::none, const Handle< YieldTermStructure > &incomeCurve=Handle< YieldTermStructure >(), const bool conditionalOnSurvival=true, const bool additionalResults=true) const

Handle< YieldTermStructure >	discountCurve () const

Handle< DefaultProbabilityTermStructure >	defaultCurve () const

Handle< Quote >	recoveryRate () const

Handle< Quote >	securitySpread () const

Protected Attributes
Handle< YieldTermStructure >	discountCurve_

Handle< DefaultProbabilityTermStructure >	defaultCurve_

Handle< Quote >	recoveryRate_

Handle< Quote >	securitySpread_

Period	timestepPeriod_

boost::optional< bool >	includeSettlementDateFlows_

Detailed Description

Discounting Risky Bond Engine.

WARNING: Only covers Vanilla coupon bonds (floating and fixed rate), and Zero Bonds (one cashflow, a redemption at maturity).

This class implements pricing of Risky Bonds by discounting the future nominal cash flows using the respective yield curves, and probability of survival. The nominal recovered in case of default is calculated as recovery rate times the integral of probability of default until maturity date. For coupon bonds the coupon periods are taken as the time step for integration, for a zero bond the time step period provided is used.

Definition at line 51 of file discountingriskybondengine.hpp.

Constructor & Destructor Documentation

◆ DiscountingRiskyBondEngine() [1/2]

DiscountingRiskyBondEngine	(	const Handle< YieldTermStructure > &	discountCurve,
		const Handle< DefaultProbabilityTermStructure > &	defaultCurve,
		const Handle< Quote > &	recoveryRate,
		const Handle< Quote > &	securitySpread,
		Period	timestepPeriod,
		boost::optional< bool >	includeSettlementDateFlows = `boost::none`
	)

Definition at line 35 of file discountingriskybondengine.cpp.

    : defaultCurve_(defaultCurve), recoveryRate_(recoveryRate), securitySpread_(securitySpread),
      timestepPeriod_(timestepPeriod), includeSettlementDateFlows_(includeSettlementDateFlows) {
    discountCurve_ =
        securitySpread_.empty()
            ? discountCurve
            : Handle<YieldTermStructure>(QuantLib::ext::make_shared<ZeroSpreadedTermStructure>(discountCurve, securitySpread));
    registerWith(discountCurve_);
    registerWith(defaultCurve_);
    registerWith(recoveryRate_);
    registerWith(securitySpread_);
}

Here is the call graph for this function:

◆ DiscountingRiskyBondEngine() [2/2]

DiscountingRiskyBondEngine	(	const Handle< YieldTermStructure > &	discountCurve,
		const Handle< Quote > &	securitySpread,
		Period	timestepPeriod,
		boost::optional< bool >	includeSettlementDateFlows = `boost::none`
	)

alternative constructor (does not require default curve or recovery rate)

Definition at line 52 of file discountingriskybondengine.cpp.

    : securitySpread_(securitySpread), timestepPeriod_(timestepPeriod),
      includeSettlementDateFlows_(includeSettlementDateFlows) {
    discountCurve_ =
        securitySpread_.empty()
            ? discountCurve
            : Handle<YieldTermStructure>(QuantLib::ext::make_shared<ZeroSpreadedTermStructure>(discountCurve, securitySpread));
    registerWith(discountCurve_);
    registerWith(securitySpread_);
}

Here is the call graph for this function:

Member Function Documentation

◆ calculate()

void calculate ( ) const

override

Definition at line 65 of file discountingriskybondengine.cpp.

                                                 {
    QL_REQUIRE(!discountCurve_.empty(), "discounting term structure handle is empty");
    results_.valuationDate = (*discountCurve_)->referenceDate();
 
    // the npv as of today, excluding cashflows before the settlement date
 
    DiscountingRiskyBondEngine::BondNPVCalculationResults npvResults = calculateNpv(
        results_.valuationDate, arguments_.settlementDate, arguments_.cashflows, includeSettlementDateFlows_);
 
    // the results value is set to the npv as of today including the cashflows before settlement
 
    results_.value = npvResults.npv + npvResults.cashflowsBeforeSettlementValue;
 
    // the settlement value is excluding cashflows before the settlement date and compounded to the settlement date
 
    results_.settlementValue = npvResults.npv * npvResults.compoundFactorSettlement;
 
    // set a few more additional results
    results_.additionalResults["cashFlowResults"] = npvResults.cashflowResults;
    results_.additionalResults["securitySpread"] = securitySpread_.empty() ? 0.0 : securitySpread_->value();
    Date maturity = CashFlows::maturityDate(arguments_.cashflows);
    if (maturity > results_.valuationDate) {
        Real t = discountCurve_->timeFromReference(maturity);
        results_.additionalResults["maturityTime"] = t;
        results_.additionalResults["maturityDiscountFactor"] = discountCurve_->discount(t);
        results_.additionalResults["maturitySurvivalProb"] =
            defaultCurve_.empty() ? 1.0 : defaultCurve_->survivalProbability(t);
        results_.additionalResults["recoveryRate"] = recoveryRate_.empty() ? 0.0 : recoveryRate_->value();
    }
}

Here is the call graph for this function:

Here is the caller graph for this function:

◆ calculateNpv()

DiscountingRiskyBondEngine::BondNPVCalculationResults calculateNpv	(	const Date &	npvDate,
		const Date &	settlementDate,
		const Leg &	cashflows,
		boost::optional< bool >	includeSettlementDateFlows = `boost::none`,
		const Handle< YieldTermStructure > &	incomeCurve = `Handle<YieldTermStructure>()`,
		const bool	conditionalOnSurvival = `true`,
		const bool	additionalResults = `true`
	)		const

Calculate the npv, compoundFactorSettlement, cashflowsBeforeSettlementValue and the additional CashflowResults as of the npvDate including cashflows eligible w.r.t. the given settlement date

If conditionalOnSurvival is set to true, the npv is computed conditional on the survival until the npvDate, otherwise the npv is including the default probability between today and the npvDate
If an incomeCurve is given, this is used to compound the npv from today to the npvDate, otherwise the curve built in the engine as discount curve + security Spread is used.

Definition at line 97 of file discountingriskybondengine.cpp.

                                                                                                               {
 
    bool includeRefDateFlows =
        includeSettlementDateFlows ? *includeSettlementDateFlows_ : Settings::instance().includeReferenceDateEvents();
 
    Real npvValue = 0.0;
    DiscountingRiskyBondEngine::BondNPVCalculationResults calculationResults;
    calculationResults.cashflowsBeforeSettlementValue = 0.0;
 
    // handle case where we wish to price simply with benchmark curve and scalar security spread
    // i.e. credit curve term structure (and recovery) have not been specified
    // we set the default probability and recovery rate to zero in this instance (issuer credit worthiness already
    // captured within security spread)
    QuantLib::ext::shared_ptr<DefaultProbabilityTermStructure> creditCurvePtr =
        defaultCurve_.empty() ? QuantLib::ext::make_shared<QuantLib::FlatHazardRate>(npvDate, 0.0, discountCurve_->dayCounter())
                              : defaultCurve_.currentLink();
    Rate recoveryVal = recoveryRate_.empty() ? 0.0 : recoveryRate_->value();
 
    // compounding factors for npv date
    Real dfNpv = incomeCurve.empty() ? discountCurve_->discount(npvDate) : incomeCurve->discount(npvDate);
    Real spNpv = conditionalOnSurvival ? creditCurvePtr->survivalProbability(npvDate) : 1.0;
 
    // compound factors for settlement date
    Real dfSettl =
        incomeCurve.empty() ? discountCurve_->discount(settlementDate) : incomeCurve->discount(settlementDate);
    Real spSettl = creditCurvePtr->survivalProbability(settlementDate);
    if (!conditionalOnSurvival)
        spSettl /= creditCurvePtr->survivalProbability(npvDate);
 
    // effective compound factor to get settlement npv from npv date npv
    calculationResults.compoundFactorSettlement = (dfNpv * spNpv) / (dfSettl * spSettl);
 
    Size numCoupons = 0;
    bool hasLiveCashFlow = false;
    for (Size i = 0; i < cashflows.size(); i++) {
        QuantLib::ext::shared_ptr<CashFlow> cf = cashflows[i];
        if (cf->hasOccurred(npvDate, includeRefDateFlows))
            continue;
        hasLiveCashFlow = true;
 
        DiscountFactor df = discountCurve_->discount(cf->date()) / dfNpv;
        // Coupon value is discounted future payment times the survival probability
        Probability S = creditCurvePtr->survivalProbability(cf->date()) / spNpv;
        Real tmp = cf->amount() * S * df;
        if (!cf->hasOccurred(settlementDate, includeRefDateFlows))
            npvValue += tmp;
        else
            calculationResults.cashflowsBeforeSettlementValue += tmp;
 
        /* The amount recovered in the case of default is the recoveryrate*Notional*Probability of
           Default; this is added to the NPV value. For coupon bonds the coupon periods are taken
           as the timesteps for integrating over the probability of default.
        */
        if (additionalResults) {
            CashFlowResults cfRes = populateCashFlowResultsFromCashflow(cf);
            cfRes.discountFactor = S * df;
            cfRes.presentValue = cfRes.amount * cfRes.discountFactor;
            calculationResults.cashflowResults.push_back(cfRes);
        }
 
        QuantLib::ext::shared_ptr<Coupon> coupon = QuantLib::ext::dynamic_pointer_cast<Coupon>(cf);
        if (coupon) {
            numCoupons++;
            Date startDate = coupon->accrualStartDate();
            Date endDate = coupon->accrualEndDate();
            Date effectiveStartDate = (startDate <= npvDate && npvDate <= endDate) ? npvDate : startDate;
            Date defaultDate = effectiveStartDate + (endDate - effectiveStartDate) / 2;
            Probability P = creditCurvePtr->defaultProbability(effectiveStartDate, endDate) / spNpv;
            Real expectedRecoveryAmount = coupon->nominal() * recoveryVal;
            DiscountFactor recoveryDiscountFactor = discountCurve_->discount(defaultDate) / dfNpv;
            if (additionalResults && !close_enough(expectedRecoveryAmount * P * recoveryDiscountFactor, 0.0)) {
                // Add a new flow for the expected recovery conditional on the default during
                CashFlowResults recoveryResult;
                recoveryResult.amount = expectedRecoveryAmount;
                recoveryResult.payDate = defaultDate;
                recoveryResult.currency = "";
                recoveryResult.discountFactor = P * recoveryDiscountFactor;
                recoveryResult.presentValue = recoveryResult.discountFactor * recoveryResult.amount;
                recoveryResult.type = "ExpectedRecovery";
                calculationResults.cashflowResults.push_back(recoveryResult);
            }
            npvValue += expectedRecoveryAmount * P * recoveryDiscountFactor;
        }
    }
 
    // the ql instrument might not yet be expired and still have not anything to value if
    // the npvDate > evaluation date
    if (!hasLiveCashFlow) {
        calculationResults.npv = 0.0;
        return calculationResults;
    }
 
    if (cashflows.size() > 1 && numCoupons == 0) {
        QL_FAIL("DiscountingRiskyBondEngine does not support bonds with multiple cashflows but no coupons");
    }
 
    /* If there are no coupon, as in a Zero Bond, we must integrate over the entire period from npv date to
       maturity. The timestepPeriod specified is used as provide the steps for the integration. This only applies
       to bonds with 1 cashflow, identified as a final redemption payment.
    */
    if (cashflows.size() == 1) {
        QuantLib::ext::shared_ptr<Redemption> redemption = QuantLib::ext::dynamic_pointer_cast<Redemption>(cashflows[0]);
        if (redemption) {
            Date startDate = npvDate;
            while (startDate < redemption->date()) {
                Date stepDate = startDate + timestepPeriod_;
                Date endDate = (stepDate > redemption->date()) ? redemption->date() : stepDate;
                Date defaultDate = startDate + (endDate - startDate) / 2;
                Probability P = creditCurvePtr->defaultProbability(startDate, endDate) / spNpv;
                if (additionalResults) {
                    CashFlowResults recoveryResult;
                    recoveryResult.amount = redemption->amount() * recoveryVal;
                    recoveryResult.payDate = defaultDate;
                    recoveryResult.currency = "";
                    recoveryResult.discountFactor = P * discountCurve_->discount(defaultDate) / dfNpv;
                    recoveryResult.presentValue = recoveryResult.discountFactor * recoveryResult.amount;
                    recoveryResult.type = "ExpectedRecovery";
                    calculationResults.cashflowResults.push_back(recoveryResult);
                }
                npvValue += redemption->amount() * recoveryVal * P * discountCurve_->discount(defaultDate) / dfNpv;
                startDate = stepDate;
            }
        }
    }
    calculationResults.npv = npvValue;
    return calculationResults;
} // namespace QuantExt