TrinomialTreeTransitionMetrics.java

  1. package org.drip.dynamics.hullwhite;

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

  81. /**
  82.  * <i>TrinomialTreeTransitionMetrics</i> records the Transition Metrics associated with Node-to-Node
  83.  * Evolution of the Instantaneous Short Rate using the Hull-White Model Trinomial Tree.
  84.  *
  85.  *  <br><br>
  86.  *  <ul>
  87.  *      <li><b>Module </b> = <a href = "https://github.com/lakshmiDRIP/DROP/tree/master/ProductCore.md">Product Core Module</a></li>
  88.  *      <li><b>Library</b> = <a href = "https://github.com/lakshmiDRIP/DROP/tree/master/FixedIncomeAnalyticsLibrary.md">Fixed Income Analytics</a></li>
  89.  *      <li><b>Project</b> = <a href = "https://github.com/lakshmiDRIP/DROP/tree/master/src/main/java/org/drip/dynamics/README.md">HJM, Hull White, LMM, and SABR Dynamic Evolution Models</a></li>
  90.  *      <li><b>Package</b> = <a href = "https://github.com/lakshmiDRIP/DROP/tree/master/src/main/java/org/drip/dynamics/hullwhite/README.md">Hull White Latent State Evolution</a></li>
  91.  *  </ul>
  92.  *
  93.  * @author Lakshmi Krishnamurthy
  94.  */

  96. public class TrinomialTreeTransitionMetrics {
  97.     private long _lTreeTimeIndex = -1L;
  98.     private long _lTreeStochasticBaseIndex = -1L;
  99.     private long _lTreeStochasticDisplacementIndex = -1L;
  100.     private double _dblXVariance = java.lang.Double.NaN;
  101.     private double _dblTerminalAlpha = java.lang.Double.NaN;
  102.     private double _dblProbabilityUp = java.lang.Double.NaN;
  103.     private int _iInitialDate = java.lang.Integer.MIN_VALUE;
  104.     private int _iTerminalDate = java.lang.Integer.MIN_VALUE;
  105.     private double _dblProbabilityDown = java.lang.Double.NaN;
  106.     private double _dblProbabilityStay = java.lang.Double.NaN;
  107.     private double _dblXStochasticShift = java.lang.Double.NaN;
  108.     private double _dblExpectedTerminalX = java.lang.Double.NaN;

  110.     /**
  111.      * TrinomialTreeTransitionMetrics Constructor
  112.      * 
  113.      * @param iInitialDate The Initial Date
  114.      * @param iTerminalDate The Terminal/Final Date
  115.      * @param lTreeTimeIndex The Tree Time Index
  116.      * @param lTreeStochasticBaseIndex The Tree Stochastic Base Index
  117.      * @param dblExpectedTerminalX Expectation of the Final/Terminal Value for X
  118.      * @param dblXVariance Variance of X
  119.      * @param dblTerminalAlpha The Final/Terminal Alpha
  120.      * 
  121.      * @throws java.lang.Exception Thrown if the Inputs are Invalid
  122.      */

  124.     public TrinomialTreeTransitionMetrics (
  125.         final int iInitialDate,
  126.         final int iTerminalDate,
  127.         final long lTreeTimeIndex,
  128.         final long lTreeStochasticBaseIndex,
  129.         final double dblExpectedTerminalX,
  130.         final double dblXVariance,
  131.         final double dblTerminalAlpha)
  132.         throws java.lang.Exception
  133.     {
  134.         if (0 > (_lTreeTimeIndex = lTreeTimeIndex) || !org.drip.numerical.common.NumberUtil.IsValid
  135.             (_dblExpectedTerminalX = dblExpectedTerminalX) || !org.drip.numerical.common.NumberUtil.IsValid
  136.                 (_dblXVariance = dblXVariance) || !org.drip.numerical.common.NumberUtil.IsValid
  137.                     (_dblTerminalAlpha = dblTerminalAlpha))
  138.             throw new java.lang.Exception ("TrinomialTreeTransitionMetrics ctr: Invalid Inputs");

  140.         _dblXStochasticShift = java.lang.Math.sqrt (_dblXVariance * 3.);

  142.         _lTreeStochasticDisplacementIndex = java.lang.Math.round (_dblExpectedTerminalX /
  143.             _dblXStochasticShift);

  145.         _iInitialDate = iInitialDate;
  146.         _iTerminalDate = iTerminalDate;
  147.         _lTreeStochasticBaseIndex = lTreeStochasticBaseIndex;
  148.         double dblEta = _dblExpectedTerminalX - _lTreeStochasticDisplacementIndex * _dblXStochasticShift;
  149.         _dblProbabilityStay = (2. / 3.) - (dblEta * dblEta / (3. * _dblXVariance));
  150.         _dblProbabilityDown = (1. / 6.) + (dblEta * dblEta / (6. * _dblXVariance)) - (0.5 * dblEta /
  151.             _dblXStochasticShift);
  152.         _dblProbabilityUp = (1. / 6.) + (dblEta * dblEta / (6. * _dblXVariance)) + (0.5 * dblEta /
  153.             _dblXStochasticShift);
  154.     }

  156.     /**
  157.      * Retrieve the Initial Date
  158.      * 
  159.      * @return The Initial Date
  160.      */

  162.     public int initialDate()
  163.     {
  164.         return _iInitialDate;
  165.     }

  167.     /**
  168.      * Retrieve the Terminal Date
  169.      * 
  170.      * @return The Terminal Date
  171.      */

  173.     public int terminalDate()
  174.     {
  175.         return _iTerminalDate;
  176.     }

  178.     /**
  179.      * Retrieve the Tree Time Index
  180.      * 
  181.      * @return The Tree Time Index
  182.      */

  184.     public long treeTimeIndex()
  185.     {
  186.         return _lTreeTimeIndex;
  187.     }

  189.     /**
  190.      * Retrieve the Expected Final/Terminal Value for X
  191.      * 
  192.      * @return The Expected Final/Terminal Value for X
  193.      */

  195.     public double expectedTerminalX()
  196.     {
  197.         return _dblExpectedTerminalX;
  198.     }

  200.     /**
  201.      * Retrieve the Variance in the Final Value of X
  202.      * 
  203.      * @return The Variance in the Final Value of X
  204.      */

  206.     public double xVariance()
  207.     {
  208.         return _dblXVariance;
  209.     }

  211.     /**
  212.      * Retrieve the Stochastic Shift of X
  213.      * 
  214.      * @return The Stochastic Shift of X
  215.      */

  217.     public double xStochasticShift()
  218.     {
  219.         return _dblXStochasticShift;
  220.     }

  222.     /**
  223.      * Retrieve the Tree Stochastic Displacement Index
  224.      * 
  225.      * @return The Tree Stochastic Displacement Index
  226.      */

  228.     public long treeStochasticDisplacementIndex()
  229.     {
  230.         return _lTreeStochasticDisplacementIndex;
  231.     }

  233.     /**
  234.      * Retrieve the Probability of the Up Stochastic Shift
  235.      * 
  236.      * @return Probability of the Up Stochastic Shift
  237.      */

  239.     public double probabilityUp()
  240.     {
  241.         return _dblProbabilityUp;
  242.     }

  244.     /**
  245.      * Retrieve the Probability of the Down Stochastic Shift
  246.      * 
  247.      * @return Probability of the Down Stochastic Shift
  248.      */

  250.     public double probabilityDown()
  251.     {
  252.         return _dblProbabilityDown;
  253.     }

  255.     /**
  256.      * Retrieve the Probability of the No Shift
  257.      * 
  258.      * @return Probability of the No Shift
  259.      */

  261.     public double probabilityStay()
  262.     {
  263.         return _dblProbabilityStay;
  264.     }

  266.     /**
  267.      * Retrieve the "Up" Value for X
  268.      * 
  269.      * @return The "Up" Value for X
  270.      */

  272.     public double xUp()
  273.     {
  274.         return (_lTreeStochasticDisplacementIndex + 1) * _dblXStochasticShift;
  275.     }

  277.     /**
  278.      * Retrieve the "Down" Value for X
  279.      * 
  280.      * @return The "Down" Value for X
  281.      */

  283.     public double xDown()
  284.     {
  285.         return (_lTreeStochasticDisplacementIndex - 1) * _dblXStochasticShift;
  286.     }

  288.     /**
  289.      * Retrieve the Final/Terminal Alpha
  290.      * 
  291.      * @return The Final/Terminal Alpha
  292.      */

  294.     public double terminalAlpha()
  295.     {
  296.         return _dblTerminalAlpha;
  297.     }

  299.     /**
  300.      * Retrieve the "Up" Node Metrics
  301.      * 
  302.      * @return The "Up" Node Metrics
  303.      */

  305.     public org.drip.dynamics.hullwhite.TrinomialTreeNodeMetrics upNodeMetrics()
  306.     {
  307.         try {
  308.             return new org.drip.dynamics.hullwhite.TrinomialTreeNodeMetrics (_lTreeTimeIndex,
  309.                 _lTreeStochasticBaseIndex + 1, (_lTreeStochasticDisplacementIndex + 1) *
  310.                     _dblXStochasticShift, _dblTerminalAlpha);
  311.         } catch (java.lang.Exception e) {
  312.             e.printStackTrace();
  313.         }

  315.         return null;
  316.     }

  318.     /**
  319.      * Retrieve the "Down" Node Metrics
  320.      * 
  321.      * @return The "Down" Node Metrics
  322.      */

  324.     public org.drip.dynamics.hullwhite.TrinomialTreeNodeMetrics downNodeMetrics()
  325.     {
  326.         try {
  327.             return new org.drip.dynamics.hullwhite.TrinomialTreeNodeMetrics (_lTreeTimeIndex,
  328.                 _lTreeStochasticBaseIndex - 1, (_lTreeStochasticDisplacementIndex - 1) *
  329.                     _dblXStochasticShift, _dblTerminalAlpha);
  330.         } catch (java.lang.Exception e) {
  331.             e.printStackTrace();
  332.         }

  334.         return null;
  335.     }

  337.     /**
  338.      * Retrieve the "Stay" Node Metrics
  339.      * 
  340.      * @return The "Stay" Node Metrics
  341.      */

  343.     public org.drip.dynamics.hullwhite.TrinomialTreeNodeMetrics stayNodeMetrics()
  344.     {
  345.         try {
  346.             return new org.drip.dynamics.hullwhite.TrinomialTreeNodeMetrics (_lTreeTimeIndex,
  347.                 _lTreeStochasticBaseIndex, _lTreeStochasticDisplacementIndex * _dblXStochasticShift,
  348.                     _dblTerminalAlpha);
  349.         } catch (java.lang.Exception e) {
  350.             e.printStackTrace();
  351.         }

  353.         return null;
  354.     }
  355. }
Created with JaCoCo 0.7.9.201702052155