structs.h

// -*-C++-*-  make sure Emacs is in C++ mode
//
// ==================================================
// andrew_kalotay_associates/common/structs.h
// ==================================================
// 
// :Version: 1.0.0
// :Date: 2020-6-1
//
// Copyright (c) 2008-COPYRIGHT, Andrew Kalotay Associates. All rights reserved.
// Consult your license for permissions and restrictions.
// 
// Description:
// ++++++++++++
// 
// - Data structs used for inputs to and outputs from
//   classes.
// - Common structs are in main namespace.
// - Input structs are in namespace ``Input``.
// - Output structs are in namespace ``Output``.
//
// ------------------------------------------------------
// 
#ifndef INCLUDED_ANDREW_KALOTAY_ASSOCIATES_COMMON_STRUCTS_H
#define INCLUDED_ANDREW_KALOTAY_ASSOCIATES_COMMON_STRUCTS_H
 
// Include directives
// ++++++++++++++++++++
//
// `dll_macros`_ : needed for Windows API
// ---------------------------------------
//
// .. _`dll_macros`: dll_macros.html
//
#include "andrew_kalotay_associates/common/dll_macros.h"
 
// 
// `enums`_ used by structs below
// -------------------------------
// 
// .. _`enums`: enums.html
//
#include "andrew_kalotay_associates/common/enums.h"
 
// 
// String_ and Array_ classes
// --------------------------
// .. _`String`: string.html
// .. _`Array`: array.html
// 
#include "andrew_kalotay_associates/common/string.h"
#include "andrew_kalotay_associates/common/array.h"
 
namespace AndrewKalotayAssociates
{
  namespace Common
  {
    COMMON_API
    double QuietNaN();
 
    COMMON_API    
    int IntMax();
 
    // IntMin()
    // --------
    COMMON_API
    int IntMin();
    
    // Common structs
    // +++++++++++++++
    //
    struct COMMON_API Date
    {
      long year;
      long month;
      long day;
 
      Date(long input_year = 0,
           long input_month = 0,
           long input_day = 0);
 
      long to_long() const;
 
      bool operator!() const;
      
      bool operator==(const Date& rhs) const;
      
      bool operator!=(const Date& rhs) const;
 
      bool operator<(const Date& rhs) const;
 
      bool is_before(const Date& rhs) const;
      
      bool operator>(const Date& rhs) const;
    
      bool operator<=(const Date& rhs) const;
    
      bool is_on_or_before(const Date& rhs) const;
      
      bool operator>=(const Date& rhs) const;
 
      Date add_months(int months) const;
      Date add_days(int days) const;
    };
 
 
    struct COMMON_API CalendarPeriod
    {
      Date start;
 
      Date end;
    };
    
    // TimeDifference
    // ---------------
    struct COMMON_API TimeDifference
    {
      long periods;
 
      CalendarUnits::type units;
 
      TimeDifference(long input_periods = IntMin(),
                     CalendarUnits::type input_units = CalendarUnits::unknown);
 
      bool operator==(const TimeDifference& rhs) const;
 
      bool operator!=(const TimeDifference& rhs) const;
 
      long months() const;
 
      double years() const;
 
      bool operator<(const TimeDifference& rhs) const;
      bool operator>(const TimeDifference& rhs) const;
      bool operator<=(const TimeDifference& rhs) const;
      bool operator>=(const TimeDifference& rhs) const;
    };
 
    namespace Input
    {
      //
      // Structs for input data
      // +++++++++++++++++++++++
      //
      // Input::Yield
      // -------------
      struct COMMON_API Yield
      {
        TimeDifference maturity;
 
        double rate;
 
        Yield(TimeDifference input_maturity = TimeDifference(),
              double input_rate = QuietNaN());
 
        ~Yield();
      };
 
      // Input::ForwardYield
      // ---------------------
      struct COMMON_API ForwardYield
      {
        Date settlement_date;
        Yield yield;
 
        ForwardYield();
      
        ForwardYield(const Date& input_date,
                     const Yield& input_yield);
      };
 
      // Input::ParYieldCurve
      // ---------------------
      struct COMMON_API ParYieldCurve
      {
        long simple_business_day_convention;
 
        Daycount::type simple_daycount;
 
        Daycount::type par_daycount;
 
        CalendarFrequency::type par_coupon_frequency;
 
        Array<Yield> simple_yields; 
        Array<ForwardYield> forward_yields;
        Array<Yield> par_yields; 
 
