R1ToR1Integrator.java

  1. package org.drip.numerical.integration;

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

  83. /**
  84.  * <i>R1ToR1Integrator</i> implements the following routines for integrating the R<sup>1</sup> To
  85.  * R<sup>1</sup> objective Function.
  86.  * 
  87.  * <br><br>
  88.  *  <ul>
  89.  *      <li>
  90.  *          Linear Quadrature
  91.  *      </li>
  92.  *      <li>
  93.  *          Mid-Point Scheme
  94.  *      </li>
  95.  *      <li>
  96.  *          Trapezoidal Scheme
  97.  *      </li>
  98.  *      <li>
  99.  *          Simpson/Simpson38 schemes
  100.  *      </li>
  101.  *      <li>
  102.  *          Boole Scheme
  103.  *      </li>
  104.  *  </ul>
  105.  * 
  106.  * <br><br>
  107.  *  <ul>
  108.  *      <li><b>Module </b> = <a href = "https://github.com/lakshmiDRIP/DROP/tree/master/ComputationalCore.md">Computational Core Module</a></li>
  109.  *      <li><b>Library</b> = <a href = "https://github.com/lakshmiDRIP/DROP/tree/master/NumericalAnalysisLibrary.md">Numerical Analysis Library</a></li>
  110.  *      <li><b>Project</b> = <a href = "https://github.com/lakshmiDRIP/DROP/tree/master/src/main/java/org/drip/numerical/README.md">Numerical Quadrature, Differentiation, Eigenization, Linear Algebra, and Utilities</a></li>
  111.  *      <li><b>Package</b> = <a href = "https://github.com/lakshmiDRIP/DROP/tree/master/src/main/java/org/drip/numerical/integration/README.md">R<sup>1</sup> R<sup>d</sup> Numerical Integration Schemes</a></li>
  112.  *  </ul>
  113.  * <br><br>
  114.  *
  115.  * @author Lakshmi Krishnamurthy
  116.  */

  118. public class R1ToR1Integrator {
  119.     private final static int NUM_QUAD = 10000;

  121.     /**
  122.      * Compute the function's integral within the specified limits using the LinearQuadrature technique.
  123.      * 
  124.      * @param funcR1ToR1 R1ToR1 Function
  125.      * @param dblLeft Left Variate
  126.      * @param dblRight Right Variate
  127.      * 
  128.      * @return The Integral
  129.      * 
  130.      * @throws java.lang.Exception Thrown if the error cannot be computed
  131.      */

  133.     public static final double LinearQuadrature (
  134.         final org.drip.function.definition.R1ToR1 funcR1ToR1,
  135.         final double dblLeft,
  136.         final double dblRight)
  137.         throws java.lang.Exception
  138.     {
  139.         if (null == funcR1ToR1 || !org.drip.numerical.common.NumberUtil.IsValid (dblLeft) ||
  140.             !org.drip.numerical.common.NumberUtil.IsValid (dblRight) || dblLeft > dblRight)
  141.             throw new java.lang.Exception ("R1ToR1Integrator::LinearQuadrature => Invalid Inputs");

  143.         if (dblLeft == dblRight) return 0.;

  145.         double dblWidth = (dblRight - dblLeft) / NUM_QUAD;
  146.         double dblX = dblLeft + dblWidth;
  147.         double dblAUArea = 0.;

  149.         while (dblX <= dblRight) {
  150.             double dblY = funcR1ToR1.evaluate (dblX - 0.5 * dblWidth);

  152.             if (!org.drip.numerical.common.NumberUtil.IsValid (dblLeft))
  153.                 throw new java.lang.Exception
  154.                     ("R1ToR1Integrator::LinearQuadrature => Cannot calculate an intermediate Y");

  156.             dblAUArea += dblY * dblWidth;
  157.             dblX += dblWidth;
  158.         }

  160.         return dblAUArea;
  161.     }

  163.     /**
  164.      * Compute the function's integral within the specified limits using the Mid-point rule.
  165.      * 
  166.      * @param funcR1ToR1 R1ToR1 Function
  167.      * @param dblLeft Left Variate
  168.      * @param dblRight Right Variate
  169.      * 
  170.      * @return The Integral
  171.      * 
  172.      * @throws java.lang.Exception Thrown if the error cannot be computed
  173.      */

  175.     public static final double MidPoint (
  176.         final org.drip.function.definition.R1ToR1 funcR1ToR1,
  177.         final double dblLeft,
  178.         final double dblRight)
  179.         throws java.lang.Exception
  180.     {
  181.         if (null == funcR1ToR1 || !org.drip.numerical.common.NumberUtil.IsValid (dblLeft) ||
  182.             !org.drip.numerical.common.NumberUtil.IsValid (dblRight) || dblLeft > dblRight)
  183.             throw new java.lang.Exception ("R1ToR1Integrator::MidPoint => Invalid Inputs");

  185.         if (dblLeft == dblRight) return 0.;

  187.         double dblYMid = funcR1ToR1.evaluate (0.5 * (dblLeft + dblRight));

  189.         if (!org.drip.numerical.common.NumberUtil.IsValid (dblYMid))
  190.             throw new java.lang.Exception ("R1ToR1Integrator::MidPoint => Cannot calculate Y at " + 0.5 *
  191.                 (dblLeft + dblRight));

  193.         return (dblRight - dblLeft) * dblYMid;
  194.     }

  196.     /**
  197.      * Compute the function's integral within the specified limits using the Trapezoidal rule.
  198.      * 
  199.      * @param funcR1ToR1 R1ToR1 Function
  200.      * @param dblLeft Left Variate
  201.      * @param dblRight Right Variate
  202.      * 
  203.      * @return The Integral
  204.      * 
  205.      * @throws java.lang.Exception Thrown if the error cannot be computed
  206.      */

  208.     public static final double Trapezoidal (
  209.         final org.drip.function.definition.R1ToR1 funcR1ToR1,
  210.         final double dblLeft,
  211.         final double dblRight)
  212.         throws java.lang.Exception
  213.     {
  214.         if (null == funcR1ToR1 || !org.drip.numerical.common.NumberUtil.IsValid (dblLeft) ||
  215.             !org.drip.numerical.common.NumberUtil.IsValid (dblRight) || dblLeft > dblRight)
  216.             throw new java.lang.Exception ("R1ToR1Integrator::Trapezoidal => Invalid Inputs");

  218.         if (dblLeft == dblRight) return 0.;

  220.         double dblYLeft = funcR1ToR1.evaluate (dblLeft);

  222.         if (!org.drip.numerical.common.NumberUtil.IsValid (dblYLeft))
  223.             throw new java.lang.Exception ("R1ToR1Integrator::Trapezoidal => Cannot calculate Y at " +
  224.                 dblLeft);

  226.         double dblYRight = funcR1ToR1.evaluate (dblRight);

  228.         if (!org.drip.numerical.common.NumberUtil.IsValid (dblYLeft))
  229.             throw new java.lang.Exception ("R1ToR1Integrator::Trapezoidal => Cannot calculate Y at " +
  230.                 dblRight);

  232.         return 0.5 * (dblRight - dblLeft) * (dblYLeft + dblYRight);
  233.     }

  235.     /**
  236.      * Compute the function's integral within the specified limits using the Simpson rule.
  237.      * 
  238.      * @param funcR1ToR1 R1ToR1 Function
  239.      * @param dblLeft Left Variate
  240.      * @param dblRight Right Variate
  241.      * 
  242.      * @return The Integral
  243.      * 
  244.      * @throws java.lang.Exception Thrown if the error cannot be computed
  245.      */

  247.     public static final double Simpson (
  248.         final org.drip.function.definition.R1ToR1 funcR1ToR1,
  249.         final double dblLeft,
  250.         final double dblRight)
  251.         throws java.lang.Exception
  252.     {
  253.         if (null == funcR1ToR1 || !org.drip.numerical.common.NumberUtil.IsValid (dblLeft) ||
  254.             !org.drip.numerical.common.NumberUtil.IsValid (dblRight) || dblLeft > dblRight)
  255.             throw new java.lang.Exception ("R1ToR1Integrator::Simpson => Invalid Inputs");

  257.         if (dblLeft == dblRight) return 0.;

  259.         double dblYLeft = funcR1ToR1.evaluate (dblLeft);

  261.         if (!org.drip.numerical.common.NumberUtil.IsValid (dblYLeft))
  262.             throw new java.lang.Exception ("R1ToR1Integrator::Simpson => Cannot calculate Y at " + dblLeft);

  264.         double dblXMid = 0.5 * (dblLeft + dblRight);

  266.         double dblYMid = funcR1ToR1.evaluate (dblXMid);

  268.         if (!org.drip.numerical.common.NumberUtil.IsValid (dblYMid))
  269.             throw new java.lang.Exception ("R1ToR1Integrator::Simpson => Cannot calculate Y at " + dblXMid);

  271.         double dblYRight = funcR1ToR1.evaluate (dblRight);

  273.         if (!org.drip.numerical.common.NumberUtil.IsValid (dblYRight))
  274.             throw new java.lang.Exception ("R1ToR1Integrator::Simpson => Cannot calculate Y at " + dblRight);

  276.         return (dblRight - dblLeft) / 6. * (dblYLeft + 4. * dblYMid + dblYRight);
  277.     }

  279.     /**
  280.      * Compute the function's integral within the specified limits using the Simpson 3/8 rule.
  281.      * 
  282.      * @param funcR1ToR1 R1ToR1 Function
  283.      * @param dblLeft Left Variate
  284.      * @param dblRight Right Variate
  285.      * 
  286.      * @return The Integral
  287.      * 
  288.      * @throws java.lang.Exception Thrown if the error cannot be computed
  289.      */

  291.     public static final double Simpson38 (
  292.         final org.drip.function.definition.R1ToR1 funcR1ToR1,
  293.         final double dblLeft,
  294.         final double dblRight)
  295.         throws java.lang.Exception
  296.     {
  297.         if (null == funcR1ToR1 || !org.drip.numerical.common.NumberUtil.IsValid (dblLeft) ||
  298.             !org.drip.numerical.common.NumberUtil.IsValid (dblRight) || dblLeft > dblRight)
  299.             throw new java.lang.Exception ("R1ToR1Integrator::Simpson38 => Invalid Inputs");

  301.         if (dblLeft == dblRight) return 0.;

  303.         double dblY0 = funcR1ToR1.evaluate (dblLeft);

  305.         if (!org.drip.numerical.common.NumberUtil.IsValid (dblY0))
  306.             throw new java.lang.Exception ("R1ToR1Integrator::Simpson38 => Cannot calculate Y at " +
  307.                 dblLeft);

  309.         double dblX1 = (2. * dblLeft + dblRight) / 3.;

  311.         double dblY1 = funcR1ToR1.evaluate (dblX1);

  313.         if (!org.drip.numerical.common.NumberUtil.IsValid (dblY1))
  314.             throw new java.lang.Exception ("R1ToR1Integrator::Simpson38 => Cannot calculate Y at " + dblX1);

  316.         double dblX2 = (dblLeft + 2. * dblRight) / 3.;

  318.         double dblY2 = funcR1ToR1.evaluate (dblX2);

  320.         if (!org.drip.numerical.common.NumberUtil.IsValid (dblY2))
  321.             throw new java.lang.Exception ("R1ToR1Integrator::Simpson38 => Cannot calculate Y at " + dblX2);

  323.         double dblY3 = funcR1ToR1.evaluate (dblRight);

  325.         if (!org.drip.numerical.common.NumberUtil.IsValid (dblY3))
  326.             throw new java.lang.Exception ("R1ToR1Integrator::Simpson38 => Cannot calculate Y at " +
  327.                 dblRight);

  329.         return (dblRight - dblLeft) * (0.125 * dblY0 + 0.375 * dblY1 + 0.375 * dblY2 + 0.125 * dblY3);
  330.     }

  332.     /**
  333.      * Compute the function's integral within the specified limits using the Boole rule.
  334.      * 
  335.      * @param funcR1ToR1 R1ToR1 Function
  336.      * @param dblLeft Left Variate
  337.      * @param dblRight Right Variate
  338.      * 
  339.      * @return The Integral
  340.      * 
  341.      * @throws java.lang.Exception Thrown if the error cannot be computed
  342.      */

  344.     public static final double Boole (
  345.         final org.drip.function.definition.R1ToR1 funcR1ToR1,
  346.         final double dblLeft,
  347.         final double dblRight)
  348.         throws java.lang.Exception
  349.     {
  350.         if (null == funcR1ToR1 || !org.drip.numerical.common.NumberUtil.IsValid (dblLeft) ||
  351.             !org.drip.numerical.common.NumberUtil.IsValid (dblRight) || dblLeft > dblRight)
  352.             throw new java.lang.Exception ("R1ToR1Integrator::Boole => Invalid Inputs");

  354.         if (dblLeft == dblRight) return 0.;

  356.         double dblY0 = funcR1ToR1.evaluate (dblLeft);

  358.         if (!org.drip.numerical.common.NumberUtil.IsValid (dblY0))
  359.             throw new java.lang.Exception ("R1ToR1Integrator::Boole => Cannot calculate Y at " + dblLeft);

  361.         double dblX1 = 0.25 * dblLeft + 0.75 * dblRight;

  363.         double dblY1 = funcR1ToR1.evaluate (dblX1);

  365.         if (!org.drip.numerical.common.NumberUtil.IsValid (dblY1))
  366.             throw new java.lang.Exception ("R1ToR1Integrator::Boole => Cannot calculate Y at " + dblX1);

  368.         double dblX2 = 0.5 * (dblLeft + dblRight);

  370.         double dblY2 = funcR1ToR1.evaluate (dblX2);

  372.         if (!org.drip.numerical.common.NumberUtil.IsValid (dblY2))
  373.             throw new java.lang.Exception ("R1ToR1Integrator::Boole => Cannot calculate Y at " + dblX2);

  375.         double dblX3 = 0.75 * dblLeft + 0.25 * dblRight;

  377.         double dblY3 = funcR1ToR1.evaluate (dblX3);

  379.         if (!org.drip.numerical.common.NumberUtil.IsValid (dblY3))
  380.             throw new java.lang.Exception ("R1ToR1Integrator::Boole => Cannot calculate Y at " + dblX3);

  382.         double dblY4 = funcR1ToR1.evaluate (dblRight);

  384.         if (!org.drip.numerical.common.NumberUtil.IsValid (dblY4))
  385.             throw new java.lang.Exception ("R1ToR1Integrator::Boole => Cannot calculate Y at " + dblRight);

  387.         return (dblRight - dblLeft) / 90 * (7 * dblY0 + 32 * dblY1 + 12 * dblY2 + 32 * dblY3 + 7 * dblY4);
  388.     }

  390.     /**
  391.      * Integrate Numerically over [-infinity, +infinity] using a Change of Variables
  392.      * 
  393.      * @param funcR1ToR1 The R1ToR1 Function
  394.      * 
  395.      * @return The Numerical Integrand
  396.      * 
  397.      * @throws java.lang.Exception Thrown if the Integral cannot be computed
  398.      */

  400.     public static final double LeftInfiniteRightInfinite (
  401.         final org.drip.function.definition.R1ToR1 funcR1ToR1)
  402.         throws java.lang.Exception
  403.     {
  404.         if (null == funcR1ToR1)
  405.             throw new java.lang.Exception ("R1ToR1Integrator::LeftInfiniteRightInfinite => Invalid Inputs");

  407.         org.drip.function.definition.R1ToR1 auTransformed = new
  408.             org.drip.function.definition.R1ToR1 (null) {
  409.             @Override public double evaluate (
  410.                 final double dblX)
  411.                 throws java.lang.Exception
  412.             {
  413.                 if (!org.drip.numerical.common.NumberUtil.IsValid (dblX))
  414.                     throw new java.lang.Exception
  415.                         ("IntegratorR1ToR1::LeftInfiniteRightInfinite => Invalid Inputs");

  417.                 double dblX2 = dblX * dblX;
  418.                 double dblXTransform = 1. / (1. - dblX2);

  420.                 return (1. + dblX2) / (dblXTransform * dblXTransform) * funcR1ToR1.evaluate (dblX /
  421.                     dblXTransform);
  422.             }
  423.         };

  425.         return auTransformed.integrate (-1., +1.);
  426.     }

  428.     /**
  429.      * Integrate the specified Function Numerically from -infinity to the specified Right Limit
  430.      * 
  431.      * @param funcR1ToR1 The Input R1ToR1 Function
  432.      * @param dblRight The Right Integration Limit
  433.      * 
  434.      * @return The Results of the Integration
  435.      * 
  436.      * @throws java.lang.Exception Thrown if the Integrand cannot be evaluated
  437.      */

  439.     public static final double LeftInfinite (
  440.         final org.drip.function.definition.R1ToR1 funcR1ToR1,
  441.         final double dblRight)
  442.         throws java.lang.Exception
  443.     {
  444.         if (null == funcR1ToR1 || !org.drip.numerical.common.NumberUtil.IsValid (dblRight))
  445.             throw new java.lang.Exception ("R1ToR1Integrator::LeftInfinite => Invalid Inputs");

  447.         org.drip.function.definition.R1ToR1 auTransformed = new
  448.             org.drip.function.definition.R1ToR1 (null) {
  449.             @Override public double evaluate (
  450.                 final double dblX)
  451.                 throws java.lang.Exception
  452.             {
  453.                 if (!org.drip.numerical.common.NumberUtil.IsValid (dblX))
  454.                     throw new java.lang.Exception ("IntegratorR1ToR1::LeftInfinite => Invalid Inputs");

  456.                 return (funcR1ToR1.evaluate (dblRight - ((1. - dblX) / dblX))) / (dblX * dblX);
  457.             }
  458.         };

  460.         return auTransformed.integrate (0., +1.);
  461.     }

  463.     /**
  464.      * Integrate the specified Function Numerically from the specified Left Limit to +infinity
  465.      * 
  466.      * @param funcR1ToR1 The Input R1ToR1 Function
  467.      * @param dblLeft The Left Integration Limit
  468.      * 
  469.      * @return The Results of the Integration
  470.      * 
  471.      * @throws java.lang.Exception Thrown if the Integrand cannot be evaluated
  472.      */

  474.     public static final double RightInfinite (
  475.         final org.drip.function.definition.R1ToR1 funcR1ToR1,
  476.         final double dblLeft)
  477.         throws java.lang.Exception
  478.     {
  479.         if (null == funcR1ToR1 || !org.drip.numerical.common.NumberUtil.IsValid (dblLeft))
  480.             throw new java.lang.Exception ("R1ToR1Integrator::RightInfinite => Invalid Inputs");

  482.         org.drip.function.definition.R1ToR1 auTransformed = new
  483.             org.drip.function.definition.R1ToR1 (null) {
  484.             @Override public double evaluate (
  485.                 final double dblX)
  486.                 throws java.lang.Exception
  487.             {
  488.                 if (!org.drip.numerical.common.NumberUtil.IsValid (dblX))
  489.                     throw new java.lang.Exception ("R1ToR1Integrator::RightInfinite => Invalid Inputs");

  491.                 double dblXInversion = 1. - dblX;

  493.                 return (funcR1ToR1.evaluate (dblLeft + (dblX / dblXInversion))) / (dblXInversion *
  494.                     dblXInversion);
  495.             }
  496.         };

  498.         return auTransformed.integrate (0., +1.);
  499.     }
  500. }
Created with JaCoCo 0.7.9.201702052155