NumericLgmFlexiSwapEngineBase Class Reference

Numerical engine for flexi swaps in the LGM model. More...

#include <qle/pricingengines/numericlgmflexiswapengine.hpp>

Inheritance diagram for NumericLgmFlexiSwapEngineBase:

Collaboration diagram for NumericLgmFlexiSwapEngineBase:

Public Types
enum class	Method { SwaptionArray , SingleSwaptions , Automatic }

Public Member Functions
	NumericLgmFlexiSwapEngineBase (const QuantLib::ext::shared_ptr< LinearGaussMarkovModel > &model, const Real sy, const Size ny, const Real sx, const Size nx, const Handle< YieldTermStructure > &discountCurve=Handle< YieldTermStructure >(), const Method method=Method::Automatic, const Real singleSwaptionThreshold=20.0)
Public Member Functions inherited from LgmConvolutionSolver
	LgmConvolutionSolver (const QuantLib::ext::shared_ptr< LinearGaussMarkovModel > &model, const Real sy, const Size ny, const Real sx, const Size nx)
	Numerical convolution solver for the LGM model. More...
Size	gridSize () const
std::vector< Real >	stateGrid (const Real t) const
template<typename ValueType = Real>
std::vector< ValueType >	rollback (const std::vector< ValueType > &v, const Real t1, const Real t0, const ValueType zero=ValueType(0.0)) const
const QuantLib::ext::shared_ptr< LinearGaussMarkovModel > &	model () const

Protected Member Functions
std::pair< Real, Real >	calculate () const
Real	underlyingValue (const Real, const Real, const Date &, const Size, const Size, const Real, const Real) const

Protected Attributes
const Handle< YieldTermStructure >	discountCurve_
const Method	method_
const Real	singleSwaptionThreshold_
QuantLib::ext::shared_ptr< IborIndex >	iborModelIndex_
QuantLib::ext::shared_ptr< LgmImpliedYieldTermStructure >	iborModelCurve_
VanillaSwap::Type	type
std::vector< Real >	fixedNominal
std::vector< Real >	floatingNominal
std::vector< Date >	fixedResetDates
std::vector< Date >	fixedPayDates
std::vector< Time >	floatingAccrualTimes
std::vector< Date >	floatingResetDates
std::vector< Date >	floatingFixingDates
std::vector< Date >	floatingPayDates
std::vector< Real >	fixedCoupons
std::vector< Real >	fixedRate
std::vector< Real >	floatingGearings
std::vector< Real >	floatingSpreads
std::vector< Real >	cappedRate
std::vector< Real >	flooredRate
std::vector< Real >	floatingCoupons
QuantLib::ext::shared_ptr< IborIndex >	iborIndex
std::vector< Real >	lowerNotionalBound
QuantLib::Position::Type	optionPosition
std::vector< bool >	notionalCanBeDecreased

Detailed Description

Numerical engine for flexi swaps in the LGM model.

This is a modifed version of qle/pricingengines/numericlgmswaptionengine.hpp Reference: F. Jamshidian, Replication of Flexi-swaps, January 2005

There are two implementations of the rollback

a) SingleSwaptions: price each swaption on its own, using the grid rollback b) SwaptionArray: price all swaptions simultaneously by rolling back suitable Arrays instead of Reals

For a large swaption basket b) is faster than a). The two methods can be specified explicitly or the Automatic mode can be used which uses a) if the "effective number of full swaptions" is below the given singleSwaptionThreshold and b) otherwise.

Here, the effective number of full swaptions is defined to be the sum of event dates of all the swaptions in the basket divided by the number of event dates of the full underlying.

Definition at line 56 of file numericlgmflexiswapengine.hpp.

Member Enumeration Documentation

Method

enum class Method

strong

Enumerator
SwaptionArray
SingleSwaptions
Automatic

Definition at line 58 of file numericlgmflexiswapengine.hpp.

{ SwaptionArray, SingleSwaptions, Automatic };

Constructor & Destructor Documentation

NumericLgmFlexiSwapEngineBase()

NumericLgmFlexiSwapEngineBase	(	const QuantLib::ext::shared_ptr< LinearGaussMarkovModel > &	model,
		const Real	sy,
		const Size	ny,
		const Real	sx,
		const Size	nx,
		const Handle< YieldTermStructure > &	discountCurve = Handle<YieldTermStructure>(),
		const Method	method = Method::Automatic,
		const Real	singleSwaptionThreshold = 20.0
	)

