LognormalLIBORPointEvolver.java

  1. package org.drip.dynamics.lmm;

  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>LognormalLIBORPointEvolver</i> sets up and implements the Multi-Factor No-arbitrage Dynamics of the
  83.  * Point Rates State Quantifiers traced from the Evolution of the LIBOR Forward Rate as formulated in:
  84.  *
  85.  *  <br><br>
  86.  *  <ul>
  87.  *      <li>
  88.  *          Goldys, B., M. Musiela, and D. Sondermann (1994): <i>Log-normality of Rates and Term Structure
  89.  *              Models</i> <b>The University of New South Wales</b>
  90.  *      </li>
  91.  *      <li>
  92.  *          Musiela, M. (1994): <i>Nominal Annual Rates and Log-normal Volatility Structure</i> <b>The
  93.  *              University of New South Wales</b>
  94.  *      </li>
  95.  *      <li>
  96.  *          Brace, A., D. Gatarek, and M. Musiela (1997): The Market Model of Interest Rate Dynamics
  97.  *              <i>Mathematical Finance</i> <b>7 (2)</b> 127-155
  98.  *      </li>
  99.  *  </ul>
  100.  *
  101.  *  <br><br>
  102.  *  <ul>
  103.  *      <li><b>Module </b> = <a href = "https://github.com/lakshmiDRIP/DROP/tree/master/ProductCore.md">Product Core Module</a></li>
  104.  *      <li><b>Library</b> = <a href = "https://github.com/lakshmiDRIP/DROP/tree/master/FixedIncomeAnalyticsLibrary.md">Fixed Income Analytics</a></li>
  105.  *      <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>
  106.  *      <li><b>Package</b> = <a href = "https://github.com/lakshmiDRIP/DROP/tree/master/src/main/java/org/drip/dynamics/lmm/README.md">LMM Based Latent State Evolution</a></li>
  107.  *  </ul>
  108.  *
  109.  * @author Lakshmi Krishnamurthy
  110.  */

  112. public class LognormalLIBORPointEvolver implements org.drip.dynamics.evolution.PointStateEvolver {
  113.     private org.drip.state.forward.ForwardCurve _fc = null;
  114.     private org.drip.state.discount.MergedDiscountForwardCurve _dc = null;
  115.     private org.drip.state.identifier.ForwardLabel _lslForward = null;
  116.     private org.drip.state.identifier.FundingLabel _lslFunding = null;
  117.     private org.drip.dynamics.lmm.LognormalLIBORVolatility _llv = null;

  119.     private double forwardDerivative (
  120.         final int iViewDate)
  121.         throws java.lang.Exception
  122.     {
  123.         org.drip.function.definition.R1ToR1 freR1ToR1 = new org.drip.function.definition.R1ToR1 (null)
  124.         {
  125.             @Override public double evaluate (
  126.                 final double dblDate)
  127.                 throws java.lang.Exception
  128.             {
  129.                 return _fc.forward ((int) dblDate);
  130.             }
  131.         };

  133.         return freR1ToR1.derivative (iViewDate, 1);
  134.     }

  136.     private double continuousForwardRateIncrement (
  137.         final int iViewDate,
  138.         final double dblAnnualizedIncrement,
  139.         final double[] adblMultivariateRandom)
  140.         throws java.lang.Exception
  141.     {
  142.         final int iNumFactor = adblMultivariateRandom.length;

  144.         final double dblSpotTimeIncrementSQRT = java.lang.Math.sqrt (dblAnnualizedIncrement);

  146.         org.drip.function.definition.R1ToR1 continuousForwardRateR1ToR1 = new
  147.             org.drip.function.definition.R1ToR1 (null) {
  148.             @Override public double evaluate (
  149.                 final double dblDate)
  150.                 throws java.lang.Exception
  151.             {
  152.                 double dblForwardPointVolatilityModulus = 0.;
  153.                 double dblPointVolatilityMultifactorRandom = 0.;

  155.                 double[] adblContinuousForwardVolatility = _llv.continuousForwardVolatility ((int) dblDate,
  156.                     _fc);

  158.                 if (null != adblContinuousForwardVolatility) {
  159.                     for (int i = 0; i < iNumFactor; ++i) {
  160.                         dblForwardPointVolatilityModulus += adblContinuousForwardVolatility[i] *
  161.                             adblContinuousForwardVolatility[i];
  162.                         dblPointVolatilityMultifactorRandom += adblContinuousForwardVolatility[i] *
  163.                             adblMultivariateRandom[i];
  164.                     }
  165.                 }

  167.                 return (_fc.forward ((int) dblDate) + 0.5 * dblForwardPointVolatilityModulus) *
  168.                     dblAnnualizedIncrement + dblPointVolatilityMultifactorRandom * dblSpotTimeIncrementSQRT;
  169.             }
  170.         };

  172.         return continuousForwardRateR1ToR1.derivative (iViewDate, 1);
  173.     }

  175.     private double spotRateIncrement (
  176.         final double dblSpotDate,
  177.         final double dblViewDate,
  178.         final double dblAnnualizedIncrement,
  179.         final double[] adblMultivariateRandom)
  180.         throws java.lang.Exception
  181.     {
  182.         final int iNumFactor = adblMultivariateRandom.length;

  184.         final double dblAnnualizedIncrementSQRT = java.lang.Math.sqrt (dblAnnualizedIncrement);

  186.         org.drip.function.definition.R1ToR1 spotRateR1ToR1 = new org.drip.function.definition.R1ToR1
  187.             (null) {
  188.             @Override public double evaluate (
  189.                 final double dblDate)
  190.                 throws java.lang.Exception
  191.             {
  192.                 double dblPointVolatilityMultifactorRandom = 0.;

  194.                 double[] adblContinuousForwardVolatility = _llv.continuousForwardVolatility ((int) dblDate,
  195.                     _fc);

  197.                 if (null != adblContinuousForwardVolatility) {
  198.                     for (int i = 0; i < iNumFactor; ++i)
  199.                         dblPointVolatilityMultifactorRandom += adblContinuousForwardVolatility[i] *
  200.                             adblMultivariateRandom[i];
  201.                 }

  203.                 return _fc.forward ((int) dblDate) * dblAnnualizedIncrement +
  204.                     dblPointVolatilityMultifactorRandom * dblAnnualizedIncrementSQRT;
  205.             }
  206.         };

  208.         return spotRateR1ToR1.derivative (dblViewDate, 1);
  209.     }

  211.     /**
  212.      * LognormalLIBORPointEvolver Constructor
  213.      * 
  214.      * @param lslFunding The Funding Latent State Label
  215.      * @param lslForward The Forward Latent State Label
  216.      * @param llv The Log-normal LIBOR Volatility Instance
  217.      * @param fc The Forward Curve Instance
  218.      * @param dc The Discount Curve Instance
  219.      * 
  220.      * @throws java.lang.Exception Thrown if Inputs are Invalid
  221.      */

  223.     public LognormalLIBORPointEvolver (
  224.         final org.drip.state.identifier.FundingLabel lslFunding,
  225.         final org.drip.state.identifier.ForwardLabel lslForward,
  226.         final org.drip.dynamics.lmm.LognormalLIBORVolatility llv,
  227.         final org.drip.state.forward.ForwardCurve fc,
  228.         final org.drip.state.discount.MergedDiscountForwardCurve dc)
  229.         throws java.lang.Exception
  230.     {
  231.         if (null == (_lslFunding = lslFunding) || null == (_lslForward = lslForward) || null == (_llv = llv)
  232.             || null == (_fc = fc) || null == (_dc = dc))
  233.             throw new java.lang.Exception ("LognormalLIBORPointEvolver ctr: Invalid Inputs");
  234.     }

  236.     /**
  237.      * Retrieve the Funding Label
  238.      * 
  239.      * @return The Funding Label
  240.      */

  242.     public org.drip.state.identifier.FundingLabel fundingLabel()
  243.     {
  244.         return _lslFunding;
  245.     }

  247.     /**
  248.      * Retrieve the Forward Label
  249.      * 
  250.      * @return The Forward Label
  251.      */

  253.     public org.drip.state.identifier.ForwardLabel forwardLabel()
  254.     {
  255.         return _lslForward;
  256.     }

  258.     /**
  259.      * Retrieve the Log-normal LIBOR Volatility Instance
  260.      * 
  261.      * @return The Log-normal LIBOR Volatility Instance
  262.      */

  264.     public org.drip.dynamics.lmm.LognormalLIBORVolatility llv()
  265.     {
  266.         return _llv;
  267.     }

  269.     /**
  270.      * Retrieve the Forward Curve Instance
  271.      * 
  272.      * @return The Forward Curve Instance
  273.      */

  275.     public org.drip.state.forward.ForwardCurve forwardCurve()
  276.     {
  277.         return _fc;
  278.     }

  280.     /**
  281.      * Retrieve the Discount Curve Instance
  282.      * 
  283.      * @return The Discount Curve Instance
  284.      */

  286.     public org.drip.state.discount.MergedDiscountForwardCurve discountCurve()
  287.     {
  288.         return _dc;
  289.     }

  291.     @Override public org.drip.dynamics.lmm.BGMPointUpdate evolve (
  292.         final int iSpotDate,
  293.         final int iViewDate,
  294.         final int iSpotTimeIncrement,
  295.         final org.drip.dynamics.evolution.LSQMPointUpdate lsqmPrev)
  296.     {
  297.         if (iSpotDate > iViewDate || (null != lsqmPrev && !(lsqmPrev instanceof
  298.             org.drip.dynamics.lmm.BGMPointUpdate)))
  299.             return null;

  301.         double dblAnnualizedIncrement = 1. * iSpotTimeIncrement / 365.25;

  303.         double dblAnnualizedIncrementSQRT = java.lang.Math.sqrt (dblAnnualizedIncrement);

  305.         double[] adblMultivariateRandom = _llv.msg().random();

  307.         java.lang.String strTenor = _lslForward.tenor();

  309.         double dblLIBOR = java.lang.Double.NaN;
  310.         double dblSpotRate = java.lang.Double.NaN;
  311.         double dblDiscountFactor = java.lang.Double.NaN;
  312.         double dblContinuouslyCompoundedForwardRate = java.lang.Double.NaN;
  313.         org.drip.dynamics.lmm.BGMPointUpdate bgmPrev = null == lsqmPrev ? null :
  314.             (org.drip.dynamics.lmm.BGMPointUpdate) lsqmPrev;

  316.         int iForwardDate = new org.drip.analytics.date.JulianDate (iViewDate).addTenor (strTenor).julian();

  318.         try {
  319.             if (null == bgmPrev) {
  320.                 dblLIBOR = _fc.forward (iForwardDate);

  322.                 dblDiscountFactor = _dc.df (iViewDate);

  324.                 dblSpotRate = _dc.forward (iSpotDate, iSpotDate + 1);

  326.                 dblContinuouslyCompoundedForwardRate = _dc.forward (iViewDate, iViewDate + 1);
  327.             } else {
  328.                 dblLIBOR = bgmPrev.libor();

  330.                 dblSpotRate = bgmPrev.spotRate();

  332.                 dblDiscountFactor = bgmPrev.discountFactor();

  334.                 dblContinuouslyCompoundedForwardRate = bgmPrev.continuousForwardRate();
  335.             }

  337.             double[] adblLognormalFactorPointVolatility = _llv.factorPointVolatility (iSpotDate, iViewDate);

  339.             double[] adblContinuousForwardVolatility = _llv.continuousForwardVolatility (iViewDate, _fc);

  341.             double dblCrossVolatilityDotProduct = 0.;
  342.             double dblLognormalPointVolatilityModulus = 0.;
  343.             double dblLIBORVolatilityMultiFactorRandom = 0.;
  344.             double dblContinuousForwardVolatilityModulus = 0.;
  345.             double dblForwardVolatilityMultiFactorRandom = 0.;
  346.             int iNumFactor = adblLognormalFactorPointVolatility.length;

  348.             for (int i = 0; i < iNumFactor; ++i) {
  349.                 dblLognormalPointVolatilityModulus += adblLognormalFactorPointVolatility[i] *
  350.                     adblLognormalFactorPointVolatility[i];
  351.                 dblCrossVolatilityDotProduct += adblLognormalFactorPointVolatility[i] *
  352.                     adblContinuousForwardVolatility[i];
  353.                 dblLIBORVolatilityMultiFactorRandom += adblLognormalFactorPointVolatility[i] *
  354.                     adblMultivariateRandom[i] * dblAnnualizedIncrementSQRT;
  355.                 dblContinuousForwardVolatilityModulus += adblContinuousForwardVolatility[i] *
  356.                     adblContinuousForwardVolatility[i];
  357.                 dblForwardVolatilityMultiFactorRandom += adblContinuousForwardVolatility[i] *
  358.                     adblMultivariateRandom[i] * dblAnnualizedIncrementSQRT;
  359.             }

  361.             double dblDCF = org.drip.analytics.support.Helper.TenorToYearFraction (strTenor);

  363.             double dblLIBORDCF = dblDCF * dblLIBOR;

  365.             double dblLIBORIncrement = dblAnnualizedIncrement * (forwardDerivative (iForwardDate) + dblLIBOR
  366.                 * dblCrossVolatilityDotProduct + (dblLognormalPointVolatilityModulus * dblLIBOR * dblLIBORDCF
  367.                     / (1. + dblLIBORDCF))) + dblLIBOR * dblLIBORVolatilityMultiFactorRandom;

  369.             double dblContinuousForwardRateIncrement = continuousForwardRateIncrement (iViewDate,
  370.                 dblAnnualizedIncrement, adblMultivariateRandom);

  372.             double dblSpotRateIncrement = spotRateIncrement (iSpotDate, iViewDate, dblAnnualizedIncrement,
  373.                 adblMultivariateRandom);

  375.             double dblEvolvedContinuousForwardRate = dblContinuouslyCompoundedForwardRate +
  376.                 dblContinuousForwardRateIncrement;
  377.             double dblDiscountFactorIncrement = dblDiscountFactor * (dblSpotRate -
  378.                 dblContinuouslyCompoundedForwardRate) * dblAnnualizedIncrement -
  379.                     dblForwardVolatilityMultiFactorRandom;

  381.             return org.drip.dynamics.lmm.BGMPointUpdate.Create (_lslFunding, _lslForward, iSpotDate,
  382.                 iSpotDate + iSpotTimeIncrement, iViewDate, dblLIBOR + dblLIBORIncrement, dblLIBORIncrement,
  383.                     dblEvolvedContinuousForwardRate, dblContinuousForwardRateIncrement, dblSpotRate +
  384.                         dblSpotRateIncrement, dblSpotRateIncrement, dblDiscountFactor +
  385.                             dblDiscountFactorIncrement, dblDiscountFactorIncrement, java.lang.Math.exp
  386.                                 (dblEvolvedContinuousForwardRate) - 1., (java.lang.Math.exp (dblDCF *
  387.                                     dblEvolvedContinuousForwardRate) - 1.) / dblDCF, java.lang.Math.sqrt
  388.                                         (dblLognormalPointVolatilityModulus), java.lang.Math.sqrt
  389.                                             (dblContinuousForwardVolatilityModulus));
  390.         } catch (java.lang.Exception e) {
  391.             e.printStackTrace();
  392.         }

  394.         return null;
  395.     }
  396. }
Created with JaCoCo 0.7.9.201702052155