        ParYieldCurve()
        :simple_business_day_convention(0),
        simple_daycount(Daycount::actual_360),
        par_daycount(Daycount::d30_360),
        par_coupon_frequency(CalendarFrequency::semiannual)
        {}
 
        bool operator!() const
        {
          return (0 == simple_yields.size()) &&
            (0 == forward_yields.size()) &&
            (0 == par_yields.size());
        }
      };
 
      // 
      // Input::SpotCurve
      // ----------------
      // 
      // - daycount = Daycount_ convention used for
      //   converting yields into future cashflows
      // - compound_frequency = CalendarFrequency_
      //   used for compounding yields
      // - spot_yields = Array of compounded zero coupon `Input::Yield`_
      // 
      struct COMMON_API SpotCurve
      {
        Daycount::type daycount;
        CalendarFrequency::type compound_frequency;
        Array<Yield> yields; 
 
        bool operator!() const;
      };
 
      // 
      // Input::SpreadCurve
      // -------------------
      struct COMMON_API SpreadCurve
      {
        int sign;
        
        Array<Yield> spreads;
 
        SpreadCurve();
      };
      
      // Input::DiscountFactor
      // ----------------------
      // 
      struct COMMON_API DiscountFactor
      {
        Date date;
 
        double factor;
 
        DiscountFactor(Date input_date = Date(),
                       double input_factor = QuietNaN());
      };
 
      // Input::DiscountCurve
      // ----------------------
      struct COMMON_API DiscountCurve
      {
        Date settlement_date;
        Array<DiscountFactor> discount_factors;
      };
 
      // Input::CurrencyForward
      // -------------------------
      struct COMMON_API CurrencyForward
      {
        Date maturity;
        double rate;
 
        CurrencyForward(Date input_maturity = Date(),
                        double input_rate = QuietNaN());
      };
 
      // Input::CurrencyForwardCurve
      // ---------------------------------
      // forwards = Array_ of `Input::CurrencyForward`_
      //
      struct COMMON_API CurrencyForwardCurve
      {
        Date settlement_date;
        Array<CurrencyForward> forwards;
      };
 
      // Input::IndexValue
      // ----------------------------
      struct COMMON_API IndexValue
      {
        Date date;
        double index;
 
        IndexValue(Date input_date = Date(),
                   double input_index = QuietNaN());
      };
 
      // Input::IndexHistory
      // -----------------------
      struct COMMON_API IndexHistory
      {
        Array<IndexValue> values;
      };
      
      // Input::SwaptionVolatilityMatrix
      // ---------------------------------
      //
      // option_maturities = Array_ of TimeDifference_
      // representing swaption maturities
      //
      // swap_maturities = Array_ of TimeDifference_
      // representing foward swap maturities
      // (relative to option exercise date)
      //
      // volatilities = matrix of volatilities
      // flattened into an Array_ of doubles.
      // Each volatility is specified as an absolute double
      // (0.10 = 10%)
      //
      // If
      //
      // - options_size = option_maturities.size()
      // - swaps_size = swap_maturities.size()
      // - 0 <= j < swaps_size
      // - 0 <= i < options_size
      //
      // then
      //
      // volatilities[j + swaps_size * i] =
      // volatility of a forward swap whose start
      // is specified by option_maturities[i]
      // and whose maturity (from start) is
      // specified by swap_maturities[j]
      // 
      struct COMMON_API SwaptionVolatilityMatrix
      {
        Array<TimeDifference> option_maturities;
        Array<TimeDifference> swap_maturities;
        Array<double> volatilities; 
      };
 
      //
      // Input::CapVolatilityMatrix
      // ----------------------------
      //
      // option_maturities = Array_ of TimeDifference_
      // representing cap maturities
      //
      // - strikes = Array_ of double
      //   representing cap strikes (0.10 = 10%)
      // - volatilities = matrix of volatilities
      //   flattened into an Array_ of doubles.
      //   Each volatility is specified as an absolute double
      //   (0.10 = 10%)
      //
      // If
      //
      // - options_size = option_maturities.size()
      // - strikes_size = strikes.size()
      // - 0 <= j < swaps_size
      // - 0 <= i < options_size
      //
      // then
      //
      // volatilities[j + strikes_size * i] =
      // volatility of a cap whose option_maturity
      // is option_maturities[i] and whose strike
      // is strikes[j].
      // 
      struct COMMON_API CapVolatilityMatrix
      {
        Array<TimeDifference> option_maturities;
        Array<double> strikes;
        Array<double> volatilities; 
      };
 
