CollateralExposureHelper Class Reference

Collateral Exposure Helper. More...

#include <orea/aggregation/collatexposurehelper.hpp>

Collaboration diagram for CollateralExposureHelper:

Public Types
enum	CalculationType { Symmetric , AsymmetricCVA , AsymmetricDVA , NoLag }

Static Public Member Functions
static Real	marginRequirementCalc (const QuantLib::ext::shared_ptr< CollateralAccount > &collat, const Real &uncollatValue, const Date &simulationDate)
template<class T >
static Real	estimateUncollatValue (const Date &simulationDate, const Real &npv_t0, const Date &date_t0, const vector< vector< T > > &scenPvProfiles, const unsigned &scenIndex, const vector< Date > &dateGrid)
static void	updateMarginCall (const QuantLib::ext::shared_ptr< CollateralAccount > &collat, const Real &uncollatValue, const Date &simulationDate, const Real &accrualFactor, const CalculationType &calcType=Symmetric, const bool &eligMarginReqDateUs=true, const bool &eligMarginReqDateCtp=true)
static Real	creditSupportAmount (const QuantLib::ext::shared_ptr< ore::data::NettingSetDefinition > &nettingSet, const Real &uncollatValueCsaCur)
static QuantLib::ext::shared_ptr< vector< QuantLib::ext::shared_ptr< CollateralAccount > > >	collateralBalancePaths (const QuantLib::ext::shared_ptr< NettingSetDefinition > &csaDef, const Real &nettingSetPv, const Date &date_t0, const vector< vector< Real > > &nettingSetValues, const Date &nettingSet_maturity, const vector< Date > &dateGrid, const Real &csaFxTodayRate, const vector< vector< Real > > &csaFxScenarioRates, const Real &csaTodayCollatCurve, const vector< vector< Real > > &csaScenCollatCurves, const CalculationType &calcType=Symmetric, const QuantLib::ext::shared_ptr< CollateralBalance > &balance=QuantLib::ext::shared_ptr< CollateralBalance >())

Detailed Description

Collateral Exposure Helper.

This class contains helper functions to aid in the calculation of collateralised exposures.

It can be used to calculate margin requirements in the presence of e.g. thresholds and minimum transfer amounts, update collateral account details with e.g. new margin call info, and return collateralised exposures to the user/invoker.

For further information refer to the detailed ORE documentation.

Definition at line 51 of file collatexposurehelper.hpp.

Member Enumeration Documentation

CalculationType

enum CalculationType

Enumeration 'CalculationType' specifies how the collateralised exposures should be calculated (please refer to Sungard white-paper titled "Closing In On the CloseOut"):

• 'Symmetric' => margin calls only settled after margin period of risk
• 'AsymmetricCVA' => margin requested from ctp only settles after margin period of risk – (our margin postings settle instantaneously)
• 'AsymmetricDVA' => margin postings to ctp only settle after margin period of risk – (margin calls to receive collateral from counterparty settle instantaneously)
• 'NoLag' => margin calls/postings settled without margin period of risk delay

Enumerator
Symmetric
AsymmetricCVA
AsymmetricDVA
NoLag

Definition at line 64 of file collatexposurehelper.hpp.

{ Symmetric, AsymmetricCVA, AsymmetricDVA, NoLag };

Member Function Documentation

marginRequirementCalc()

Real marginRequirementCalc ( const QuantLib::ext::shared_ptr< CollateralAccount > &  collat, const Real &  uncollatValue, const Date &  simulationDate  )

static

Calculates CSA margin requirement, taking the following into account

• uncollateralised value
• collateral value
• threshold
• minimum transfer amount
• independent amount

