GaussContiguousEqualityLemma.java

  1. package org.drip.specialfunction.property;

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

  77. /**
  78.  * <i>GaussContiguousEqualityLemma</i> verifies the Hyper-geometric Gauss Contiguous Equality Lemma
  79.  * Properties. The References are:
  80.  * 
  81.  * <br><br>
  82.  *  <ul>
  83.  *      <li>
  84.  *          Gessel, I., and D. Stanton (1982): Strange Evaluations of Hyper-geometric Series <i>SIAM Journal
  85.  *              on Mathematical Analysis</i> <b>13 (2)</b> 295-308
  86.  *      </li>
  87.  *      <li>
  88.  *          Koepf, W (1995): Algorithms for m-fold Hyper-geometric Summation <i>Journal of Symbolic
  89.  *              Computation</i> <b>20 (4)</b> 399-417
  90.  *      </li>
  91.  *      <li>
  92.  *          Lavoie, J. L., F. Grondin, and A. K. Rathie (1996): Generalization of Whipple’s Theorem on the
  93.  *              Sum of a (_2^3)F(a,b;c;z) <i>Journal of Computational and Applied Mathematics</i> <b>72</b>
  94.  *              293-300
  95.  *      </li>
  96.  *      <li>
  97.  *          National Institute of Standards and Technology (2019): Hyper-geometric Function
  98.  *              https://dlmf.nist.gov/15
  99.  *      </li>
  100.  *      <li>
  101.  *          Wikipedia (2019): Hyper-geometric Function https://en.wikipedia.org/wiki/Hypergeometric_function
  102.  *      </li>
  103.  *  </ul>
  104.  *
  105.  *  <br><br>
  106.  *  <ul>
  107.  *      <li><b>Module </b> = <a href = "https://github.com/lakshmiDRIP/DROP/tree/master/ComputationalCore.md">Computational Core Module</a></li>
  108.  *      <li><b>Library</b> = <a href = "https://github.com/lakshmiDRIP/DROP/tree/master/FunctionAnalysisLibrary.md">Function Analysis Library</a></li>
  109.  *      <li><b>Project</b> = <a href = "https://github.com/lakshmiDRIP/DROP/tree/master/src/main/java/org/drip/specialfunction/README.md">Special Function Implementation Analysis</a></li>
  110.  *      <li><b>Package</b> = <a href = "https://github.com/lakshmiDRIP/DROP/tree/master/src/main/java/org/drip/specialfunction/property/README.md">Special Function Property Lemma Verifiers</a></li>
  111.  *  </ul>
  112.  *
  113.  * @author Lakshmi Krishnamurthy
  114.  */

  116. public class GaussContiguousEqualityLemma
  117. {

  119.     /**
  120.      * Construct the Hyper-geometric Gauss Contiguous Identity #2 Verifier
  121.      * 
  122.      * @param a A
  123.      * @param b B
  124.      * @param c C
  125.      * 
  126.      * @return The Hyper-geometric Gauss Contiguous Identity #2 Verifier
  127.      */

  129.     public static final org.drip.function.definition.R1ToR1Property RelationIdentity2 (
  130.         final double a,
  131.         final double b,
  132.         final double c)
  133.     {
  134.         org.drip.function.definition.R2ToR1 logBetaEstimator =
  135.             org.drip.specialfunction.beta.LogGammaEstimator.Weierstrass (1000);

  137.         if (null == logBetaEstimator)
  138.         {
  139.             return null;
  140.         }

  142.         try
  143.         {
  144.             final org.drip.specialfunction.hypergeometric.EulerQuadratureEstimator hypergeometricEstimator =
  145.                 new org.drip.specialfunction.hypergeometric.EulerQuadratureEstimator (
  146.                     new org.drip.specialfunction.definition.HypergeometricParameters (
  147.                         a,
  148.                         b,
  149.                         c
  150.                     ),
  151.                     logBetaEstimator,
  152.                     10000
  153.                 );

  155.             final org.drip.specialfunction.definition.RegularHypergeometricEstimator
  156.                 aPlusRegularHypergeometricEstimator = new
  157.                     org.drip.specialfunction.hypergeometric.GaussContiguousRelations
  158.                         (hypergeometricEstimator).aPlus();

  160.             return new org.drip.function.definition.R1ToR1Property (
  161.                 org.drip.function.definition.R1ToR1Property.EQ,
  162.                 new org.drip.function.definition.R1ToR1 (null)
  163.                 {
  164.                     @Override public double evaluate (
  165.                         final double z)
  166.                         throws java.lang.Exception
  167.                     {
  168.                         return z * hypergeometricEstimator.derivative (
  169.                             z,
  170.                             1
  171.                         );
  172.                     }
  173.                 },
  174.                 new org.drip.function.definition.R1ToR1 (null)
  175.                 {
  176.                     @Override public double evaluate (
  177.                         final double z)
  178.                         throws java.lang.Exception
  179.                     {
  180.                         return a * (
  181.                             aPlusRegularHypergeometricEstimator.regularHypergeometric (z) -
  182.                             hypergeometricEstimator.regularHypergeometric (z)
  183.                         );
  184.                     }
  185.                 },
  186.                 org.drip.function.definition.R1ToR1Property.MISMATCH_TOLERANCE
  187.             );
  188.         }
  189.         catch (java.lang.Exception e)
  190.         {
  191.             e.printStackTrace();
  192.         }

  194.         return null;
  195.     }

  197.     /**
  198.      * Construct the Hyper-geometric Gauss Contiguous Identity #3 Verifier
  199.      * 
  200.      * @param a A
  201.      * @param b B
  202.      * @param c C
  203.      * 
  204.      * @return The Hyper-geometric Gauss Contiguous Identity #3 Verifier
  205.      */

  207.     public static final org.drip.function.definition.R1ToR1Property RelationIdentity3 (
  208.         final double a,
  209.         final double b,
  210.         final double c)
  211.     {
  212.         org.drip.function.definition.R2ToR1 logBetaEstimator =
  213.             org.drip.specialfunction.beta.LogGammaEstimator.Weierstrass (1000);

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

  220.         try
  221.         {
  222.             final org.drip.specialfunction.hypergeometric.EulerQuadratureEstimator hypergeometricEstimator =
  223.                 new org.drip.specialfunction.hypergeometric.EulerQuadratureEstimator (
  224.                     new org.drip.specialfunction.definition.HypergeometricParameters (
  225.                         a,
  226.                         b,
  227.                         c
  228.                     ),
  229.                     logBetaEstimator,
  230.                     10000
  231.                 );

  233.             final org.drip.specialfunction.definition.RegularHypergeometricEstimator
  234.                 bPlusHypergeometricEstimator = new
  235.                     org.drip.specialfunction.hypergeometric.GaussContiguousRelations
  236.                         (hypergeometricEstimator).bPlus();

  238.             return new org.drip.function.definition.R1ToR1Property (
  239.                 org.drip.function.definition.R1ToR1Property.EQ,
  240.                 new org.drip.function.definition.R1ToR1 (null)
  241.                 {
  242.                     @Override public double evaluate (
  243.                         final double z)
  244.                         throws java.lang.Exception
  245.                     {
  246.                         return z * hypergeometricEstimator.derivative (
  247.                             z,
  248.                             1
  249.                         );
  250.                     }
  251.                 },
  252.                 new org.drip.function.definition.R1ToR1 (null)
  253.                 {
  254.                     @Override public double evaluate (
  255.                         final double z)
  256.                         throws java.lang.Exception
  257.                     {
  258.                         return b * (
  259.                             bPlusHypergeometricEstimator.regularHypergeometric (z) -
  260.                             hypergeometricEstimator.regularHypergeometric (z)
  261.                         );
  262.                     }
  263.                 },
  264.                 org.drip.function.definition.R1ToR1Property.MISMATCH_TOLERANCE
  265.             );
  266.         }
  267.         catch (java.lang.Exception e)
  268.         {
  269.             e.printStackTrace();
  270.         }

  272.         return null;
  273.     }

  275.     /**
  276.      * Construct the Hyper-geometric Gauss Contiguous Identity #4 Verifier
  277.      * 
  278.      * @param a A
  279.      * @param b B
  280.      * @param c C
  281.      * 
  282.      * @return The Hyper-geometric Gauss Contiguous Identity #4 Verifier
  283.      */

  285.     public static final org.drip.function.definition.R1ToR1Property RelationIdentity4 (
  286.         final double a,
  287.         final double b,
  288.         final double c)
  289.     {
  290.         org.drip.function.definition.R2ToR1 logBetaEstimator =
  291.             org.drip.specialfunction.beta.LogGammaEstimator.Weierstrass (10000);

  293.         if (null == logBetaEstimator)
  294.         {
  295.             return null;
  296.         }

  298.         try
  299.         {
  300.             final org.drip.specialfunction.hypergeometric.EulerQuadratureEstimator hypergeometricEstimator =
  301.                 new org.drip.specialfunction.hypergeometric.EulerQuadratureEstimator (
  302.                     new org.drip.specialfunction.definition.HypergeometricParameters (
  303.                         a,
  304.                         b,
  305.                         c
  306.                     ),
  307.                     logBetaEstimator,
  308.                     100000
  309.                 );

  311.             final org.drip.specialfunction.definition.RegularHypergeometricEstimator
  312.                 cMinusHypergeometricEstimator = new
  313.                     org.drip.specialfunction.hypergeometric.GaussContiguousRelations
  314.                         (hypergeometricEstimator).cMinus();

  316.             return new org.drip.function.definition.R1ToR1Property (
  317.                 org.drip.function.definition.R1ToR1Property.EQ,
  318.                 new org.drip.function.definition.R1ToR1 (null)
  319.                 {
  320.                     @Override public double evaluate (
  321.                         final double z)
  322.                         throws java.lang.Exception
  323.                     {
  324.                         return z * hypergeometricEstimator.derivative (
  325.                             z,
  326.                             1
  327.                         );
  328.                     }
  329.                 },
  330.                 new org.drip.function.definition.R1ToR1 (null)
  331.                 {
  332.                     @Override public double evaluate (
  333.                         final double z)
  334.                         throws java.lang.Exception
  335.                     {
  336.                         return (c - 1.) * (
  337.                             cMinusHypergeometricEstimator.regularHypergeometric (z) -
  338.                             hypergeometricEstimator.regularHypergeometric (z)
  339.                         );
  340.                     }
  341.                 },
  342.                 org.drip.function.definition.R1ToR1Property.MISMATCH_TOLERANCE
  343.             );
  344.         }
  345.         catch (java.lang.Exception e)
  346.         {
  347.             e.printStackTrace();
  348.         }

  350.         return null;
  351.     }

  353.     /**
  354.      * Construct the Hyper-geometric Gauss Contiguous Identity #5 Verifier
  355.      * 
  356.      * @param a A
  357.      * @param b B
  358.      * @param c C
  359.      * 
  360.      * @return The Hyper-geometric Gauss Contiguous Identity #5 Verifier
  361.      */

  363.     public static final org.drip.function.definition.R1ToR1Property RelationIdentity5 (
  364.         final double a,
  365.         final double b,
  366.         final double c)
  367.     {
  368.         org.drip.function.definition.R2ToR1 logBetaEstimator =
  369.             org.drip.specialfunction.beta.LogGammaEstimator.Weierstrass (10000);

  371.         if (null == logBetaEstimator)
  372.         {
  373.             return null;
  374.         }

  376.         try
  377.         {
  378.             final org.drip.specialfunction.hypergeometric.EulerQuadratureEstimator hypergeometricEstimator =
  379.                 new org.drip.specialfunction.hypergeometric.EulerQuadratureEstimator (
  380.                     new org.drip.specialfunction.definition.HypergeometricParameters (
  381.                         a,
  382.                         b,
  383.                         c
  384.                     ),
  385.                     logBetaEstimator,
  386.                     100000
  387.                 );

  389.             final org.drip.specialfunction.definition.RegularHypergeometricEstimator
  390.                 aMinusHypergeometricEstimator = new
  391.                     org.drip.specialfunction.hypergeometric.GaussContiguousRelations
  392.                         (hypergeometricEstimator).aMinus();

  394.             return new org.drip.function.definition.R1ToR1Property (
  395.                 org.drip.function.definition.R1ToR1Property.EQ,
  396.                 new org.drip.function.definition.R1ToR1 (null)
  397.                 {
  398.                     @Override public double evaluate (
  399.                         final double z)
  400.                         throws java.lang.Exception
  401.                     {
  402.                         return z * hypergeometricEstimator.derivative (
  403.                             z,
  404.                             1
  405.                         );
  406.                     }
  407.                 },
  408.                 new org.drip.function.definition.R1ToR1 (null)
  409.                 {
  410.                     @Override public double evaluate (
  411.                         final double z)
  412.                         throws java.lang.Exception
  413.                     {
  414.                         return (
  415.                             (c - a) * aMinusHypergeometricEstimator.regularHypergeometric (z) +
  416.                             (a - c + b * z) * hypergeometricEstimator.regularHypergeometric (z)
  417.                         ) / (1. - z);
  418.                     }
  419.                 },
  420.                 org.drip.function.definition.R1ToR1Property.MISMATCH_TOLERANCE
  421.             );
  422.         }
  423.         catch (java.lang.Exception e)
  424.         {
  425.             e.printStackTrace();
  426.         }

  428.         return null;
  429.     }

  431.     /**
  432.      * Construct the Hyper-geometric Gauss Contiguous Identity #6 Verifier
  433.      * 
  434.      * @param a A
  435.      * @param b B
  436.      * @param c C
  437.      * 
  438.      * @return The Hyper-geometric Gauss Contiguous Identity #6 Verifier
  439.      */

  441.     public static final org.drip.function.definition.R1ToR1Property RelationIdentity6 (
  442.         final double a,
  443.         final double b,
  444.         final double c)
  445.     {
  446.         org.drip.function.definition.R2ToR1 logBetaEstimator =
  447.             org.drip.specialfunction.beta.LogGammaEstimator.Weierstrass (10000);

  449.         if (null == logBetaEstimator)
  450.         {
  451.             return null;
  452.         }

  454.         try
  455.         {
  456.             final org.drip.specialfunction.hypergeometric.EulerQuadratureEstimator hypergeometricEstimator =
  457.                 new org.drip.specialfunction.hypergeometric.EulerQuadratureEstimator (
  458.                     new org.drip.specialfunction.definition.HypergeometricParameters (
  459.                         a,
  460.                         b,
  461.                         c
  462.                     ),
  463.                     logBetaEstimator,
  464.                     100000
  465.                 );

  467.             final org.drip.specialfunction.definition.RegularHypergeometricEstimator
  468.                 bMinusHypergeometricEstimator = new
  469.                     org.drip.specialfunction.hypergeometric.GaussContiguousRelations
  470.                         (hypergeometricEstimator).bMinus();

  472.             return new org.drip.function.definition.R1ToR1Property (
  473.                 org.drip.function.definition.R1ToR1Property.EQ,
  474.                 new org.drip.function.definition.R1ToR1 (null)
  475.                 {
  476.                     @Override public double evaluate (
  477.                         final double z)
  478.                         throws java.lang.Exception
  479.                     {
  480.                         return z * hypergeometricEstimator.derivative (
  481.                             z,
  482.                             1
  483.                         );
  484.                     }
  485.                 },
  486.                 new org.drip.function.definition.R1ToR1 (null)
  487.                 {
  488.                     @Override public double evaluate (
  489.                         final double z)
  490.                         throws java.lang.Exception
  491.                     {
  492.                         return (
  493.                             (c - b) * bMinusHypergeometricEstimator.regularHypergeometric (z) +
  494.                             (b - c + a * z) * hypergeometricEstimator.regularHypergeometric (z)
  495.                         ) / (1. - z);
  496.                     }
  497.                 },
  498.                 org.drip.function.definition.R1ToR1Property.MISMATCH_TOLERANCE
  499.             );
  500.         }
  501.         catch (java.lang.Exception e)
  502.         {
  503.             e.printStackTrace();
  504.         }

  506.         return null;
  507.     }

  509.     /**
  510.      * Construct the Hyper-geometric Gauss Contiguous Identity #7 Verifier
  511.      * 
  512.      * @param a A
  513.      * @param b B
  514.      * @param c C
  515.      * 
  516.      * @return The Hyper-geometric Gauss Contiguous Identity #7 Verifier
  517.      */

  519.     public static final org.drip.function.definition.R1ToR1Property RelationIdentity7 (
  520.         final double a,
  521.         final double b,
  522.         final double c)
  523.     {
  524.         org.drip.function.definition.R2ToR1 logBetaEstimator =
  525.             org.drip.specialfunction.beta.LogGammaEstimator.Weierstrass (10000);

  527.         if (null == logBetaEstimator)
  528.         {
  529.             return null;
  530.         }

  532.         try
  533.         {
  534.             final org.drip.specialfunction.hypergeometric.EulerQuadratureEstimator hypergeometricEstimator =
  535.                 new org.drip.specialfunction.hypergeometric.EulerQuadratureEstimator (
  536.                     new org.drip.specialfunction.definition.HypergeometricParameters (
  537.                         a,
  538.                         b,
  539.                         c
  540.                     ),
  541.                     logBetaEstimator,
  542.                     100000
  543.                 );

  545.             final org.drip.specialfunction.definition.RegularHypergeometricEstimator
  546.                 cPlusHypergeometricEstimator = new
  547.                     org.drip.specialfunction.hypergeometric.GaussContiguousRelations
  548.                         (hypergeometricEstimator).cPlus();

  550.             return new org.drip.function.definition.R1ToR1Property (
  551.                 org.drip.function.definition.R1ToR1Property.EQ,
  552.                 new org.drip.function.definition.R1ToR1 (null)
  553.                 {
  554.                     @Override public double evaluate (
  555.                         final double z)
  556.                         throws java.lang.Exception
  557.                     {
  558.                         return hypergeometricEstimator.derivative (
  559.                             z,
  560.                             1
  561.                         );
  562.                     }
  563.                 },
  564.                 new org.drip.function.definition.R1ToR1 (null)
  565.                 {
  566.                     @Override public double evaluate (
  567.                         final double z)
  568.                         throws java.lang.Exception
  569.                     {
  570.                         return (
  571.                             (c - a) * (c - b) * cPlusHypergeometricEstimator.regularHypergeometric (z) +
  572.                             c * (a + b - c) * hypergeometricEstimator.regularHypergeometric (z)
  573.                         ) / (c * (1. - z));
  574.                     }
  575.                 },
  576.                 org.drip.function.definition.R1ToR1Property.MISMATCH_TOLERANCE
  577.             );
  578.         }
  579.         catch (java.lang.Exception e)
  580.         {
  581.             e.printStackTrace();
  582.         }

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