Definition at line 39 of file numericlgmflexiswapengine.cpp.

    : LgmConvolutionSolver(model, sy, ny, sx, nx), discountCurve_(discountCurve), method_(method),
      singleSwaptionThreshold_(singleSwaptionThreshold) {}

Member Function Documentation

calculate()

std::pair< Real, Real > calculate ( ) const

protected

Definition at line 69 of file numericlgmflexiswapengine.cpp.

                                                                   {
 
    Date today = model()->parametrization()->termStructure()->referenceDate();
    Real phi = optionPosition == Position::Long ? 1.0 : -1.0;
 
    // the event times are the floating leg's fixing times > 0 and zero itself, also mark those events where a notional
    // decrease is admissable we might miss some payments, those are handled below
    QL_REQUIRE(fixedNominal.size() > 0, "NumericLgmFlexiSwapEngine::calculate(): fixed nominal size is zero");
    QL_REQUIRE(floatingNominal.size() > 0, "NumericLgmFlexiSwapEngine::calculate(): floating nominal size is zero");
    Size legRatio = floatingNominal.size() / fixedNominal.size(); // we know there is no remainder
    std::vector<Real> times;
    std::vector<Date> dates;
    std::vector<Size> fixCpnIndex, fltCpnIndex; // argument's vector index per event date / time
    std::vector<Real> fixPayTime, fltPayTime;   // per event date / time
    Size firstAliveIndex = Null<Size>();
    for (Size i = 0; i < floatingFixingDates.size(); ++i) {
        Date d = floatingFixingDates[i];
        if (d > today) {
            if (firstAliveIndex == Null<Size>())
                firstAliveIndex = i;
            times.push_back(model()->parametrization()->termStructure()->timeFromReference(d));
            dates.push_back(d);
            fltCpnIndex.push_back(i);
            fltPayTime.push_back(model()->parametrization()->termStructure()->timeFromReference(floatingPayDates[i]));
            if (i % legRatio == 0) {
                Size idx = static_cast<Size>(i / legRatio);
                fixCpnIndex.push_back(idx);
                fixPayTime.push_back(
                    model()->parametrization()->termStructure()->timeFromReference(fixedPayDates[idx]));
            } else {
                fixCpnIndex.push_back(Null<Size>());
                fixPayTime.push_back(Null<Real>());
            }
        }
    }
 
    int n = times.size();
 
    // construct swaption basket
 
    std::vector<Real> swaptionVolTmp;
    std::vector<Size> swaptionStartIdx, swaptionEndIdx;
    // skip indices where there is no optionality (and the notional might also still increase)
    // or where the lower notional bound is ignored, because the corresponding option date is in the past
    Size i = 0;
    while (i < fixedNominal.size() &&
           (QuantLib::close_enough(fixedNominal[i], lowerNotionalBound[i]) || i * legRatio < firstAliveIndex))
        ++i;
    Size firstIndex = i;
    for (; i < fixedNominal.size(); ++i) {
        // volume attach and detach points for which we have to generate swaptions
        Real currentVolUpper =
            i == firstIndex ? fixedNominal[firstIndex] : std::min(lowerNotionalBound[i - 1], fixedNominal[i]);
        Real currentVolLower = lowerNotionalBound[i];
        if (!QuantLib::close_enough(currentVolUpper, currentVolLower)) {
            for (Size j = i; j < fixedNominal.size(); ++j) {
                Real nextNotional = j == fixedNominal.size() - 1 ? 0.0 : fixedNominal[j + 1];
                if (nextNotional < currentVolUpper && !QuantLib::close_enough(currentVolLower, currentVolUpper)) {
                    Real tmpVol = std::min(currentVolUpper - nextNotional, currentVolUpper - currentVolLower);
                    if (!QuantLib::close_enough(tmpVol, 0.0)) {
                        swaptionStartIdx.push_back(i);
                        swaptionEndIdx.push_back(j + 1);
                        swaptionVolTmp.push_back(tmpVol);
                        currentVolUpper = std::max(nextNotional, currentVolLower);
                    }
                }
            }
            QL_REQUIRE(QuantLib::close_enough(currentVolUpper, currentVolLower),
                       "NumericLgmFlexiSwapEngine:calculate(): currentVolUpper ("
                           << currentVolUpper << ") does not match currentVolLower (" << currentVolLower
                           << "), this is unexpected");
        }
    }
 
    int m = swaptionVolTmp.size(); // number of generated swaptions
 
    // compute equivalent number of swaptions with full grid, decide on whether to price a swaption array
    // or a series of single swaptions
 
    Real fullGridSwaptions = 0.0;
    for (int i = 0; i < m; ++i) {
        fullGridSwaptions += static_cast<Size>(swaptionEndIdx[i] - swaptionStartIdx[i]);
    }
    fullGridSwaptions /= static_cast<Real>(n);
    Method effectiveMethod =
        method_ != Method::Automatic
            ? method_
            : (fullGridSwaptions < singleSwaptionThreshold_ ? Method::SingleSwaptions : Method::SwaptionArray);
    // if we do not have any swaptions, swaption array is the only method that works (and which is fast also,
    // since the operations on empty arrays do not cost much)
    if (m == 0)
        effectiveMethod = Method::SwaptionArray;
 
    // per event date, per swaption, indicator if coupon belongs to underlying
    std::vector<Array> underlyingMultiplier(n, Array(m, 0.0));
    // per event date, per swaption, indicator if exercise is possible
    std::vector<Array> exerciseIndicator(n, Array(m, 0.0));
    // per swaption, its notional
    Array notionals(m);
 
    for (int i = 0; i < m; ++i) {
        notionals[i] = swaptionVolTmp[i];
        for (Size j = swaptionStartIdx[i]; j < swaptionEndIdx[i]; ++j) {
            Size index = j * legRatio;
            if (notionalCanBeDecreased[j] && index >= firstAliveIndex) {
                index -= firstAliveIndex;
                exerciseIndicator[index][i] = 1.0;
                for (Size k = 0; k < legRatio; ++k) {
                    underlyingMultiplier[index + k][i] = swaptionVolTmp[i];
                }
            }
        }
    }
 
    // model linked ibor index curve
 
    iborModelCurve_ = QuantLib::ext::make_shared<LgmImpliedYtsFwdFwdCorrected>(model(), iborIndex->forwardingTermStructure());
    iborModelIndex_ = iborIndex->clone(Handle<YieldTermStructure>(iborModelCurve_));
 
    // x grid for each expiry
 
    // underlying u and continuation value v for single swaption (_s) and array swaption (_a) approach)
    std::vector<Array> u_a, v_a;
    std::vector<Real> u_s, v_s;
    if (effectiveMethod == Method::SingleSwaptions) {
        u_s.resize(gridSize(), 0.0);
        v_s.resize(gridSize(), 0.0);
    } else {
        u_a.resize(gridSize(), Array(m, 0.0));
        v_a.resize(gridSize(), Array(m, 0.0));
    }
 
    Real undValAll0 = 0.0;    // underlying value valued on the grid
    int undValAllIdx = n + 1; // index until which we have collected the underlying coupons
    Array value0(m, 0.0);     // option values
 
    // loop over swaption for single swaptions method, otherwise this is one loop
    for (int sw = (effectiveMethod == Method::SingleSwaptions ? m - 1 : 0); sw >= 0; --sw) {
 
        // per grid index underlying value (independent of swaptions, just to collect the underlying value)
        std::vector<Real> uAll(gridSize(), 0.0);
 
        // init at last grid point
        // determine last time index for relevant swaption if in single swaption mode
        // for the first swaption we start at the maximum always to make sure we collect
        // all coupons for the underlying value
        if (effectiveMethod == Method::SingleSwaptions && sw != m - 1) {
            QL_REQUIRE(swaptionEndIdx[sw] * legRatio >= firstAliveIndex,
                       "swaptionEndIndex[" << sw << "] * legRatio (" << legRatio << ") < firstAliveIndex ("
                                           << firstAliveIndex << ") - this is unexpected.");
            n = swaptionEndIdx[sw] * legRatio - firstAliveIndex;
        }
 
        auto states = stateGrid(times[n - 1]);
        for (Size k = 0; k < gridSize(); ++k) {
            Real tmp = underlyingValue(states[k], times[n - 1], dates[n - 1], fltCpnIndex[n - 1], fixCpnIndex[n - 1],
                                       fltPayTime[n - 1], fixPayTime[n - 1]);
            // we can use the floating notional for both legs, since they have a consistent notional by construction
            if (n < undValAllIdx) {
                uAll[k] = tmp * floatingNominal[fltCpnIndex[n - 1]];
            }
            if (effectiveMethod == Method::SingleSwaptions) {
                u_s[k] = tmp * underlyingMultiplier[n - 1][sw];
                v_s[k] = exerciseIndicator[n - 1][sw] * std::max(-phi * u_s[k], 0.0);
            } else {
                u_a[k] = tmp * underlyingMultiplier[n - 1];
                v_a[k] = exerciseIndicator[n - 1] * max(-phi * u_a[k], 0.0);
            }
        }
 
        // roll back to first positive event time (in single swaption mode this might be > 1 though)
        // for the last swaption we roll back to 1 in every case to make sure that we collect all
        // coupons for the underlying value
 
        int minIndex = 0;
        if (effectiveMethod == Method::SingleSwaptions && sw != 0) {
            QL_REQUIRE(swaptionStartIdx[sw] * legRatio >= firstAliveIndex,
                       "swaptionStartIndex[" << sw << "] * legRatio (" << legRatio << ") < firstAliveIndex ("
                                             << firstAliveIndex << ") - this is unexpected.");
            minIndex = swaptionStartIdx[sw] * legRatio - firstAliveIndex;
        }
 
        for (int j = n - 1; j > minIndex; j--) {
            // rollback
            auto states = stateGrid(times[j - 1]);
            if (effectiveMethod == Method::SingleSwaptions) {
                u_s = rollback(u_s, times[j], times[j - 1]);
                v_s = rollback(v_s, times[j], times[j - 1]);
            } else {
                u_a = rollback(u_a, times[j], times[j - 1], Array(m, 0.0));
                v_a = rollback(v_a, times[j], times[j - 1], Array(m, 0.0));
            }
            if (j < undValAllIdx) {
                uAll = rollback(uAll, times[j], times[j - 1]);
            }
            // update
            for (Size k = 0; k < gridSize(); ++k) {
                Real tmp = underlyingValue(states[k], times[j - 1], dates[j - 1], fltCpnIndex[j - 1],
                                           fixCpnIndex[j - 1], fltPayTime[j - 1], fixPayTime[j - 1]);
                uAll[k] += (j < undValAllIdx ? tmp * floatingNominal[fltCpnIndex[j - 1]] : 0.0);
                if (effectiveMethod == Method::SingleSwaptions) {
                    u_s[k] += tmp * underlyingMultiplier[j - 1][sw];
                    v_s[k] = exerciseIndicator[j - 1][sw] * std::max(v_s[k], -phi * u_s[k]) +
                             (1.0 - exerciseIndicator[j - 1][sw]) * v_s[k];
                } else {
                    u_a[k] += tmp * underlyingMultiplier[j - 1];
                    v_a[k] = exerciseIndicator[j - 1] * max(v_a[k], -phi * u_a[k]) +
                             (1.0 - exerciseIndicator[j - 1]) * v_a[k];
                }
            } // for k (lgm grid)
        }     // for j (options)
 
        // roll back to time zero
 
        if (effectiveMethod == Method::SingleSwaptions) {
            v_s = rollback(v_s, times[minIndex], 0.0);
        } else {
            v_a = rollback(v_a, times[minIndex], 0.0, Array(m, 0.0));
        }
        uAll = rollback(uAll, times[minIndex], 0.0);
 
        // update undValAllIndx
        undValAllIdx = minIndex + 1;
 
        // populate option values
        if (effectiveMethod == Method::SingleSwaptions)
            value0[sw] = v_s[0];
        else
            value0 = v_a[0];
 
        // update underlying value
        undValAll0 += uAll[0];
 
    } // for swaptions (in single swaption mode, otherwise this is a loop that runs once only)
 
    // handle coupons we omitted above and add them to underlying value
 
    Size minFltCpnIdx = fltCpnIndex.empty() ? 0 : *std::min_element(fltCpnIndex.begin(), fltCpnIndex.end());
    Size minFixCpnIdx = fixCpnIndex.empty() ? 0 : *std::min_element(fixCpnIndex.begin(), fixCpnIndex.end());
 
    for (Size i = 0; i < fixedCoupons.size(); ++i) {
        if (fixedPayDates[i] > today && i < minFixCpnIdx) {
            undValAll0 += (type == VanillaSwap::Payer ? -1.0 : 1.0) * fixedCoupons[i] *
                          (discountCurve_.empty() ? model()->parametrization()->termStructure() : discountCurve_)
                              ->discount(fixedPayDates[i]);
        }
    }
 
    for (Size i = 0; i < floatingCoupons.size(); ++i) {
        if (floatingPayDates[i] > today && i < minFltCpnIdx) {
            QL_REQUIRE(floatingCoupons[i] != Null<Real>(),
                       "NumericLgmFlexiSwapEngineBase: no floating coupon provided for fixing date "
                           << floatingFixingDates[i]);
            undValAll0 += (type == VanillaSwap::Payer ? 1.0 : -1.0) * floatingCoupons[i] *
                          (discountCurve_.empty() ? model()->parametrization()->termStructure() : discountCurve_)
                              ->discount(floatingPayDates[i]);
        }
    }
 
    // sum over option values
    Real sumOptions = std::accumulate(value0.begin(), value0.end(), 0.0);
 
    // debug logging
    // std::cerr << "Flexi-Swap pricing engine log:\n";
    // std::cerr << "===========================\n";
    // std::cerr << "underlying value = " << undValAll0 << "\n";
    // std::cerr << "option value     = " << phi * sumOptions << "\n";
    // std::cerr << "===========================\n";
    // std::cerr << "swaption basket (" << m << "):\n";
    // Real sumNot = 0.0;
    // for (Size i = 0; i < m; ++i) {
    //     std::cerr << "swaption #" << i << " (start,end)=(" << swaptionStartIdx[i] << "," << swaptionEndIdx[i]
    //               << ") notional = " << notionals[i] << " NPV = " << phi * value0[i] << "\n";
    //     sumNot += notionals[i];
    // }
    // std::cerr << "sum of swaption notional = " << sumNot << "\n";
    // std::cerr << "number of equivalent full swaptions = " << fullGridSwaptions
    //           << ", singleSwaptionThreshold = " << singleSwaptionThreshold_ << "\n";
    // std::cerr << "method = " << static_cast<int>(method_) << " (0=array, 1=single, 2=auto)\n";
    // details
    // std::cerr << "===========================\n";
    // std::cerr << "times  underlying  exercise\n";
    // for (Size i = 0; i < times.size(); ++i) {
    //     std::cerr << times[i] << " " << underlyingMultiplier[i] << " " << exerciseIndicator[i] << "\n";
    // }
    // end details
    // std::cerr << "Flex-Swap pricing engine log end" << std::endl;
    // end logging
 
    return std::make_pair(phi * sumOptions + undValAll0, undValAll0);
 
} // NumericLgmFlexiSwapEngineBase::calculate()

