ExerciseBuilder Class Reference

#include <ored/portfolio/optiondata.hpp>

Collaboration diagram for ExerciseBuilder:

Public Member Functions
	ExerciseBuilder (const OptionData &optionData, const std::vector< QuantLib::Leg > legs, bool removeNoticeDatesAfterLastAccrualStart=true)
QuantLib::ext::shared_ptr< QuantLib::Exercise >	exercise () const
const std::vector< QuantLib::Date > &	exerciseDates () const
const std::vector< QuantLib::Date > &	noticeDates () const
bool	isExercised () const
const QuantLib::Date &	exerciseDate () const
QuantLib::ext::shared_ptr< QuantLib::CashFlow >	cashSettlement () const
QuantLib::ext::shared_ptr< QuantLib::CashFlow >	feeSettlement () const

Private Attributes
QuantLib::ext::shared_ptr< QuantLib::Exercise >	exercise_
std::vector< QuantLib::Date >	exerciseDates_
std::vector< QuantLib::Date >	noticeDates_
bool	isExercised_ = false
QuantLib::Date	exerciseDate_
QuantLib::ext::shared_ptr< QuantLib::CashFlow >	cashSettlement_
QuantLib::ext::shared_ptr< QuantLib::CashFlow >	feeSettlement_
Size	exerciseDateIndex_ = QuantLib::Null<QuantLib::Size>()

Detailed Description

Definition at line 148 of file optiondata.hpp.

Constructor & Destructor Documentation

ExerciseBuilder()

ExerciseBuilder	(	const OptionData &	optionData,
		const std::vector< QuantLib::Leg >	legs,
		bool	removeNoticeDatesAfterLastAccrualStart = true
	)

TODO removeNoticeDatesAfterLastAccrualStart is only there for backwards compatibility, we should remove it at some point and handle such notice dates in the callling code as appropriate. If the exercise style is American the flag is set to false always internally.

