FlatForwardDiscountCurve.java

package org.drip.state.nonlinear;

/*
 * -*- mode: java; tab-width: 4; indent-tabs-mode: nil; c-basic-offset: 4 -*-
 */

/*!
 * Copyright (C) 2020 Lakshmi Krishnamurthy
 * Copyright (C) 2019 Lakshmi Krishnamurthy
 * Copyright (C) 2018 Lakshmi Krishnamurthy
 * Copyright (C) 2017 Lakshmi Krishnamurthy
 * Copyright (C) 2016 Lakshmi Krishnamurthy
 * Copyright (C) 2015 Lakshmi Krishnamurthy
 * Copyright (C) 2014 Lakshmi Krishnamurthy
 * Copyright (C) 2013 Lakshmi Krishnamurthy
 * Copyright (C) 2012 Lakshmi Krishnamurthy
 * Copyright (C) 2011 Lakshmi Krishnamurthy
 * 
 *  This file is part of DROP, an open-source library targeting analytics/risk, transaction cost analytics,
 *  	asset liability management analytics, capital, exposure, and margin analytics, valuation adjustment
 *  	analytics, and portfolio construction analytics within and across fixed income, credit, commodity,
 *  	equity, FX, and structured products. It also includes auxiliary libraries for algorithm support,
 *  	numerical analysis, numerical optimization, spline builder, model validation, statistical learning,
 *  	and computational support.
 *  
 *  	https://lakshmidrip.github.io/DROP/
 *  
 *  DROP is composed of three modules:
 *  
 *  - DROP Product Core - https://lakshmidrip.github.io/DROP-Product-Core/
 *  - DROP Portfolio Core - https://lakshmidrip.github.io/DROP-Portfolio-Core/
 *  - DROP Computational Core - https://lakshmidrip.github.io/DROP-Computational-Core/
 * 
 * 	DROP Product Core implements libraries for the following:
 * 	- Fixed Income Analytics
 * 	- Loan Analytics
 * 	- Transaction Cost Analytics
 * 
 * 	DROP Portfolio Core implements libraries for the following:
 * 	- Asset Allocation Analytics
 *  - Asset Liability Management Analytics
 * 	- Capital Estimation Analytics
 * 	- Exposure Analytics
 * 	- Margin Analytics
 * 	- XVA Analytics
 * 
 * 	DROP Computational Core implements libraries for the following:
 * 	- Algorithm Support
 * 	- Computation Support
 * 	- Function Analysis
 *  - Model Validation
 * 	- Numerical Analysis
 * 	- Numerical Optimizer
 * 	- Spline Builder
 *  - Statistical Learning
 * 
 * 	Documentation for DROP is Spread Over:
 * 
 * 	- Main                     => https://lakshmidrip.github.io/DROP/
 * 	- Wiki                     => https://github.com/lakshmiDRIP/DROP/wiki
 * 	- GitHub                   => https://github.com/lakshmiDRIP/DROP
 * 	- Repo Layout Taxonomy     => https://github.com/lakshmiDRIP/DROP/blob/master/Taxonomy.md
 * 	- Javadoc                  => https://lakshmidrip.github.io/DROP/Javadoc/index.html
 * 	- Technical Specifications => https://github.com/lakshmiDRIP/DROP/tree/master/Docs/Internal
 * 	- Release Versions         => https://lakshmidrip.github.io/DROP/version.html
 * 	- Community Credits        => https://lakshmidrip.github.io/DROP/credits.html
 * 	- Issues Catalog           => https://github.com/lakshmiDRIP/DROP/issues
 * 	- JUnit                    => https://lakshmidrip.github.io/DROP/junit/index.html
 * 	- Jacoco                   => https://lakshmidrip.github.io/DROP/jacoco/index.html
 * 
 *  Licensed under the Apache License, Version 2.0 (the "License");
 *   	you may not use this file except in compliance with the License.
 *   
 *  You may obtain a copy of the License at
 *  	http://www.apache.org/licenses/LICENSE-2.0
 *  
 *  Unless required by applicable law or agreed to in writing, software
 *  	distributed under the License is distributed on an "AS IS" BASIS,
 *  	WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
 *  
 *  See the License for the specific language governing permissions and
 *  	limitations under the License.
 */

