cpicoupon.hpp

/* -*- mode: c++; tab-width: 4; indent-tabs-mode: nil; c-basic-offset: 4 -*- */
 
/*
 Copyright (C) 2011 Chris Kenyon
 Copyright (C) 2022 Quaternion Risk Management Ltd
 
 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
 <http://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.
 */
 
#ifndef quantlib_cpicoupon_hpp
#define quantlib_cpicoupon_hpp
 
#include <ql/cashflows/inflationcoupon.hpp>
#include <ql/cashflows/indexedcashflow.hpp>
#include <ql/indexes/inflationindex.hpp>
#include <ql/time/schedule.hpp>
 
namespace QuantLib {
 
 
    class CPICouponPricer;
 
 
    class CPICoupon : public InflationCoupon {
      public:
 
        CPICoupon(Real baseCPI,
                  const Date& paymentDate,
                  Real nominal,
                  const Date& startDate,
                  const Date& endDate,
                  const ext::shared_ptr<ZeroInflationIndex>& index,
                  const Period& observationLag,
                  CPI::InterpolationType observationInterpolation,
                  const DayCounter& dayCounter,
                  Real fixedRate,
                  const Date& refPeriodStart = Date(),
                  const Date& refPeriodEnd = Date(),
                  const Date& exCouponDate = Date());
 
        CPICoupon(const Date& baseDate, // user provided, could be arbitrary
                  const Date& paymentDate,
                  Real nominal,
                  const Date& startDate,
                  const Date& endDate,
                  const ext::shared_ptr<ZeroInflationIndex>& index,
                  const Period& observationLag,
                  CPI::InterpolationType observationInterpolation,
                  const DayCounter& dayCounter,
                  Real fixedRate,
                  const Date& refPeriodStart = Date(),
                  const Date& refPeriodEnd = Date(),
                  const Date& exCouponDate = Date());
 
        CPICoupon(Real baseCPI, // user provided, could be arbitrary
                  const Date& baseDate,
                  const Date& paymentDate,
                  Real nominal,
                  const Date& startDate,
                  const Date& endDate,
                  const ext::shared_ptr<ZeroInflationIndex>& index,
                  const Period& observationLag,
                  CPI::InterpolationType observationInterpolation,
                  const DayCounter& dayCounter,
                  Real fixedRate,
                  const Date& refPeriodStart = Date(),
                  const Date& refPeriodEnd = Date(),
                  const Date& exCouponDate = Date());
 
        QL_DEPRECATED
        CPICoupon(Real baseCPI, // user provided, could be arbitrary
                  const Date& paymentDate,
                  Real nominal,
                  const Date& startDate,
                  const Date& endDate,
                  const ext::shared_ptr<ZeroInflationIndex>& index,
                  const Period& observationLag,
                  CPI::InterpolationType observationInterpolation,
                  const DayCounter& dayCounter,
                  Real fixedRate,
                  Spread spread,
                  const Date& refPeriodStart = Date(),
                  const Date& refPeriodEnd = Date(),
                  const Date& exCouponDate = Date());
 
        QL_DEPRECATED
        CPICoupon(const Date& baseDate, // user provided, could be arbitrary
                  const Date& paymentDate,
                  Real nominal,
                  const Date& startDate,
                  const Date& endDate,
                  const ext::shared_ptr<ZeroInflationIndex>& index,
                  const Period& observationLag,
                  CPI::InterpolationType observationInterpolation,
                  const DayCounter& dayCounter,
                  Real fixedRate,
                  Spread spread,
                  const Date& refPeriodStart = Date(),
                  const Date& refPeriodEnd = Date(),
                  const Date& exCouponDate = Date());
 
        QL_DEPRECATED
        CPICoupon(Real baseCPI, // user provided, could be arbitrary
                  const Date& baseDate,
                  const Date& paymentDate,
                  Real nominal,
                  const Date& startDate,
                  const Date& endDate,
                  const ext::shared_ptr<ZeroInflationIndex>& index,
                  const Period& observationLag,
                  CPI::InterpolationType observationInterpolation,
                  const DayCounter& dayCounter,
                  Real fixedRate,
                  Spread spread,
                  const Date& refPeriodStart = Date(),
                  const Date& refPeriodEnd = Date(),
                  const Date& exCouponDate = Date());
 
        QL_DEPRECATED_DISABLE_WARNING
        ~CPICoupon() override = default;
        QL_DEPRECATED_ENABLE_WARNING
 
 
 
        Real fixedRate() const;
 
        [[deprecated("Do not use this method. A spread doesn't make sense for this coupon.")]]
        Spread spread() const;
 
 
        Rate baseCPI() const;
 
        Date baseDate() const;
 
        CPI::InterpolationType observationInterpolation() const;
 
        ext::shared_ptr<ZeroInflationIndex> cpiIndex() const;
 
 
        Real accruedAmount(const Date&) const override;
 
        Rate indexFixing() const override;
 
 
        Rate indexRatio(Date d) const;
 
 
        Rate adjustedIndexGrowth() const;
 
 
        void accept(AcyclicVisitor&) override;
      protected:
        Real baseCPI_;
        Real fixedRate_;
        [[deprecated("Do not use this data member. A spread doesn't make sense for this coupon.")]]
        Spread spread_;
        CPI::InterpolationType observationInterpolation_;
        Date baseDate_;
 
