RdToR1.java

  1. package org.drip.function.definition;

  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>RdToR1</i> provides the evaluation of the R<sup>d</sup> To R<sup>1</sup> objective function and its
  83.  * derivatives for a specified set of R<sup>d</sup> variates. Default implementation of the derivatives are
  84.  * for non-analytical lack box objective functions.
  85.  *
  86.  *  <br><br>
  87.  *  <ul>
  88.  *      <li><b>Module </b> = <a href = "https://github.com/lakshmiDRIP/DROP/tree/master/ComputationalCore.md">Computational Core Module</a></li>
  89.  *      <li><b>Library</b> = <a href = "https://github.com/lakshmiDRIP/DROP/tree/master/NumericalAnalysisLibrary.md">Numerical Analysis Library</a></li>
  90.  *      <li><b>Project</b> = <a href = "https://github.com/lakshmiDRIP/DROP/tree/master/src/main/java/org/drip/function/README.md">R<sup>d</sup> To R<sup>d</sup> Function Analysis</a></li>
  91.  *      <li><b>Package</b> = <a href = "https://github.com/lakshmiDRIP/DROP/tree/master/src/main/java/org/drip/function/definition/README.md">Function Implementation Ancillary Support Objects</a></li>
  92.  *  </ul>
  93.  *
  94.  * @author Lakshmi Krishnamurthy
  95.  */

  97. public abstract class RdToR1 {
  98.     private static final int EXTREMA_SAMPLING = 10000;
  99.     private static final int QUADRATURE_SAMPLING = 10000;

  101.     protected static final int DIMENSION_NOT_FIXED = -1;

  103.     protected org.drip.numerical.differentiation.DerivativeControl _dc = null;

  105.     /**
  106.      * Validate the Input Double Array
  107.      * 
  108.      * @param adblVariate The Input Double Array
  109.      * 
  110.      * @return The Input Double Array consists of valid Values
  111.      */

  113.     public static final boolean ValidateInput (
  114.         final double[] adblVariate)
  115.     {
  116.         if (null == adblVariate) return false;

  118.         int iNumVariate = adblVariate.length;

  120.         if (0 == iNumVariate) return false;

  122.         for (int i = 0; i < iNumVariate; ++i) {
  123.             if (!org.drip.numerical.common.NumberUtil.IsValid (adblVariate[i])) return false;
  124.         }

  126.         return true;
  127.     }

  129.     protected RdToR1 (
  130.         final org.drip.numerical.differentiation.DerivativeControl dc)
  131.     {
  132.         if (null == (_dc = dc)) _dc = new org.drip.numerical.differentiation.DerivativeControl();
  133.     }

  135.     /**
  136.      * Retrieve the Dimension of the Input Variate
  137.      * 
  138.      * @return The Dimension of the Input Variate
  139.      */

  141.     public abstract int dimension();

  143.     /**
  144.      * Evaluate for the given Input Variates
  145.      * 
  146.      * @param adblVariate Array of Input Variates
  147.      *  
  148.      * @return The Calculated Value
  149.      * 
  150.      * @throws java.lang.Exception Thrown if the Evaluation cannot be done
  151.      */

  153.     public abstract double evaluate (
  154.         final double[] adblVariate)
  155.         throws java.lang.Exception;

  157.     /**
  158.      * Calculate the Differential
  159.      * 
  160.      * @param adblVariate Variate Array at which the derivative is to be calculated
  161.      * @param iVariateIndex Index of the Variate whose Derivative is to be computed
  162.      * @param iOrder Order of the derivative to be computed
  163.      * 
  164.      * @return The Derivative
  165.      */

  167.     public org.drip.numerical.differentiation.Differential differential (
  168.         final double[] adblVariate,
  169.         final int iVariateIndex,
  170.         final int iOrder)
  171.     {
  172.         if (!org.drip.numerical.common.NumberUtil.IsValid (adblVariate) || 0 >= iOrder) return null;

  174.         double dblDerivative = 0.;
  175.         int iNumVariate = adblVariate.length;
  176.         double dblOrderedVariateInfinitesimal = 1.;
  177.         double dblVariateInfinitesimal = java.lang.Double.NaN;

  179.         if (iNumVariate <= iVariateIndex) return null;

  181.         try {
  182.             dblVariateInfinitesimal = _dc.getVariateInfinitesimal (adblVariate[iVariateIndex]);
  183.         } catch (java.lang.Exception e) {
  184.             e.printStackTrace();

  186.             return null;
  187.         }

  189.         for (int i = 0; i <= iOrder; ++i) {
  190.             if (0 != i) dblOrderedVariateInfinitesimal *= (2. * dblVariateInfinitesimal);

  192.             double[] adblVariateIncremental = new double[iNumVariate];

  194.             for (int j = 0; j < iNumVariate; ++j)
  195.                 adblVariateIncremental[j] = j == iVariateIndex ? adblVariate[j] + dblVariateInfinitesimal *
  196.                     (iOrder - 2. * i) : adblVariate[j];

  198.             try {
  199.                 dblDerivative += (i % 2 == 0 ? 1 : -1) * org.drip.numerical.common.NumberUtil.NCK (iOrder, i) *
  200.                     evaluate (adblVariateIncremental);
  201.             } catch (java.lang.Exception e) {
  202.                 e.printStackTrace();

  204.                 return null;
  205.             }
  206.         }

  208.         try {
  209.             return new org.drip.numerical.differentiation.Differential (dblOrderedVariateInfinitesimal, dblDerivative);
  210.         } catch (java.lang.Exception e) {
  211.             e.printStackTrace();
  212.         }

  214.         return null;
  215.     }

  217.     /**
  218.      * Calculate the derivative as a double
  219.      * 
  220.      * @param adblVariate Variate Array at which the derivative is to be calculated
  221.      * @param iVariateIndex Index of the Variate whose Derivative is to be computed
  222.      * @param iOrder Order of the derivative to be computed
  223.      * 
  224.      * @return The Derivative
  225.      * 
  226.      * @throws java.lang.Exception Thrown if the Derivative cannot be calculated
  227.      */

  229.     public double derivative (
  230.         final double[] adblVariate,
  231.         final int iVariateIndex,
  232.         final int iOrder)
  233.         throws java.lang.Exception
  234.     {
  235.         return differential (adblVariate, iVariateIndex, iOrder).calcSlope (true);
  236.     }

  238.     /**
  239.      * Evaluate the Jacobian for the given Input Variates
  240.      * 
  241.      * @param adblVariate Array of Input Variates
  242.      *  
  243.      * @return The Jacobian Array
  244.      */

  246.     public double[] jacobian (
  247.         final double[] adblVariate)
  248.     {
  249.         if (null == adblVariate) return null;

  251.         int iNumVariate = adblVariate.length;
  252.         double[] adblJacobian = new double[iNumVariate];

  254.         if (0 == iNumVariate) return null;

  256.         for (int i = 0; i < iNumVariate; ++i) {
  257.             try {
  258.                 adblJacobian[i] = derivative (adblVariate, i, 1);
  259.             } catch (java.lang.Exception e) {
  260.                 e.printStackTrace();

  262.                 return null;
  263.             }
  264.         }

  266.         return adblJacobian;
  267.     }

  269.     /**
  270.      * Construct an Instance of the Unit Gradient Vector at the given Input Variates
  271.      * 
  272.      * @param adblVariate Array of Input Variates
  273.      *  
  274.      * @return Instance of the Unit Gradient Vector Array
  275.      */

  277.     public org.drip.function.definition.UnitVector gradient (
  278.         final double[] adblVariate)
  279.     {
  280.         return org.drip.function.definition.UnitVector.Standard (jacobian (adblVariate));
  281.     }

  283.     /**
  284.      * Evaluate The Hessian for the given Input Variates
  285.      * 
  286.      * @param adblVariate Array of Input Variates
  287.      *  
  288.      * @return The Hessian Matrix
  289.      */

  291.     public double[][] hessian (
  292.         final double[] adblVariate)
  293.     {
  294.         if (null == adblVariate) return null;

  296.         final int iNumVariate = adblVariate.length;
  297.         double[][] adblHessian = new double[iNumVariate][iNumVariate];

  299.         if (0 == iNumVariate) return null;

  301.         for (int i = 0; i < iNumVariate; ++i) {
  302.             final int iVariateIndex = i;

  304.             org.drip.function.definition.RdToR1 gradientRdToR1 = new org.drip.function.definition.RdToR1
  305.                 (null) {
  306.                 @Override public int dimension()
  307.                 {
  308.                     return iNumVariate;
  309.                 }

  311.                 @Override public double evaluate (
  312.                     final double[] adblVariate)
  313.                     throws java.lang.Exception
  314.                 {
  315.                     return derivative (adblVariate, iVariateIndex, 1);
  316.                 }
  317.             };

  319.             for (int j = 0; j < iNumVariate; ++j) {
  320.                 try {
  321.                     adblHessian[i][j] = gradientRdToR1.derivative (adblVariate, j, 1);
  322.                 } catch (java.lang.Exception e) {
  323.                     e.printStackTrace();

  325.                     return null;
  326.                 }
  327.             }
  328.         }

  330.         return adblHessian;
  331.     }

  333.     /**
  334.      * Integrate over the given Input Range Using Uniform Monte-Carlo
  335.      * 
  336.      * @param adblLeftEdge Array of Input Left Edge
  337.      * @param adblRightEdge Array of Input Right Edge
  338.      *  
  339.      * @return The Result of the Integration over the specified Range
  340.      * 
  341.      * @throws java.lang.Exception Thrown if the Integration cannot be done
  342.      */

  344.     public double integrate (
  345.         final double[] adblLeftEdge,
  346.         final double[] adblRightEdge)
  347.         throws java.lang.Exception
  348.     {
  349.         if (!org.drip.numerical.common.NumberUtil.IsValid (adblLeftEdge) ||
  350.             !org.drip.numerical.common.NumberUtil.IsValid (adblRightEdge))
  351.             throw new java.lang.Exception ("RdToR1::integrate => Invalid Inputs");

  353.         double dblIntegrand = 0.;
  354.         int iNumVariate = adblLeftEdge.length;
  355.         double[] adblVariate = new double[iNumVariate];
  356.         double[] adblVariateWidth = new double[iNumVariate];

  358.         if (adblRightEdge.length != iNumVariate)
  359.             throw new java.lang.Exception ("RdToR1::integrate => Invalid Inputs");

  361.         for (int j = 0; j < iNumVariate; ++j)
  362.             adblVariateWidth[j] = adblRightEdge[j] - adblLeftEdge[j];

  364.         for (int i = 0; i < QUADRATURE_SAMPLING; ++i) {
  365.             for (int j = 0; j < iNumVariate; ++j)
  366.                 adblVariate[j] = adblLeftEdge[j] + java.lang.Math.random() * adblVariateWidth[j];

  368.             dblIntegrand += evaluate (adblVariate);
  369.         }

  371.         for (int j = 0; j < iNumVariate; ++j)
  372.             dblIntegrand = dblIntegrand * adblVariateWidth[j];

  374.         return dblIntegrand / QUADRATURE_SAMPLING;
  375.     }

  377.     /**
  378.      * Compute the Maximum VOP within the Variate Array Range Using Uniform Monte-Carlo
  379.      * 
  380.      * @param adblVariateLeft The Range Left End Array
  381.      * @param adblVariateRight The Range Right End Array
  382.      * 
  383.      * @return The Maximum VOP
  384.      */

  386.     public org.drip.function.definition.VariateOutputPair maxima (
  387.         final double[] adblVariateLeft,
  388.         final double[] adblVariateRight)
  389.     {
  390.         if (!org.drip.numerical.common.NumberUtil.IsValid (adblVariateLeft) ||
  391.             !org.drip.numerical.common.NumberUtil.IsValid (adblVariateRight))
  392.             return null;

  394.         double dblValue = java.lang.Double.NaN;
  395.         double dblMaxima = java.lang.Double.NaN;
  396.         int iNumVariate = adblVariateLeft.length;
  397.         double[] adblVariate = new double[iNumVariate];
  398.         double[] adblVariateWidth = new double[iNumVariate];
  399.         double[] adblMaximaVariate = new double[iNumVariate];

  401.         if (adblVariateRight.length != iNumVariate) return null;

  403.         for (int j = 0; j < iNumVariate; ++j)
  404.             adblVariateWidth[j] = adblVariateRight[j] - adblVariateLeft[j];

  406.         for (int i = 0; i < EXTREMA_SAMPLING; ++i) {
  407.             for (int j = 0; j < iNumVariate; ++j)
  408.                 adblVariate[j] = adblVariateLeft[j] + java.lang.Math.random() * adblVariateWidth[j];

  410.             try {
  411.                 dblValue = evaluate (adblVariate);
  412.             } catch (java.lang.Exception e) {
  413.                 e.printStackTrace();

  415.                 return null;
  416.             }

  418.             if (!org.drip.numerical.common.NumberUtil.IsValid (dblMaxima)) {
  419.                 dblMaxima = dblValue;

  421.                 for (int j = 0; j < iNumVariate; ++j)
  422.                     adblMaximaVariate[j] = adblVariate[j];
  423.             } else {
  424.                 if (dblMaxima < dblValue) {
  425.                     dblMaxima = dblValue;

  427.                     for (int j = 0; j < iNumVariate; ++j)
  428.                         adblMaximaVariate[j] = adblVariate[j];
  429.                 }
  430.             }
  431.         }

  433.         try {
  434.             return new org.drip.function.definition.VariateOutputPair (adblMaximaVariate, new double[]
  435.                 {dblMaxima});
  436.         } catch (java.lang.Exception e) {
  437.             e.printStackTrace();
  438.         }

  440.         return null;
  441.     }

  443.     /**
  444.      * Compute the Minimum VOP within the Variate Array Range Using Uniform Monte-Carlo
  445.      * 
  446.      * @param adblVariateLeft The Range Left End Array
  447.      * @param adblVariateRight The Range Right End Array
  448.      * 
  449.      * @return The Minimum VOP
  450.      */

  452.     public org.drip.function.definition.VariateOutputPair minima (
  453.         final double[] adblVariateLeft,
  454.         final double[] adblVariateRight)
  455.     {
  456.         if (!org.drip.numerical.common.NumberUtil.IsValid (adblVariateLeft) ||
  457.             !org.drip.numerical.common.NumberUtil.IsValid (adblVariateRight))
  458.             return null;

  460.         double dblValue = java.lang.Double.NaN;
  461.         double dblMinima = java.lang.Double.NaN;
  462.         int iNumVariate = adblVariateLeft.length;
  463.         double[] adblVariate = new double[iNumVariate];
  464.         double[] adblVariateWidth = new double[iNumVariate];
  465.         double[] adblMinimaVariate = new double[iNumVariate];

  467.         if (adblVariateRight.length != iNumVariate) return null;

  469.         for (int j = 0; j < iNumVariate; ++j)
  470.             adblVariateWidth[j] = adblVariateRight[j] - adblVariateLeft[j];

  472.         for (int i = 0; i < EXTREMA_SAMPLING; ++i) {
  473.             for (int j = 0; j < iNumVariate; ++j)
  474.                 adblVariate[j] = adblVariateLeft[j] + java.lang.Math.random() * adblVariateWidth[j];

  476.             try {
  477.                 dblValue = evaluate (adblVariate);
  478.             } catch (java.lang.Exception e) {
  479.                 e.printStackTrace();

  481.                 return null;
  482.             }

  484.             if (!org.drip.numerical.common.NumberUtil.IsValid (dblMinima)) {
  485.                 dblMinima = dblValue;

  487.                 for (int j = 0; j < iNumVariate; ++j)
  488.                     adblMinimaVariate[j] = adblVariate[j];
  489.             } else {
  490.                 if (dblMinima > dblValue) {
  491.                     dblMinima = dblValue;

  493.                     for (int j = 0; j < iNumVariate; ++j)
  494.                         adblMinimaVariate[j] = adblVariate[j];
  495.                 }
  496.             }
  497.         }

  499.         try {
  500.             return new org.drip.function.definition.VariateOutputPair (adblMinimaVariate, new double[]
  501.                 {dblMinima});
  502.         } catch (java.lang.Exception e) {
  503.             e.printStackTrace();
  504.         }

  506.         return null;
  507.     }

  509.     /**
  510.      * Compute the Modulus of the Gradient at the Specified Variate location
  511.      * 
  512.      * @param adblVariate The Variate Array location
  513.      * 
  514.      * @return The Modulus of the Gradient at the Specified Variate location
  515.      * 
  516.      * @throws java.lang.Exception Thrown if the Inputs are Invalid
  517.      */

  519.     public double gradientModulus (
  520.         final double[] adblVariate)
  521.         throws java.lang.Exception
  522.     {
  523.         double[] adblJacobian = jacobian (adblVariate);

  525.         if (null == adblJacobian)
  526.             throw new java.lang.Exception ("RdToR1::gradientModulus => Invalid Inputs!");

  528.         double dblGradientModulus = 0.;
  529.         int iNumVariate = adblVariate.length;

  531.         for (int i = 0; i < iNumVariate; ++i)
  532.             dblGradientModulus += adblJacobian[i] * adblJacobian[i];

  534.         return dblGradientModulus;
  535.     }

  537.     /**
  538.      * Generate the Gradient Modulus Function
  539.      * 
  540.      * @return The Gradient Modulus Function
  541.      */

  543.     public org.drip.function.definition.RdToR1 gradientModulusFunction()
  544.     {
  545.         org.drip.function.definition.RdToR1 gradientModulusRdToR1 = new org.drip.function.definition.RdToR1
  546.             (null) {
  547.             @Override public int dimension()
  548.             {
  549.                 return dimension();
  550.             }

  552.             @Override public double evaluate (
  553.                 final double[] adblVariate)
  554.                 throws java.lang.Exception
  555.             {
  556.                 return gradientModulus (adblVariate);
  557.             }

  559.             @Override public double[] jacobian (
  560.                 final double[] adblVariate)
  561.             {
  562.                 double[] adblParentJacobian = jacobian (adblVariate);

  564.                 double[][] adblParentHessian = hessian (adblVariate);

  566.                 if (null == adblParentJacobian || null == adblParentHessian) return null;

  568.                 int iDimension = adblParentJacobian.length;
  569.                 double[] adblGradientModulusJacobian = new double[iDimension];

  571.                 for (int k = 0; k < iDimension; ++k) {
  572.                     adblGradientModulusJacobian[k] = 0.;

  574.                     for (int i = 0; i < iDimension; ++i)
  575.                         adblGradientModulusJacobian[k] += adblParentJacobian[i] * adblParentHessian[i][k];

  577.                     adblGradientModulusJacobian[k] *= 2.;
  578.                 }

  580.                 return adblGradientModulusJacobian;
  581.             }
  582.         };

  584.         return gradientModulusRdToR1;
  585.     }
  586. }
Created with JaCoCo 0.7.9.201702052155