MultiSegmentSequenceModifier.java

  1. package org.drip.spline.stretch;

  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>MultiSegmentSequenceModifier</i> exports Stretch modification/alteration methods to generate customized
  85.  * basis splines, with customized segment behavior using the segment control. It exposes the following
  86.  * stretch modification methods:
  87.  *
  88.  * <br><br>
  89.  *  <ul>
  90.  *      <li>
  91.  *          Insert the specified Predictor Ordinate Knot into the specified Stretch, using the specified
  92.  *              Response Value
  93.  *      </li>
  94.  *      <li>
  95.  *          Append a Segment to the Right of the Specified Stretch using the Supplied Constraint
  96.  *      </li>
  97.  *      <li>
  98.  *          Insert the Predictor Ordinate Knot into the specified Stretch
  99.  *      </li>
  100.  *      <li>
  101.  *          Insert a Cardinal Knot into the specified Stretch at the specified Predictor Ordinate Location
  102.  *      </li>
  103.  *      <li>
  104.  *          Insert a Catmull-Rom Knot into the specified Stretch at the specified Predictor Ordinate Location
  105.  *      </li>
  106.  *  </ul>
  107.  *
  108.  * <br><br>
  109.  *  <ul>
  110.  *      <li><b>Module </b> = <a href = "https://github.com/lakshmiDRIP/DROP/tree/master/ComputationalCore.md">Computational Core Module</a></li>
  111.  *      <li><b>Library</b> = <a href = "https://github.com/lakshmiDRIP/DROP/tree/master/SplineBuilderLibrary.md">Spline Builder Library</a></li>
  112.  *      <li><b>Project</b> = <a href = "https://github.com/lakshmiDRIP/DROP/tree/master/src/main/java/org/drip/spline/README.md">Basis Splines and Linear Compounders across a Broad Family of Spline Basis Functions</a></li>
  113.  *      <li><b>Package</b> = <a href = "https://github.com/lakshmiDRIP/DROP/tree/master/src/main/java/org/drip/spline/stretch/README.md">Multi-Segment Sequence Spline Stretch</a></li>
  114.  *  </ul>
  115.  * <br><br>
  116.  *
  117.  * @author Lakshmi Krishnamurthy
  118.  */

  120. public class MultiSegmentSequenceModifier {

  122.     /**
  123.      * Insert the specified Predictor Ordinate Knot into the specified Stretch, using the specified Response
  124.      *  Value
  125.      * 
  126.      * @param mssIn Input Stretch
  127.      * @param dblPredictorOrdinate Predictor Ordinate Knot
  128.      * @param dblResponseValue Response Value
  129.      * @param bs The Calibration Boundary Condition
  130.      * @param iCalibrationDetail The Calibration Detail
  131.      * 
  132.      * @return The Stretch with the Knot inserted
  133.      */

  135.     public static final org.drip.spline.stretch.MultiSegmentSequence InsertKnot (
  136.         final org.drip.spline.stretch.MultiSegmentSequence mssIn,
  137.         final double dblPredictorOrdinate,
  138.         final double dblResponseValue,
  139.         final org.drip.spline.stretch.BoundarySettings bs,
  140.         final int iCalibrationDetail)
  141.     {
  142.         if (!org.drip.numerical.common.NumberUtil.IsValid (dblPredictorOrdinate) ||
  143.             !org.drip.numerical.common.NumberUtil.IsValid (dblResponseValue) || null == mssIn || mssIn.isKnot
  144.                 (dblPredictorOrdinate))
  145.             return null;

  147.         org.drip.spline.segment.LatentStateResponseModel[] aCS = mssIn.segments();

  149.         int iNewIndex = 0;
  150.         int iNumSegmentIn = aCS.length;
  151.         double[] adblResponseValue = new double[iNumSegmentIn + 2];
  152.         double[] adblPredictorOrdinate = new double[iNumSegmentIn + 2];
  153.         org.drip.spline.params.SegmentCustomBuilderControl[] aSCBCOut = new
  154.             org.drip.spline.params.SegmentCustomBuilderControl[iNumSegmentIn + 1];

  156.         org.drip.spline.params.SegmentCustomBuilderControl[] aSCBCIn = mssIn.segmentBuilderControl();

  158.         if (dblPredictorOrdinate < aCS[0].left()) {
  159.             adblPredictorOrdinate[iNewIndex] = dblPredictorOrdinate;
  160.             adblResponseValue[iNewIndex] = dblResponseValue;
  161.             aSCBCOut[iNewIndex++] = aSCBCIn[0];
  162.         }

  164.         for (int i = 0; i < iNumSegmentIn; ++i) {
  165.             aSCBCOut[iNewIndex] = aSCBCIn[i];

  167.             adblPredictorOrdinate[iNewIndex] = aCS[i].left();

  169.             try {
  170.                 adblResponseValue[iNewIndex++] = mssIn.responseValue (aCS[i].left());
  171.             } catch (java.lang.Exception e) {
  172.                 e.printStackTrace();

  174.                 return null;
  175.             }

  177.             if (dblPredictorOrdinate > aCS[i].left() && dblPredictorOrdinate < aCS[i].right()) {
  178.                 adblPredictorOrdinate[iNewIndex] = dblPredictorOrdinate;
  179.                 adblResponseValue[iNewIndex] = dblResponseValue;
  180.                 aSCBCOut[iNewIndex++] = aSCBCIn[i];
  181.             }
  182.         }

  184.         adblPredictorOrdinate[iNewIndex] = aCS[iNumSegmentIn - 1].right();

  186.         try {
  187.             adblResponseValue[iNewIndex++] = mssIn.responseValue (aCS[iNumSegmentIn - 1].right());
  188.         } catch (java.lang.Exception e) {
  189.             e.printStackTrace();

  191.             return null;
  192.         }

  194.         if (dblPredictorOrdinate > aCS[iNumSegmentIn - 1].right()) {
  195.             adblResponseValue[iNewIndex] = dblResponseValue;
  196.             adblPredictorOrdinate[iNewIndex] = dblPredictorOrdinate;
  197.             aSCBCOut[aSCBCOut.length - 1] = aSCBCIn[aSCBCIn.length - 1];
  198.         }

  200.         return org.drip.spline.stretch.MultiSegmentSequenceBuilder.CreateCalibratedStretchEstimator
  201.             (mssIn.name(), adblPredictorOrdinate, adblResponseValue, aSCBCOut, null, bs, iCalibrationDetail);
  202.     }

  204.     /**
  205.      * Append a Segment to the Right of the Specified Stretch using the Supplied Constraint
  206.      * 
  207.      * @param mssIn Input Stretch
  208.      * @param dblPredictorOrdinateAppendRight The Predictor Ordinate at the Right Edge of the Segment to be
  209.      *  appended
  210.      * @param srvc The Segment Response Value Constraint
  211.      * @param scbc Segment Builder Parameters
  212.      * @param bs The Calibration Boundary Condition
  213.      * @param iCalibrationDetail The Calibration Detail
  214.      * 
  215.      * @return The Stretch with the Segment Appended
  216.      */

  218.     public static final org.drip.spline.stretch.MultiSegmentSequence AppendSegment (
  219.         final org.drip.spline.stretch.MultiSegmentSequence mssIn,
  220.         final double dblPredictorOrdinateAppendRight,
  221.         final org.drip.spline.params.SegmentResponseValueConstraint srvc,
  222.         final org.drip.spline.params.SegmentCustomBuilderControl scbc,
  223.         final org.drip.spline.stretch.BoundarySettings bs,
  224.         final int iCalibrationDetail)
  225.     {
  226.         if (null == mssIn || null == srvc || null == scbc || !org.drip.numerical.common.NumberUtil.IsValid
  227.             (dblPredictorOrdinateAppendRight))
  228.             return null;

  230.         double dblStretchPredictorOrdinateRight = mssIn.getRightPredictorOrdinateEdge();

  232.         double[] adblConstraintOrdinate = srvc.predictorOrdinates();

  234.         for (int i = 0; i < adblConstraintOrdinate.length; ++i) {
  235.             if (adblConstraintOrdinate[i] <= dblStretchPredictorOrdinateRight) return null;
  236.         }

  238.         org.drip.spline.segment.LatentStateResponseModel[] aCS = mssIn.segments();

  240.         org.drip.spline.params.SegmentCustomBuilderControl[] aSCBCIn = mssIn.segmentBuilderControl();

  242.         int iNumSegmentIn = aCS.length;
  243.         double dblStretchResponseValueLeft = java.lang.Double.NaN;
  244.         double[] adblPredictorOrdinateOut = new double[iNumSegmentIn + 2];
  245.         org.drip.spline.params.SegmentCustomBuilderControl[] aSCBCOut = new
  246.             org.drip.spline.params.SegmentCustomBuilderControl[iNumSegmentIn + 1];
  247.         org.drip.spline.params.SegmentResponseValueConstraint[] aSRVCOut = new
  248.             org.drip.spline.params.SegmentResponseValueConstraint[iNumSegmentIn + 1];

  250.         try {
  251.             dblStretchResponseValueLeft = mssIn.responseValue (mssIn.getLeftPredictorOrdinateEdge());
  252.         } catch (java.lang.Exception e) {
  253.             e.printStackTrace();

  255.             return null;
  256.         }

  258.         for (int i = 0; i < iNumSegmentIn; ++i) {
  259.             aSCBCOut[i] = aSCBCIn[i];

  261.             adblPredictorOrdinateOut[i] = aCS[i].left();

  263.             double dblPredictorOrdinateRight = aCS[i].right();

  265.             try {
  266.                 aSRVCOut[i] = new org.drip.spline.params.SegmentResponseValueConstraint (new double[]
  267.                     {dblPredictorOrdinateRight}, new double[] {1.}, mssIn.responseValue
  268.                         (dblPredictorOrdinateRight));
  269.             } catch (java.lang.Exception e) {
  270.                 e.printStackTrace();

  272.                 return null;
  273.             }
  274.         }

  276.         aSRVCOut[iNumSegmentIn] = srvc;
  277.         aSCBCOut[iNumSegmentIn] = scbc;
  278.         adblPredictorOrdinateOut[iNumSegmentIn + 1] = dblPredictorOrdinateAppendRight;

  280.         adblPredictorOrdinateOut[iNumSegmentIn] = aCS[iNumSegmentIn - 1].right();

  282.         return org.drip.spline.stretch.MultiSegmentSequenceBuilder.CreateCalibratedStretchEstimator
  283.             (mssIn.name(), adblPredictorOrdinateOut, dblStretchResponseValueLeft, aSRVCOut, aSCBCOut, null,
  284.                 bs, iCalibrationDetail);
  285.     }

  287.     /**
  288.      * Insert the Predictor Ordinate Knot into the specified Stretch
  289.      * 
  290.      * @param mssIn Input Stretch
  291.      * @param dblPredictorOrdinate Knot Predictor Ordinate
  292.      * @param sprdLeftSegmentRightEdge Response Values for the Right Edge of the Left Segment
  293.      * @param sprdRightSegmentLeftEdge Response Values for the Left Edge of the Right segment
  294.      * 
  295.      * @return The Stretch with the Predictor Ordinate Knot inserted
  296.      */

  298.     public static final org.drip.spline.stretch.MultiSegmentSequence InsertKnot (
  299.         final org.drip.spline.stretch.MultiSegmentSequence mssIn,
  300.         final double dblPredictorOrdinate,
  301.         final org.drip.spline.params.SegmentPredictorResponseDerivative sprdLeftSegmentRightEdge,
  302.         final org.drip.spline.params.SegmentPredictorResponseDerivative sprdRightSegmentLeftEdge)
  303.     {
  304.         if (!org.drip.numerical.common.NumberUtil.IsValid (dblPredictorOrdinate) || null == mssIn ||
  305.             mssIn.isKnot (dblPredictorOrdinate) || null == sprdLeftSegmentRightEdge || null ==
  306.                 sprdRightSegmentLeftEdge)
  307.             return null;

  309.         org.drip.spline.segment.LatentStateResponseModel[] aCSIn = mssIn.segments();

  311.         int iOutSegmentIndex = 1;
  312.         int iNumSegmentIn = aCSIn.length;
  313.         double[] adblPredictorOrdinateOut = new double[iNumSegmentIn + 2];
  314.         org.drip.spline.params.SegmentPredictorResponseDerivative[] aSPRDOutLeft = new
  315.             org.drip.spline.params.SegmentPredictorResponseDerivative[iNumSegmentIn + 1];
  316.         org.drip.spline.params.SegmentPredictorResponseDerivative[] aSPRDOutRight = new
  317.             org.drip.spline.params.SegmentPredictorResponseDerivative[iNumSegmentIn + 1];
  318.         org.drip.spline.params.SegmentCustomBuilderControl[] aSCBCOut = new
  319.             org.drip.spline.params.SegmentCustomBuilderControl[iNumSegmentIn + 1];

  321.         if (dblPredictorOrdinate < aCSIn[0].left() || dblPredictorOrdinate >
  322.             aCSIn[iNumSegmentIn - 1].right())
  323.             return null;

  325.         adblPredictorOrdinateOut[0] = aCSIn[0].left();

  327.         org.drip.spline.params.SegmentCustomBuilderControl[] aSCBCIn = mssIn.segmentBuilderControl();

  329.         for (int i = 0; i < iNumSegmentIn; ++i) {
  330.             aSCBCOut[iOutSegmentIndex - 1] = aSCBCIn[i];

  332.             aSPRDOutLeft[iOutSegmentIndex - 1] = mssIn.calcSPRD (aCSIn[i].left());

  334.             if (dblPredictorOrdinate > aCSIn[i].left() && dblPredictorOrdinate < aCSIn[i].right()) {
  335.                 aSPRDOutRight[iOutSegmentIndex - 1] = sprdLeftSegmentRightEdge;
  336.                 adblPredictorOrdinateOut[iOutSegmentIndex++] = dblPredictorOrdinate;
  337.                 aSCBCOut[iOutSegmentIndex - 1] = aSCBCIn[i];
  338.                 aSPRDOutLeft[iOutSegmentIndex - 1] = sprdRightSegmentLeftEdge;
  339.             }

  341.             aSPRDOutRight[iOutSegmentIndex - 1] = mssIn.calcSPRD (aCSIn[i].right());

  343.             adblPredictorOrdinateOut[iOutSegmentIndex++] = aCSIn[i].right();
  344.         }

  346.         org.drip.spline.stretch.MultiSegmentSequence mssOut =
  347.             org.drip.spline.stretch.MultiSegmentSequenceBuilder.CreateUncalibratedStretchEstimator
  348.                 (mssIn.name(), adblPredictorOrdinateOut, aSCBCOut);

  350.         if (null == mssOut) return null;

  352.         return mssOut.setupHermite (aSPRDOutLeft, aSPRDOutRight, null, null,
  353.             org.drip.spline.stretch.MultiSegmentSequence.CALIBRATE) ? mssOut : null;
  354.     }

  356.     /**
  357.      * Insert a Cardinal Knot into the specified Stretch at the specified Predictor Ordinate Location
  358.      * 
  359.      * @param mssIn Input Stretch
  360.      * @param dblPredictorOrdinate Knot Predictor Ordinate
  361.      * @param dblCardinalTension Cardinal Tension Parameter
  362.      * 
  363.      * @return The Stretch with the Knot inserted
  364.      */

  366.     public static final org.drip.spline.stretch.MultiSegmentSequence InsertCardinalKnot (
  367.         final org.drip.spline.stretch.MultiSegmentSequence mssIn,
  368.         final double dblPredictorOrdinate,
  369.         final double dblCardinalTension)
  370.     {
  371.         if (!org.drip.numerical.common.NumberUtil.IsValid (dblPredictorOrdinate) ||
  372.             !org.drip.numerical.common.NumberUtil.IsValid (dblCardinalTension) || null == mssIn || mssIn.isKnot
  373.                 (dblPredictorOrdinate))
  374.             return null;

  376.         org.drip.spline.segment.LatentStateResponseModel[] aCSIn = mssIn.segments();

  378.         int iOutSegmentIndex = 0;
  379.         int iNumSegmentIn = aCSIn.length;

  381.         if (dblPredictorOrdinate < aCSIn[0].left() || dblPredictorOrdinate >
  382.             aCSIn[iNumSegmentIn - 1].right())
  383.             return null;

  385.         for (; iOutSegmentIndex < iNumSegmentIn; ++iOutSegmentIndex) {
  386.             if (dblPredictorOrdinate > aCSIn[iOutSegmentIndex].left() && dblPredictorOrdinate <
  387.                 aCSIn[iOutSegmentIndex].right())
  388.                 break;
  389.         }

  391.         org.drip.spline.params.SegmentPredictorResponseDerivative sprdCardinalOut =
  392.             org.drip.spline.params.SegmentPredictorResponseDerivative.CardinalEdgeAggregate
  393.                 (mssIn.calcSPRD (aCSIn[iOutSegmentIndex].left()), mssIn.calcSPRD
  394.                     (aCSIn[iOutSegmentIndex].right()), dblCardinalTension);

  396.         return null == sprdCardinalOut ? null : InsertKnot (mssIn, dblPredictorOrdinate, sprdCardinalOut,
  397.             sprdCardinalOut);
  398.     }

  400.     /**
  401.      * Insert a Catmull-Rom Knot into the specified Stretch at the specified Predictor Ordinate Location
  402.      * 
  403.      * @param mssIn Input Stretch
  404.      * @param dblPredictorOrdinate Knot Predictor Ordinate
  405.      * 
  406.      * @return The Stretch with the Knot inserted
  407.      */

  409.     public static final org.drip.spline.stretch.MultiSegmentSequence InsertCatmullRomKnot (
  410.         final org.drip.spline.stretch.MultiSegmentSequence mssIn,
  411.         final double dblPredictorOrdinate)
  412.     {
  413.         return InsertCardinalKnot (mssIn, dblPredictorOrdinate, 0.);
  414.     }
  415. }
Created with JaCoCo 0.7.9.201702052155