/**
 * <i>FlatForwardDiscountCurve</i> manages the Discounting Latent State, using the Forward Rate as the State
 * Response Representation. It exports the following functionality:
 *
 *  <br><br>
 *  <ul>
 *  	<li>
 *  		Boot Methods - Set/Bump Specific Node Quantification Metric, or Set Flat Value
 *  	</li>
 *  	<li>
 *  		Boot Calibration - Initialize Run, Compute Calibration Metric
 *  	</li>
 *  	<li>
 *  		Compute the discount factor, forward rate, or the zero rate from the Forward Rate Latent State
 *  	</li>
 *  	<li>
 *  		Create a ForwardRateEstimator instance for the given Index
 *  	</li>
 *  	<li>
 *  		Retrieve Array of the Calibration Components
 *  	</li>
 *  	<li>
 *  		Retrieve the Curve Construction Input Set
 *  	</li>
 *  	<li>
 *  		Compute the Jacobian of the Discount Factor Latent State to the input Quote
 *  	</li>
 *  	<li>
 *  		Synthesize scenario Latent State by parallel shifting/custom tweaking the quantification metric
 *  	</li>
 *  	<li>
 *  		Synthesize scenario Latent State by parallel/custom shifting/custom tweaking the manifest measure
 *  	</li>
 *  </ul>
 *
 *  <br><br>
 *  <ul>
 *		<li><b>Module </b> = <a href = "https://github.com/lakshmiDRIP/DROP/tree/master/ProductCore.md">Product Core Module</a></li>
 *		<li><b>Library</b> = <a href = "https://github.com/lakshmiDRIP/DROP/tree/master/FixedIncomeAnalyticsLibrary.md">Fixed Income Analytics</a></li>
 *		<li><b>Project</b> = <a href = "https://github.com/lakshmiDRIP/DROP/tree/master/src/main/java/org/drip/state/README.md">Latent State Inference and Creation Utilities</a></li>
 *		<li><b>Package</b> = <a href = "https://github.com/lakshmiDRIP/DROP/tree/master/src/main/java/org/drip/state/nonlinear/README.md">Nonlinear (i.e., Boot) Latent State Construction</a></li>
 *  </ul>
 * <br><br>
 *
 * @author Lakshmi Krishnamurthy
 */

public class FlatForwardDiscountCurve extends org.drip.state.discount.ExplicitBootDiscountCurve {
	private int _aiDate[] = null;
	private int _iCompoundingFreq = -1;
	private double _adblForwardRate[] = null;
	private boolean _bDiscreteCompounding = false;
	private java.lang.String _strCompoundingDayCount = "";

	protected double yearFract (
		final int iStartDate,
		final int iEndDate)
		throws java.lang.Exception
	{
		return _bDiscreteCompounding ? org.drip.analytics.daycount.Convention.YearFraction (iStartDate,
			iEndDate, _strCompoundingDayCount, false, null, currency()) : 1. * (iEndDate - iStartDate) /
				365.25;
	}

	private FlatForwardDiscountCurve shiftManifestMeasure (
		final double[] adblShift)
	{
		if (!org.drip.numerical.common.NumberUtil.IsValid (adblShift) || null == _ccis) return null;

		org.drip.product.definition.CalibratableComponent[] aCalibInst = _ccis.components();

		org.drip.param.valuation.ValuationParams valParam = _ccis.valuationParameter();

		org.drip.param.valuation.ValuationCustomizationParams quotingParam = _ccis.quotingParameter();

		org.drip.analytics.support.CaseInsensitiveTreeMap<org.drip.analytics.support.CaseInsensitiveTreeMap<java.lang.Double>>
			mapQuote = _ccis.quoteMap();

		org.drip.analytics.support.CaseInsensitiveTreeMap<java.lang.String[]> mapMeasures =
			_ccis.measures();

		org.drip.param.market.LatentStateFixingsContainer lsfc = _ccis.fixing();

		int iNumComp = aCalibInst.length;

		if (adblShift.length != iNumComp) return null;

		try {
			FlatForwardDiscountCurve ffdc = new FlatForwardDiscountCurve (new
				org.drip.analytics.date.JulianDate (_iEpochDate), _strCurrency, _aiDate, _adblForwardRate,
					_bDiscreteCompounding, _strCompoundingDayCount, _iCompoundingFreq);

			for (int i = 0; i < iNumComp; ++i) {
				java.lang.String strInstrumentCode = aCalibInst[i].primaryCode();

				org.drip.analytics.support.CaseInsensitiveTreeMap<java.lang.Double> mapInstrumentQuote =
					mapQuote.get (aCalibInst[i].primaryCode());

				java.lang.String strCalibMeasure = mapMeasures.get (strInstrumentCode)[0];

				if (null == mapInstrumentQuote || !mapInstrumentQuote.containsKey (strCalibMeasure))
					return null;

				org.drip.state.nonlinear.NonlinearCurveBuilder.DiscountCurveNode (valParam, aCalibInst[i],
					mapInstrumentQuote.get (strCalibMeasure) + adblShift[i], strCalibMeasure, false, i, ffdc,
						null, lsfc, quotingParam);
			}

			return ffdc.setCCIS (new org.drip.analytics.input.BootCurveConstructionInput (valParam,
				quotingParam, aCalibInst, mapQuote, mapMeasures, lsfc)) ? ffdc : null;
		} catch (java.lang.Exception e) {
			e.printStackTrace();
		}

		return null;
	}

