Array2D.java

  1. package org.drip.numerical.common;

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

  85. /**
  86.  * <i>Array2D</i> the contains array of x and y. It provides methods to create/access different varieties of
  87.  * x/y schedule creation.
  88.  * 
  89.  * <br><br>
  90.  *  <ul>
  91.  *      <li><b>Module </b> = <a href = "https://github.com/lakshmiDRIP/DROP/tree/master/ComputationalCore.md">Computational Core Module</a></li>
  92.  *      <li><b>Library</b> = <a href = "https://github.com/lakshmiDRIP/DROP/tree/master/NumericalAnalysisLibrary.md">Numerical Analysis Library</a></li>
  93.  *      <li><b>Project</b> = <a href = "https://github.com/lakshmiDRIP/DROP/tree/master/src/main/java/org/drip/numerical">Numerical Quadrature, Differentiation, Eigenization, Linear Algebra, and Utilities</a></li>
  94.  *      <li><b>Package</b> = <a href = "https://github.com/lakshmiDRIP/DROP/tree/master/src/main/java/org/drip/numerical/common">Primitives/Array Manipulate Format Display Utilities</a></li>
  95.  *  </ul>
  96.  * <br><br>
  97.  *
  98.  * @author Lakshmi Krishnamurthy
  99.  */

  101. public class Array2D {
  102.     private double _adblX[] = null;
  103.     private double _adblY[] = null;

  105.     /**
  106.      * Generate the Array2D Schedule from the String Representation of the Vertex Dates and Edge Payments
  107.      *  Combination.
  108.      * 
  109.      * @param strDateAmountVertex The String Array consisting of the Date and the Amount Vertexes
  110.      * @param iMaturityDate The Maturity Date
  111.      * @param dblInitialAmount The Initial Amount
  112.      * 
  113.      * @return The Array2D Instance
  114.      */

  116.     public static final Array2D FromDateAmountVertex (
  117.         final java.lang.String strDateAmountVertex,
  118.         final int iMaturityDate,
  119.         final double dblInitialAmount)
  120.     {
  121.         if (null == strDateAmountVertex || strDateAmountVertex.isEmpty() ||
  122.             !org.drip.numerical.common.NumberUtil.IsValid (dblInitialAmount) || 0. >= dblInitialAmount)
  123.             return null;

  125.         java.lang.String[] astrDateAmountEdge = org.drip.numerical.common.StringUtil.Split (strDateAmountVertex,
  126.             ";");

  128.         if (null == astrDateAmountEdge) return null;

  130.         int iNumDateFactorPair = astrDateAmountEdge.length;
  131.         int iNumVertex = iNumDateFactorPair / 2 + 1;
  132.         double[] adblVertexDate = new double[iNumVertex];
  133.         double[] adblVertexFactor = new double[iNumVertex];
  134.         double[] adblVertexOutstanding = new double[iNumVertex];
  135.         adblVertexOutstanding[0] = dblInitialAmount;

  137.         if (0 == iNumDateFactorPair || 1 == iNumDateFactorPair % 2) return null;

  139.         for (int i = 0; i < iNumVertex - 1; ++i) {
  140.             org.drip.analytics.date.JulianDate dt = org.drip.analytics.date.DateUtil.FromMDY
  141.                 (astrDateAmountEdge[2 * i], "/");

  143.             java.lang.String strEdgeAmount = astrDateAmountEdge[2 * i + 1];

  145.             if (null == dt || null == strEdgeAmount || strEdgeAmount.isEmpty()) return null;

  147.             adblVertexDate[i] = dt.julian();

  149.             double dblPrincipalPayAmount = java.lang.Double.parseDouble (strEdgeAmount.trim());

  151.             if (!org.drip.numerical.common.NumberUtil.IsValid (dblPrincipalPayAmount)) return null;

  153.             if (0. >= dblPrincipalPayAmount || 0. >= (adblVertexOutstanding[i + 1] = adblVertexOutstanding[i]
  154.                 - dblPrincipalPayAmount))
  155.                 return null;
  156.         }

  158.         for (int i = 0; i < iNumVertex; ++i)
  159.             adblVertexFactor[i] = adblVertexOutstanding[i] / dblInitialAmount;

  161.         adblVertexDate[iNumVertex - 1] = iMaturityDate;

  163.         return FromArray (adblVertexDate, adblVertexFactor);
  164.     }

  166.     /**
  167.      * Generate an Array2D Instance from the String Array containing semi-colon delimited Date/Factor Vertex
  168.      *  Pair
  169.      * 
  170.      * @param strDateFactorVertex The String Array containing semi-colon delimited Date/Edge Pair
  171.      * @param iMaturityDate The Maturity Date
  172.      * @param dblInitialAmount The Initial Amount
  173.      * 
  174.      * @return The Array2D Instance
  175.      */

  177.     public static final Array2D FromDateFactorVertex (
  178.         final java.lang.String strDateFactorVertex,
  179.         final int iMaturityDate,
  180.         final double dblInitialAmount)
  181.     {
  182.         if (null == strDateFactorVertex || strDateFactorVertex.isEmpty() ||
  183.             !org.drip.numerical.common.NumberUtil.IsValid (dblInitialAmount))
  184.             return null;

  186.         java.lang.String[] astrDateFactorVertex = org.drip.numerical.common.StringUtil.Split
  187.             (strDateFactorVertex, ";");

  189.         if (null == astrDateFactorVertex) return null;

  191.         int iNumDateFactorPair = astrDateFactorVertex.length;
  192.         int iNumVertex = iNumDateFactorPair / 2 + 1;
  193.         double[] adblVertexDate = new double[iNumVertex];
  194.         double[] adblVertexFactor = new double[iNumVertex];
  195.         adblVertexFactor[0] = 1.;

  197.         if (0 == iNumDateFactorPair || 1 == iNumDateFactorPair % 2) return null;

  199.         for (int i = 0; i < iNumVertex - 1; ++i) {
  200.             org.drip.analytics.date.JulianDate dt = org.drip.analytics.date.DateUtil.FromMDY
  201.                 (astrDateFactorVertex[2 * i], "/");

  203.             java.lang.String strFactor = astrDateFactorVertex[2 * i + 1];

  205.             if (null == dt || null == strFactor || strFactor.isEmpty()) return null;

  207.             adblVertexDate[i] = dt.julian();

  209.             if (!org.drip.numerical.common.NumberUtil.IsValid (adblVertexFactor[i + 1] =
  210.                 java.lang.Double.parseDouble (strFactor.trim()) / dblInitialAmount))
  211.                 return null;
  212.         }

  214.         adblVertexDate[iNumVertex - 1] = iMaturityDate;

  216.         return FromArray (adblVertexDate, adblVertexFactor);
  217.     }

  219.     /**
  220.      * Generate an Array2D Instance from the String Array containing semi-colon delimited Date/Factor Vertex
  221.      *  Pair
  222.      * 
  223.      * @param strDateFactorVertex The String Array containing semi-colon delimited Date/Edge Pair
  224.      * @param iMaturityDate The Maturity Date
  225.      * 
  226.      * @return The Array2D Instance
  227.      */

  229.     public static final Array2D FromDateFactorVertex (
  230.         final java.lang.String strDateFactorVertex,
  231.         final int iMaturityDate)
  232.     {
  233.         if (null == strDateFactorVertex || strDateFactorVertex.isEmpty()) return null;

  235.         java.lang.String[] astrDateFactorVertex = org.drip.numerical.common.StringUtil.Split
  236.             (strDateFactorVertex, ";");

  238.         if (null == astrDateFactorVertex) return null;

  240.         int iNumDateFactorPair = astrDateFactorVertex.length;
  241.         int iNumVertex = iNumDateFactorPair / 2 + 1;
  242.         double[] adblVertexDate = new double[iNumVertex];
  243.         double[] adblVertexFactor = new double[iNumVertex];
  244.         adblVertexFactor[0] = 1.;

  246.         if (0 == iNumDateFactorPair || 1 == iNumDateFactorPair % 2) return null;

  248.         for (int i = 0; i < iNumVertex - 1; ++i) {
  249.             org.drip.analytics.date.JulianDate dt = org.drip.analytics.date.DateUtil.FromMDY
  250.                 (astrDateFactorVertex[2 * i], "/");

  252.             java.lang.String strFactor = astrDateFactorVertex[2 * i + 1];

  254.             if (null == dt || null == strFactor || strFactor.isEmpty()) return null;

  256.             adblVertexDate[i] = dt.julian();

  258.             if (!org.drip.numerical.common.NumberUtil.IsValid (adblVertexFactor[i + 1] =
  259.                 java.lang.Double.parseDouble (strFactor.trim())))
  260.                 return null;
  261.         }

  263.         adblVertexDate[iNumVertex - 1] = iMaturityDate;

  265.         for (int i = 0; i < iNumVertex - 1; ++i) {
  266.             System.out.println (new org.drip.analytics.date.JulianDate ((int) adblVertexDate[i]) + " | " + adblVertexFactor[i]);
  267.         }

  269.         return FromArray (adblVertexDate, adblVertexFactor);
  270.     }

  272.     /**
  273.      * Create the Array2D Instance from a Matched String Array of X and Y
  274.      * 
  275.      * @param strX String Array of X
  276.      * @param strY String Array of Y
  277.      * 
  278.      * @return The Array2D Instance
  279.      */

  281.     public static final Array2D FromStringSet (
  282.         final java.lang.String strX,
  283.         final java.lang.String strY)
  284.     {
  285.         if (null == strX || strX.isEmpty() || null == strY || strY.isEmpty()) return null;

  287.         try {
  288.             return new Array2D (org.drip.numerical.common.StringUtil.MakeDoubleArrayFromStringTokenizer (new
  289.                 java.util.StringTokenizer (strX, ";")),
  290.                     org.drip.numerical.common.StringUtil.MakeDoubleArrayFromStringTokenizer (new
  291.                         java.util.StringTokenizer (strY, ";")));
  292.         } catch (java.lang.Exception e) {
  293.             e.printStackTrace();
  294.         }

  296.         return null;
  297.     }

  299.     /**
  300.      * Create the Array2D Instance from a Matched Array of X and Y
  301.      * 
  302.      * @param adblX Array of X
  303.      * @param adblY Array of Y
  304.      * 
  305.      * @return The Array2D Instance
  306.      */

  308.     public static final Array2D FromArray (
  309.         final double[] adblX,
  310.         final double[] adblY)
  311.     {
  312.         try {
  313.             return new Array2D (adblX, adblY);
  314.         } catch (java.lang.Exception e) {
  315.             e.printStackTrace();
  316.         }

  318.         return null;
  319.     }

  321.     /**
  322.      * Create the Array2D Instance from a Matched Array of X and Y
  323.      * 
  324.      * @param aiX Array of X
  325.      * @param adblY Array of Y
  326.      * 
  327.      * @return The Array2D Instance
  328.      */

  330.     public static final Array2D FromArray (
  331.         final int[] aiX,
  332.         final double[] adblY)
  333.     {
  334.         if (null == aiX) return null;

  336.         int iSize = aiX.length;
  337.         double[] adblX = new double[iSize];

  339.         if (0 == iSize) return null;

  341.         for (int i = 0; i < iSize; ++i)
  342.             adblX[i] = aiX[i];

  344.         return FromArray (adblX, adblY);
  345.     }

  347.     /**
  348.      * Create the Array2D Instance from a Matched Array of X and Y Deltas
  349.      * 
  350.      * @param adblX Array of X
  351.      * @param adblYDelta Array of Y Deltas
  352.      * @param dblYInitial The Initial Value of Y
  353.      * 
  354.      * @return The Array2D Instance
  355.      */

  357.     public static final Array2D FromXYDeltaArray (
  358.         final double[] adblX,
  359.         final double[] adblYDelta,
  360.         final double dblYInitial)
  361.     {
  362.         if (null == adblX || null == adblYDelta || !org.drip.numerical.common.NumberUtil.IsValid (dblYInitial))
  363.             return null;

  365.         int i = 0;
  366.         int iLength = adblX.length;
  367.         double[] adblY = new double[iLength];
  368.         adblY[0] = dblYInitial;

  370.         if (0 == iLength || iLength != adblYDelta.length) return null;

  372.         for (double dblYDelta : adblYDelta) {
  373.             if (i < iLength - 1) adblY[i + 1] = adblY[i] - dblYDelta;

  375.             ++i;
  376.         }

  378.         try {
  379.             return new Array2D (adblX, adblY);
  380.         } catch (java.lang.Exception e) {
  381.             e.printStackTrace();
  382.         }

  384.         return null;
  385.     }

  387.     /**
  388.      * Create an Array2D Instance from the Flat Unit Y
  389.      * 
  390.      * @return The Array2D Instance
  391.      */

  393.     public static final Array2D BulletSchedule()
  394.     {
  395.         double[] adblFactor = new double[1];
  396.         double[] adblDate = new double[1];
  397.         adblFactor[0] = 1.;

  399.         adblDate[0] = org.drip.analytics.date.DateUtil.CreateFromYMD (1900, 1, 1).julian();

  401.         try {
  402.             return new Array2D (adblDate, adblFactor);
  403.         } catch (java.lang.Exception e) {
  404.             e.printStackTrace();
  405.         }

  407.         return null;
  408.     }

  410.     private Array2D (
  411.         final double[] adblX,
  412.         final double[] adblY)
  413.         throws java.lang.Exception
  414.     {
  415.         if (null == adblX || null == adblY) throw new java.lang.Exception ("Array2D ctr => Invalid params");

  417.         int iLength = adblX.length;
  418.         _adblX = new double[iLength];
  419.         _adblY = new double[iLength];

  421.         if (0 == iLength || iLength != adblY.length)
  422.             throw new java.lang.Exception ("Array2D ctr => Invalid params");

  424.         for (int i = 0; i < iLength; ++i) {
  425.             // System.out.println (new org.drip.analytics.date.JulianDate ((int) _adblX[i]) + " | " + _adblY[i]);

  427.             if (!org.drip.numerical.common.NumberUtil.IsValid (_adblX[i] = adblX[i]) ||
  428.                 !org.drip.numerical.common.NumberUtil.IsValid (_adblY[i] = adblY[i]))
  429.                 throw new java.lang.Exception ("Array2D ctr => Invalid params");
  430.         }
  431.     }

  433.     /**
  434.      * Retrieve the Y given X
  435.      * 
  436.      * @param dblX X
  437.      * 
  438.      * @return Y 
  439.      * 
  440.      * @throws java.lang.Exception Thrown if the Y cannot be computed
  441.      */

  443.     public double y (
  444.         final double dblX)
  445.         throws java.lang.Exception
  446.     {
  447.         if (!org.drip.numerical.common.NumberUtil.IsValid (dblX))
  448.             throw new java.lang.Exception ("Array2D::y => Invalid Input");

  450.         if (dblX <= _adblX[0]) return _adblY[0];

  452.         int iLength = _adblX.length;

  454.         for (int i = 1; i < iLength; ++i) {
  455.             if (dblX > _adblX[i - 1] && dblX <= _adblX[i]) return _adblY[i];
  456.         }

  458.         return _adblY[iLength - 1];
  459.     }

  461.     /**
  462.      * Retrieve the Index that corresponds to the given X
  463.      * 
  464.      * @param dblX X
  465.      * 
  466.      * @return Index 
  467.      * 
  468.      * @throws java.lang.Exception Thrown if the Index cannot be computed
  469.      */

  471.     public int index (
  472.         final double dblX)
  473.         throws java.lang.Exception
  474.     {
  475.         if (!org.drip.numerical.common.NumberUtil.IsValid (dblX))
  476.             throw new java.lang.Exception ("Array2D::index => Invalid Input/State");

  478.         if (dblX <= _adblX[0]) return 0;

  480.         int iLength = _adblX.length;

  482.         for (int i = 1; i < iLength; ++i) {
  483.             if (dblX <= _adblX[i]) return i;
  484.         }

  486.         return iLength - 1;
  487.     }

  489.     /**
  490.      * Retrieve the X-Weighted Y
  491.      * 
  492.      * @param dblStartX Start X
  493.      * @param dblEndX End X
  494.      * 
  495.      * @return The X-Weighted Y 
  496.      * 
  497.      * @throws java.lang.Exception Thrown if the Y cannot be computed
  498.      */

  500.     public double y (
  501.         final double dblStartX,
  502.         final double dblEndX)
  503.         throws java.lang.Exception
  504.     {
  505.         if (!org.drip.numerical.common.NumberUtil.IsValid (dblStartX) ||
  506.             !org.drip.numerical.common.NumberUtil.IsValid (dblEndX))
  507.             throw new java.lang.Exception ("Array2D::y => Invalid Inputs");

  509.         int iEndIndex = index (dblEndX);

  511.         int iStartIndex = index (dblStartX);

  513.         if (iStartIndex == iEndIndex) return _adblY[iStartIndex];

  515.         double dblWeightedY = _adblY[iStartIndex] * (_adblX[iStartIndex] - dblStartX);

  517.         for (int i = iStartIndex + 1; i <= iEndIndex; ++i)
  518.             dblWeightedY += _adblY[i] * (_adblX[i] - _adblX[i - 1]);

  520.         return (dblWeightedY + _adblY[iEndIndex] * (dblEndX - _adblX[iEndIndex])) / (dblEndX - dblStartX);
  521.     }

  523.     /**
  524.      * Retrieve the Array of X
  525.      * 
  526.      * @return Array of X
  527.      */

  529.     public double[] x()
  530.     {
  531.         return _adblX;
  532.     }

  534.     /**
  535.      * Retrieve the Array of Y
  536.      * 
  537.      * @return Array of Y
  538.      */

  540.     public double[] y()
  541.     {
  542.         return _adblY;
  543.     }

  545.     /**
  546.      * Indicate if this Array2D Instance matches the "other" Entry-by-Entry
  547.      * 
  548.      * @param a2DOther The "Other" Array2D Instance
  549.      * 
  550.      * @return TRUE - The Array2D Instances match Entry-by-Entry
  551.      */

  553.     public boolean match (
  554.         final Array2D a2DOther)
  555.     {
  556.         if (null == a2DOther) return false;

  558.         double[] adblOtherX = a2DOther._adblX;
  559.         double[] adblOtherY = a2DOther._adblY;
  560.         int iNumOtherX = adblOtherX.length;
  561.         int iNumOtherY = adblOtherY.length;

  563.         if (iNumOtherX != _adblX.length || iNumOtherY != _adblY.length) return false;

  565.         for (int i = 0; i < iNumOtherX; ++i) {
  566.             if (adblOtherX[i] != _adblX[i]) return false;
  567.         }

  569.         for (int i = 0; i < iNumOtherY; ++i) {
  570.             if (adblOtherY[i] != _adblY[i]) return false;
  571.         }

  573.         return true;
  574.     }
  575. }
Created with JaCoCo 0.7.9.201702052155