Here is the call graph for this function:

Here is the caller graph for this function:

underlyingValue()

Real underlyingValue ( const Real  x, const Real  t, const Date &  d, const Size  fltIndex, const Size  fixIndex, const Real  fltPayTime, const Real  fixPayTime  ) const

protected

Definition at line 46 of file numericlgmflexiswapengine.cpp.

                                                                                 {
    Real val = 0.0;
    Real om = type == VanillaSwap::Payer ? -1.0 : 1.0;
    if (fixIndex != Null<Size>()) {
        if (!QuantLib::close_enough(fixedNominal[fixIndex], 0.0))
            val = om * fixedCoupons[fixIndex] / fixedNominal[fixIndex] *
                  model()->reducedDiscountBond(t, fixPayTime, x, discountCurve_);
    }
    if (fltIndex != Null<Size>()) {
        iborModelCurve_->move(d, x);
        Real fixing = floatingGearings[fltIndex] * iborModelIndex_->fixing(d) + floatingSpreads[fltIndex];
        if (cappedRate[fltIndex] != Null<Real>())
            fixing = std::min(fixing, cappedRate[fltIndex]);
        if (flooredRate[fltIndex] != Null<Real>())
            fixing = std::max(fixing, flooredRate[fltIndex]);
        val += -om * fixing * floatingAccrualTimes[fltIndex] *
               model()->reducedDiscountBond(t, fltPayTime, x, discountCurve_);
    }
    return val;
} // NumericLgmFlexiSwapEngineBase::underlyingValue()