	/**
	 * Boot-strap a constant forward discount curve from an array of dates and discount rates
	 * 
	 * @param dtStart Epoch Date
	 * @param strCurrency Currency
	 * @param aiDate Array of Dates
	 * @param adblForwardRate Array of Forward Rates
	 * @param bDiscreteCompounding TRUE - Compounding is Discrete
	 * @param strCompoundingDayCount Day Count Convention to be used for Discrete Compounding
	 * @param iCompoundingFreq Frequency to be used for Discrete Compounding
	 * 
	 * @throws java.lang.Exception Thrown if the curve cannot be created
	 */

	public FlatForwardDiscountCurve (
		final org.drip.analytics.date.JulianDate dtStart,
		final java.lang.String strCurrency,
		final int[] aiDate,
		final double[] adblForwardRate,
		final boolean bDiscreteCompounding,
		final java.lang.String strCompoundingDayCount,
		final int iCompoundingFreq)
		throws java.lang.Exception
	{
		super (
			dtStart.julian(),
			strCurrency
		);

		if (null == aiDate || null == adblForwardRate)
			throw new java.lang.Exception ("FlatForwardDiscountCurve ctr: Invalid inputs");

		int iNumDate = aiDate.length;

		if (0 == iNumDate || iNumDate != adblForwardRate.length)
			throw new java.lang.Exception ("FlatForwardDiscountCurve ctr: Invalid inputs");

		_aiDate = new int[iNumDate];
		_iCompoundingFreq = iCompoundingFreq;
		_adblForwardRate = new double[iNumDate];
		_bDiscreteCompounding = bDiscreteCompounding;
		_strCompoundingDayCount = strCompoundingDayCount;

		for (int i = 0; i < iNumDate; ++i) {
			_aiDate[i] = aiDate[i];
			_adblForwardRate[i] = adblForwardRate[i];
		}
	}

	protected FlatForwardDiscountCurve (
		final FlatForwardDiscountCurve dc)
		throws java.lang.Exception
	{
		super (dc.epoch().julian(), dc.currency());

		_aiDate = dc._aiDate;
		_strCurrency = dc._strCurrency;
		_iEpochDate = dc._iEpochDate;
		_adblForwardRate = dc._adblForwardRate;
		_iCompoundingFreq = dc._iCompoundingFreq;
		_bDiscreteCompounding = dc._bDiscreteCompounding;
		_strCompoundingDayCount = dc._strCompoundingDayCount;
	}

	/**
	 * Retrieve the Forward Node Dates
	 * 
	 * @return The Forward Node Dates
	 */

	public int[] dates()
	{
		return _aiDate;
	}

	/**
	 * Retrieve the Forward Node Values
	 * 
	 * @return The Forward Node Values
	 */

	public double[] nodeValues()
	{
		return _adblForwardRate;
	}

	/**
	 * Retrieve the Discrete Compounding Flag
	 * 
	 * @return TRUE - Discrete Compounding
	 */

	public boolean discreteCompounding()
	{
		return _bDiscreteCompounding;
	}

	/**
	 * Retrieve the Compounding Frequency
	 * 
	 * @return The Compounding Frequency
	 */

	public int compoundingFrequency()
	{
		return _iCompoundingFreq;
	}

	/**
	 * Retrieve the Compounding Day Count
	 * 
	 * @return The Compounding Day Count
	 */

	public java.lang.String compoundingDayCount()
	{
		return _strCompoundingDayCount;
	}

