CollateralGroupPath.java

  1. package org.drip.xva.netting;

  3. /*
  4.  * -*- mode: java; tab-width: 4; indent-tabs-mode: nil; c-basic-offset: 4 -*-
  5.  */

  7. /*!
  8.  * Copyright (C) 2020 Lakshmi Krishnamurthy
  9.  * Copyright (C) 2019 Lakshmi Krishnamurthy
  10.  * Copyright (C) 2018 Lakshmi Krishnamurthy
  11.  * Copyright (C) 2017 Lakshmi Krishnamurthy
  12.  * 
  13.  *  This file is part of DROP, an open-source library targeting analytics/risk, transaction cost analytics,
  14.  *      asset liability management analytics, capital, exposure, and margin analytics, valuation adjustment
  15.  *      analytics, and portfolio construction analytics within and across fixed income, credit, commodity,
  16.  *      equity, FX, and structured products. It also includes auxiliary libraries for algorithm support,
  17.  *      numerical analysis, numerical optimization, spline builder, model validation, statistical learning,
  18.  *      and computational support.
  19.  *  
  20.  *      https://lakshmidrip.github.io/DROP/
  21.  *  
  22.  *  DROP is composed of three modules:
  23.  *  
  24.  *  - DROP Product Core - https://lakshmidrip.github.io/DROP-Product-Core/
  25.  *  - DROP Portfolio Core - https://lakshmidrip.github.io/DROP-Portfolio-Core/
  26.  *  - DROP Computational Core - https://lakshmidrip.github.io/DROP-Computational-Core/
  27.  * 
  28.  *  DROP Product Core implements libraries for the following:
  29.  *  - Fixed Income Analytics
  30.  *  - Loan Analytics
  31.  *  - Transaction Cost Analytics
  32.  * 
  33.  *  DROP Portfolio Core implements libraries for the following:
  34.  *  - Asset Allocation Analytics
  35.  *  - Asset Liability Management Analytics
  36.  *  - Capital Estimation Analytics
  37.  *  - Exposure Analytics
  38.  *  - Margin Analytics
  39.  *  - XVA Analytics
  40.  * 
  41.  *  DROP Computational Core implements libraries for the following:
  42.  *  - Algorithm Support
  43.  *  - Computation Support
  44.  *  - Function Analysis
  45.  *  - Model Validation
  46.  *  - Numerical Analysis
  47.  *  - Numerical Optimizer
  48.  *  - Spline Builder
  49.  *  - Statistical Learning
  50.  * 
  51.  *  Documentation for DROP is Spread Over:
  52.  * 
  53.  *  - Main                     => https://lakshmidrip.github.io/DROP/
  54.  *  - Wiki                     => https://github.com/lakshmiDRIP/DROP/wiki
  55.  *  - GitHub                   => https://github.com/lakshmiDRIP/DROP
  56.  *  - Repo Layout Taxonomy     => https://github.com/lakshmiDRIP/DROP/blob/master/Taxonomy.md
  57.  *  - Javadoc                  => https://lakshmidrip.github.io/DROP/Javadoc/index.html
  58.  *  - Technical Specifications => https://github.com/lakshmiDRIP/DROP/tree/master/Docs/Internal
  59.  *  - Release Versions         => https://lakshmidrip.github.io/DROP/version.html
  60.  *  - Community Credits        => https://lakshmidrip.github.io/DROP/credits.html
  61.  *  - Issues Catalog           => https://github.com/lakshmiDRIP/DROP/issues
  62.  *  - JUnit                    => https://lakshmidrip.github.io/DROP/junit/index.html
  63.  *  - Jacoco                   => https://lakshmidrip.github.io/DROP/jacoco/index.html
  64.  * 
  65.  *  Licensed under the Apache License, Version 2.0 (the "License");
  66.  *      you may not use this file except in compliance with the License.
  67.  *   
  68.  *  You may obtain a copy of the License at
  69.  *      http://www.apache.org/licenses/LICENSE-2.0
  70.  *  
  71.  *  Unless required by applicable law or agreed to in writing, software
  72.  *      distributed under the License is distributed on an "AS IS" BASIS,
  73.  *      WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
  74.  *  
  75.  *  See the License for the specific language governing permissions and
  76.  *      limitations under the License.
  77.  */

  79. /**
  80.  * <i>CollateralGroupPath</i> accumulates the Vertex Realizations of the Sequence in a Single Path Projection
  81.  * Run along the Granularity of a Regular Collateral Hypothecation Group. The References are:
  82.  *
  83.  *  <br><br>
  84.  *  <ul>
  85.  *      <li>
  86.  *          Burgard, C., and M. Kjaer (2014): PDE Representations of Derivatives with Bilateral Counter-party
  87.  *              Risk and Funding Costs <i>Journal of Credit Risk</i> <b>7 (3)</b> 1-19
  88.  *      </li>
  89.  *      <li>
  90.  *          Burgard, C., and M. Kjaer (2014): In the Balance <i>Risk</i> <b>24 (11)</b> 72-75
  91.  *      </li>
  92.  *      <li>
  93.  *          Gregory, J. (2009): Being Two-faced over Counter-party Credit Risk <i>Risk</i> <b>20 (2)</b>
  94.  *              86-90
  95.  *      </li>
  96.  *      <li>
  97.  *          Li, B., and Y. Tang (2007): <i>Quantitative Analysis, Derivatives Modeling, and Trading
  98.  *              Strategies in the Presence of Counter-party Credit Risk for the Fixed Income Market</i>
  99.  *              <b>World Scientific Publishing</b> Singapore
  100.  *      </li>
  101.  *      <li>
  102.  *          Piterbarg, V. (2010): Funding Beyond Discounting: Collateral Agreements and Derivatives Pricing
  103.  *              <i>Risk</i> <b>21 (2)</b> 97-102
  104.  *      </li>
  105.  *  </ul>
  106.  *
  107.  *  <br><br>
  108.  *  <ul>
  109.  *      <li><b>Module </b> = <a href = "https://github.com/lakshmiDRIP/DROP/tree/master/PortfolioCore.md">Portfolio Core Module</a></li>
  110.  *      <li><b>Library</b> = <a href = "https://github.com/lakshmiDRIP/DROP/tree/master/XVAAnalyticsLibrary.md">XVA Analytics Library</a></li>
  111.  *      <li><b>Project</b> = <a href = "https://github.com/lakshmiDRIP/DROP/tree/master/src/main/java/org/drip/xva/README.md">Valuation Adjustments that account for Collateral, CC Credit/Debt and Funding Overhead</a></li>
  112.  *      <li><b>Package</b> = <a href = "https://github.com/lakshmiDRIP/DROP/tree/master/src/main/java/org/drip/xva/netting/README.md">Credit/Debt/Funding Netting Groups</a></li>
  113.  *  </ul>
  114.  * <br><br>
  115.  * 
  116.  * @author Lakshmi Krishnamurthy
  117.  */

  119. public class CollateralGroupPath
  120. {
  121.     private double _overnightReplicatorStart = java.lang.Double.NaN;
  122.     private org.drip.exposure.universe.MarketPath _marketPath = null;
  123.     private org.drip.xva.hypothecation.CollateralGroupVertex[] _collateralGroupVertexArray = null;

  125.     /**
  126.      * CollateralGroupPath Constructor
  127.      * 
  128.      * @param collateralGroupVertexArray The Array of Collateral Hypothecation Group Trajectory Vertexes
  129.      * @param marketPath The Market Path
  130.      * 
  131.      * @throws java.lang.Exception Thrown if the Inputs are Invalid
  132.      */

  134.     public CollateralGroupPath (
  135.         final org.drip.xva.hypothecation.CollateralGroupVertex[] collateralGroupVertexArray,
  136.         final org.drip.exposure.universe.MarketPath marketPath)
  137.         throws java.lang.Exception
  138.     {
  139.         if (null == (_collateralGroupVertexArray = collateralGroupVertexArray) ||
  140.             null == (_marketPath = marketPath))
  141.         {
  142.             throw new java.lang.Exception ("CollateralGroupPath Constructor => Invalid Inputs");
  143.         }

  145.         _overnightReplicatorStart = _marketPath.epochalMarketVertex().overnightReplicator();

  147.         int vertexCount = _collateralGroupVertexArray.length;

  149.         if (1 >= vertexCount)
  150.         {
  151.             throw new java.lang.Exception ("CollateralGroupPath Constructor => Invalid Inputs");
  152.         }

  154.         for (int vertexIndex = 0; vertexIndex < vertexCount; ++vertexIndex)
  155.         {
  156.             if (null == _collateralGroupVertexArray[vertexIndex])
  157.             {
  158.                 throw new java.lang.Exception ("CollateralGroupPath Constructor => Invalid Inputs");
  159.             }

  161.             if (0 != vertexIndex && _collateralGroupVertexArray[vertexIndex - 1].vertexDate().julian() >=
  162.                 _collateralGroupVertexArray[vertexIndex].vertexDate().julian())
  163.             {
  164.                 throw new java.lang.Exception ("CollateralGroupPath Constructor => Invalid Inputs");
  165.             }
  166.         }
  167.     }

  169.     /**
  170.      * Retrieve the Array of Collateral Group Trajectory Vertexes
  171.      * 
  172.      * @return The Array of Collateral Group Trajectory Vertexes
  173.      */

  175.     public org.drip.xva.hypothecation.CollateralGroupVertex[] collateralGroupVertex()
  176.     {
  177.         return _collateralGroupVertexArray;
  178.     }

  180.     /**
  181.      * Retrieve the Market Path
  182.      * 
  183.      * @return The Market Path
  184.      */

  186.     public org.drip.exposure.universe.MarketPath marketPath()
  187.     {
  188.         return _marketPath;
  189.     }

  191.     /**
  192.      * Retrieve the Array of the Vertex Anchor Dates
  193.      * 
  194.      * @return The Array of the Vertex Anchor Dates
  195.      */

  197.     public org.drip.analytics.date.JulianDate[] vertexDates()
  198.     {
  199.         int vertexCount = _collateralGroupVertexArray.length;
  200.         org.drip.analytics.date.JulianDate[] vertexDateArray = new
  201.             org.drip.analytics.date.JulianDate[vertexCount];

  203.         for (int vertexIndex = 0; vertexIndex < vertexCount; ++vertexIndex)
  204.         {
  205.             vertexDateArray[vertexIndex] = _collateralGroupVertexArray[vertexIndex].vertexDate();
  206.         }

  208.         return vertexDateArray;
  209.     }

  211.     /**
  212.      * Retrieve the Array of Vertex Collateralized Exposures
  213.      * 
  214.      * @return The Array of Vertex Collateralized Exposures
  215.      */

  217.     public double[] vertexCollateralizedExposure()
  218.     {
  219.         int vertexCount = _collateralGroupVertexArray.length;
  220.         double[] collateralizedExposure = new double[vertexCount];

  222.         for (int vertexIndex = 0; vertexIndex < vertexCount; ++vertexIndex)
  223.         {
  224.             collateralizedExposure[vertexIndex] = _collateralGroupVertexArray[vertexIndex].collateralized();
  225.         }

  227.         return collateralizedExposure;
  228.     }

  230.     /**
  231.      * Retrieve the Array of Vertex Collateralized Exposure PV
  232.      * 
  233.      * @return The Array of Vertex Collateralized Exposure PV
  234.      */

  236.     public double[] vertexCollateralizedExposurePV()
  237.     {
  238.         int vertexCount = _collateralGroupVertexArray.length;
  239.         double[] collateralizedExposurePV = new double[vertexCount];

  241.         org.drip.analytics.date.JulianDate[] vertexDateArray = _marketPath.anchorDates();

  243.         for (int vertexIndex = 0; vertexIndex < vertexCount; ++vertexIndex)
  244.         {
  245.             collateralizedExposurePV[vertexIndex] = _collateralGroupVertexArray[vertexIndex].collateralized()
  246.                 * _overnightReplicatorStart /
  247.                 _marketPath.marketVertex (vertexDateArray[vertexIndex].julian()).overnightReplicator();
  248.         }

  250.         return collateralizedExposurePV;
  251.     }

  253.     /**
  254.      * Retrieve the Array of Vertex Uncollateralized Exposures
  255.      * 
  256.      * @return The Array of Vertex Uncollateralized Exposures
  257.      */

  259.     public double[] vertexUncollateralizedExposure()
  260.     {
  261.         int vertexCount = _collateralGroupVertexArray.length;
  262.         double[] uncollateralizedExposure = new double[vertexCount];

  264.         for (int vertexIndex = 0; vertexIndex < vertexCount; ++vertexIndex)
  265.         {
  266.             uncollateralizedExposure[vertexIndex] =
  267.                 _collateralGroupVertexArray[vertexIndex].uncollateralized();
  268.         }

  270.         return uncollateralizedExposure;
  271.     }

  273.     /**
  274.      * Retrieve the Array of Vertex Uncollateralized Exposure PV
  275.      * 
  276.      * @return The Array of Vertex Uncollateralized Exposure PV
  277.      */

  279.     public double[] vertexUncollateralizedExposurePV()
  280.     {
  281.         int vertexCount = _collateralGroupVertexArray.length;
  282.         double[] uncollateralizedExposurePV = new double[vertexCount];

  284.         org.drip.analytics.date.JulianDate[] vertexDateArray = _marketPath.anchorDates();

  286.         for (int vertexIndex = 0; vertexIndex < vertexCount; ++vertexIndex)
  287.         {
  288.             uncollateralizedExposurePV[vertexIndex] =
  289.                 _collateralGroupVertexArray[vertexIndex].uncollateralized() *
  290.                 _overnightReplicatorStart /
  291.                 _marketPath.marketVertex (vertexDateArray[vertexIndex].julian()).overnightReplicator();
  292.         }

  294.         return uncollateralizedExposurePV;
  295.     }

  297.     /**
  298.      * Retrieve the Array of Vertex Credit Exposures
  299.      * 
  300.      * @return The Array of Vertex Credit Exposures
  301.      */

  303.     public double[] vertexCreditExposure()
  304.     {
  305.         int vertexCount = _collateralGroupVertexArray.length;
  306.         double[] creditExposure = new double[vertexCount];

  308.         for (int vertexIndex = 0; vertexIndex < vertexCount; ++vertexIndex)
  309.         {
  310.             creditExposure[vertexIndex] = _collateralGroupVertexArray[vertexIndex].credit();
  311.         }

  313.         return creditExposure;
  314.     }

  316.     /**
  317.      * Retrieve the Array of Vertex Credit Exposure PV
  318.      * 
  319.      * @return The Array of Vertex Credit Exposure PV
  320.      */

  322.     public double[] vertexCreditExposurePV()
  323.     {
  324.         int vertexCount = _collateralGroupVertexArray.length;
  325.         double[] creditExposurePV = new double[vertexCount];

  327.         org.drip.analytics.date.JulianDate[] vertexDateArray = _marketPath.anchorDates();

  329.         for (int vertexIndex = 0; vertexIndex < vertexCount; ++vertexIndex)
  330.         {
  331.             creditExposurePV[vertexIndex] = _collateralGroupVertexArray[vertexIndex].credit() *
  332.                 _overnightReplicatorStart /
  333.                 _marketPath.marketVertex (vertexDateArray[vertexIndex].julian()).overnightReplicator();
  334.         }

  336.         return creditExposurePV;
  337.     }

  339.     /**
  340.      * Retrieve the Array of Vertex Debt Exposures
  341.      * 
  342.      * @return The Array of Vertex Debt Exposures
  343.      */

  345.     public double[] vertexDebtExposure()
  346.     {
  347.         int vertexCount = _collateralGroupVertexArray.length;
  348.         double[] debtExposure = new double[vertexCount];

  350.         for (int vertexIndex = 0; vertexIndex < vertexCount; ++vertexIndex)
  351.         {
  352.             debtExposure[vertexIndex] = _collateralGroupVertexArray[vertexIndex].debt();
  353.         }

  355.         return debtExposure;
  356.     }

  358.     /**
  359.      * Retrieve the Array of Vertex Debt Exposures PV
  360.      * 
  361.      * @return The Array of Vertex Debt Exposures PV
  362.      */

  364.     public double[] vertexDebtExposurePV()
  365.     {
  366.         int vertexCount = _collateralGroupVertexArray.length;
  367.         double[] debtExposurePV = new double[vertexCount];

  369.         org.drip.analytics.date.JulianDate[] vertexDateArray = _marketPath.anchorDates();

  371.         for (int vertexIndex = 0; vertexIndex < vertexCount; ++vertexIndex)
  372.         {
  373.             debtExposurePV[vertexIndex] = _collateralGroupVertexArray[vertexIndex].debt() *
  374.                 _overnightReplicatorStart /
  375.                 _marketPath.marketVertex (vertexDateArray[vertexIndex].julian()).overnightReplicator();
  376.         }

  378.         return debtExposurePV;
  379.     }

  381.     /**
  382.      * Retrieve the Array of Vertex Funding Exposures
  383.      * 
  384.      * @return The Array of Vertex Funding Exposures
  385.      */

  387.     public double[] vertexFundingExposure()
  388.     {
  389.         int vertexCount = _collateralGroupVertexArray.length;
  390.         double[] fundingExposure = new double[vertexCount];

  392.         for (int vertexIndex = 0; vertexIndex < vertexCount; ++vertexIndex)
  393.         {
  394.             fundingExposure[vertexIndex] = _collateralGroupVertexArray[vertexIndex].funding();
  395.         }

  397.         return fundingExposure;
  398.     }

  400.     /**
  401.      * Retrieve the Array of Vertex Funding Exposures PV
  402.      * 
  403.      * @return The Array of Vertex Funding Exposures PV
  404.      */

  406.     public double[] vertexFundingExposurePV()
  407.     {
  408.         int vertexCount = _collateralGroupVertexArray.length;
  409.         double[] fundingExposurePV = new double[vertexCount];

  411.         org.drip.analytics.date.JulianDate[] vertexDateArray = _marketPath.anchorDates();

  413.         for (int vertexIndex = 0; vertexIndex < vertexCount; ++vertexIndex)
  414.         {
  415.             fundingExposurePV[vertexIndex] = _collateralGroupVertexArray[vertexIndex].funding() *
  416.                 _overnightReplicatorStart /
  417.                 _marketPath.marketVertex (vertexDateArray[vertexIndex].julian()).overnightReplicator();
  418.         }

  420.         return fundingExposurePV;
  421.     }

  423.     /**
  424.      * Retrieve the Array of Vertex Collateral Balances
  425.      * 
  426.      * @return The Array of Vertex Collateral Balances
  427.      */

  429.     public double[] vertexCollateralBalance()
  430.     {
  431.         int vertexCount = _collateralGroupVertexArray.length;
  432.         double[] collateralizedBalance = new double[vertexCount];

  434.         for (int vertexIndex = 0; vertexIndex < vertexCount; ++vertexIndex)
  435.         {
  436.             collateralizedBalance[vertexIndex] =
  437.                 _collateralGroupVertexArray[vertexIndex].variationMarginPosting();
  438.         }

  440.         return collateralizedBalance;
  441.     }

  443.     /**
  444.      * Retrieve the Array of Vertex Collateral Balances PV
  445.      * 
  446.      * @return The Array of Vertex Collateral Balances PV
  447.      */

  449.     public double[] vertexCollateralBalancePV()
  450.     {
  451.         int vertexCount = _collateralGroupVertexArray.length;
  452.         double[] collateralizedBalancePV = new double[vertexCount];

  454.         org.drip.analytics.date.JulianDate[] vertexDateArray = _marketPath.anchorDates();

  456.         for (int vertexIndex = 0; vertexIndex < vertexCount; ++vertexIndex)
  457.         {
  458.             collateralizedBalancePV[vertexIndex] =
  459.                 _collateralGroupVertexArray[vertexIndex].variationMarginPosting() * _overnightReplicatorStart /
  460.                 _marketPath.marketVertex (vertexDateArray[vertexIndex].julian()).overnightReplicator();
  461.         }

  463.         return collateralizedBalancePV;
  464.     }

  466.     /**
  467.      * Compute Period-wise Path Collateral Spread 01
  468.      * 
  469.      * @return The Period-wise Path Collateral Spread 01
  470.      */

  472.     public double[] periodCollateralSpread01()
  473.     {
  474.         org.drip.analytics.date.JulianDate[] vertexDateArray = _marketPath.anchorDates();

  476.         double[] vertexCollateralBalancePV = vertexCollateralBalancePV();

  478.         int vertexCount = vertexCollateralBalancePV.length;
  479.         double[] periodCollateralValueAdjustment = new double[vertexCount - 1];

  481.         for (int vertexIndex = 1; vertexIndex < vertexCount; ++vertexIndex)
  482.         {
  483.             periodCollateralValueAdjustment[vertexIndex - 1] = -0.5 *
  484.                 (vertexCollateralBalancePV[vertexIndex - 1] + vertexCollateralBalancePV[vertexIndex]) *
  485.                 (vertexDateArray[vertexIndex].julian() - vertexDateArray[vertexIndex - 1].julian()) / 365.25;
  486.         }

  488.         return periodCollateralValueAdjustment;
  489.     }

  491.     /**
  492.      * Compute Period-wise Path Collateral Value Adjustment
  493.      * 
  494.      * @return The Period-wise Path Collateral Value Adjustment
  495.      */

  497.     public double[] periodCollateralValueAdjustment()
  498.     {
  499.         org.drip.analytics.date.JulianDate[] vertexDateArray = _marketPath.anchorDates();

  501.         double[] vertexCollateralBalancePV = vertexCollateralBalancePV();

  503.         int vertexCount = vertexCollateralBalancePV.length;
  504.         double[] periodCollateralValueAdjustment = new double[vertexCount - 1];

  506.         for (int vertexIndex = 1; vertexIndex < vertexCount; ++vertexIndex)
  507.         {
  508.             int previousVertexDate = vertexDateArray[vertexIndex - 1].julian();

  510.             int currentVertexDate = vertexDateArray[vertexIndex].julian();

  512.             double periodIntegrandStart = vertexCollateralBalancePV[vertexIndex - 1] *
  513.                 _marketPath.marketVertex (previousVertexDate).csaSpread();

  515.             double periodIntegrandEnd = vertexCollateralBalancePV[vertexIndex] *
  516.                 _marketPath.marketVertex (currentVertexDate).csaSpread();

  518.             periodCollateralValueAdjustment[vertexIndex - 1] =
  519.                 -0.5 * (periodIntegrandStart + periodIntegrandEnd) *
  520.                 (currentVertexDate - previousVertexDate) / 365.25;
  521.         }

  523.         return periodCollateralValueAdjustment;
  524.     }
  525. }
Created with JaCoCo 0.7.9.201702052155