Here is the call graph for this function:

Here is the caller graph for this function:

Member Data Documentation

discountCurve_

const Handle<YieldTermStructure> discountCurve_

protected

Definition at line 70 of file numericlgmflexiswapengine.hpp.

method_

const Method method_

protected

Definition at line 71 of file numericlgmflexiswapengine.hpp.

singleSwaptionThreshold_

const Real singleSwaptionThreshold_

protected

Definition at line 72 of file numericlgmflexiswapengine.hpp.

iborModelIndex_

QuantLib::ext::shared_ptr<IborIndex> iborModelIndex_

mutableprotected

Definition at line 74 of file numericlgmflexiswapengine.hpp.

iborModelCurve_

QuantLib::ext::shared_ptr<LgmImpliedYieldTermStructure> iborModelCurve_

mutableprotected

Definition at line 75 of file numericlgmflexiswapengine.hpp.

type

VanillaSwap::Type type

mutableprotected

Definition at line 77 of file numericlgmflexiswapengine.hpp.

fixedNominal

std::vector<Real> fixedNominal

mutableprotected

Definition at line 78 of file numericlgmflexiswapengine.hpp.

floatingNominal

std::vector<Real> floatingNominal

protected

Definition at line 78 of file numericlgmflexiswapengine.hpp.