Definition at line 60 of file collatexposurehelper.cpp.

                                                                                                            {
    // first step, make sure collateral balance is up to date.
    //        collat->updateAccountBalance(simulationDate);
 
    Real collatBalance = collat->accountBalance();
    Real csa = creditSupportAmount(collat->csaDef(), uncollatValue);
 
    Real openMargins = collat->outstandingMarginAmount(simulationDate);
    Real collatShortfall = csa - collatBalance - openMargins;
 
    Real mta;
    if (collatShortfall >= 0.0)
      mta = collat->csaDef()->csaDetails()->mtaRcv();
    else
      mta = collat->csaDef()->csaDetails()->mtaPay();
 
    Real deliveryAmount = fabs(collatShortfall) >= mta ? (collatShortfall) : 0.0;
 
    return deliveryAmount;
}

Here is the call graph for this function:

Here is the caller graph for this function:

estimateUncollatValue()

Real estimateUncollatValue ( const Date &  simulationDate, const Real &  npv_t0, const Date &  date_t0, const vector< vector< T > > &  scenPvProfiles, const unsigned &  scenIndex, const vector< Date > &  dateGrid  )

static

Performs linear interpolation between dates to estimate the value as of simulationDate. Flat extrapolation at far end.

Definition at line 101 of file collatexposurehelper.cpp.

                                                                                                              {
 
    QL_REQUIRE(simulationDate >= date_t0, "CollatExposureHelper error: simulation date < start date");
    QL_REQUIRE(dateGrid[0] >= date_t0, "CollatExposureHelper error: cube dateGrid starts before t0");
 
    if (simulationDate >= dateGrid.back())
        return scenPvProfiles.back()[scenIndex]; // flat extrapolation
    if (simulationDate == date_t0)
        return npv_t0;
    for (unsigned i = 0; i < dateGrid.size(); i++) {
        if (dateGrid[i] == simulationDate)
            // return if collat sim-date is the same as an exposure grid date
            return scenPvProfiles[i][scenIndex];
#ifdef FLAT_INTERPOLATION
        else if (simulationDate < dateGrid.front())
            return scenPvProfiles.front()[scenIndex];
        else if (i < dateGrid.size() - 1 && simulationDate > dateGrid[i] && simulationDate < dateGrid[i + 1])
            return scenPvProfiles[i + 1][scenIndex];
#endif
    }
 
    // if none of above criteria are met, perform interpolation
    Date t1, t2;
    Real npv1, npv2;
    if (simulationDate <= dateGrid[0]) {
        t1 = date_t0;
        t2 = dateGrid[0];
        npv1 = npv_t0;
        npv2 = scenPvProfiles[0][scenIndex];
    } else {
        vector<Date>::const_iterator it = lower_bound(dateGrid.begin(), dateGrid.end(), simulationDate);
        QL_REQUIRE(it != dateGrid.end(), "CollatExposureHelper error; "
                                             << "date interpolation points not found (it.end())");
        QL_REQUIRE(it != dateGrid.begin(), "CollatExposureHelper error; "
                                               << "date interpolation points not found (it.begin())");
        Size pos1 = (it - 1) - dateGrid.begin();
        Size pos2 = it - dateGrid.begin();
        t1 = dateGrid[pos1];
        t2 = dateGrid[pos2];
        npv1 = scenPvProfiles[pos1][scenIndex];
        npv2 = scenPvProfiles[pos2][scenIndex];
    }
 
    Real newPv = npv1 + ((npv2 - npv1) * (double(simulationDate - t1) / double(t2 - t1)));
    QL_REQUIRE((npv1 <= newPv && newPv <= npv2) || (npv1 >= newPv && newPv >= npv2),
               "CollatExposureHelper error; "
                   << "interpolated Pv value " << newPv << " out of range (" << npv1 << " " << npv2 << ") "
                   << "for simulation date " << simulationDate << " between " << t1 << " and " << t2);
 
    return newPv;
}

Here is the caller graph for this function:

updateMarginCall()

void updateMarginCall ( const QuantLib::ext::shared_ptr< CollateralAccount > &  collat, const Real &  uncollatValue, const Date &  simulationDate, const Real &  accrualFactor, const CalculationType &  calcType = Symmetric, const bool &  eligMarginReqDateUs = true, const bool &  eligMarginReqDateCtp = true  )

static

Checks if margin call is in need of update, and updates if necessary

