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

/*
 Copyright (C) 2002, 2003 RiskMap srl
 Copyright (C) 2003, 2004, 2005, 2006 StatPro Italia srl
 Copyright (C) 2015 Peter Caspers
 Copyright (C) 2015 Michael von den Driesch

 This file is part of QuantLib, a free-software/open-source library
 for financial quantitative analysts and developers - http://quantlib.org/

 QuantLib is free software: you can redistribute it and/or modify it
 under the terms of the QuantLib license.  You should have received a
 copy of the license along with this program; if not, please email
 <quantlib-dev@lists.sf.net>. The license is also available online at
 <https://www.quantlib.org/license.shtml>.

 This program is distributed in the hope that it will be useful, but WITHOUT
 ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS
 FOR A PARTICULAR PURPOSE.  See the license for more details.
*/

/*! \file optionletvolatilitystructure.hpp
    \brief optionlet (caplet/floorlet) volatility structure
*/

#ifndef quantlib_optionlet_volatility_structure_hpp
#define quantlib_optionlet_volatility_structure_hpp

#include <ql/termstructures/voltermstructure.hpp>
#include <ql/termstructures/volatility/optionlet/optionletstripper.hpp>
#include <ql/termstructures/volatility/volatilitytype.hpp>

namespace QuantLib {

    class SmileSection;

    //! Optionlet (caplet/floorlet) volatility structure
    /*! This class is purely abstract and defines the interface of
        concrete structures which will be derived from this one.
    */
    class OptionletVolatilityStructure : public VolatilityTermStructure {
      public:
        /*! \name Constructors
            See the TermStructure documentation for issues regarding
            constructors.
        */
        //@{
        //! default constructor
        /*! \warning term structures initialized by means of this
                     constructor must manage their own reference date
                     by overriding the referenceDate() method.
        */
        OptionletVolatilityStructure(BusinessDayConvention bdc = Following,
                                     const DayCounter& dc = DayCounter());
        //! initialize with a fixed reference date
        OptionletVolatilityStructure(const Date& referenceDate,
                                     const Calendar& cal,
                                     BusinessDayConvention bdc,
                                     const DayCounter& dc = DayCounter());
        //! calculate the reference date based on the global evaluation date
        OptionletVolatilityStructure(Natural settlementDays,
                                     const Calendar&,
                                     BusinessDayConvention bdc,
                                     const DayCounter& dc = DayCounter());
        //@}
        ~OptionletVolatilityStructure() override = default;
        //! \name Volatility and Variance
        //@{
        //! returns the volatility for a given option tenor and strike rate
        Volatility volatility(const Period& optionTenor,
                              Rate strike,
                              bool extrapolate = false) const;
        //! returns the volatility for a given option date and strike rate
        Volatility volatility(const Date& optionDate,
                              Rate strike,
                              bool extrapolate = false) const;
        //! returns the volatility for a given option time and strike rate
        Volatility volatility(Time optionTime,
                              Rate strike,
                              bool extrapolate = false) const;

        //! returns the Black variance for a given option tenor and strike rate
        Real blackVariance(const Period& optionTenor,
                           Rate strike,
                           bool extrapolate = false) const;
        //! returns the Black variance for a given option date and strike rate
        Real blackVariance(const Date& optionDate,
                           Rate strike,
                           bool extrapolate = false) const;
        //! returns the Black variance for a given option time and strike rate
        Real blackVariance(Time optionTime,
                           Rate strike,
                           bool extrapolate = false) const;

        //! returns the smile for a given option tenor
        ext::shared_ptr<SmileSection> smileSection(const Period& optionTenor,
                                                     bool extr = false) const;
        //! returns the smile for a given option date
        ext::shared_ptr<SmileSection> smileSection(const Date& optionDate,
                                                     bool extr = false) const;
        //! returns the smile for a given option time
        ext::shared_ptr<SmileSection> smileSection(Time optionTime,
                                                     bool extr = false) const;
        //@}
        virtual VolatilityType volatilityType() const;
        virtual Real displacement() const;

