Square.java

  1. package org.drip.function.matrix;

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

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

  66. /**
  67.  * <i>Square</i> implements a Square Matrix. The References are:
  68.  *  
  69.  * <br><br>
  70.  *  <ul>
  71.  *      <li>
  72.  *          Claerbout, J. F. (1985): <i>Fundamentals of Geo-physical Data Processing</i> <b>Blackwell
  73.  *              Scientific</b>
  74.  *      </li>
  75.  *      <li>
  76.  *          Horn, R. A., and C. R. Johnson (1991): <i>Topics in Matrix Analysis</i> <b>Cambridge University
  77.  *              Press</b>
  78.  *      </li>
  79.  *      <li>
  80.  *          Schwerdtfeger, A. (1938): <i>Les Fonctions de Matrices: Les Fonctions Univalentes I</i>
  81.  *              <b>Hermann</b> Paris, France
  82.  *      </li>
  83.  *      <li>
  84.  *          Sylvester, J. J. (1883): On the Equation to the Secular Inequalities in the Planetary Theory
  85.  *              <i>The London, Edinburgh, and Dublin Philosophical Magazine and Journal of Science</i> <b>16
  86.  *              (100)</b> 267-269
  87.  *      </li>
  88.  *      <li>
  89.  *          Wikipedia (2019): Sylvester Formula https://en.wikipedia.org/wiki/Sylvester%27s_formula
  90.  *      </li>
  91.  *  </ul>
  92.  *  
  93.  * <br><br>
  94.  *  <ul>
  95.  *      <li><b>Module </b> = <a href = "https://github.com/lakshmiDRIP/DROP/tree/master/NumericalCore.md">Numerical Core Module</a></li>
  96.  *      <li><b>Library</b> = <a href = "https://github.com/lakshmiDRIP/DROP/tree/master/NumericalSupportLibrary.md">Numerical Support Library</a></li>
  97.  *      <li><b>Project</b> = <a href = "https://github.com/lakshmiDRIP/DROP/tree/master/src/main/java/org/drip/sample/README.md">Sample</a></li>
  98.  *      <li><b>Package</b> = <a href = "https://github.com/lakshmiDRIP/DROP/tree/master/src/main/java/org/drip/sample/matrix/README.md">Linear Algebra and Matrix Utilities</a></li>
  99.  *  </ul>
  100.  * <br><br>
  101.  * 
  102.  * @author Lakshmi Krishnamurthy
  103.  */

  105. public class Square
  106. {
  107.     public double[][] _grid = null;

  109.     /**
  110.      * Square Constructor
  111.      * 
  112.      * @param grid Grid of Elements
  113.      * 
  114.      * @throws java.lang.Exception Throwjn if the Inputs are Invalid
  115.      */

  117.     public Square (
  118.         final double[][] grid)
  119.         throws java.lang.Exception
  120.     {
  121.         if (null == (_grid = grid))
  122.         {
  123.             throw new java.lang.Exception (
  124.                 "Square Constructor => Invalid Inputs"
  125.             );
  126.         }

  128.         int dimension = _grid.length;

  130.         if (0 == dimension)
  131.         {
  132.             throw new java.lang.Exception (
  133.                 "Square Constructor => Invalid Inputs"
  134.             );
  135.         }

  137.         for (int dimensionIndex = 0;
  138.             dimensionIndex < dimension;
  139.             ++dimensionIndex)
  140.         {
  141.             if (null == _grid[dimensionIndex] ||
  142.                 dimension != _grid[dimensionIndex].length ||
  143.                 !org.drip.numerical.common.NumberUtil.IsValid (
  144.                     _grid[dimensionIndex]
  145.                 )
  146.             )
  147.             {
  148.                 throw new java.lang.Exception (
  149.                     "Square Constructor => Invalid Inputs"
  150.                 );
  151.             }
  152.         }
  153.     }

  155.     /**
  156.      * Retrieve the Grid of Elements
  157.      * 
  158.      * @return Grid of Elements
  159.      */

  161.     public double[][] grid()
  162.     {
  163.         return _grid;
  164.     }

  166.     /**
  167.      * Retrieve the Dimension of the Square Matrix
  168.      * 
  169.      * @return Dimension of the Square Matrix
  170.      */

  172.     public int dimension()
  173.     {
  174.         return _grid.length;
  175.     }

  177.     /**
  178.      * Retrieve the Eigen-Components of the Square Matrix
  179.      * 
  180.      * @return The Eigen-Components of the Square Matrix
  181.      */

  183.     public org.drip.numerical.eigen.EigenOutput eigenize()
  184.     {
  185.         try
  186.         {
  187.             return new org.drip.numerical.eigen.QREigenComponentExtractor (
  188.                 100,
  189.                 1.e-06
  190.             ).eigenize (
  191.                 _grid
  192.             );
  193.         }
  194.         catch (java.lang.Exception e)
  195.         {
  196.             e.printStackTrace();
  197.         }

  199.         return null;
  200.     }

  202.     /**
  203.      * Generate the Frobenius Covariance
  204.      * 
  205.      * @return The Frobenius Covariance
  206.      */

  208.     public org.drip.function.matrix.FrobeniusCovariance frobeniusCovariance()
  209.     {
  210.         org.drip.function.matrix.FrobeniusCovariance frobeniusCovariance =
  211.             new org.drip.function.matrix.FrobeniusCovariance();

  213.         org.drip.numerical.eigen.EigenOutput eigenOutput = eigenize();

  215.         if (null == eigenOutput)
  216.         {
  217.             return null;
  218.         }

  220.         double[] eigenValueArray = eigenOutput.eigenValueArray();

  222.         int dimension = _grid.length;
  223.         double[][][] eigenShadowArray = new double[dimension][dimension][dimension];

  225.         for (int eigenIndex = 0;
  226.             eigenIndex < dimension;
  227.             ++eigenIndex)
  228.         {
  229.             for (int dimensionIndexI = 0;
  230.                 dimensionIndexI < dimension;
  231.                 ++dimensionIndexI)
  232.             {
  233.                 for (int dimensionIndexJ = 0;
  234.                     dimensionIndexJ < dimension;
  235.                     ++dimensionIndexJ)
  236.                 {
  237.                     eigenShadowArray[eigenIndex][dimensionIndexI][dimensionIndexJ] =
  238.                         _grid[dimensionIndexI][dimensionIndexJ] - (
  239.                             dimensionIndexI == dimensionIndexJ ? eigenValueArray[eigenIndex] : 0.
  240.                         );
  241.                 }
  242.             }
  243.         }

  245.         for (int componentIndex = 0;
  246.             componentIndex < dimension;
  247.             ++componentIndex)
  248.         {
  249.             double[][] frobeniusComponentMatrix = null;
  250.             double componentEigenValue = eigenValueArray[componentIndex];

  252.             for (int eigenIndex = 0;
  253.                 eigenIndex < dimension;
  254.                 ++eigenIndex)
  255.             {
  256.                 if (eigenIndex == componentIndex)
  257.                 {
  258.                     continue;
  259.                 }

  261.                 if (null == frobeniusComponentMatrix)
  262.                 {
  263.                     frobeniusComponentMatrix = org.drip.numerical.linearalgebra.Matrix.Scale2D (
  264.                         eigenShadowArray[eigenIndex],
  265.                         1. / (componentEigenValue - eigenValueArray[eigenIndex])
  266.                     );
  267.                 }
  268.                 else
  269.                 {
  270.                     frobeniusComponentMatrix = org.drip.numerical.linearalgebra.Matrix.Scale2D (
  271.                         org.drip.numerical.linearalgebra.Matrix.Product (
  272.                             frobeniusComponentMatrix,
  273.                             eigenShadowArray[eigenIndex]
  274.                         ),
  275.                         1. / (componentEigenValue - eigenValueArray[eigenIndex])
  276.                     );
  277.                 }
  278.             }

  280.             try
  281.             {
  282.                 if (!frobeniusCovariance.addComponent (
  283.                     componentEigenValue,
  284.                     new org.drip.function.matrix.Square (
  285.                         frobeniusComponentMatrix
  286.                     )
  287.                 ))
  288.                 {
  289.                     return null;
  290.                 }
  291.             }
  292.             catch (java.lang.Exception e)
  293.             {
  294.                 e.printStackTrace();
  295.             }
  296.         }

  298.         return frobeniusCovariance;
  299.     }

  301.     /**
  302.      * Compute the Value of the Matrix using the specified Function
  303.      * 
  304.      * @param r1ToR1Function The R<sup>1</sup> To R<sup>1</sup> Function
  305.      * 
  306.      * @return The Function Matrix Value
  307.      */

  309.     public double[][] evaluate (
  310.         final org.drip.function.definition.R1ToR1 r1ToR1Function)
  311.     {
  312.         if (null == r1ToR1Function)
  313.         {
  314.             return null;
  315.         }

  317.         int dimension = _grid.length;
  318.         double[][] matrixFunction = null;

  320.         org.drip.function.matrix.FrobeniusCovariance frobeniusCovariance = frobeniusCovariance();

  322.         if (null == frobeniusCovariance)
  323.         {
  324.             return null;
  325.         }

  327.         for (java.util.Map.Entry<java.lang.Double, org.drip.function.matrix.Square> componentMapEntry :
  328.             frobeniusCovariance.componentMap().entrySet())
  329.         {
  330.             double[][] frobeniusComponentFunctionProjection = null;

  332.             try
  333.             {
  334.                 frobeniusComponentFunctionProjection = org.drip.numerical.linearalgebra.Matrix.Scale2D (
  335.                     componentMapEntry.getValue().grid(),
  336.                     r1ToR1Function.evaluate (
  337.                         componentMapEntry.getKey()
  338.                     )
  339.                 );
  340.             }
  341.             catch (java.lang.Exception e)
  342.             {
  343.                 e.printStackTrace();

  345.                 return null;
  346.             }

  348.             if (null == frobeniusComponentFunctionProjection)
  349.             {
  350.                 return null;
  351.             }

  353.             if (null == matrixFunction)
  354.             {
  355.                 matrixFunction = frobeniusComponentFunctionProjection;
  356.             }
  357.             else
  358.             {
  359.                 for (int dimensionIndexI = 0;
  360.                     dimensionIndexI < dimension;
  361.                     ++dimensionIndexI)
  362.                 {
  363.                     for (int dimensionIndexJ = 0;
  364.                         dimensionIndexJ < dimension;
  365.                         ++dimensionIndexJ)
  366.                     {
  367.                         matrixFunction[dimensionIndexI][dimensionIndexJ] =
  368.                             matrixFunction[dimensionIndexI][dimensionIndexJ] +
  369.                             frobeniusComponentFunctionProjection[dimensionIndexI][dimensionIndexJ];
  370.                     }
  371.                 }
  372.             }
  373.         }

  375.         return matrixFunction;
  376.     }

  378.     /**
  379.      * Compute the Determinant
  380.      *
  381.      * @return The Determinant
  382.      */

  384.     public double determinant()
  385.     {
  386.         org.drip.numerical.eigen.EigenOutput eigenOutput = eigenize();

  388.         if (null == eigenOutput)
  389.         {
  390.             return 0.;
  391.         }

  393.         double[] eigenValueArray = eigenOutput.eigenValueArray();

  395.         double determinant = 1.;
  396.         int dimension = _grid.length;

  398.         for (int eigenIndex = 0;
  399.             eigenIndex < dimension;
  400.             ++eigenIndex)
  401.         {
  402.              determinant = determinant * eigenValueArray[eigenIndex];
  403.         }

  405.         return determinant;
  406.     }
  407. }
Created with JaCoCo 0.7.9.201702052155