	@Override public double df (
		final int iDate)
		throws java.lang.Exception
	{
		if (iDate <= _iEpochDate) return 1.;

		int i = 0;
		double dblDF = 1.;
		double dblExpArg = 0.;
		int iStartDate = _iEpochDate;
		int iNumDate = _aiDate.length;

		while (i < iNumDate && (int) iDate >= (int) _aiDate[i]) {
			if (_bDiscreteCompounding)
				dblDF *= java.lang.Math.pow (1. + (_adblForwardRate[i] / _iCompoundingFreq), -1. * yearFract
					(iStartDate, _aiDate[i]) * _iCompoundingFreq);
				// dblDF /= (1. + (_adblForwardRate[i] * yearFract (iStartDate, _aiDate[i])));
			else
				dblExpArg -= _adblForwardRate[i] * yearFract (iStartDate, _aiDate[i]);

			iStartDate = _aiDate[i++];
		}

		if (i >= iNumDate) i = iNumDate - 1;

		if (_bDiscreteCompounding)
			dblDF *= java.lang.Math.pow (1. + (_adblForwardRate[i] / _iCompoundingFreq), -1. * yearFract
				(iStartDate, iDate) * _iCompoundingFreq);
			// dblDF /= (1. + (_adblForwardRate[i] * yearFract (iStartDate, iDate)));
		else
			dblExpArg -= _adblForwardRate[i] * yearFract (iStartDate, iDate);

		return (_bDiscreteCompounding ? dblDF : java.lang.Math.exp (dblExpArg)) * turnAdjust (_iEpochDate,
			iDate);
	}

	@Override public double forward (
		final int iDate1,
		final int iDate2)
		throws java.lang.Exception
	{
		int iStartDate = epoch().julian();

		if (iDate1 < iStartDate || iDate2 < iStartDate) return 0.;

		return 365.25 / (iDate2 - iDate1) * java.lang.Math.log (df (iDate1) / df (iDate2));
	}

	@Override public double zero (
		final int iDate)
		throws java.lang.Exception
	{
		double iStartDate = epoch().julian();

		if (iDate < iStartDate) return 0.;

		return -365.25 / (iDate - iStartDate) * java.lang.Math.log (df (iDate));
	}

	@Override public org.drip.state.forward.ForwardRateEstimator forwardRateEstimator (
		final int iDate,
		final org.drip.state.identifier.ForwardLabel fri)
	{
		return null;
	}

	@Override public java.util.Map<java.lang.Integer, java.lang.Double> canonicalTruthness (
		final java.lang.String strLatentQuantificationMetric)
	{
		return null;
	}

	@Override public FlatForwardDiscountCurve parallelShiftManifestMeasure (
		final java.lang.String strManifestMeasure,
		final double dblShift)
	{
		if (!org.drip.numerical.common.NumberUtil.IsValid (dblShift) || null == _ccis) return null;

		org.drip.product.definition.CalibratableComponent[] aCalibInst = _ccis.components();

		int iNumComp = aCalibInst.length;
		double[] adblShift = new double[iNumComp];

		for (int i = 0; i < iNumComp; ++i)
			adblShift[i] = dblShift;

		return shiftManifestMeasure (adblShift);
	}

	@Override public FlatForwardDiscountCurve shiftManifestMeasure (
		final int iSpanIndex,
		final java.lang.String strManifestMeasure,
		final double dblShift)
	{
		if (!org.drip.numerical.common.NumberUtil.IsValid (dblShift) || null == _ccis) return null;

		org.drip.product.definition.CalibratableComponent[] aCalibInst = _ccis.components();

		int iNumComp = aCalibInst.length;
		double[] adblShift = new double[iNumComp];

		if (iSpanIndex >= iNumComp) return null;

		for (int i = 0; i < iNumComp; ++i)
			adblShift[i] = i == iSpanIndex ? dblShift : 0.;

		return shiftManifestMeasure (adblShift);
	}

	@Override public org.drip.state.discount.ExplicitBootDiscountCurve customTweakManifestMeasure (
		final java.lang.String strManifestMeasure,
		final org.drip.param.definition.ManifestMeasureTweak rvtp)
	{
		return shiftManifestMeasure (org.drip.analytics.support.Helper.TweakManifestMeasure
			(_adblForwardRate, rvtp));
	}

	@Override public FlatForwardDiscountCurve parallelShiftQuantificationMetric (
		final double dblShift)
	{
		if (!org.drip.numerical.common.NumberUtil.IsValid (dblShift)) return null;

		int iNumDate = _adblForwardRate.length;
		double[] adblForwardRate = new double[iNumDate];

		for (int i = 0; i < iNumDate; ++i)
			adblForwardRate[i] = _adblForwardRate[i] + dblShift;

		try {
			return new FlatForwardDiscountCurve (new org.drip.analytics.date.JulianDate (_iEpochDate),
				_strCurrency, _aiDate, adblForwardRate, _bDiscreteCompounding, _strCompoundingDayCount,
					_iCompoundingFreq);
		} catch (java.lang.Exception e) {
			e.printStackTrace();
		}

		return null;
	}