        bool checkPricerImpl(const ext::shared_ptr<InflationCouponPricer>&) const override;
    };
 
 
 
    class CPICashFlow : public IndexedCashFlow {
      public:
        CPICashFlow(Real notional,
                    const ext::shared_ptr<ZeroInflationIndex>& index,
                    const Date& baseDate,
                    Real baseFixing,
                    const Date& observationDate,
                    const Period& observationLag,
                    CPI::InterpolationType interpolation,
                    const Date& paymentDate,
                    bool growthOnly = false);
 
 
        Real baseFixing() const override;
        Date baseDate() const override;
 
        Date observationDate() const { return observationDate_; }
        Period observationLag() const { return observationLag_; }
        virtual CPI::InterpolationType interpolation() const {
            return interpolation_;
        }
        virtual Frequency frequency() const { return frequency_; }
 
        ext::shared_ptr<ZeroInflationIndex> cpiIndex() const;
 
        Real indexFixing() const override;
 
        Real amount() const override;
 
      protected:
        Real baseFixing_;
        Date observationDate_;
        Period observationLag_;
        CPI::InterpolationType interpolation_;
        Frequency frequency_;
    };
 
 
 
    class CPILeg {
      public:
        CPILeg(const Schedule& schedule,
               ext::shared_ptr<ZeroInflationIndex> index,
               Real baseCPI,
               const Period& observationLag);
        CPILeg& withNotionals(Real notional);
        CPILeg& withNotionals(const std::vector<Real>& notionals);
        CPILeg& withFixedRates(Real fixedRate);
        CPILeg& withFixedRates(const std::vector<Real>& fixedRates);
        CPILeg& withPaymentDayCounter(const DayCounter&);
        CPILeg& withPaymentAdjustment(BusinessDayConvention);
        CPILeg& withPaymentCalendar(const Calendar&);
        CPILeg& withObservationInterpolation(CPI::InterpolationType);
        CPILeg& withSubtractInflationNominal(bool);
        [[deprecated("Do not use this method. A spread doesn't make sense for these coupons.")]]
        CPILeg& withSpreads(Spread spread);
        [[deprecated("Do not use this method. A spread doesn't make sense for these coupons.")]]
        CPILeg& withSpreads(const std::vector<Spread>& spreads);
        CPILeg& withCaps(Rate cap);
        CPILeg& withCaps(const std::vector<Rate>& caps);
        CPILeg& withFloors(Rate floor);
        CPILeg& withFloors(const std::vector<Rate>& floors);
        CPILeg& withExCouponPeriod(const Period&,
                                         const Calendar&,
                                         BusinessDayConvention,
                                         bool endOfMonth = false);
        CPILeg& withBaseDate(const Date& baseDate);
 
        operator Leg() const;
 
      private:
        Schedule schedule_;
        ext::shared_ptr<ZeroInflationIndex> index_;
        Real baseCPI_;
        Period observationLag_;
        std::vector<Real> notionals_;
        std::vector<Real> fixedRates_;
        DayCounter paymentDayCounter_;
        BusinessDayConvention paymentAdjustment_ = ModifiedFollowing;
        Calendar paymentCalendar_;
        CPI::InterpolationType observationInterpolation_ = CPI::AsIndex;
        bool subtractInflationNominal_ = true;
        std::vector<Spread> spreads_;
        std::vector<Rate> caps_, floors_;
        Period exCouponPeriod_;
        Calendar exCouponCalendar_;
        BusinessDayConvention exCouponAdjustment_ = Following;
        bool exCouponEndOfMonth_ = false;
        Date baseDate_ = Null<Date>();
    };
 
 
    // inline definitions
 
    inline Real CPICoupon::fixedRate() const {
        return fixedRate_;
    }
 
    inline Real CPICoupon::spread() const {
        QL_DEPRECATED_DISABLE_WARNING
        return spread_;
        QL_DEPRECATED_ENABLE_WARNING
    }
 
    inline Rate CPICoupon::adjustedIndexGrowth() const {
        QL_DEPRECATED_DISABLE_WARNING
        return (rate()-spread())/fixedRate();
        QL_DEPRECATED_ENABLE_WARNING
    }
 
    inline Rate CPICoupon::indexFixing() const {
        return CPI::laggedFixing(cpiIndex(), accrualEndDate(), observationLag(), observationInterpolation());
    }
 
    inline Rate CPICoupon::baseCPI() const {
        return baseCPI_;
    }
 
    inline Date CPICoupon::baseDate() const {
        return baseDate_;
    }
 
    inline CPI::InterpolationType CPICoupon::observationInterpolation() const {
        return observationInterpolation_;
    }
 
    inline ext::shared_ptr<ZeroInflationIndex> CPICoupon::cpiIndex() const {
        return ext::dynamic_pointer_cast<ZeroInflationIndex>(index());
    }
 
 
    inline ext::shared_ptr<ZeroInflationIndex> CPICashFlow::cpiIndex() const {
        return ext::dynamic_pointer_cast<ZeroInflationIndex>(index());
    }
 
}
 
#endif