Definition at line 140 of file optiondata.cpp.

                                                                              {
 
    // for american style exercise, never remove notice dates after last accrual start
 
    if (optionData.style() == "American")
        removeNoticeDatesAfterLastAccrualStart = false;
 
    // only keep a) future exercise dates and b) exercise dates that exercise into a whole
    // accrual period of the underlying; TODO handle exercises into broken periods?
 
    // determine last accrual start date present in the underlying legs
 
    Date lastAccrualStartDate = Date::minDate();
    for (auto const& l : legs) {
        for (auto const& c : l) {
            if (auto cpn = QuantLib::ext::dynamic_pointer_cast<Coupon>(c))
                lastAccrualStartDate = std::max(lastAccrualStartDate, cpn->accrualStartDate());
        }
    }
 
    // get notice period, calendar, bdc
 
    Period noticePeriod = optionData.noticePeriod().empty() ? 0 * Days : parsePeriod(optionData.noticePeriod());
    Calendar noticeCal =
        optionData.noticeCalendar().empty() ? NullCalendar() : parseCalendar(optionData.noticeCalendar());
    BusinessDayConvention noticeBdc =
        optionData.noticeConvention().empty() ? Unadjusted : parseBusinessDayConvention(optionData.noticeConvention());
 
    // build vector of sorted exercise dates
 
    std::vector<QuantLib::Date> sortedExerciseDates;
    if (optionData.exerciseDatesSchedule().hasData()) {
        Schedule schedule = makeSchedule(optionData.exerciseDatesSchedule());
        sortedExerciseDates = schedule.dates();
    } else {
        // For backward compatibility
        for (auto const& d : optionData.exerciseDates())
            sortedExerciseDates.push_back(parseDate(d));
    }
    std::sort(sortedExerciseDates.begin(), sortedExerciseDates.end());
 
    // check that we have exactly two exercise dates for american style
 
    QL_REQUIRE(optionData.style() != "American" || sortedExerciseDates.size() == 2,
               "ExerciseBuilder: expected 2 exercise dates for style 'American', got " << sortedExerciseDates.size());
 
    // build vector of alive exercise dates and corresponding notice dates
 
    std::vector<bool> isExerciseDateAlive(sortedExerciseDates.size(), false);
 
    Date today = Settings::instance().evaluationDate();
 
    for (Size i = 0; i < sortedExerciseDates.size(); i++) {
        Date noticeDate = noticeCal.advance(sortedExerciseDates[i], -noticePeriod, noticeBdc);
        // keep two alive notice dates always for american style exercise
        if (optionData.style() == "American" && i == 0) {
            noticeDate = std::max(today + 1, noticeDate);
            sortedExerciseDates[0] = std::max(today + 1, sortedExerciseDates[0]);
        }
        if (noticeDate > today && (noticeDate <= lastAccrualStartDate || !removeNoticeDatesAfterLastAccrualStart)) {
            isExerciseDateAlive[i] = true;
            noticeDates_.push_back(noticeDate);
            exerciseDates_.push_back(sortedExerciseDates[i]);
            DLOG("Got notice date " << QuantLib::io::iso_date(noticeDate) << " using notice period " << noticePeriod
                                    << ", convention " << noticeBdc << ", calendar " << noticeCal.name()
                                    << " from exercise date " << exerciseDates_.back());
        }
        if (noticeDate > lastAccrualStartDate && removeNoticeDatesAfterLastAccrualStart)
            WLOG("Remove notice date " << ore::data::to_string(noticeDate) << " (exercise date "
                                       << sortedExerciseDates[i] << ") after last accrual start date "
                                       << ore ::data::to_string(lastAccrualStartDate));
    }
 
    // build exercise instance if we have alive notice dates
 
    if (!noticeDates_.empty()) {
        if (optionData.style() == "European") {
            QL_REQUIRE(exerciseDates_.size() == 1, "Got 'European' option style, but "
                                                       << exerciseDates_.size()
                                                       << " exercise dates. Should the style be 'Bermudan'?");
            exercise_ = QuantLib::ext::make_shared<EuropeanExercise>(noticeDates_.back());
        } else if (optionData.style() == "Bermudan" || optionData.style().empty()) {
            // Note: empty exercise style defaults to Bermudan for backwards compatibility
            exercise_ = QuantLib::ext::make_shared<BermudanExercise>(noticeDates_);
        } else if (optionData.style() == "American") {
            QL_REQUIRE(noticeDates_.size() == 2, "ExerciseBuilder: internal error, style is american but got "
                                                     << noticeDates_.size() << " notice dates, expected 2.");
            exercise_ = QuantLib::ext::make_shared<AmericanExercise>(noticeDates_.front(), noticeDates_.back(),
                                                             optionData.payoffAtExpiry());
        } else {
            QL_FAIL("ExerciseBuilder: style '"
                    << optionData.style() << "' not recognized. Expected one of 'European', 'Bermudan', 'American'");
        }
    }
 
    // check if the exercise right was executed and if so set cash settlement amount
 
    if (optionData.exerciseData()) {
        Date d = optionData.exerciseData()->date();
        Real p = optionData.exerciseData()->price();
        auto nextDate = std::lower_bound(sortedExerciseDates.begin(), sortedExerciseDates.end(), d);
        if (nextDate != sortedExerciseDates.end()) {
            isExercised_ = true;
            exerciseDateIndex_ = std::distance(sortedExerciseDates.begin(), nextDate);
            // Note: we set the exercise date to the notification date here
            exerciseDate_ = optionData.style() == "American" ? d : *nextDate;
            DLOG("Option is exercised, exercise date = " << exerciseDate_);
            if (optionData.settlement() == "Cash") {
                Date cashSettlementDate = d; // default to exercise date
                if (optionData.paymentData()) {
                    if (optionData.paymentData()->rulesBased()) {
                        cashSettlementDate = optionData.paymentData()->calendar().advance(
                            d, optionData.paymentData()->lag(), Days, optionData.paymentData()->convention());
                    } else {
                        auto const& dates = optionData.paymentData()->dates();
                        auto nextDate = std::lower_bound(dates.begin(), dates.end(), d);
                        if (nextDate != dates.end())
                            cashSettlementDate = *nextDate;
                    }
                }
                if (p != Null<Real>())
                    cashSettlement_ = QuantLib::ext::make_shared<QuantLib::SimpleCashFlow>(p, cashSettlementDate);
                DLOG("Option is cash settled, amount " << p << " paid on " << cashSettlementDate);
            }
        }
    }
 
    // build fee and rebated exercise instance, if any fees are present
 
    if (!optionData.exerciseFees().empty()) {
 
        QL_REQUIRE(optionData.style() != "American" || optionData.exerciseFees().size() == 1,
                   "ExerciseBuilder: for style 'American' at most one exercise fee is allowed");
 
        // build an exercise date "schedule" by adding the maximum possible date at the end
 
        std::vector<Date> exDatesPlusInf(sortedExerciseDates);
        exDatesPlusInf.push_back(Date::maxDate());
        vector<double> allRebates = buildScheduledVectorNormalised(optionData.exerciseFees(),
                                                                   optionData.exerciseFeeDates(), exDatesPlusInf, 0.0);
 
        // flip the sign of the fee to get a rebate
 
        for (auto& r : allRebates)
            r = -r;
 
        vector<string> feeType = buildScheduledVectorNormalised<string>(
            optionData.exerciseFeeTypes(), optionData.exerciseFeeDates(), exDatesPlusInf, "");
 
        // convert relative to absolute fees if required
 
        for (Size i = 0; i < allRebates.size(); ++i) {
 
            // default to Absolute
 
            if (feeType[i].empty())
                feeType[i] = "Absolute";
 
            if (feeType[i] == "Percentage") {
 
                // get next coupon after exercise to determine relevant notional
 
                std::set<std::pair<Date, Real>> notionals;
                for (auto const& l : legs) {
                    for (auto const& c : l) {
                        if (auto cpn = QuantLib::ext::dynamic_pointer_cast<Coupon>(c)) {
                            if (cpn->accrualStartDate() >= sortedExerciseDates[i])
                                notionals.insert(std::make_pair(cpn->accrualStartDate(), cpn->nominal()));
                        }
                    }
                }
 
                if (notionals.empty())
                    allRebates[i] = 0.0; // notional is zero
                else {
                    Real feeNotional = notionals.begin()->second;
                    DLOG("Convert percentage rebate "
                         << allRebates[i] << " to absolute rebate " << allRebates[i] * feeNotional << " using nominal "
                         << feeNotional << " for exercise date " << QuantLib::io::iso_date(sortedExerciseDates[i]));
                    allRebates[i] *= feeNotional; // multiply percentage fee by relevant notional
                }
 
            } else {
                QL_REQUIRE(feeType[i] == "Absolute", "fee type must be Absolute or Relative");
            }
        }
 
        // set fee settlement conventions
 
        Period feeSettlPeriod = optionData.exerciseFeeSettlementPeriod().empty()
                                    ? 0 * Days
                                    : parsePeriod(optionData.exerciseFeeSettlementPeriod());
 
        Calendar feeSettlCal = optionData.exerciseFeeSettlementCalendar().empty()
                                   ? NullCalendar()
                                   : parseCalendar(optionData.exerciseFeeSettlementCalendar());
 
        BusinessDayConvention feeSettlBdc =
            optionData.exerciseFeeSettlementConvention().empty()
                ? Unadjusted
                : parseBusinessDayConvention(optionData.exerciseFeeSettlementConvention());
 
        // set fee settlement amount if option is exercised
 
        if (isExercised_) {
            feeSettlement_ = QuantLib::ext::make_shared<QuantLib::SimpleCashFlow>(
                -allRebates[exerciseDateIndex_], feeSettlCal.advance(exerciseDate_, feeSettlPeriod, feeSettlBdc));
            DLOG("Settlement fee for exercised option is " << feeSettlement_->amount() << " paid on "
                                                           << feeSettlement_->date() << ".");
        }
 
        // update exercise instance with rebate information
 
        if (exercise_ != nullptr) {
            vector<double> rebates;
            for (Size i = 0; i < sortedExerciseDates.size(); ++i) {
                if (isExerciseDateAlive[i])
                    rebates.push_back(allRebates[i]);
            }
            if (optionData.style() == "American") {
                // Note: we compute the settl date relative to notification, not exercise here
                exercise_ = QuantLib::ext::make_shared<QuantExt::RebatedExercise>(*exercise_, rebates.front(), feeSettlPeriod,
                                                                          feeSettlCal, feeSettlBdc);
                auto dbgEx = QuantLib::ext::static_pointer_cast<QuantExt::RebatedExercise>(exercise_);
                DLOG("Got rebate " << dbgEx->rebate(0) << " for American exercise with fee settle period "
                                   << feeSettlPeriod << ", cal " << feeSettlCal << ", bdc " << feeSettlBdc);
            } else {
                exercise_ = QuantLib::ext::make_shared<QuantExt::RebatedExercise>(*exercise_, exerciseDates_, rebates,
                                                                          feeSettlPeriod, feeSettlCal, feeSettlBdc);
                auto dbgEx = QuantLib::ext::static_pointer_cast<QuantExt::RebatedExercise>(exercise_);
                for (Size i = 0; i < exerciseDates_.size(); ++i) {
                    DLOG("Got rebate " << dbgEx->rebate(i) << " with payment date "
                                       << QuantLib::io::iso_date(dbgEx->rebatePaymentDate(i))
                                       << " (exercise date=" << QuantLib::io::iso_date(exerciseDates_[i])
                                       << ") using rebate settl period " << feeSettlPeriod << ", calendar "
                                       << feeSettlCal << ", convention " << feeSettlBdc);
                }
            }
        }
    } // if exercise fees are given
} // ExerciseBuilder()