      // Input::YieldParameters
      // ------------------------
      struct COMMON_API YieldParameters
      {
        Daycount::type daycount;
        CalendarFrequency::type frequency;
        double initial_guess;
        double tolerance;
        int iterations;
        bool use_compounded_yield;
        
        YieldParameters()
        :daycount(Daycount::d30_360),
        frequency(CalendarFrequency::semiannual),
        initial_guess(0.05),
        tolerance(1E-5),
        iterations(10),
        use_compounded_yield(false)
        {}
        
      };
    
      // 
      // Security terms and conditions
      // ++++++++++++++++++++++++++++++
      // 
      // Input::CommonTerms
      // --------------------
      //  
      // - initial_principal = starting principal amount,
      //   usually set to 100
      // - effective = start Date_ of bond or swap,
      //   also known as dated date
      // - maturity = maturity Date_
      //
      struct COMMON_API CommonTerms
      {
        double initial_principal;
 
        Date effective;
 
        Date maturity;
 
        CommonTerms()
        :initial_principal(100)
        {}
        
      };
    
      // Input::CouponTerms
      // --------------------
      struct COMMON_API CouponTerms
      {
        long ex_coupon_days;
 
        Daycount::type daycount;
 
        CalendarFrequency::type reset_frequency;
 
        CalendarFrequency::type payment_frequency;
 
        bool end_of_month;
 
        bool in_arrears;
 
        Date last_reset_date;
 
        double current_index;
 
        BusinessDayConvention::type business_day_convention;
 
        CouponTerms()
        :ex_coupon_days(0),
        daycount(Daycount::d30_360),
        reset_frequency(CalendarFrequency::semiannual),
        payment_frequency(CalendarFrequency::semiannual),
        end_of_month(false),
        in_arrears(false),
        current_index(0),
        business_day_convention(BusinessDayConvention::unadjusted)
        {}
      };
    
      // Input::CouponParameters
      // ------------------------
      struct COMMON_API CouponParameters
      {
        Date start;
 
        double fixed_interest;
 
        enum type_type
        {
          standard = 0,
          range_accrual = 1
        };
      
        type_type type;
 
        double index_factor;
 
        double floor;
 
        double cap;
 
        CouponParameters()
        :fixed_interest(0),
        type(standard),
        index_factor(0),
        floor(0),
        cap(0)
        {}
        
        CouponParameters(const Date& input_start,
                         double input_fixed_interest,
                         double input_index_factor = 0,
                         type_type input_type = standard,
                         double input_floor = 0,
                         double input_cap = 0);
      };
 
      // Input::PrincipalPayment
      // -------------------------
      struct COMMON_API PrincipalPayment
      {
        Date date;
 
        double amount;
 
        PrincipalPayment(Date input_date = Date(), double input_amount = 0);
      };
 
      // 
      // Input::BulletBond 
      // ------------------
      struct COMMON_API BulletBond
      {
        BondType::type type;
 
        CommonTerms common_terms;
        CouponTerms coupon_terms;
 
        Date first_coupon_date;
 
        Date penultimate_coupon_date;
 
        Array<CouponParameters> coupon_schedule;
 
        Array<PrincipalPayment> principal_payments;
 
        BulletBond()
        :type(BondType::fixed)
        {}
        
      };
 
      // Input::StrikeScheduleItem
      // ------------------------------
      struct COMMON_API StrikeScheduleItem
      {
        Date start;
 
        double strike;
 
        StrikeScheduleItem(Date input_start = Date(),
                           double input_strike = 100.0);
      };
 
      // 
      // Input::Option
      // --------------
      // - notice_period = TimeDifference_ specifying
      //   how far in advance one must announce that
      //   a put or call will be exercised
      // - frequency = CalendarFrequency_ of option exercise
      //   opportunities.
      //
      //   - Set to CalendarFrequency::zero if there is no option
      //   - Set to CalendarFrequency::custom for European option or
      //     a custom discrete exercise schedule
      //   - Set to CalendarFrequency::daily for American option
      //   - Set to appropriate value for Bermudan option
      //
      // - end = maturity Date for standard options or
      //   earlier date for canary options
      //
      struct COMMON_API Option
      {
        TimeDifference notice_period;
 
        CalendarFrequency::type frequency;
 
        Date end;
 
        Array<StrikeScheduleItem> strike_schedule;
 
        Option()
        :frequency(CalendarFrequency::zero)
        {}
      };
        