fixedResetDates

std::vector<Date> fixedResetDates

mutableprotected

Definition at line 79 of file numericlgmflexiswapengine.hpp.

fixedPayDates

std::vector<Date> fixedPayDates

mutableprotected

Definition at line 80 of file numericlgmflexiswapengine.hpp.

floatingAccrualTimes

std::vector<Time> floatingAccrualTimes

mutableprotected

Definition at line 81 of file numericlgmflexiswapengine.hpp.

floatingResetDates

std::vector<Date> floatingResetDates

mutableprotected

Definition at line 82 of file numericlgmflexiswapengine.hpp.

floatingFixingDates

std::vector<Date> floatingFixingDates

mutableprotected

Definition at line 83 of file numericlgmflexiswapengine.hpp.

floatingPayDates

std::vector<Date> floatingPayDates

mutableprotected

Definition at line 84 of file numericlgmflexiswapengine.hpp.

fixedCoupons

std::vector<Real> fixedCoupons

mutableprotected

Definition at line 85 of file numericlgmflexiswapengine.hpp.

fixedRate

std::vector<Real> fixedRate

mutableprotected

Definition at line 86 of file numericlgmflexiswapengine.hpp.

floatingGearings

std::vector<Real> floatingGearings

mutableprotected

Definition at line 87 of file numericlgmflexiswapengine.hpp.

floatingSpreads

std::vector<Real> floatingSpreads

mutableprotected

Definition at line 88 of file numericlgmflexiswapengine.hpp.

cappedRate

std::vector<Real> cappedRate

mutableprotected

Definition at line 89 of file numericlgmflexiswapengine.hpp.

flooredRate

std::vector<Real> flooredRate

mutableprotected

Definition at line 90 of file numericlgmflexiswapengine.hpp.

floatingCoupons

std::vector<Real> floatingCoupons

mutableprotected

Definition at line 91 of file numericlgmflexiswapengine.hpp.

iborIndex

QuantLib::ext::shared_ptr<IborIndex> iborIndex

mutableprotected

Definition at line 92 of file numericlgmflexiswapengine.hpp.

lowerNotionalBound

std::vector<Real> lowerNotionalBound

mutableprotected

Definition at line 93 of file numericlgmflexiswapengine.hpp.

optionPosition

QuantLib::Position::Type optionPosition

mutableprotected

Definition at line 94 of file numericlgmflexiswapengine.hpp.

notionalCanBeDecreased

std::vector<bool> notionalCanBeDecreased

mutableprotected

Definition at line 95 of file numericlgmflexiswapengine.hpp.