ConstantPaymentBondBuilder.java

  1. package org.drip.product.creator;

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

  81. /**
  82.  * <i>ConstantPaymentBondBuilder</i> contains the Suite of Helper Functions for creating Constant Payments
  83.  * Based Bonds.
  84.  *
  85.  *  <br><br>
  86.  *  <ul>
  87.  *      <li><b>Module </b> = <a href = "https://github.com/lakshmiDRIP/DROP/tree/master/ProductCore.md">Product Core Module</a></li>
  88.  *      <li><b>Library</b> = <a href = "https://github.com/lakshmiDRIP/DROP/tree/master/FixedIncomeAnalyticsLibrary.md">Fixed Income Analytics</a></li>
  89.  *      <li><b>Project</b> = <a href = "https://github.com/lakshmiDRIP/DROP/tree/master/src/main/java/org/drip/product/README.md">Product Components/Baskets for Credit, FRA, FX, Govvie, Rates, and Option AssetClasses</a></li>
  90.  *      <li><b>Package</b> = <a href = "https://github.com/lakshmiDRIP/DROP/tree/master/src/main/java/org/drip/product/creator/README.md">Streams and Products Construction Utilities</a></li>
  91.  *  </ul>
  92.  * <br><br>
  93.  * 
  94.  * @author Lakshmi Krishnamurthy
  95.  */

  97. public class ConstantPaymentBondBuilder {

  99.     /**
  100.      * Construct an Instance of the Constant Payment Bond
  101.      * 
  102.      * @param strName Mortgage Bond Instance Name
  103.      * @param dtEffective Effective Date
  104.      * @param strCurrency Currency
  105.      * @param iNumPayment The (Maximum) Number of Payments
  106.      * @param strDayCount Coupon/Accrual Day Count
  107.      * @param iPayFrequency Pay Frequency
  108.      * @param dblCouponRate The Coupon Rate
  109.      * @param dblFeeRate The Fee Rate
  110.      * @param dblConstantAmount The Fixed Monthly Amount
  111.      * @param dblInitialNotional The Initial Bond Notional
  112.      * 
  113.      * @return Instance of the Fixed Mortgage Product
  114.      */

  116.     public static final org.drip.product.credit.BondComponent Standard (
  117.         final java.lang.String strName,
  118.         final org.drip.analytics.date.JulianDate dtEffective,
  119.         final java.lang.String strCurrency,
  120.         final int iNumPayment,
  121.         final java.lang.String strDayCount,
  122.         final int iPayFrequency,
  123.         final double dblCouponRate,
  124.         final double dblFeeRate,
  125.         final double dblConstantAmount,
  126.         final double dblInitialNotional)
  127.     {
  128.         if (null == dtEffective || !org.drip.numerical.common.NumberUtil.IsValid (dblCouponRate) ||
  129.             !org.drip.numerical.common.NumberUtil.IsValid (dblFeeRate) || dblFeeRate > dblCouponRate ||
  130.                 !org.drip.numerical.common.NumberUtil.IsValid (dblConstantAmount) ||
  131.                     !org.drip.numerical.common.NumberUtil.IsValid (dblInitialNotional))
  132.             return null;

  134.         double dblOutstandingPrincipal = dblInitialNotional;

  136.         java.util.List<java.lang.Double> lsCouponPayment = new java.util.ArrayList<java.lang.Double>();

  138.         java.util.List<java.lang.Double> lsOutstandingPrincipal = new
  139.             java.util.ArrayList<java.lang.Double>();

  141.         java.util.List<org.drip.analytics.date.JulianDate> lsPaymentDate = new
  142.             java.util.ArrayList<org.drip.analytics.date.JulianDate>();

  144.         for (int i = 0; i < iNumPayment; ++i) {
  145.             double dblCouponPayment = java.lang.Double.NaN;

  147.             org.drip.analytics.date.JulianDate dtPayment = dtEffective.addMonths (i + 1);

  149.             org.drip.analytics.date.JulianDate dtPrev = 0 == i ? dtEffective : lsPaymentDate.get (i - 1);

  151.             try {
  152.                 dblCouponPayment = dblOutstandingPrincipal * (dblCouponRate - dblFeeRate) *
  153.                     org.drip.analytics.daycount.Convention.YearFraction (dtPrev.julian(), dtPayment.julian(),
  154.                         strDayCount, false, null, "");
  155.             } catch (java.lang.Exception e) {
  156.                 e.printStackTrace();

  158.                 return null;
  159.             }

  161.             lsPaymentDate.add (dtPayment);

  163.             lsCouponPayment.add (dblCouponPayment);

  165.             double dblPrincipalPayment = dblConstantAmount - dblCouponPayment;

  167.             if (dblPrincipalPayment > dblOutstandingPrincipal) {
  168.                 lsOutstandingPrincipal.add (0.);

  170.                 break;
  171.             }

  173.             dblOutstandingPrincipal -= dblPrincipalPayment;

  175.             lsOutstandingPrincipal.add (dblOutstandingPrincipal);
  176.         }

  178.         int iNumValidPayment = lsOutstandingPrincipal.size();

  180.         double[] adblCouponPayment = new double[iNumValidPayment];
  181.         double[] adblOutstandingPrincipal = new double[iNumValidPayment];
  182.         org.drip.analytics.date.JulianDate[] adtPayment = new
  183.             org.drip.analytics.date.JulianDate[iNumValidPayment];

  185.         for (int i = 0; i < iNumValidPayment; ++i) {
  186.             adtPayment[i] = lsPaymentDate.get (i);

  188.             adblCouponPayment[i] = lsCouponPayment.get (i);

  190.             adblOutstandingPrincipal[i] = lsOutstandingPrincipal.get (i);
  191.         }

  193.         return org.drip.product.creator.BondBuilder.CreateBondFromCF (strName, dtEffective, strCurrency, "",
  194.             strDayCount, dblInitialNotional, dblCouponRate - dblFeeRate, iPayFrequency, adtPayment,
  195.                 adblCouponPayment, adblOutstandingPrincipal, false);
  196.     }

  198.     /**
  199.      * Construct an Instance of the Constant Payment Bond with a Deterministic Pre-payment Rate
  200.      * 
  201.      * @param strName Mortgage Bond Instance Name
  202.      * @param dtEffective Effective Date
  203.      * @param strCurrency Currency
  204.      * @param iNumPayment The (Maximum) Number of Payments
  205.      * @param strDayCount Coupon/Accrual Day Count
  206.      * @param iPayFrequency Pay Frequency
  207.      * @param dblCouponRate The Coupon Rate
  208.      * @param dblFeeRate The Fee Rate
  209.      * @param dblCPR the Constant Pre-payment Rate
  210.      * @param dblConstantAmount The Fixed Monthly Amount
  211.      * @param dblInitialNotional The Initial Bond Notional
  212.      * 
  213.      * @return Instance of the Fixed Mortgage Product
  214.      */

  216.     public static final org.drip.product.credit.BondComponent Prepay (
  217.         final java.lang.String strName,
  218.         final org.drip.analytics.date.JulianDate dtEffective,
  219.         final java.lang.String strCurrency,
  220.         final int iNumPayment,
  221.         final java.lang.String strDayCount,
  222.         final int iPayFrequency,
  223.         final double dblCouponRate,
  224.         final double dblFeeRate,
  225.         final double dblCPR,
  226.         final double dblConstantAmount,
  227.         final double dblInitialNotional)
  228.     {
  229.         if (null == dtEffective || !org.drip.numerical.common.NumberUtil.IsValid (dblCouponRate) ||
  230.             !org.drip.numerical.common.NumberUtil.IsValid (dblFeeRate) || dblFeeRate > dblCouponRate ||
  231.                 !org.drip.numerical.common.NumberUtil.IsValid (dblCPR) ||
  232.                     !org.drip.numerical.common.NumberUtil.IsValid (dblConstantAmount) ||
  233.                         !org.drip.numerical.common.NumberUtil.IsValid (dblInitialNotional))
  234.             return null;

  236.         double dblOutstandingPrincipal = dblInitialNotional;

  238.         java.util.List<java.lang.Double> lsCouponPayment = new java.util.ArrayList<java.lang.Double>();

  240.         java.util.List<java.lang.Double> lsOutstandingPrincipal = new
  241.             java.util.ArrayList<java.lang.Double>();

  243.         java.util.List<org.drip.analytics.date.JulianDate> lsPaymentDate = new
  244.             java.util.ArrayList<org.drip.analytics.date.JulianDate>();

  246.         for (int i = 0; i < iNumPayment; ++i) {
  247.             double dblCouponPayment = java.lang.Double.NaN;

  249.             org.drip.analytics.date.JulianDate dtPayment = dtEffective.addMonths (i + 1);

  251.             org.drip.analytics.date.JulianDate dtPrev = 0 == i ? dtEffective : lsPaymentDate.get (i - 1);

  253.             try {
  254.                 dblCouponPayment = dblOutstandingPrincipal * (dblCouponRate - dblFeeRate) *
  255.                     org.drip.analytics.daycount.Convention.YearFraction (dtPrev.julian(), dtPayment.julian(),
  256.                         strDayCount, false, null, "");
  257.             } catch (java.lang.Exception e) {
  258.                 e.printStackTrace();

  260.                 return null;
  261.             }

  263.             lsPaymentDate.add (dtPayment);

  265.             lsCouponPayment.add (dblCouponPayment);

  267.             double dblPrincipalPayment = dblConstantAmount - dblCouponPayment + dblCPR *
  268.                 dblOutstandingPrincipal;

  270.             if (dblPrincipalPayment > dblOutstandingPrincipal) {
  271.                 lsOutstandingPrincipal.add (0.);

  273.                 break;
  274.             }

  276.             dblOutstandingPrincipal -= dblPrincipalPayment;

  278.             lsOutstandingPrincipal.add (dblOutstandingPrincipal);
  279.         }

  281.         int iNumValidPayment = lsOutstandingPrincipal.size();

  283.         double[] adblCouponPayment = new double[iNumValidPayment];
  284.         double[] adblOutstandingPrincipal = new double[iNumValidPayment];
  285.         org.drip.analytics.date.JulianDate[] adtPayment = new
  286.             org.drip.analytics.date.JulianDate[iNumValidPayment];

  288.         for (int i = 0; i < iNumValidPayment; ++i) {
  289.             adtPayment[i] = lsPaymentDate.get (i);

  291.             adblCouponPayment[i] = lsCouponPayment.get (i);

  293.             adblOutstandingPrincipal[i] = lsOutstandingPrincipal.get (i);
  294.         }

  296.         return org.drip.product.creator.BondBuilder.CreateBondFromCF (strName, dtEffective, strCurrency, "",
  297.             strDayCount, dblInitialNotional, dblCouponRate - dblFeeRate, iPayFrequency, adtPayment,
  298.                 adblCouponPayment, adblOutstandingPrincipal, false);
  299.     }

  301.     /**
  302.      * Compute the Constant Uniform Payment Amount for the Parameters of the Specified Mortgage Bond
  303.      * 
  304.      * @param dblBondNotional The Current Notional
  305.      * @param dblCouponRate The Coupon Rate
  306.      * @param iTenorInYears Tenor in Years
  307.      * 
  308.      * @return The Constant Uniform Payment Amount
  309.      * 
  310.      * @throws java.lang.Exception Thrown if the Constant Uniform Payment Amount cannot be computed
  311.      */

  313.     public static final double ConstantUniformPaymentAmount (
  314.         final double dblBondNotional,
  315.         final double dblCouponRate,
  316.         final int iTenorInYears)
  317.         throws java.lang.Exception
  318.     {
  319.         if (!org.drip.numerical.common.NumberUtil.IsValid (dblBondNotional) ||
  320.             !org.drip.numerical.common.NumberUtil.IsValid (dblCouponRate))
  321.                 throw new java.lang.Exception
  322.                     ("ConstantPaymentBondBuilder::ConstantUniformPaymentAmount => Invalid Inputs");

  324.         int iNumPeriod = iTenorInYears * 12;
  325.         double dblPeriodRate = dblCouponRate / 12.;

  327.         return dblPeriodRate * dblBondNotional * java.lang.Math.pow (1. + dblPeriodRate, iNumPeriod - 1) /
  328.             (java.lang.Math.pow (1. + dblPeriodRate, iNumPeriod) - 1.);
  329.     }
  330. }
Created with JaCoCo 0.7.9.201702052155