Here is the call graph for this function:

Member Function Documentation

exercise()

QuantLib::ext::shared_ptr< QuantLib::Exercise > exercise

(

)

const

Definition at line 157 of file optiondata.hpp.

{ return exercise_; }

Here is the caller graph for this function:

exerciseDates()

const std::vector< QuantLib::Date > & exerciseDates

(

)

const

Definition at line 159 of file optiondata.hpp.

{ return exerciseDates_; }

noticeDates()

const std::vector< QuantLib::Date > & noticeDates

(

)

const

Definition at line 161 of file optiondata.hpp.

{ return noticeDates_; }

isExercised()

bool isExercised

(

)

const

Definition at line 164 of file optiondata.hpp.

{ return isExercised_; }

exerciseDate()

const QuantLib::Date & exerciseDate

(

)

const

Definition at line 166 of file optiondata.hpp.

{ return exerciseDate_; }

cashSettlement()

QuantLib::ext::shared_ptr< QuantLib::CashFlow > cashSettlement

(

)

const

Definition at line 168 of file optiondata.hpp.

{ return cashSettlement_; }

feeSettlement()

QuantLib::ext::shared_ptr< QuantLib::CashFlow > feeSettlement

(

)

const

Definition at line 170 of file optiondata.hpp.

{ return feeSettlement_; }

Member Data Documentation

exercise_

QuantLib::ext::shared_ptr<QuantLib::Exercise> exercise_

private

Definition at line 173 of file optiondata.hpp.

exerciseDates_

std::vector<QuantLib::Date> exerciseDates_

private

Definition at line 175 of file optiondata.hpp.

noticeDates_

std::vector<QuantLib::Date> noticeDates_

private

Definition at line 176 of file optiondata.hpp.

isExercised_

bool isExercised_ = false

private

Definition at line 178 of file optiondata.hpp.

exerciseDate_

QuantLib::Date exerciseDate_

private

Definition at line 179 of file optiondata.hpp.

cashSettlement_

QuantLib::ext::shared_ptr<QuantLib::CashFlow> cashSettlement_

private

Definition at line 180 of file optiondata.hpp.

feeSettlement_

QuantLib::ext::shared_ptr<QuantLib::CashFlow> feeSettlement_

private

Definition at line 181 of file optiondata.hpp.

exerciseDateIndex_

Size exerciseDateIndex_ = QuantLib::Null<QuantLib::Size>()

private

Definition at line 184 of file optiondata.hpp.