InitializationHeuristics.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>InitializationHeuristics</i> implements several heuristics used to kick off the fixed point
  86.  * bracketing/search process.
  87.  * <br><br>
  88.  * The following custom heuristics are implemented as part of the heuristics based kick-off:
  89.  * <br>
  90.  * <ul>
  91.  *  <li>
  92.  *      Custom Bracketing Control Parameters: Any of the standard bracketing control parameters can be
  93.  *          customized to kick-off the bracketing search.
  94.  *  </li>
  95.  *  <li>
  96.  *      Soft Left/Right Bracketing Hints: The left/right starting bracket edges are used as soft bracketing
  97.  *          initialization hints.
  98.  *  </li>
  99.  *  <li>
  100.  *      Soft Mid Bracketing Hint: A mid bracketing level is specified to indicate the soft bracketing
  101.  *          kick-off.
  102.  *  </li>
  103.  *  <li>
  104.  *      Hard Bracketing Floor/Ceiling: A pair of hard floor and ceiling limits are specified as a constraint
  105.  *          to the bracketing.
  106.  *  </li>
  107.  *  <li>
  108.  *      Hard Search Boundaries: A pair of hard left and right boundaries are specified to kick-off the final
  109.  *          fixed point search.
  110.  *  </li>
  111.  * </ul>
  112.  * <br><br>
  113.  * These heuristics are further interpreted and developed inside the ExecutionInitializer and the
  114.  *  ExecutionControl implementations.
  115.  *
  116.  *  <br><br>
  117.  *  <ul>
  118.  *      <li><b>Module </b> = <a href = "https://github.com/lakshmiDRIP/DROP/tree/master/ComputationalCore.md">Computational Core Module</a></li>
  119.  *      <li><b>Library</b> = <a href = "https://github.com/lakshmiDRIP/DROP/tree/master/NumericalAnalysisLibrary.md">Numerical Analysis Library</a></li>
  120.  *      <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>
  121.  *      <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>
  122.  *  </ul>
  123.  *
  124.  * @author Lakshmi Krishnamurthy
  125.  */

  127. public class InitializationHeuristics {

  129.     /**
  130.      * Start bracket initialization from the Generic Bracket Initializer
  131.      */

  133.     public static final int BRACKETING_GENERIC_BCP = 0;

  135.     /**
  136.      * Start bracket initialization from Pre-specified left/right edge hints
  137.      */

  139.     public static final int BRACKETING_EDGE_HINTS = 1;

  141.     /**
  142.      * Start bracket initialization from Pre-specified Starting Mid Bracketing Variate
  143.      */

  145.     public static final int BRACKETING_MID_HINT = 2;

  147.     /**
  148.      * Restrict the bracket initialization to within the specified Floor and Ceiling
  149.      */

  151.     public static final int BRACKETING_FLOOR_CEILING = 4;

  153.     /**
  154.      * Start search from Pre-specified Hard Search Brackets
  155.      */

  157.     public static final int SEARCH_HARD_BRACKETS = 8;

  159.     /**
  160.      * Start search from Custom Bracketing Control Parameters
  161.      */

  163.     public static final int BRACKETING_CUSTOM_BCP = 16;

  165.     private int _iDeterminant = BRACKETING_GENERIC_BCP;
  166.     private double _dblBracketFloor = java.lang.Double.NaN;
  167.     private double _dblBracketCeiling = java.lang.Double.NaN;
  168.     private double _dblSearchStartLeft = java.lang.Double.NaN;
  169.     private double _dblSearchStartRight = java.lang.Double.NaN;
  170.     private double _dblStartingBracketMid = java.lang.Double.NaN;
  171.     private double _dblStartingBracketLeft = java.lang.Double.NaN;
  172.     private double _dblStartingBracketRight = java.lang.Double.NaN;
  173.     private org.drip.function.r1tor1solver.BracketingControlParams _bcpCustom = null;

  175.     /**
  176.      * Construct an Initialization Heuristics Instance from the hard search edges
  177.      * 
  178.      * @param dblSearchStartLeft Search Start Left Edge
  179.      * @param dblSearchStartRight Search Start Right Edge
  180.      * 
  181.      * @return InitializationHeuristics instance
  182.      */

  184.     public static final InitializationHeuristics FromHardSearchEdges (
  185.         final double dblSearchStartLeft,
  186.         final double dblSearchStartRight)
  187.     {
  188.         try {
  189.             return new InitializationHeuristics (SEARCH_HARD_BRACKETS, dblSearchStartLeft,
  190.                 dblSearchStartRight, java.lang.Double.NaN, java.lang.Double.NaN, java.lang.Double.NaN,
  191.                     java.lang.Double.NaN, java.lang.Double.NaN, null);
  192.         } catch (java.lang.Exception e) {
  193.             e.printStackTrace();
  194.         }

  196.         return null;
  197.     }

  199.     /**
  200.      * Construct an Initialization Heuristics Instance from the bracketing edge soft hints
  201.      * 
  202.      * @param dblStartingBracketLeft Starting Soft Left Bracketing Edge Hint
  203.      * @param dblStartingBracketRight Starting Soft Right Bracketing Edge Hint
  204.      * 
  205.      * @return InitializationHeuristics instance
  206.      */

  208.     public static final InitializationHeuristics FromBracketingEdgeHints (
  209.         final double dblStartingBracketLeft,
  210.         final double dblStartingBracketRight)
  211.     {
  212.         try {
  213.             return new InitializationHeuristics (BRACKETING_EDGE_HINTS, java.lang.Double.NaN,
  214.                 java.lang.Double.NaN, dblStartingBracketLeft, dblStartingBracketRight, java.lang.Double.NaN,
  215.                     java.lang.Double.NaN, java.lang.Double.NaN, null);
  216.         } catch (java.lang.Exception e) {
  217.             e.printStackTrace();
  218.         }

  220.         return null;
  221.     }

  223.     /**
  224.      * Construct an Initialization Heuristics Instance from the bracketing mid hint
  225.      * 
  226.      * @param dblStartingBracketMid Starting Soft Right Bracketing Mid Hint
  227.      * 
  228.      * @return InitializationHeuristics instance
  229.      */

  231.     public static final InitializationHeuristics FromBracketingMidHint (
  232.         final double dblStartingBracketMid)
  233.     {
  234.         try {
  235.             return new InitializationHeuristics (BRACKETING_MID_HINT, java.lang.Double.NaN,
  236.                 java.lang.Double.NaN, java.lang.Double.NaN, java.lang.Double.NaN, dblStartingBracketMid,
  237.                     java.lang.Double.NaN, java.lang.Double.NaN, null);
  238.         } catch (java.lang.Exception e) {
  239.             e.printStackTrace();
  240.         }

  242.         return null;
  243.     }

  245.     /**
  246.      * Construct an Initialization Heuristics Instance from the bracketing hard floor/ceiling
  247.      * 
  248.      * @param dblBracketFloor Starting Hard Left Bracketing Floor
  249.      * @param dblBracketCeiling Starting Hard Right Bracketing Ceiling
  250.      * 
  251.      * @return InitializationHeuristics instance
  252.      */

  254.     public static final InitializationHeuristics FromBracketingFloorCeiling (
  255.         final double dblBracketFloor,
  256.         final double dblBracketCeiling)
  257.     {
  258.         try {
  259.             return new InitializationHeuristics (BRACKETING_FLOOR_CEILING, java.lang.Double.NaN,
  260.                 java.lang.Double.NaN, java.lang.Double.NaN, java.lang.Double.NaN, java.lang.Double.NaN,
  261.                     dblBracketFloor, dblBracketCeiling, null);
  262.         } catch (java.lang.Exception e) {
  263.             e.printStackTrace();
  264.         }

  266.         return null;
  267.     }

  269.     /**
  270.      * Construct an Initialization Heuristics Instance from Custom Bracketing Control Parameters
  271.      * 
  272.      * @param bcpCustom Custom Bracketing Control Parameters
  273.      * 
  274.      * @return InitializationHeuristics instance
  275.      */

  277.     public static final InitializationHeuristics FromBracketingCustomBCP (
  278.         final org.drip.function.r1tor1solver.BracketingControlParams bcpCustom)
  279.     {
  280.         try {
  281.             return new InitializationHeuristics (BRACKETING_CUSTOM_BCP, java.lang.Double.NaN,
  282.                 java.lang.Double.NaN, java.lang.Double.NaN, java.lang.Double.NaN, java.lang.Double.NaN,
  283.                     java.lang.Double.NaN, java.lang.Double.NaN, bcpCustom);
  284.         } catch (java.lang.Exception e) {
  285.             e.printStackTrace();
  286.         }

  288.         return null;
  289.     }

  291.     /**
  292.      * Construct an Initialization Heuristics Instance from the set of Heuristics Parameters
  293.      * 
  294.      * @param iDeterminant Initialization Heuristics Instance Type
  295.      * @param dblSearchStartLeft Hard Search Start Left Edge
  296.      * @param dblSearchStartRight Hard Search Start Right Edge
  297.      * @param dblStartingBracketLeft Starting Soft Left Bracketing Edge Hint
  298.      * @param dblStartingBracketRight Starting Soft Right Bracketing Edge Hint
  299.      * @param dblStartingBracketMid Starting Soft Right Bracketing Mid Hint
  300.      * @param dblBracketFloor Starting Hard Left Bracketing Floor
  301.      * @param dblBracketCeiling Starting Hard Right Bracketing Ceiling
  302.      * @param bcpCustom Custom Bracketing Control Parameters
  303.      * 
  304.      * @throws java.lang.Exception Thrown if the Input Determinant/parameters are unknown/invalid
  305.      */

  307.     public InitializationHeuristics (
  308.         final int iDeterminant,
  309.         final double dblSearchStartLeft,
  310.         final double dblSearchStartRight,
  311.         final double dblStartingBracketLeft,
  312.         final double dblStartingBracketRight,
  313.         final double dblStartingBracketMid,
  314.         final double dblBracketFloor,
  315.         final double dblBracketCeiling,
  316.         final org.drip.function.r1tor1solver.BracketingControlParams bcpCustom)
  317.         throws java.lang.Exception
  318.     {
  319.         if (BRACKETING_EDGE_HINTS == (_iDeterminant = iDeterminant)) {
  320.             if (!org.drip.numerical.common.NumberUtil.IsValid (_dblStartingBracketLeft = dblStartingBracketLeft)
  321.                 || !org.drip.numerical.common.NumberUtil.IsValid (_dblStartingBracketRight =
  322.                     dblStartingBracketRight))
  323.                 throw new java.lang.Exception
  324.                     ("InitializationHeuristics constructor: Invalid BRACKETING_EDGE_HINTS params!");
  325.         } else if (BRACKETING_MID_HINT == _iDeterminant) {
  326.             if (!org.drip.numerical.common.NumberUtil.IsValid (_dblStartingBracketMid = dblStartingBracketMid))
  327.                 throw new java.lang.Exception
  328.                     ("InitializationHeuristics constructor: Invalid BRACKETING_MID_HINT params!");
  329.         } else if (BRACKETING_FLOOR_CEILING == _iDeterminant) {
  330.             if (!org.drip.numerical.common.NumberUtil.IsValid (_dblBracketFloor = dblBracketFloor) ||
  331.                 !org.drip.numerical.common.NumberUtil.IsValid (_dblBracketCeiling = dblBracketCeiling))
  332.                 throw new java.lang.Exception
  333.                     ("InitializationHeuristics constructor: Invalid BRACKETING_FLOOR_CEILING params!");
  334.         } else if (SEARCH_HARD_BRACKETS == _iDeterminant) {
  335.             if (!org.drip.numerical.common.NumberUtil.IsValid (_dblSearchStartLeft = dblSearchStartLeft) ||
  336.                 !org.drip.numerical.common.NumberUtil.IsValid (_dblSearchStartRight = dblSearchStartRight))
  337.                 throw new java.lang.Exception
  338.                     ("InitializationHeuristics constructor: Invalid SEARCH_HARD_BRACKETS params!");
  339.         } else if (BRACKETING_CUSTOM_BCP == _iDeterminant) {
  340.             if (null == (_bcpCustom = bcpCustom))
  341.                 throw new java.lang.Exception
  342.                     ("InitializationHeuristics constructor: Invalid BRACKETING_CUSTOM_BCP params!");
  343.         } else if (BRACKETING_GENERIC_BCP != _iDeterminant)
  344.             throw new java.lang.Exception
  345.                 ("InitializationHeuristics constructor: Invalid BRACKETING_GENERIC_BCP params!");
  346.     }

  348.     /**
  349.      * Retrieve the Determinant
  350.      * 
  351.      * @return The Determinant
  352.      */

  354.     public int getDeterminant()
  355.     {
  356.         return _iDeterminant;
  357.     }

  359.     /**
  360.      * Retrieve the Hard Left Search Start
  361.      * 
  362.      * @return The Hard Left Search Start
  363.      */

  365.     public double getSearchStartLeft()
  366.     {
  367.         return _dblSearchStartLeft;
  368.     }

  370.     /**
  371.      * Retrieve the Hard Right Search Start
  372.      * 
  373.      * @return The Hard Right Search Start
  374.      */

  376.     public double getSearchStartRight()
  377.     {
  378.         return _dblSearchStartRight;
  379.     }

  381.     /**
  382.      * Retrieve the Soft Bracket Start Mid
  383.      * 
  384.      * @return The Soft Bracket Start Mid
  385.      */

  387.     public double getStartingBracketMid()
  388.     {
  389.         return _dblStartingBracketMid;
  390.     }

  392.     /**
  393.      * Retrieve the Soft Bracket Start Left
  394.      * 
  395.      * @return The Soft Bracket Start Left
  396.      */

  398.     public double getStartingBracketLeft()
  399.     {
  400.         return _dblStartingBracketLeft;
  401.     }

  403.     /**
  404.      * Retrieve the Hard Bracket Floor
  405.      * 
  406.      * @return The Hard Bracket Floor
  407.      */

  409.     public double getBracketFloor()
  410.     {
  411.         return _dblBracketFloor;
  412.     }

  414.     /**
  415.      * Retrieve the Soft Bracket Start Right
  416.      * 
  417.      * @return The Soft Bracket Start Right
  418.      */

  420.     public double getStartingBracketRight()
  421.     {
  422.         return _dblStartingBracketRight;
  423.     }

  425.     /**
  426.      * Retrieve the Hard Bracket Ceiling
  427.      * 
  428.      * @return The Hard Bracket Ceiling
  429.      */

  431.     public double getBracketCeiling()
  432.     {
  433.         return _dblBracketCeiling;
  434.     }

  436.     /**
  437.      * Retrieve the Custom BCP
  438.      * 
  439.      * @return The Custom BCP
  440.      */

  442.     public org.drip.function.r1tor1solver.BracketingControlParams getCustomBCP()
  443.     {
  444.         return _bcpCustom;
  445.     }
  446. }
Created with JaCoCo 0.7.9.201702052155