Definition at line 155 of file collatexposurehelper.cpp.

                                                                                                                   {
    collat->updateAccountBalance(simulationDate, annualisedZeroRate);
 
    Real margin = marginRequirementCalc(collat, uncollatValue, simulationDate);
 
    if (margin != 0.0) {
        // settle margin call on appropriate date
        // (dependent upon MPR and collateralised calculation methodology)
        Date marginPayDate;
    // RL 2020-07-17
    // 1) If the calculation type is set to NoLag:
    //    Collateral balances are NOT delayed by the MPoR, but we use the close-out NPV in exposure calculations,
    //    see similar comment and the equivalent change in the post processor.
    // 2) Otherwise:
    //    Collateral balances are delayed by the MPoR (if possible, i.e. the valuation grid has MPoR spacing),
    //    and we use the default date NPV.
    //    This is the treatment in the ORE releases up to June 2020).
    Period lag = (calcType == NoLag ? 0*Days : collat->csaDef()->csaDetails()->marginPeriodOfRisk());
        if (margin > 0.0 && eligMarginReqDateUs) {
        marginPayDate =
                (calcType == AsymmetricDVA ? simulationDate : simulationDate + lag);
            collat->updateMarginCall(margin, marginPayDate, simulationDate);
        } else if (margin < 0.0 && eligMarginReqDateCtp) {
            marginPayDate =
                (calcType == AsymmetricCVA ? simulationDate : simulationDate + lag);
            collat->updateMarginCall(margin, marginPayDate, simulationDate);
        } else {
        }
    }
}

Here is the call graph for this function:

Here is the caller graph for this function:

creditSupportAmount()

Real creditSupportAmount ( const QuantLib::ext::shared_ptr< ore::data::NettingSetDefinition > &  nettingSet, const Real &  uncollatValueCsaCur  )

static

Computes the Credit Support Amount for the portfolio, given an unsecured exposure as input All calculations done in CSA currency

Definition at line 82 of file collatexposurehelper.cpp.

                                     {
 
    Real ia = nettingSet->csaDetails()->independentAmountHeld();
    Real threshold, csa;
    if (uncollatValueCsaCur + ia >= 0) {
        threshold = nettingSet->csaDetails()->thresholdRcv();
        csa = max(uncollatValueCsaCur + ia - threshold, 0.0);
    }
    else {
        threshold = nettingSet->csaDetails()->thresholdPay();
        // N.B. the min and change of sign on threshold.
        csa = min(uncollatValueCsaCur + ia + threshold, 0.0);
    }
    return csa;
}

Here is the call graph for this function:

Here is the caller graph for this function:

collateralBalancePaths()

QuantLib::ext::shared_ptr< vector< QuantLib::ext::shared_ptr< CollateralAccount > > > collateralBalancePaths ( const QuantLib::ext::shared_ptr< NettingSetDefinition > &  csaDef, const Real &  nettingSetPv, const Date &  date_t0, const vector< vector< Real > > &  nettingSetValues, const Date &  nettingSet_maturity, const vector< Date > &  dateGrid, const Real &  csaFxTodayRate, const vector< vector< Real > > &  csaFxScenarioRates, const Real &  csaTodayCollatCurve, const vector< vector< Real > > &  csaScenCollatCurves, const CalculationType &  calcType = Symmetric, const QuantLib::ext::shared_ptr< CollateralBalance > &  balance = QuantLib::ext::shared_ptr<CollateralBalance>()  )

static

Takes a netting set (and scenario exposures) as input and returns collateral balance paths per scenario

