VariateIteratorPrimitive.java

  1. package org.drip.function.r1tor1solver;

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

  84. /**
  85.  * <i>VariateIteratorPrimitive</i> implements the various Primitive Variate Iterator routines.
  86.  * 
  87.  * VariateIteratorPrimitive implements the following iteration primitives:
  88.  * <br>
  89.  * <ul>
  90.  *  <li>
  91.  *      Bisection
  92.  *  </li>
  93.  *  <li>
  94.  *      False Position
  95.  *  </li>
  96.  *  <li>
  97.  *      Quadratic
  98.  *  </li>
  99.  *  <li>
  100.  *      Inverse Quadratic
  101.  *  </li>
  102.  *  <li>
  103.  *      Ridder
  104.  *  </li>
  105.  * </ul>
  106.  * <br>
  107.  * It may be readily enhanced to accommodate additional primitives.
  108.  *
  109.  *  <br><br>
  110.  *  <ul>
  111.  *      <li><b>Module </b> = <a href = "https://github.com/lakshmiDRIP/DROP/tree/master/ComputationalCore.md">Computational Core Module</a></li>
  112.  *      <li><b>Library</b> = <a href = "https://github.com/lakshmiDRIP/DROP/tree/master/NumericalAnalysisLibrary.md">Numerical Analysis Library</a></li>
  113.  *      <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>
  114.  *      <li><b>Package</b> = <a href = "https://github.com/lakshmiDRIP/DROP/tree/master/src/main/java/org/drip/function/r1tor1solver/README.md">Built-in R<sup>1</sup> To R<sup>1</sup> Solvers</a></li>
  115.  *  </ul>
  116.  *
  117.  * @author Lakshmi Krishnamurthy
  118.  */

  120. public class VariateIteratorPrimitive {

  122.     /**
  123.      * Bisection
  124.      */

  126.     public static int BISECTION = 0;

  128.     /**
  129.      * False Position
  130.      */

  132.     public static int FALSE_POSITION = 1;

  134.     /**
  135.      * Quadratic Interpolation
  136.      */

  138.     public static int QUADRATIC_INTERPOLATION = 2;

  140.     /**
  141.      * Inverse Quadratic Interpolation
  142.      */

  144.     public static int INVERSE_QUADRATIC_INTERPOLATION = 3;

  146.     /**
  147.      * Ridder's Method
  148.      */

  150.     public static int RIDDER = 4;

  152.     /**
  153.      * Iterate for the next variate using bisection
  154.      * 
  155.      * @param dblX1 Left variate
  156.      * @param dblX2 Right variate
  157.      * 
  158.      * @return The next variate
  159.      * 
  160.      * @throws java.lang.Exception Thrown if inputs are invalid
  161.      */

  163.     public static final double Bisection (
  164.         final double dblX1,
  165.         final double dblX2)
  166.         throws java.lang.Exception
  167.     {
  168.         if (!org.drip.numerical.common.NumberUtil.IsValid (dblX1) || !org.drip.numerical.common.NumberUtil.IsValid
  169.             (dblX2))
  170.             throw new java.lang.Exception ("VariateIteratorPrimitive::Bisection => Invalid inputs " + dblX2);

  172.         return 0.5 * (dblX1 + dblX2);
  173.     }

  175.     /**
  176.      * Iterate for the next variate using false position
  177.      * 
  178.      * @param dblX1 Left variate
  179.      * @param dblX2 Right variate
  180.      * @param dblY1 Left OF value
  181.      * @param dblY2 Right OF value
  182.      * 
  183.      * @return The next variate
  184.      * 
  185.      * @throws java.lang.Exception Thrown if inputs are invalid
  186.      */

  188.     public static final double FalsePosition (
  189.         final double dblX1,
  190.         final double dblX2,
  191.         final double dblY1,
  192.         final double dblY2)
  193.         throws java.lang.Exception
  194.     {
  195.         if (!org.drip.numerical.common.NumberUtil.IsValid (dblX1) || !org.drip.numerical.common.NumberUtil.IsValid
  196.             (dblX2) || !org.drip.numerical.common.NumberUtil.IsValid (dblY1) ||
  197.                 !org.drip.numerical.common.NumberUtil.IsValid (dblY2))
  198.             throw new java.lang.Exception ("VariateIteratorPrimitive::FalsePosition => Invalid inputs");

  200.         return dblX1 + ((dblX1 - dblX2) / (dblY2 - dblY1) * dblY1);
  201.     }

  203.     /**
  204.      * Iterate for the next variate using quadratic interpolation
  205.      * 
  206.      * @param dblX1 Left variate
  207.      * @param dblX2 Intermediate variate
  208.      * @param dblX3 Right variate
  209.      * @param dblY1 Left OF value
  210.      * @param dblY2 Intermediate OF value
  211.      * @param dblY3 Right OF value
  212.      * 
  213.      * @return The next variate
  214.      * 
  215.      * @throws java.lang.Exception Thrown if inputs are invalid
  216.      */

  218.     public static final double QuadraticInterpolation (
  219.         final double dblX1,
  220.         final double dblX2,
  221.         final double dblX3,
  222.         final double dblY1,
  223.         final double dblY2,
  224.         final double dblY3)
  225.         throws java.lang.Exception
  226.     {
  227.         if (!org.drip.numerical.common.NumberUtil.IsValid (dblX1) || !org.drip.numerical.common.NumberUtil.IsValid
  228.             (dblX2) || !org.drip.numerical.common.NumberUtil.IsValid (dblX3) ||
  229.                 !org.drip.numerical.common.NumberUtil.IsValid (dblY1) || !org.drip.numerical.common.NumberUtil.IsValid
  230.                     (dblY2) || !org.drip.numerical.common.NumberUtil.IsValid (dblY3))
  231.             throw new java.lang.Exception
  232.                 ("VariateIteratorPrimitive.QuadraticInterpolation => Invalid inputs!");

  234.         double dblA = dblY1 / (dblX1 - dblX2) / (dblX1 - dblX3);
  235.         dblA       += dblY2 / (dblX2 - dblX3) / (dblX2 - dblX1);
  236.         dblA       += dblY3 / (dblX3 - dblX1) / (dblX3 - dblX2);
  237.         double dblB = -1. * (dblX2 + dblX3) * dblY1 / (dblX1 - dblX2) / (dblX1 - dblX3);
  238.         dblB       -=       (dblX3 + dblX1) * dblY2 / (dblX2 - dblX3) / (dblX2 - dblX1);
  239.         dblB       -=       (dblX1 + dblX2) * dblY3 / (dblX3 - dblX1) / (dblX3 - dblX2);
  240.         double dblC = dblX2 * dblX3 * dblY1 / (dblX1 - dblX2) / (dblX1 - dblX3);
  241.         dblC       += dblX3 * dblX1 * dblY2 / (dblX2 - dblX3) / (dblX2 - dblX1);
  242.         dblC       += dblX1 * dblX2 * dblY3 / (dblX3 - dblX1) / (dblX3 - dblX2);
  243.         double dblSQRTArg = dblB * dblB - 4. * dblA * dblC;

  245.         if (0. > dblSQRTArg)
  246.             throw new java.lang.Exception
  247.                 ("VariateIteratorPrimitive.QuadraticInterpolation => No real roots!");

  249.         double dblSQRT = java.lang.Math.sqrt (dblSQRTArg);

  251.         double dblRoot1 = (-1. * dblB + dblSQRT) / 2. / dblA;
  252.         double dblRoot2 = (-1. * dblB - dblSQRT) / 2. / dblA;

  254.         if (dblX1 > dblRoot1 || dblX3 < dblRoot1) return dblRoot2;

  256.         if (dblX1 > dblRoot2 || dblX3 < dblRoot2) return dblRoot1;

  258.         return java.lang.Math.abs (dblX2 - dblRoot1) < java.lang.Math.abs (dblX2 - dblRoot2) ? dblRoot1 :
  259.             dblRoot2;
  260.     }

  262.     /**
  263.      * Iterate for the next variate using inverse quadratic interpolation
  264.      * 
  265.      * @param dblX1 Left variate
  266.      * @param dblX2 Intermediate variate
  267.      * @param dblX3 Right variate
  268.      * @param dblY1 Left OF value
  269.      * @param dblY2 Intermediate OF value
  270.      * @param dblY3 Right OF value
  271.      * 
  272.      * @return The next variate
  273.      * 
  274.      * @throws java.lang.Exception Thrown if inputs are invalid
  275.      */

  277.     public static final double InverseQuadraticInterpolation (
  278.         final double dblX1,
  279.         final double dblX2,
  280.         final double dblX3,
  281.         final double dblY1,
  282.         final double dblY2,
  283.         final double dblY3)
  284.         throws java.lang.Exception
  285.     {
  286.         if (!org.drip.numerical.common.NumberUtil.IsValid (dblX1) || !org.drip.numerical.common.NumberUtil.IsValid
  287.             (dblX2) || !org.drip.numerical.common.NumberUtil.IsValid (dblX3) ||
  288.                 !org.drip.numerical.common.NumberUtil.IsValid (dblY1) || !org.drip.numerical.common.NumberUtil.IsValid
  289.                     (dblY2) || !org.drip.numerical.common.NumberUtil.IsValid (dblY3))
  290.             throw new java.lang.Exception
  291.                 ("VariateIteratorPrimitive.InverseQuadraticInterpolation => Invalid inputs!");

  293.         double dblNextRoot = (dblY2 * dblY3 * dblX1 / (dblY1 - dblY2) / (dblY1 - dblY3));
  294.         dblNextRoot       += (dblY3 * dblY1 * dblX2 / (dblY2 - dblY3) / (dblY2 - dblY1));
  295.         dblNextRoot       += (dblY1 * dblY2 * dblX3 / (dblY3 - dblY1) / (dblY3 - dblY2));
  296.         return dblNextRoot;
  297.     }

  299.     /**
  300.      * Iterate for the next variate using Ridder's method
  301.      * 
  302.      * @param dblX1 Left variate
  303.      * @param dblX2 Intermediate variate
  304.      * @param dblX3 Right variate
  305.      * @param dblY1 Left OF value
  306.      * @param dblY2 Intermediate OF value
  307.      * @param dblY3 Right OF value
  308.      * 
  309.      * @return The next variate
  310.      * 
  311.      * @throws java.lang.Exception Thrown if inputs are invalid
  312.      */

  314.     public static final double Ridder (
  315.         final double dblX1,
  316.         final double dblX2,
  317.         final double dblX3,
  318.         final double dblY1,
  319.         final double dblY2,
  320.         final double dblY3)
  321.         throws java.lang.Exception
  322.     {
  323.         if (!org.drip.numerical.common.NumberUtil.IsValid (dblX1) || !org.drip.numerical.common.NumberUtil.IsValid
  324.             (dblX2) || !org.drip.numerical.common.NumberUtil.IsValid (dblX3) ||
  325.                 !org.drip.numerical.common.NumberUtil.IsValid (dblY1) || !org.drip.numerical.common.NumberUtil.IsValid
  326.                     (dblY2) || !org.drip.numerical.common.NumberUtil.IsValid (dblY3))
  327.             throw new java.lang.Exception ("VariateIteratorPrimitive.Ridder => Invalid inputs!");

  329.         double dblSQRTArg = dblY3 * dblY3 - dblY1 * dblY2;

  331.         if (0. > dblSQRTArg)
  332.             throw new java.lang.Exception ("VariateIteratorPrimitive.Ridder => No real roots!");

  334.         return dblX3 + (dblX3 - dblX1) * dblY3 * java.lang.Math.signum (dblY1 - dblY2) / java.lang.Math.sqrt
  335.             (dblSQRTArg);
  336.     }

  338.     /**
  339.      * Iterate for the next variate using the multi-function method
  340.      * 
  341.      * @param dblX1 Left variate
  342.      * @param dblX2 Intermediate variate
  343.      * @param dblX3 Right variate
  344.      * @param dblY1 Left OF value
  345.      * @param dblY2 Intermediate OF value
  346.      * @param dblY3 Right OF value
  347.      * @param of Objective Function
  348.      * @param dblOFTarget OF Target
  349.      * @param rfop Root Finder Output
  350.      * 
  351.      * @return The next variate
  352.      * 
  353.      * @throws java.lang.Exception Thrown if inputs are invalid
  354.      */

  356.     public static final double MultiFunction (
  357.         final double dblX1,
  358.         final double dblX2,
  359.         final double dblX3,
  360.         final double dblY1,
  361.         final double dblY2,
  362.         final double dblY3,
  363.         final org.drip.function.definition.R1ToR1 of,
  364.         final double dblOFTarget,
  365.         final org.drip.function.r1tor1solver.FixedPointFinderOutput rfop)
  366.         throws java.lang.Exception
  367.     {
  368.         if (!org.drip.numerical.common.NumberUtil.IsValid (dblX1) || !org.drip.numerical.common.NumberUtil.IsValid
  369.             (dblX2) || !org.drip.numerical.common.NumberUtil.IsValid (dblX3) ||
  370.                 !org.drip.numerical.common.NumberUtil.IsValid (dblY1) || !org.drip.numerical.common.NumberUtil.IsValid
  371.                     (dblY2) || !org.drip.numerical.common.NumberUtil.IsValid (dblY3) ||
  372.                         !org.drip.numerical.common.NumberUtil.IsValid (dblOFTarget) || null == rfop || null == of)
  373.             throw new java.lang.Exception ("VariateIteratorPrimitive.MultiFunction => Invalid inputs!");

  375.         double dblNextRoot = Bisection (dblX1, dblX2);

  377.         if (!rfop.incrOFCalcs())
  378.             throw new java.lang.Exception
  379.                 ("VariateIteratorPrimitive.MultiFunction => Cannot increment rfop!");

  381.         double dblTargetDiff = java.lang.Math.abs (of.evaluate (dblNextRoot) - dblOFTarget);

  383.         try {
  384.             double dblRootSecant = FalsePosition (dblX1, dblX2, dblY1, dblY2);

  386.             if (!rfop.incrOFCalcs())
  387.                 throw new java.lang.Exception
  388.                     ("VariateIteratorPrimitive.MultiFunction => Cannot increment rfop!");

  390.             double dblTargetDiffSecant = java.lang.Math.abs (of.evaluate (dblRootSecant) - dblOFTarget);

  392.             if (dblTargetDiffSecant < dblTargetDiff) {
  393.                 dblNextRoot = dblRootSecant;
  394.                 dblTargetDiff = dblTargetDiffSecant;
  395.             }
  396.         } catch (java.lang.Exception e) {
  397.             // e.printStackTrace();
  398.         }

  400.         try {
  401.             double dblRootQuadraticInterpolation = QuadraticInterpolation (dblX1, dblX2, dblX3, dblY1, dblY2,
  402.                 dblY3);

  404.             if (!rfop.incrOFCalcs())
  405.                 throw new java.lang.Exception
  406.                     ("VariateIteratorPrimitive.MultiFunction => Cannot increment rfop!");

  408.             double dblTargetDiffQuadraticInterpolation = java.lang.Math.abs (of.evaluate
  409.                 (dblRootQuadraticInterpolation) - dblOFTarget);

  411.             if (dblTargetDiffQuadraticInterpolation < dblTargetDiff) {
  412.                 dblNextRoot = dblRootQuadraticInterpolation;
  413.                 dblTargetDiff = dblTargetDiffQuadraticInterpolation;
  414.             }
  415.         } catch (java.lang.Exception e) {
  416.             // e.printStackTrace();
  417.         }

  419.         try {
  420.             double dblRootInverseQuadraticInterpolation = QuadraticInterpolation (dblX1, dblX2, dblX3, dblY1,
  421.                 dblY2, dblY3);

  423.             if (!rfop.incrOFCalcs())
  424.                 throw new java.lang.Exception
  425.                     ("VariateIteratorPrimitive.MultiFunction => Cannot increment rfop!");

  427.             double dblTargetDiffInverseQuadraticInterpolation = java.lang.Math.abs (of.evaluate
  428.                 (dblRootInverseQuadraticInterpolation) - dblOFTarget);

  430.             if (dblTargetDiffInverseQuadraticInterpolation < dblTargetDiff) {
  431.                 dblNextRoot = dblRootInverseQuadraticInterpolation;
  432.                 dblTargetDiff = dblTargetDiffInverseQuadraticInterpolation;
  433.             }
  434.         } catch (java.lang.Exception e) {
  435.             // e.printStackTrace();
  436.         }

  438.         try {
  439.             double dblRootRidder = Ridder (dblX1, dblX2, dblX3, dblY1, dblY2, dblY3);

  441.             if (!rfop.incrOFCalcs())
  442.                 throw new java.lang.Exception
  443.                     ("VariateIteratorPrimitive.MultiFunction => Cannot increment rfop!");

  445.             double dblTargetDiffRidder = java.lang.Math.abs (of.evaluate (dblRootRidder) - dblOFTarget);

  447.             if (dblTargetDiffRidder < dblTargetDiff) {
  448.                 dblNextRoot = dblRootRidder;
  449.                 dblTargetDiff = dblTargetDiffRidder;
  450.             }
  451.         } catch (java.lang.Exception e) {
  452.             // e.printStackTrace();
  453.         }

  455.         return dblNextRoot;
  456.     }
  457. }
Created with JaCoCo 0.7.9.201702052155