      // Input::Security
      // -----------------
      // Template data struct for a fixed or floating rate security
      // with or without a call or put
      //      template <class BondType>
      //      struct COMMON_API Security
      //      {
      //        typedef Security<BondType> this_type;
      //
      //        BondType bond;
      //        Option call;
      //        Option put;
      //      };
 
      // Input::Quote
      // --------------
      struct COMMON_API Quote
      {
        enum type_type
        {
          unspecified = -1,
          oas = 0,           // Conforms with BondOAS value
          clean_price = 1,   // Conforms with BondOAS value
          dirty_price = 10,
          yield_to_maturity = 2, // Conforms with BondOAS value
          yield_to_call = 3, // Conforms with BondOAS value
          yield_to_worst = 9,
          discount_margin = 20, // For floaters only
          das = 100,         // Used by DefaultAdjustedSpread library
        };
 
        type_type type;
 
        double value;
 
        Quote()
        :type(unspecified),
        value(QuietNaN())
        {}
 
        bool is_price() const;
      };
    }
 
    //
    // Output data structs
    // +++++++++++++++++++++
    //
    // Returns error code and message String_
    //
    namespace Output
    {
      struct COMMON_API Status
      {
        int code;
 
        String message;
 
        enum code_type
        {
          ok = 0,
          warning = 2,
          no_lattice_model = 2*2,
          fatal = 256,
          invalid_license = 256*2, 
          no_curve_model= 256*4,
          computation_failed = 256*8,
          invalid_quote = 256*16,
          no_default_model = 256*32,
          no_stock_model = 256*64,
          invalid_handle = 256*256*256
        };
 
        bool operator!() const;
        
        Status(code_type this_code = ok,
               const char* this_message = "");
 
        ~Status();
      
        void set_to_worst(int this_code = Status::ok);
 
        void set_message(const char* m);
 
        void set(int code = ok, const char* m = "");
 
        void set_to_worst(int code, const char* m);
 
        void set_to_worst(Status status);
      };
 
      // Output::Price
      // --------------
      struct COMMON_API Price
      {
        double clean_price;
        double accrued_interest;
        double dirty_price;
        double oas;
 
        double call_value;
        double put_value;
 
        Price()
        :clean_price(QuietNaN()),
        accrued_interest(QuietNaN()),
        dirty_price(QuietNaN()),
        oas(QuietNaN()),
        call_value(QuietNaN()),
        put_value(QuietNaN())
        {}
 
        const Status& status() const;
 
        void set(const Status& status);
        void set_to_worst(Output::Status::code_type code,
                          const char* m);
 
        // private:
        Status status_;
      };
 
      // Output::Risk
      // --------------
      struct COMMON_API Risk
      {
        double duration;
        double convexity;
 
        Risk()
        :duration(QuietNaN()),
        convexity(QuietNaN())
        {}
        
      };
 
      // Output::PartialDuration
      // ------------------------
      struct COMMON_API PartialDuration
      {
        TimeDifference maturity;
        double duration;
 
        PartialDuration()
        :duration(QuietNaN())
        {}
      };
 
      // Output::Yield
      // --------------
      struct COMMON_API Yield
      {
        double yield;
        double clean_price;
        double accrued_interest;
        Date redemption_date;
 
        const Risk& modified_risk() const;
 
        const Status& status() const;
 
        Yield()
        :yield(QuietNaN()),
        clean_price(QuietNaN()),
        accrued_interest(QuietNaN())
        {}
        
        void set(const Risk& modified_risk);
        void set(const Status& status);
        
        // private:
        Risk modified_risk_;
        Status status_;
      };
 
      // Output::Cashflow
      // -----------------
      struct COMMON_API Cashflow
      {
        double principal;
        double interest;
 
        Cashflow()
        :principal(QuietNaN()),
        interest(QuietNaN())
        {}
        
      };
    
      // Output::BondCashflow
      // ---------------------
      struct COMMON_API BondCashflow
      {
        Date date;
        double principal;
        double interest;
 
        BondCashflow()
        :principal(QuietNaN()),
        interest(QuietNaN())
        {}
      };
    }
  }
}
 
 
#endif
 
// .. _`BondType`: enums.html#BondType
// .. _`CalendarUnits`: enums.html#CalendarUnits
// .. _`BusinessDayConvention`: enums.html#BusinessDayConvention
// .. _`BusinessCenter`: enums.html#BusinessCenter
// .. _`Daycount`: enums.html#Daycount
// .. _`CalendarFrequency`: enums.html#CalendarFrequency