FixedRdFinder.java

  1. package org.drip.function.rdtor1solver;

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

  80. /**
  81.  * <i>FixedRdFinder</i> exports the Methods needed for the locating a Fixed R<sup>d</sup> Point.
  82.  *
  83.  *  <br><br>
  84.  *  <ul>
  85.  *      <li><b>Module </b> = <a href = "https://github.com/lakshmiDRIP/DROP/tree/master/NumericalCore.md">Numerical Core Module</a></li>
  86.  *      <li><b>Library</b> = <a href = "https://github.com/lakshmiDRIP/DROP/tree/master/NumericalOptimizerLibrary.md">Numerical Optimizer</a></li>
  87.  *      <li><b>Project</b> = <a href = "https://github.com/lakshmiDRIP/DROP/tree/master/src/main/java/org/drip/feed/README.md">Function</a></li>
  88.  *      <li><b>Package</b> = <a href = "https://github.com/lakshmiDRIP/DROP/tree/master/src/main/java/org/drip/feed/rdtor1solver/README.md">R<sup>d</sup> To R<sup>1</sup> Solver</a></li>
  89.  *  </ul>
  90.  *
  91.  * @author Lakshmi Krishnamurthy
  92.  */

  94. public abstract class FixedRdFinder
  95. {

  97.     /**
  98.      * Flag Indicating whether the Verifier Increment Metrics are to be Traced
  99.      */

  101.     public static boolean s_verifierIncrementBlog = false;

  103.     private org.drip.function.definition.RdToR1 _objectiveFunction = null;
  104.     private org.drip.function.rdtor1solver.ConvergenceControl _convergenceControl = null;
  105.     private org.drip.function.rdtor1descent.LineStepEvolutionControl _lineStepEvolutionControl = null;

  107.     protected FixedRdFinder (
  108.         final org.drip.function.definition.RdToR1 objectiveFunction,
  109.         final org.drip.function.rdtor1descent.LineStepEvolutionControl lineStepEvolutionControl,
  110.         final org.drip.function.rdtor1solver.ConvergenceControl convergenceControl)
  111.         throws java.lang.Exception
  112.     {
  113.         if (null == (_objectiveFunction = objectiveFunction) ||
  114.             null == (_convergenceControl = convergenceControl))
  115.         {
  116.             throw new java.lang.Exception ("FixedRdFinder Constructor => Invalid Inputs");
  117.         }

  119.         _lineStepEvolutionControl = lineStepEvolutionControl;
  120.     }

  122.     /**
  123.      * Retrieve the Objective Function
  124.      * 
  125.      * @return The Objective Function
  126.      */

  128.     public org.drip.function.definition.RdToR1 objectiveFunction()
  129.     {
  130.         return _objectiveFunction;
  131.     }

  133.     /**
  134.      * Retrieve the Line Step Evolution Control
  135.      * 
  136.      * @return The Line Step Evolution Control
  137.      */

  139.     public org.drip.function.rdtor1descent.LineStepEvolutionControl lineStepEvolutionControl()
  140.     {
  141.         return _lineStepEvolutionControl;
  142.     }

  144.     /**
  145.      * Retrieve the Convergence Control Parameters
  146.      * 
  147.      * @return The Convergence Control Parameters
  148.      */

  150.     public org.drip.function.rdtor1solver.ConvergenceControl convergenceControl()
  151.     {
  152.         return _convergenceControl;
  153.     }

  155.     /**
  156.      * Solve for the Optimal Variate-Inequality Constraint Multiplier Tuple Using the Variate/Inequality
  157.      *  Constraint Tuple Convergence
  158.      *  
  159.      * @param startingVariateConstraint The Starting Variate/Inequality Constraint Tuple
  160.      * 
  161.      * @return The Optimal Variate-Inequality Constraint Multiplier Tuple
  162.      */

  164.     public org.drip.function.rdtor1solver.VariateInequalityConstraintMultiplier convergeVariate (
  165.         final org.drip.function.rdtor1solver.VariateInequalityConstraintMultiplier startingVariateConstraint)
  166.     {
  167.         if (null == startingVariateConstraint)
  168.         {
  169.             return null;
  170.         }

  172.         org.drip.function.definition.RdToR1 objectiveFunction = objectiveFunction();

  174.         boolean fixedPointFound = false;
  175.         org.drip.function.rdtor1solver.VariateInequalityConstraintMultiplier currentVariateConstraint =
  176.             startingVariateConstraint;
  177.         org.drip.function.rdtor1solver.VariateInequalityConstraintMultiplier previousVariateConstraint =
  178.             startingVariateConstraint;

  180.         int comparisonVariateCount = objectiveFunction instanceof
  181.             org.drip.function.rdtor1.LagrangianMultivariate ? (
  182.                 (org.drip.function.rdtor1.LagrangianMultivariate) objectiveFunction).objectiveFunctionDimension() :
  183.                 objectiveFunction.dimension();

  185.         double absoluteToleranceFallback = _convergenceControl.absoluteTolerance();

  187.         double relativeTolerance = _convergenceControl.relativeTolerance();

  189.         while (!fixedPointFound)
  190.         {
  191.             org.drip.function.rdtor1solver.VariateInequalityConstraintMultiplier variateConstraint =
  192.                 increment (
  193.                     currentVariateConstraint
  194.                 );

  196.             if (null == variateConstraint ||
  197.                 null == (
  198.                     currentVariateConstraint = next (
  199.                         previousVariateConstraint,
  200.                         variateConstraint,
  201.                         incrementFraction (
  202.                             currentVariateConstraint,
  203.                             variateConstraint
  204.                         )
  205.                     )
  206.                 )
  207.             )
  208.             {
  209.                 return null;
  210.             }

  212.             try
  213.             {
  214.                 fixedPointFound =
  215.                     org.drip.function.rdtor1solver.VariateInequalityConstraintMultiplier.Compare (
  216.                         currentVariateConstraint,
  217.                         previousVariateConstraint,
  218.                         relativeTolerance,
  219.                         absoluteToleranceFallback,
  220.                         comparisonVariateCount
  221.                     );
  222.             }
  223.             catch (java.lang.Exception e)
  224.             {
  225.                 e.printStackTrace();

  227.                 return null;
  228.             }

  230.             previousVariateConstraint = currentVariateConstraint;
  231.         }

  233.         return currentVariateConstraint;
  234.     }

  236.     /**
  237.      * Solve for the Optimal Variate-Inequality Constraint Multiplier Tuple Using the Objective Function
  238.      *  Convergence
  239.      *  
  240.      * @param startingVariateConstraint The Starting Variate/Inequality Constraint Tuple Set
  241.      * 
  242.      * @return The Optimal Variate-Inequality Constraint Multiplier Tuple
  243.      */

  245.     public org.drip.function.rdtor1solver.VariateInequalityConstraintMultiplier convergeObjectiveFunction (
  246.         final org.drip.function.rdtor1solver.VariateInequalityConstraintMultiplier startingVariateConstraint)
  247.     {
  248.         if (null == startingVariateConstraint)
  249.         {
  250.             return null;
  251.         }

  253.         boolean fixedPointFound = false;
  254.         double objectiveFunctionValuePrevious = java.lang.Double.NaN;
  255.         org.drip.function.rdtor1solver.VariateInequalityConstraintMultiplier variateConstraint =
  256.             startingVariateConstraint;

  258.         try
  259.         {
  260.             objectiveFunctionValuePrevious = _objectiveFunction.evaluate (
  261.                 variateConstraint.variateArray()
  262.             );
  263.         }
  264.         catch (java.lang.Exception e)
  265.         {
  266.             e.printStackTrace();

  268.             return null;
  269.         }

  271.         double convergenceControlAbsoluteTolerance = _convergenceControl.absoluteTolerance();

  273.         double objectiveFunctionAbsoluteTolerance = java.lang.Math.abs (
  274.             objectiveFunctionValuePrevious * _convergenceControl.relativeTolerance()
  275.         );

  277.         double dblAbsoluteTolerance = convergenceControlAbsoluteTolerance <
  278.             objectiveFunctionAbsoluteTolerance ?
  279.             convergenceControlAbsoluteTolerance : objectiveFunctionAbsoluteTolerance;

  281.         while (!fixedPointFound)
  282.         {
  283.             org.drip.function.rdtor1solver.VariateInequalityConstraintMultiplier incrementalVariateConstraint
  284.                 = increment (
  285.                     variateConstraint
  286.                 );

  288.             if (null == incrementalVariateConstraint ||
  289.                 null == (
  290.                     variateConstraint = next (
  291.                         variateConstraint,
  292.                         incrementalVariateConstraint,
  293.                         incrementFraction (
  294.                             variateConstraint,
  295.                             incrementalVariateConstraint
  296.                         )
  297.                     )
  298.                 )
  299.             )
  300.             {
  301.                 return null;
  302.             }

  304.             try
  305.             {
  306.                 double objectiveFunctionValue = _objectiveFunction.evaluate (
  307.                     variateConstraint.variateArray()
  308.                 );

  310.                 if (java.lang.Math.abs (
  311.                         objectiveFunctionValuePrevious - objectiveFunctionValue
  312.                     ) < dblAbsoluteTolerance
  313.                 )
  314.                 {
  315.                     fixedPointFound = true;
  316.                 }

  318.                 objectiveFunctionValuePrevious = objectiveFunctionValue;
  319.             }
  320.             catch (java.lang.Exception e)
  321.             {
  322.                 e.printStackTrace();

  324.                 return null;
  325.             }
  326.         }

  328.         return variateConstraint;
  329.     }

  331.     /**
  332.      * Find the Optimal Variate-Inequality Constraint Multiplier Tuple using the Iteration Parameters
  333.      *  provided by the Convergence Control Instance
  334.      *  
  335.      * @param startingVariateConstraint The Starting Variate-Inequality Constraint Multiplier Tuple
  336.      * 
  337.      * @return The Optimal Variate-Inequality Constraint Multiplier Tuple
  338.      */

  340.     public org.drip.function.rdtor1solver.VariateInequalityConstraintMultiplier find (
  341.         final org.drip.function.rdtor1solver.VariateInequalityConstraintMultiplier startingVariateConstraint)
  342.     {
  343.         int convergenceType = _convergenceControl.convergenceType();

  345.         if (org.drip.function.rdtor1solver.InteriorPointBarrierControl.OBJECTIVE_FUNCTION_SEQUENCE_CONVERGENCE
  346.             == convergenceType)
  347.         {
  348.             return convergeObjectiveFunction (startingVariateConstraint);
  349.         }

  351.         if (org.drip.function.rdtor1solver.InteriorPointBarrierControl.VARIATE_CONSTRAINT_SEQUENCE_CONVERGENCE
  352.             == convergenceType)
  353.         {
  354.             return convergeVariate (startingVariateConstraint);
  355.         }

  357.         return null;
  358.     }

  360.     /**
  361.      * Retrieve the Incremental Step Length Fraction
  362.      * 
  363.      * @param variateConstraint The VariateInequalityConstraintMultiplier Base Instance
  364.      * @param variateConstraintIncrement The Full VariateInequalityConstraintMultiplier Instance Increment
  365.      * 
  366.      * @return The VariateInequalityConstraintMultiplier Incremental Step Length Fraction
  367.      */

  369.     public double incrementFraction (
  370.         final org.drip.function.rdtor1solver.VariateInequalityConstraintMultiplier variateConstraint,
  371.         final org.drip.function.rdtor1solver.VariateInequalityConstraintMultiplier
  372.             variateConstraintIncrement)
  373.     {
  374.         if (null == _lineStepEvolutionControl ||
  375.             null == variateConstraint || variateConstraint.incremental() ||
  376.             null == variateConstraintIncrement || !variateConstraintIncrement.incremental())
  377.         {
  378.             return 1.;
  379.         }

  381.         org.drip.function.rdtor1descent.LineEvolutionVerifier lineEvolutionVerifier =
  382.             _lineStepEvolutionControl.lineEvolutionVerifier();

  384.         org.drip.function.definition.UnitVector variateIncrementDirectionVector =
  385.             variateConstraintIncrement.variateIncrementVector().direction();

  387.         int reductionStepCount = _lineStepEvolutionControl.reductionStepCount();

  389.         double reductionFactor = _lineStepEvolutionControl.reductionFactor();

  391.         double[] variateArray = variateConstraint.variateArray();

  393.         double stepLength = 1.;

  395.         while (0 <= --reductionStepCount)
  396.         {
  397.             org.drip.function.rdtor1descent.LineEvolutionVerifierMetrics lineEvolutionVerifierMetrics =
  398.                 lineEvolutionVerifier.metrics (
  399.                     variateIncrementDirectionVector,
  400.                     variateArray,
  401.                     _objectiveFunction,
  402.                     stepLength
  403.                 );

  405.             if (null == lineEvolutionVerifierMetrics)
  406.             {
  407.                 return 1.;
  408.             }

  410.             if (s_verifierIncrementBlog)
  411.             {
  412.                 System.out.println (lineEvolutionVerifierMetrics);
  413.             }

  415.             if (lineEvolutionVerifierMetrics.verify())
  416.             {
  417.                 return stepLength;
  418.             }

  420.             stepLength *= reductionFactor;
  421.         }

  423.         return 1.;
  424.     }

  426.     /**
  427.      * Produce the Incremental Variate-Constraint Multiplier
  428.      * 
  429.      * @param currentVariateConstraint The Current Variate-Constraint Multiplier Tuple
  430.      * 
  431.      * @return The Incremental Variate-Constraint Multiplier
  432.      */

  434.     abstract public org.drip.function.rdtor1solver.VariateInequalityConstraintMultiplier increment (
  435.         final org.drip.function.rdtor1solver.VariateInequalityConstraintMultiplier currentVariateConstraint);

  437.     /**
  438.      * Iterate Over to the Next Variate-Constraint Multiplier Tuple
  439.      * 
  440.      * @param currentVariateConstraint The Current Variate-Constraint Multiplier Tuple
  441.      * @param incrementalVariateConstraint The Incremental Variate-Constraint Multiplier Tuple
  442.      * @param incrementFraction The Incremental Fraction to be applied
  443.      * 
  444.      * @return The Next Variate-Constraint Multiplier Set
  445.      */

  447.     abstract public org.drip.function.rdtor1solver.VariateInequalityConstraintMultiplier next (
  448.         final org.drip.function.rdtor1solver.VariateInequalityConstraintMultiplier currentVariateConstraint,
  449.         final org.drip.function.rdtor1solver.VariateInequalityConstraintMultiplier incrementalVariateConstraint,
  450.         final double incrementFraction);
  451. }
Created with JaCoCo 0.7.9.201702052155