basket.hpp

/* -*- mode: c++; tab-width: 4; indent-tabs-mode: nil; c-basic-offset: 4 -*- */
 
/*
 Copyright (C) 2008 Roland Lichters
 Copyright (C) 2009, 2014 Jose Aparicio
 
 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_basket_hpp
#define quantlib_basket_hpp
 
#include <ql/instruments/claim.hpp>
#include <ql/termstructures/defaulttermstructure.hpp>
#include <ql/patterns/lazyobject.hpp>
#include <ql/experimental/credit/defaultprobabilitykey.hpp>
#include <ql/experimental/credit/issuer.hpp>
#include <ql/experimental/credit/recoveryratemodel.hpp>
#include <ql/experimental/credit/pool.hpp>
#include <ql/experimental/credit/loss.hpp>
 
namespace QuantLib {
 
    class DefaultLossModel;
 
    class Basket : public LazyObject {
      public:
        Basket() = default;
        Basket(const Date& refDate,
               const std::vector<std::string>& names,
               std::vector<Real> notionals,
               ext::shared_ptr<Pool> pool,
               Real attachmentRatio = 0.0,
               Real detachmentRatio = 1.0,
               ext::shared_ptr<Claim> claim = ext::shared_ptr<Claim>(new FaceValueClaim()));
        void update() override {
            computeBasket();
            LazyObject::update();
        }
        void computeBasket() const {
            Date today = Settings::instance().evaluationDate();
            /* update cache values at the calculation date (work as arguments 
              to the Loss Models)
            \to do: IMPORTANT: notice that defaults added to Issuers dont get
            notify as the codes stnds today. Issuers need to be observables.
            */
            //this one must remain on top since there are dependencies
            evalDateLiveKeys_      = remainingDefaultKeys(today);
            evalDateSettledLoss_   = settledLoss(today);
            evalDateRemainingNot_  = remainingNotional(today);
            evalDateLiveNotionals_ = remainingNotionals(today);
            evalDateLiveNames_     = remainingNames(today);
            evalDateAttachAmount_  = remainingAttachmentAmount(today);
            evalDateDetachAmmount_ = 
                remainingDetachmentAmount(today);
            evalDateLiveList_ = liveList(today);
        }
        Size size() const;
        const std::vector<std::string>& names() const {return pool_->names();}
        const std::vector<Real>& notionals() const;
        Real notional() const;
        Real exposure(const std::string& name, const Date& = Date()) const;
        const ext::shared_ptr<Pool>& pool() const;
        std::vector<DefaultProbKey> defaultKeys() const;
        const Date& refDate() const {return refDate_;}
        Real attachmentRatio() const {return attachmentRatio_;}
        Real detachmentRatio() const {return detachmentRatio_;}
        Real basketNotional() const {return basketNotional_;}
        Real trancheNotional() const {return trancheNotional_;}
        Real attachmentAmount() const {return attachmentAmount_;}
        Real detachmentAmount() const {return detachmentAmount_;}
        ext::shared_ptr<Claim> claim() const {return claim_;}
        std::vector<Probability> probabilities(const Date& d) const;
        Real settledLoss() const;
        Real settledLoss(const Date&) const;
        Real cumulatedLoss() const;
        Real cumulatedLoss(const Date&) const;
        Real remainingNotional() const;
        Real remainingNotional(const Date&) const;
        const std::vector<Real>& remainingNotionals() const;
        std::vector<Real> remainingNotionals(const Date&) const;
        const std::vector<std::string>& remainingNames() const;
        std::vector<std::string> remainingNames(const Date&) const;
        const std::vector<DefaultProbKey>& remainingDefaultKeys() const;
        std::vector<DefaultProbKey> remainingDefaultKeys(const Date&) const;
        Size remainingSize() const;
        Size remainingSize(const Date&) const;
        std::vector<Probability> remainingProbabilities(const Date& d) const;
        Real remainingAttachmentAmount() const;
        Real remainingAttachmentAmount(const Date& endDate) const;
 
        Real remainingDetachmentAmount() const;
        Real remainingDetachmentAmount(const Date& endDate) const;
 
        Real remainingTrancheNotional() const {
            calculate();
            return evalDateDetachAmmount_ - evalDateAttachAmount_;
        }
        Real remainingTrancheNotional(const Date& endDate) const {
            calculate();
            return remainingDetachmentAmount(endDate) - 
                remainingAttachmentAmount(endDate);
        }
        const std::vector<Size>& liveList() const;
        std::vector<Size> liveList(const Date&) const;//?? keep?
        void setLossModel(
            const ext::shared_ptr<DefaultLossModel>& lossModel);
        Real expectedTrancheLoss(const Date& d) const;
        Probability probOverLoss(const Date& d, Real lossFraction) const;
        Real percentile(const Date& d, Probability prob) const;
        Real expectedShortfall(const Date& d, Probability prob) const;
        /* Split a portfolio loss along counterparties. Typically loss 
        corresponds to some percentile.*/
        std::vector<Real> splitVaRLevel(const Date& date, Real loss) const;
        std::map<Real, Probability> lossDistribution(const Date&) const;
        Real densityTrancheLoss(const Date& d, Real lossFraction) const;
        Real defaultCorrelation(const Date& d, Size iName, Size jName) const;
        std::vector<Probability> probsBeingNthEvent(
            Size n, const Date& d) const;
        Probability probAtLeastNEvents(Size n, const Date& d) const;
        Real recoveryRate(const Date& d, Size iName) const;
      private:
        // LazyObject interface
        void performCalculations() const override;
 
        std::vector<Real> notionals_;
        ext::shared_ptr<Pool> pool_;
        const ext::shared_ptr<Claim> claim_;
 
        Real attachmentRatio_;
        Real detachmentRatio_;
        Real basketNotional_;
        mutable Real attachmentAmount_;
        mutable Real detachmentAmount_;
        mutable Real trancheNotional_;
        /* Caches. Most of the times one wants statistics on the distribution of
        futures losses at arbitrary dates but some problems (e.g. derivatives 
        pricing) work with todays (evalDate) magnitudes which do not require a 
        loss model and would be too expensive to recompute on every call.
        */
        mutable Real evalDateSettledLoss_,
            evalDateRemainingNot_,
            evalDateAttachAmount_,
            evalDateDetachAmmount_;
        mutable std::vector<Size> evalDateLiveList_;
        mutable std::vector<Real> evalDateLiveNotionals_;
        mutable std::vector<std::string> evalDateLiveNames_;
        mutable std::vector<DefaultProbKey> evalDateLiveKeys_;
        const Date refDate_;
        /* It is the basket responsibility to ensure that the model assigned it 
          is properly initialized to the basket current data. 
          This might not be the case for various reasons: the basket data might
          have been updated, the evaluation date has changed or the model has 
          received another request from another basket pointing to it. For
          this last reason we can never be sure between calls that this is the 
          case (and that is true in a single thread environment only).
        */
        ext::shared_ptr<DefaultLossModel> lossModel_;
    };
 
    // ------------ Inlines -------------------------------------------------
 
    inline Size Basket::size() const {
        return pool_->size();
    }
 
    inline const std::vector<Real>& Basket::notionals() const {
        return notionals_;
    }
 
    inline std::vector<DefaultProbKey> Basket::defaultKeys() const {
        return pool_->defaultKeys();
    }
 
    inline const ext::shared_ptr<Pool>& Basket::pool() const {
        return pool_;
    }
 
    inline const std::vector<Size>& Basket::liveList() const {
        return evalDateLiveList_;
    }
 
    inline Real Basket::remainingDetachmentAmount() const {
        return evalDateDetachAmmount_;
    }
 
    inline Real Basket::remainingAttachmentAmount() const {
        return evalDateAttachAmount_;
    }
 
    inline const std::vector<std::string>& Basket::remainingNames() const {
        return evalDateLiveNames_;
    }
 
    inline const std::vector<Real>& Basket::remainingNotionals() const {
        return evalDateLiveNotionals_;
    }
 
    inline Real Basket::cumulatedLoss() const {
        return this->evalDateSettledLoss_;
    }
    
    inline Real Basket::settledLoss() const {
        return evalDateSettledLoss_;
    }
 
    inline const std::vector<DefaultProbKey>& 
        Basket::remainingDefaultKeys() const 
    {
        return evalDateLiveKeys_;
    }
 
}
 
 
#endif