	@Override public org.drip.analytics.definition.Curve customTweakQuantificationMetric (
		final org.drip.param.definition.ManifestMeasureTweak rvtp)
	{
		try {
			return new FlatForwardDiscountCurve (new org.drip.analytics.date.JulianDate (_iEpochDate),
				_strCurrency, _aiDate, org.drip.analytics.support.Helper.TweakManifestMeasure
					(_adblForwardRate, rvtp), _bDiscreteCompounding, _strCompoundingDayCount,
						_iCompoundingFreq);
		} catch (java.lang.Exception e) {
			e.printStackTrace();
		}

		return null;
	}

	@Override public FlatForwardDiscountCurve createBasisRateShiftedCurve (
		final int[] aiDate,
		final double[] adblBasis)
	{
		if (null == aiDate || null == adblBasis) return null;

		int iNumDate = aiDate.length;

		if (0 == iNumDate || iNumDate != adblBasis.length) return null;

		double[] adblShiftedRate = new double[iNumDate];

		try {
			for (int i = 0; i < aiDate.length; ++i)
				adblShiftedRate[i] = zero (aiDate[i]) + adblBasis[i];

			return new FlatForwardDiscountCurve (new org.drip.analytics.date.JulianDate (_iEpochDate),
				_strCurrency, aiDate, adblShiftedRate, _bDiscreteCompounding, _strCompoundingDayCount,
					_iCompoundingFreq);
		} catch (java.lang.Exception e) {
			e.printStackTrace();
		}

		return null;
	}

	@Override public java.lang.String latentStateQuantificationMetric()
	{
		return org.drip.analytics.definition.LatentStateStatic.DISCOUNT_QM_ZERO_RATE;
	}

	@Override public org.drip.numerical.differentiation.WengertJacobian jackDDFDManifestMeasure (
		final int iDate,
		final java.lang.String strManifestMeasure)
	{
		if (!org.drip.numerical.common.NumberUtil.IsValid (iDate)) return null;

		int i = 0;
		double dblDF = java.lang.Double.NaN;
		double iStartDate = _iEpochDate;
		org.drip.numerical.differentiation.WengertJacobian wj = null;

		try {
			wj = new org.drip.numerical.differentiation.WengertJacobian (1, _adblForwardRate.length);
		} catch (java.lang.Exception e) {
			e.printStackTrace();

			return null;
		}

		if (iDate <= _iEpochDate) {
			if (!wj.setWengert (0, 0.)) return null;

			return wj;
		}

		try {
			if (!wj.setWengert (0, dblDF = df (iDate))) return null;
		} catch (java.lang.Exception e) {
			e.printStackTrace();

			return null;
		}

		while (i < _adblForwardRate.length && (int) iDate >= (int) _aiDate[i]) {
			if (!wj.accumulatePartialFirstDerivative (0, i, dblDF * (iStartDate - _aiDate[i]) / 365.25))
				return null;

			iStartDate = _aiDate[i++];
		}

		if (i >= _adblForwardRate.length) i = _adblForwardRate.length - 1;

		return wj.accumulatePartialFirstDerivative (0, i, dblDF * (iStartDate - iDate) / 365.25) ? wj :
			null;
	}

	@Override public boolean setNodeValue (
		final int iNodeIndex,
		final double dblValue)
	{
		if (!org.drip.numerical.common.NumberUtil.IsValid (dblValue) || iNodeIndex > _adblForwardRate.length)
			return false;

		for (int i = iNodeIndex; i < _adblForwardRate.length; ++i)
			_adblForwardRate[i] = dblValue;

		return true;
	}

	@Override public boolean bumpNodeValue (
		final int iNodeIndex,
		final double dblValue)
	{
		if (!org.drip.numerical.common.NumberUtil.IsValid (dblValue) || iNodeIndex > _adblForwardRate.length)
			return false;

		for (int i = iNodeIndex; i < _adblForwardRate.length; ++i)
			_adblForwardRate[i] += dblValue;

		return true;
	}

	@Override public boolean setFlatValue (
		final double dblValue)
	{
		if (!org.drip.numerical.common.NumberUtil.IsValid (dblValue)) return false;

		for (int i = 0; i < _adblForwardRate.length; ++i)
			_adblForwardRate[i] = dblValue;

		return true;
	}
}