OptionHelper.java

  1. package org.drip.analytics.support;

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

  82. /**
  83.  * <i>OptionHelper</i> contains the collection of the option valuation related utility functions used by the
  84.  * modules.
  85.  *
  86.  *  <br><br>
  87.  *  <ul>
  88.  *      <li><b>Module </b> = <a href = "https://github.com/lakshmiDRIP/DROP/tree/master/ProductCore.md">Product Core Module</a></li>
  89.  *      <li><b>Library</b> = <a href = "https://github.com/lakshmiDRIP/DROP/tree/master/FixedIncomeAnalyticsLibrary.md">Fixed Income Analytics</a></li>
  90.  *      <li><b>Project</b> = <a href = "https://github.com/lakshmiDRIP/DROP/tree/master/src/main/java/org/drip/analytics/README.md">Date, Cash Flow, and Cash Flow Period Measure Generation Utilities</a></li>
  91.  *      <li><b>Package</b> = <a href = "https://github.com/lakshmiDRIP/DROP/tree/master/src/main/java/org/drip/analytics/support/README.md">Assorted Support and Helper Utilities</a></li>
  92.  *  </ul>
  93.  * 
  94.  * @author Lakshmi Krishnamurthy
  95.  */

  97. public class OptionHelper {

  99.     static class CrossVolatilityQuantoProduct extends org.drip.function.definition.R1ToR1 {
  100.         org.drip.state.volatility.VolatilityCurve _vcForward = null;
  101.         org.drip.state.volatility.VolatilityCurve _vcForwardToDiscount = null;
  102.         org.drip.function.definition.R1ToR1 _r1r1ForwardForwardToDiscountCorrelation = null;

  104.         CrossVolatilityQuantoProduct (
  105.             final org.drip.state.volatility.VolatilityCurve vcForward,
  106.             final org.drip.state.volatility.VolatilityCurve vcForwardToDiscount,
  107.             final org.drip.function.definition.R1ToR1 r1r1ForwardForwardToDiscountCorrelation)
  108.         {
  109.             super (null);

  111.             _vcForward = vcForward;
  112.             _vcForwardToDiscount = vcForwardToDiscount;
  113.             _r1r1ForwardForwardToDiscountCorrelation = r1r1ForwardForwardToDiscountCorrelation;
  114.         }

  116.         @Override public double evaluate (
  117.             final double dblVariate)
  118.             throws java.lang.Exception
  119.         {
  120.             return _vcForward.impliedVol ((int) dblVariate) * _vcForwardToDiscount.impliedVol ((int)
  121.                 dblVariate) * _r1r1ForwardForwardToDiscountCorrelation.evaluate (dblVariate);
  122.         }
  123.     }

  125.     static class CrossVolatilityConvexityExponent extends org.drip.function.definition.R1ToR1 {
  126.         org.drip.state.volatility.VolatilityCurve _vcForward = null;
  127.         org.drip.state.volatility.VolatilityCurve _vcFunding = null;
  128.         double _dblForwardShiftedLogNormalScaler = java.lang.Double.NaN;
  129.         double _dblFundingShiftedLogNormalScaler = java.lang.Double.NaN;
  130.         org.drip.function.definition.R1ToR1 _r1r1ForwardFundingCorrelation = null;

  132.         CrossVolatilityConvexityExponent (
  133.             final org.drip.state.volatility.VolatilityCurve vcForward,
  134.             final double dblForwardShiftedLogNormalScaler,
  135.             final org.drip.state.volatility.VolatilityCurve vcFunding,
  136.             final double dblFundingShiftedLogNormalScaler,
  137.             final org.drip.function.definition.R1ToR1 r1r1ForwardFundingCorrelation)
  138.         {
  139.             super (null);

  141.             _vcForward = vcForward;
  142.             _vcFunding = vcFunding;
  143.             _r1r1ForwardFundingCorrelation = r1r1ForwardFundingCorrelation;
  144.             _dblForwardShiftedLogNormalScaler = dblForwardShiftedLogNormalScaler;
  145.             _dblFundingShiftedLogNormalScaler = dblFundingShiftedLogNormalScaler;
  146.         }

  148.         @Override public double evaluate (
  149.             final double dblVariate)
  150.             throws java.lang.Exception
  151.         {
  152.             double dblForwardShiftedLogNormalScaler = java.lang.Double.isNaN
  153.                 (_dblForwardShiftedLogNormalScaler) ? 1. : _dblForwardShiftedLogNormalScaler;
  154.             double dblFundingShiftedLogNormalScaler = java.lang.Double.isNaN
  155.                 (_dblFundingShiftedLogNormalScaler) ? 1. : _dblFundingShiftedLogNormalScaler;

  157.             return _r1r1ForwardFundingCorrelation.evaluate (dblVariate) * _vcFunding.impliedVol ((int)
  158.                 dblVariate) * _vcFunding.impliedVol ((int) dblVariate) * dblFundingShiftedLogNormalScaler *
  159.                     dblForwardShiftedLogNormalScaler - _vcForward.impliedVol ((int) dblVariate) *
  160.                         _vcForward.impliedVol ((int) dblVariate) * dblForwardShiftedLogNormalScaler *
  161.                             dblForwardShiftedLogNormalScaler;
  162.         }
  163.     }

  165.     static class PeriodVariance extends org.drip.function.definition.R1ToR1 {
  166.         org.drip.state.volatility.VolatilityCurve _vc = null;

  168.         PeriodVariance (
  169.             final org.drip.state.volatility.VolatilityCurve vc)
  170.         {
  171.             super (null);

  173.             _vc = vc;
  174.         }

  176.         @Override public double evaluate (
  177.             final double dblVariate)
  178.             throws java.lang.Exception
  179.         {
  180.             return _vc.impliedVol ((int) dblVariate) * _vc.impliedVol ((int) dblVariate);
  181.         }
  182.     }

  184.     /**
  185.      * Compute the Integrated Surface Variance given the corresponding volatility and the date spans
  186.      * 
  187.      * @param csqs Market Parameters
  188.      * @param strCustomMetricLabel Custom Metric Label
  189.      * @param iStartDate Evolution Start Date
  190.      * @param iEndDate Evolution End Date
  191.      * 
  192.      * @return The Integrated Volatility Surface
  193.      * 
  194.      * @throws java.lang.Exception Thrown if inputs are invalid
  195.      */

  197.     public static final double IntegratedSurfaceVariance (
  198.         final org.drip.param.market.CurveSurfaceQuoteContainer csqs,
  199.         final java.lang.String strCustomMetricLabel,
  200.         final int iStartDate,
  201.         final int iEndDate)
  202.         throws java.lang.Exception
  203.     {
  204.         if (iEndDate < iStartDate)
  205.             throw new java.lang.Exception ("OptionHelper::IntegratedSurfaceVariance => Invalid Inputs");

  207.         if (null == csqs || null == strCustomMetricLabel || strCustomMetricLabel.isEmpty() || iEndDate ==
  208.             iStartDate)
  209.             return 0.;

  211.         org.drip.state.volatility.VolatilityCurve vc = csqs.customVolatility
  212.             (org.drip.state.identifier.CustomLabel.Standard (strCustomMetricLabel));

  214.         return null != vc ? new PeriodVariance (vc).integrate (iStartDate, iEndDate) / 365.25 : 0.;
  215.     }

  217.     /**
  218.      * Compute the Integrated Surface Variance given the corresponding volatility and the date spans
  219.      * 
  220.      * @param vc The Volatility Curve
  221.      * @param iStartDate Evolution Start Date
  222.      * @param iEndDate Evolution End Date
  223.      * 
  224.      * @return The Integrated Volatility Surface
  225.      * 
  226.      * @throws java.lang.Exception Thrown if inputs are invalid
  227.      */

  229.     public static final double IntegratedSurfaceVariance (
  230.         final org.drip.state.volatility.VolatilityCurve vc,
  231.         final int iStartDate,
  232.         final int iEndDate)
  233.         throws java.lang.Exception
  234.     {
  235.         if (null == vc || iEndDate < iStartDate)
  236.             throw new java.lang.Exception ("OptionHelper::IntegratedSurfaceVariance => Invalid Inputs");

  238.         return null != vc ? new PeriodVariance (vc).integrate (iStartDate, iEndDate) / 365.25 : 0.;
  239.     }

  241.     /**
  242.      * Compute the Integrated Cross Volatility Quanto Product given the corresponding volatility and the
  243.      *  correlation curves, and the date spans
  244.      * 
  245.      * @param vc1 Volatility Curve #1
  246.      * @param vc2 Volatility Curve #2
  247.      * @param r1r1Correlation Correlation Curve
  248.      * @param iStartDate Evolution Start Date
  249.      * @param iEndDate Evolution End Date
  250.      * 
  251.      * @return The Integrated Cross Volatility Quanto Product
  252.      * 
  253.      * @throws java.lang.Exception Thrown if inputs are invalid
  254.      */

  256.     public static final double IntegratedCrossVolQuanto (
  257.         final org.drip.state.volatility.VolatilityCurve vc1,
  258.         final org.drip.state.volatility.VolatilityCurve vc2,
  259.         final org.drip.function.definition.R1ToR1 r1r1Correlation,
  260.         final int iStartDate,
  261.         final int iEndDate)
  262.         throws java.lang.Exception
  263.     {
  264.         if (iEndDate < iStartDate)
  265.             throw new java.lang.Exception ("OptionHelper::IntegratedCrossVolQuanto => Invalid Inputs");

  267.         return null == vc1 || null == vc2 || null == r1r1Correlation ? 0. : new CrossVolatilityQuantoProduct
  268.             (vc1, vc2, r1r1Correlation).integrate (iStartDate, iEndDate) / 365.25;
  269.     }

  271.     /**
  272.      * Compute the Integrated FRA Cross Volatility Convexity Exponent given the corresponding volatility and
  273.      *  the correlation Curves, and the date spans
  274.      * 
  275.      * @param vcForward Volatility Term Structure of the Funding Rate
  276.      * @param vcFunding Volatility Term Structure of the Forward Rate
  277.      * @param r1r1ForwardFundingCorrelation Correlation Term Structure between the Forward and the Funding
  278.      *  States
  279.      * @param dblForwardShiftedLogNormalScaler Scaling for the Forward Log Normal Volatility
  280.      * @param dblFundingShiftedLogNormalScaler Scaling for the Funding Log Normal Volatility
  281.      * @param iStartDate Evolution Start Date
  282.      * @param iEndDate Evolution End Date
  283.      * 
  284.      * @return The Integrated FRA Cross Volatility Convexity Exponent
  285.      * 
  286.      * @throws java.lang.Exception Thrown if inputs are invalid
  287.      */

  289.     public static final double IntegratedFRACrossVolConvexityExponent (
  290.         final org.drip.state.volatility.VolatilityCurve vcForward,
  291.         final org.drip.state.volatility.VolatilityCurve vcFunding,
  292.         final org.drip.function.definition.R1ToR1 r1r1ForwardFundingCorrelation,
  293.         final double dblForwardShiftedLogNormalScaler,
  294.         final double dblFundingShiftedLogNormalScaler,
  295.         final int iStartDate,
  296.         final int iEndDate)
  297.         throws java.lang.Exception
  298.     {
  299.         if (iEndDate < iStartDate)
  300.             throw new java.lang.Exception
  301.                 ("OptionHelper::IntegratedFRACrossVolConvexityExponent => Invalid Inputs");

  303.         return null == vcFunding || null == vcForward || null == r1r1ForwardFundingCorrelation ? 0. : new
  304.             CrossVolatilityConvexityExponent (vcForward, dblForwardShiftedLogNormalScaler, vcFunding,
  305.                 dblFundingShiftedLogNormalScaler, r1r1ForwardFundingCorrelation).integrate (iStartDate,
  306.                     iEndDate) / 365.25;
  307.     }

  309.     /**
  310.      * Compute the Integrated Cross Volatility Quanto Product given the corresponding volatility and the
  311.      *  correlation Curves and the date spans
  312.      * 
  313.      * @param csqs Market Parameters
  314.      * @param strCustomMetricLabel1 Custom Metric Label #1
  315.      * @param strCustomMetricLabel2 Custom Metric Label #2
  316.      * @param iStartDate Evolution Start Date
  317.      * @param iEndDate Evolution End Date
  318.      * 
  319.      * @return The Integrated Cross Volatility Quanto Product
  320.      * 
  321.      * @throws java.lang.Exception Thrown if inputs are invalid
  322.      */

  324.     public static final double IntegratedCrossVolQuanto (
  325.         final org.drip.param.market.CurveSurfaceQuoteContainer csqs,
  326.         final java.lang.String strCustomMetricLabel1,
  327.         final java.lang.String strCustomMetricLabel2,
  328.         final int iStartDate,
  329.         final int iEndDate)
  330.         throws java.lang.Exception
  331.     {
  332.         if (iEndDate < iStartDate)
  333.             throw new java.lang.Exception ("OptionHelper::IntegratedCrossVolQuanto => Invalid Inputs");

  335.         if (null == csqs || null == strCustomMetricLabel1 || strCustomMetricLabel1.isEmpty() || null ==
  336.             strCustomMetricLabel2 || strCustomMetricLabel2.isEmpty() || iEndDate == iStartDate)
  337.             return 0.;

  339.         org.drip.state.identifier.CustomLabel cml1 =
  340.             org.drip.state.identifier.CustomLabel.Standard (strCustomMetricLabel1);

  342.         org.drip.state.identifier.CustomLabel cml2 =
  343.             org.drip.state.identifier.CustomLabel.Standard (strCustomMetricLabel2);

  345.         return null == cml1 || null == cml2 ? 0. : IntegratedCrossVolQuanto (csqs.customVolatility (cml1),
  346.             csqs.customVolatility (cml2), csqs.customCustomCorrelation (cml1, cml2), iStartDate, iEndDate);
  347.     }

  349.     /**
  350.      * Compute the Multiplicative Cross Volatility Quanto Product given the corresponding volatility and the
  351.      *  correlation Curves, and the date spans
  352.      * 
  353.      * @param csqs Market Parameters
  354.      * @param strCustomMetricLabel1 Custom Metric Label #1
  355.      * @param strCustomMetricLabel2 Custom Metric Label #2
  356.      * @param iStartDate Evolution Start Date
  357.      * @param iEndDate Evolution End Date
  358.      * 
  359.      * @return The Multiplicative Cross Volatility Quanto Product
  360.      * 
  361.      * @throws java.lang.Exception Thrown if inputs are invalid
  362.      */

  364.     public static final double MultiplicativeCrossVolQuanto (
  365.         final org.drip.param.market.CurveSurfaceQuoteContainer csqs,
  366.         final java.lang.String strCustomMetricLabel1,
  367.         final java.lang.String strCustomMetricLabel2,
  368.         final int iStartDate,
  369.         final int iEndDate)
  370.         throws java.lang.Exception
  371.     {
  372.         return java.lang.Math.exp (-1. * IntegratedCrossVolQuanto (csqs, strCustomMetricLabel1,
  373.             strCustomMetricLabel2, iStartDate, iEndDate));
  374.     }

  376.     /**
  377.      * Compute the Integrated FRA Cross Volatility Convexity Adjuster given the corresponding volatility and
  378.      *  the correlation Curves and the date spans
  379.      * 
  380.      * @param csqs Market Parameters
  381.      * @param forwardLabel Forward Latent State Label
  382.      * @param fundingLabel Funding Latent State Label
  383.      * @param dblForwardShiftedLogNormalScaler Scaling for the Forward Log Normal Volatility
  384.      * @param dblFundingShiftedLogNormalScaler Scaling for the Funding Log Normal Volatility
  385.      * @param iStartDate Evolution Start Date
  386.      * @param iEndDate Evolution End Date
  387.      * 
  388.      * @return The Integrated FRA Cross Volatility Convexity Adjuster
  389.      * 
  390.      * @throws java.lang.Exception Thrown if inputs are invalid
  391.      */

  393.     public static final double IntegratedFRACrossVolConvexityAdjuster (
  394.         final org.drip.param.market.CurveSurfaceQuoteContainer csqs,
  395.         final org.drip.state.identifier.ForwardLabel forwardLabel,
  396.         final org.drip.state.identifier.FundingLabel fundingLabel,
  397.         final double dblForwardShiftedLogNormalScaler,
  398.         final double dblFundingShiftedLogNormalScaler,
  399.         final int iStartDate,
  400.         final int iEndDate)
  401.         throws java.lang.Exception
  402.     {
  403.         if (iEndDate < iStartDate)
  404.             throw new java.lang.Exception
  405.                 ("OptionHelper::IntegratedFRACrossVolConvexityAdjuster => Invalid Inputs");

  407.         return null == csqs || null == forwardLabel || null == fundingLabel || iEndDate == iStartDate ? 0. :
  408.             IntegratedFRACrossVolConvexityExponent (csqs.fundingVolatility (fundingLabel),
  409.                 csqs.forwardVolatility (forwardLabel), csqs.forwardFundingCorrelation (forwardLabel,
  410.                     fundingLabel), dblFundingShiftedLogNormalScaler, dblForwardShiftedLogNormalScaler,
  411.                         iStartDate, iEndDate);
  412.     }
  413. }
Created with JaCoCo 0.7.9.201702052155