      protected:
        virtual ext::shared_ptr<SmileSection> smileSectionImpl(
                                                const Date& optionDate) const;
        //! implements the actual smile calculation in derived classes
        virtual ext::shared_ptr<SmileSection> smileSectionImpl(
                                                    Time optionTime) const = 0;
        virtual Volatility volatilityImpl(const Date& optionDate,
                                          Rate strike) const;
        //! implements the actual volatility calculation in derived classes
        virtual Volatility volatilityImpl(Time optionTime,
                                          Rate strike) const = 0;
    };

    // inline definitions

    // 1. Period-based methods convert Period to Date and then
    //    use the equivalent Date-based methods
    inline Volatility
    OptionletVolatilityStructure::volatility(const Period& optionTenor,
                                             Rate strike,
                                             bool extrapolate) const {
        Date optionDate = optionDateFromTenor(optionTenor);
        return volatility(optionDate, strike, extrapolate);
    }

    inline
    Real OptionletVolatilityStructure::blackVariance(const Period& optionTenor,
                                                     Rate strike,
                                                     bool extrapolate) const {
        Date optionDate = optionDateFromTenor(optionTenor);
        return blackVariance(optionDate, strike, extrapolate);
    }

    inline ext::shared_ptr<SmileSection>
    OptionletVolatilityStructure::smileSection(const Period& optionTenor,
                                               bool extrapolate) const {
        Date optionDate = optionDateFromTenor(optionTenor);
        return smileSection(optionDate, extrapolate);
    }

    // 2. blackVariance methods rely on volatility methods
    inline
    Real OptionletVolatilityStructure::blackVariance(const Date& optionDate,
                                                     Rate strike,
                                                     bool extrapolate) const {
        Volatility v = volatility(optionDate, strike, extrapolate);
        Time t = timeFromReference(optionDate);
        return v*v*t;
    }

    inline
    Real OptionletVolatilityStructure::blackVariance(Time optionTime,
                                                     Rate strike,
                                                     bool extrapolate) const {
        Volatility v = volatility(optionTime, strike, extrapolate);
        return v*v*optionTime;
    }

    // 3. relying on xxxImpl methods
    inline Volatility
    OptionletVolatilityStructure::volatility(const Date& optionDate,
                                             Rate strike,
                                             bool extrapolate) const {
        checkRange(optionDate, extrapolate);
        checkStrike(strike, extrapolate);
        return volatilityImpl(optionDate, strike);
    }

    inline Volatility
    OptionletVolatilityStructure::volatility(Time optionTime,
                                             Rate strike,
                                             bool extrapolate) const {
        checkRange(optionTime, extrapolate);
        checkStrike(strike, extrapolate);
        return volatilityImpl(optionTime, strike);
    }

    inline ext::shared_ptr<SmileSection>
    OptionletVolatilityStructure::smileSection(const Date& optionDate,
                                               bool extrapolate) const {
        checkRange(optionDate, extrapolate);
        return smileSectionImpl(optionDate);
    }

    inline ext::shared_ptr<SmileSection>
    OptionletVolatilityStructure::smileSection(Time optionTime,
                                               bool extrapolate) const {
        checkRange(optionTime, extrapolate);
        return smileSectionImpl(optionTime);
    }

    // 4. default implementation of Date-based xxxImpl methods
    //    relying on the equivalent Time-based methods
    inline ext::shared_ptr<SmileSection>
    OptionletVolatilityStructure::smileSectionImpl(const Date& optionDate) const {
        return smileSectionImpl(timeFromReference(optionDate));
    }

    inline Volatility
    OptionletVolatilityStructure::volatilityImpl(const Date& optionDate,
                                                 Rate strike) const {
        return volatilityImpl(timeFromReference(optionDate), strike);
    }

    inline VolatilityType
    OptionletVolatilityStructure::volatilityType() const {
        return ShiftedLognormal;
    }

    inline Real OptionletVolatilityStructure::displacement() const {
        return 0.0;
    }
}

#endif