Definition at line 189 of file collatexposurehelper.cpp.

                                                             {
 
    try {
        // step 1; build a collateral account object, assuming t0 VM balance from the balance object (zero balance if missing),
        //         and calculate t0 margin requirement
 
        Real initialBalance = 0.0;
        if (balance && balance->variationMargin() != Null<Real>()) {            
            initialBalance = balance->variationMargin();
            DLOG("initial collateral balance: " << initialBalance);
        }
        else {
            DLOG("initial collateral balance not found");
        }
        
        QuantLib::ext::shared_ptr<CollateralAccount> tmpAcc(new CollateralAccount(csaDef, initialBalance, date_t0));
        DLOG("tmp initial collateral balance: " << tmpAcc->balance_t0());
        DLOG("tmp current collateral balance: " << tmpAcc->accountBalance());
 
        Real bal_t0 = marginRequirementCalc(tmpAcc, nettingSetPv, date_t0);
 
        // step 2; build a new collateral account object with t0 balance = bal_t0
        // a copy of this new object will be used as base for each scenario collateral path
        CollateralAccount baseAcc(csaDef, bal_t0, date_t0);
        DLOG("base current collateral balance: " << bal_t0 << ", " << baseAcc.accountBalance());
 
        // step 3; build an empty container for the return value(s)
        QuantLib::ext::shared_ptr<vector<QuantLib::ext::shared_ptr<CollateralAccount>>> scenarioCollatPaths(
            new vector<QuantLib::ext::shared_ptr<CollateralAccount>>());
 
        // step 4; start loop over scenarios
        Size numScenarios = nettingSetValues.front().size();
        QL_REQUIRE(numScenarios == csaFxScenarioRates.front().size(), "netting values -v- scenario FX rate mismatch");
        Date simEndDate = std::min(nettingSet_maturity, dateGrid.back()) + csaDef->csaDetails()->marginPeriodOfRisk();
        for (unsigned i = 0; i < numScenarios; i++) {
            QuantLib::ext::shared_ptr<CollateralAccount> collat(new CollateralAccount(baseAcc));
            Date tmpDate = date_t0; // the date which gets evolved
            Date nextMarginReqDateUs = date_t0;
            Date nextMarginReqDateCtp = date_t0;
            while (tmpDate <= simEndDate) {
                QL_REQUIRE(tmpDate <= nextMarginReqDateUs && tmpDate <= nextMarginReqDateCtp &&
                               (tmpDate == nextMarginReqDateUs || tmpDate == nextMarginReqDateCtp),
                           "collateral balance path generation error; invalid time stepping");
                bool eligMarginReqDateUs = tmpDate == nextMarginReqDateUs ? true : false;
                bool eligMarginReqDateCtp = tmpDate == nextMarginReqDateCtp ? true : false;
                Real uncollatVal = estimateUncollatValue(tmpDate, nettingSetPv, date_t0, nettingSetValues, i, dateGrid);
                Real fxValue = estimateUncollatValue(tmpDate, csaFxTodayRate, date_t0, csaFxScenarioRates, i, dateGrid);
                Real annualisedZeroRate =
                    estimateUncollatValue(tmpDate, csaTodayCollatCurve, date_t0, csaScenCollatCurves, i, dateGrid);
                uncollatVal /= fxValue;
                updateMarginCall(collat, uncollatVal, tmpDate, annualisedZeroRate, calcType, eligMarginReqDateUs,
                                 eligMarginReqDateCtp);
 
                if (nextMarginReqDateUs == tmpDate)
                    nextMarginReqDateUs = tmpDate + collat->csaDef()->csaDetails()->marginCallFrequency();
                if (nextMarginReqDateCtp == tmpDate)
                    nextMarginReqDateCtp = tmpDate + collat->csaDef()->csaDetails()->marginPostFrequency();
                tmpDate = std::min(nextMarginReqDateUs, nextMarginReqDateCtp);
            }
            QL_REQUIRE(tmpDate > simEndDate,
                       "collateral balance path generation error; while loop terminated too early. ("
                           << tmpDate << ", " << simEndDate << ")");
            // set account balance to zero after maturity of portfolio
            collat->closeAccount(simEndDate + Period(1, Days));
            scenarioCollatPaths->push_back(collat);
        }
        return scenarioCollatPaths;
    } catch (const std::exception& e) {
        QL_FAIL(e.what());
    } catch (...) {
        QL_FAIL("CollateralExposureHelper - unknown error when generating collateralBalancePaths");
    }
}

Here is the call graph for this function:

Here is the caller graph for this function: