ledger.hpp

Go to the documentation of this file.

#pragma once
 
#include "../strategy/event.hpp"
#include "../strategy/portfolio.hpp"
#include "cost.hpp"
 
#include <algotradelib/core>
 
#include <optional>
#include <string_view>
#include <utility>
#include <vector>
 
namespace algotradelib {
namespace backtest {


struct BacktestTag {
  static constexpr std::string_view name = "backtest";
};

struct Execution {
  strategy::Fill fill_;
  Decimal64 commission_;
  std::optional<Decimal64> institution_fee_;
  Currency currency_{Currency{"KRW"}};
  AppliedRate applied_;
  Decimal64 slippage_;
  Decimal64 tax_;
};

class ReplayLedger {
public:
  ReplayLedger(Decimal64 cash, Currency currency) {
    cash_.push_back(Money{std::move(cash), std::move(currency)});
  }

  std::optional<Decimal64> cash_in(const Currency& currency) const {
    for (const auto& amount : cash_) {
      if (amount.currency_ == currency) {
        return amount.amount_;
      }
    }
    return std::nullopt;
  }

  std::optional<Decimal64> quantity_of(const InstrumentId& instrument) const {
    for (const auto& lot : positions_) {
      if (lot.instrument_ == instrument) {
        return lot.quantity_;
      }
    }
    return std::nullopt;
  }

  std::optional<Decimal64> average_price_of(const InstrumentId& instrument) const {
    for (const auto& lot : positions_) {
      if (lot.instrument_ == instrument && lot.quantity_.coefficient() != 0) {
        return lot.average_purchase_price_;
      }
    }
    return std::nullopt;
  }

  Decimal64 realized_in(const Currency& currency) const {
    for (const auto& entry : realized_) {
      if (entry.currency_ == currency) {
        return entry.amount_;
      }
    }
    return Decimal64::parse("0");
  }

  const std::vector<HoldingPosition>& positions() const noexcept { return positions_; }

  const std::vector<Execution>& executions() const noexcept { return executions_; }

  bool apply(const Execution& execution, const Currency& currency) {
    const auto& fill = execution.fill_;
    const auto zero = Decimal64::parse("0");
 
    // Signed quantity: a sale reduces the position.
    const auto signed_quantity = fill.side_ == OrderSide::BUY ?
      std::optional<Decimal64>(fill.quantity_) :
      decimal_subtract(zero, fill.quantity_);
    if (!signed_quantity) {
      return false;
    }
 
    const auto gross = decimal_multiply(fill.quantity_, fill.price_);
    if (!gross) {
      return false;
    }
    // Cash out on a buy, in on a sale, and commission out either way.
    const auto cash_change = fill.side_ == OrderSide::BUY ?
      decimal_subtract(zero, *gross) :
      std::optional<Decimal64>(*gross);
    if (!cash_change) {
      return false;
    }
    const auto after_commission = decimal_subtract(*cash_change, execution.commission_);
    if (!after_commission) {
      return false;
    }
    // Both the broker's commission and the institution fee leave cash.
    const auto after_fees = execution.institution_fee_ ?
      decimal_subtract(*after_commission, *execution.institution_fee_) :
      after_commission;
    if (!after_fees) {
      return false;
    }
    const auto after_tax = decimal_subtract(*after_fees, execution.tax_);
    if (!after_tax) {
      return false;
    }
 
    // Read, never opened. Opening the lot here is what made an early return leave a trace.
    const auto* existing = find(fill.instrument_);
    const auto held = existing != nullptr ? existing->quantity_ : zero;
    const auto average = existing != nullptr ? existing->average_purchase_price_ : zero;
 
    // A non-flat position cannot change currency; refuse rather than relabel it.
    if (existing != nullptr && held.coefficient() != 0 &&
        !(existing->market_value_.currency_ == currency)) {
      return false;
    }
 
    const auto closing = closed_quantity(held, *signed_quantity);
    if (!closing) {
      return false;
    }
 
    // Realized profit exists only on the part that closed, and only against the old average.
    std::optional<Decimal64> realized_total;
    if (closing->coefficient() != 0) {
      const auto moved = decimal_subtract(fill.price_, average);
      if (!moved) {
        return false;
      }
      auto banked = decimal_multiply(*closing, *moved);
      if (!banked) {
        return false;
      }
      // Closing a short banks the opposite sign: it profits when the price fell.
      if (decimal_less(held, zero)) {
        banked = decimal_subtract(zero, *banked);
        if (!banked) {
          return false;
        }
      }
      realized_total = decimal_add(realized_in(currency), *banked);
      if (!realized_total) {
        return false;
      }
    }
 
    const auto resulting = decimal_add(held, *signed_quantity);
    if (!resulting) {
      return false;
    }
 
    const auto valued = decimal_multiply(*resulting, fill.price_);
    if (!valued) {
      return false;
    }
 
    // The average price follows only the part that opened or added. A position crossing flat takes the
    // fill price outright, because nothing of the old basis survives.
    auto new_average = average;
    if (resulting->coefficient() == 0) {
      new_average = zero;
    } else if (crossed_or_opened(held, *resulting)) {
      new_average = fill.price_;
    } else if (adding(held, *signed_quantity)) {
      const auto blended = weighted_average(held, average, *signed_quantity, fill.price_);
      if (!blended) {
        return false;
      }
      new_average = *blended;
    }
    // Reducing without crossing leaves the average alone: selling half a position does not change
    // what the remaining half cost.
 
    const auto cash_total = decimal_add(
      cash_in(currency).value_or(zero), *after_tax
    );
    if (!cash_total) {
      return false;
    }
 
    // --- No arithmetic below can fail, and nothing below returns false -----------------------
    auto* lot = find_or_open(fill.instrument_);
    lot->average_purchase_price_ = new_average;
    lot->quantity_ = *resulting;
    lot->last_price_ = fill.price_;
    // **The currency is recorded here because this is the only place it is known.** `mark` is not
    // told one and neither is `equity_in`'s caller beyond the currency it is asking about, so a
    // position that never wrote its own currency down cannot be told apart from one denominated in
    // whatever the caller happened to ask for. `Currency` default-constructs to KRW
    // (`Currency`'s default constructor), which makes the untold case silently *answer* rather than be absent --
    // a USD position would read as Korean won to anything summing per currency.
    lot->market_value_ = Money{*valued, currency};
    set_amount(cash_, currency, *cash_total);
    if (realized_total) {
      set_amount(realized_, currency, *realized_total);
    }
    executions_.push_back(execution);
    return true;
  }

  bool mark(const InstrumentId& instrument, const Decimal64& price) {
    bool marked = true;
    for (auto& lot : positions_) {
      if (lot.instrument_ == instrument) {
        // **Both fields move or neither does, and the caller is told which.** Two earlier versions
        // each lost one half of that. Advancing the price and leaving the old `market_value_`
        // handed a strategy reading `positions()` or `snapshot()` a stale number presented as
        // current, with no error anywhere; skipping the row silently declined to apply a price the
        // caller asked for. The currency is the one `apply` recorded -- a lot exists only because a
        // fill opened it -- and it is the half nothing can invalidate.
        const auto valued = decimal_multiply(lot.quantity_, price);
        if (!valued) {
          marked = false;
          continue;
        }
        lot.last_price_ = price;
        lot.market_value_ = Money{*valued, lot.market_value_.currency_};
      }
    }
    return marked;
  }

  template <typename BrokerTag>
  strategy::Portfolio<BrokerTag> snapshot(
    std::chrono::system_clock::time_point as_of
  ) const {
    strategy::Portfolio<BrokerTag> portfolio;
    portfolio.positions_ = positions_;
    // Every held share is sellable: a model consistent with crediting sales on the fill (no
    // settlement); `ReportCaveats` discloses it.
    for (auto& position : portfolio.positions_) {
      position.sellable_quantity_ = position.quantity_;
    }
    // The basis a producer of sellable figures must state: whole holding, deduct resting, unverified.
    portfolio.sellable_basis_ = SellableBasis{
      SellableBasis::Coverage::WHOLE_HOLDING,
      SellableBasis::RestingTreatment::DEDUCT,
      false,
    };
    portfolio.cash_ = cash_;
    // Buying power modelled as this ledger's cash, stamped at the snapshot time; the report states
    // the model.
    portfolio.buying_power_.reserve(cash_.size());
    for (const auto& amount : cash_) {
      portfolio.buying_power_.push_back(BuyingPower{amount, as_of});
    }
    portfolio.as_of_ = as_of;
    return portfolio;
  }

  std::optional<Decimal64> equity_in(const Currency& currency) const {
    auto total = cash_in(currency).value_or(Decimal64::parse("0"));
    for (const auto& lot : positions_) {
      if (lot.quantity_.coefficient() == 0) {
        continue;
      }
      // Only positions in `currency` (recorded on `market_value_` by `apply`); no conversion.
      if (!(lot.market_value_.currency_ == currency)) {
        continue;
      }
      // Computed from the last mark rather than read from `market_value_`.
      const auto value = decimal_multiply(lot.quantity_, lot.last_price_);
      if (!value) {
        return std::nullopt;
      }
      const auto sum = decimal_add(total, *value);
      if (!sum) {
        return std::nullopt;
      }
      total = *sum;
    }
    return total;
  }
 
private:
  // Returns the position in `instrument`, or nothing, **without creating one**.
  const HoldingPosition* find(const InstrumentId& instrument) const {
    for (const auto& lot : positions_) {
      if (lot.instrument_ == instrument) {
        return &lot;
      }
    }
    return nullptr;
  }
 
  HoldingPosition* find_or_open(const InstrumentId& instrument) {
    for (auto& lot : positions_) {
      if (lot.instrument_ == instrument) {
        return &lot;
      }
    }
    HoldingPosition opened;
    opened.instrument_ = instrument;
    opened.quantity_ = Decimal64::parse("0");
    opened.average_purchase_price_ = Decimal64::parse("0");
    opened.last_price_ = Decimal64::parse("0");
    positions_.push_back(opened);
    return &positions_.back();
  }
 
  // Returns how much of `held` this trade closes, which is zero when it only adds.
  static std::optional<Decimal64> closed_quantity(
    const Decimal64& held,
    const Decimal64& traded
  ) {
    const auto zero = Decimal64::parse("0");
    const bool long_held = decimal_less(zero, held);
    const bool short_held = decimal_less(held, zero);
    const bool buying = decimal_less(zero, traded);
    if ((long_held && buying) || (short_held && !buying) || held.coefficient() == 0) {
      return zero;
    }
    const auto magnitude_held = long_held ? held : decimal_subtract(zero, held);
    const auto magnitude_traded = buying ? traded : decimal_subtract(zero, traded);
    if (!magnitude_held || !magnitude_traded) {
      return std::nullopt;
    }
    return decimal_less(*magnitude_held, *magnitude_traded) ? *magnitude_held : *magnitude_traded;
  }
 
  // Returns whether the trade opened from flat or crossed through it.
  static bool crossed_or_opened(const Decimal64& held, const Decimal64& resulting) {
    const auto zero = Decimal64::parse("0");
    if (held.coefficient() == 0) {
      return true;
    }
    return decimal_less(zero, held) != decimal_less(zero, resulting);
  }
 
  // Returns whether the trade added to a position rather than reducing it.
  static bool adding(const Decimal64& held, const Decimal64& traded) {
    const auto zero = Decimal64::parse("0");
    return decimal_less(zero, held) == decimal_less(zero, traded);
  }
 
  // Returns the average of two lots by magnitude, which is what adding to a position produces.
  static std::optional<Decimal64> weighted_average(
    const Decimal64& held,
    const Decimal64& held_price,
    const Decimal64& traded,
    const Decimal64& traded_price
  ) {
    const auto zero = Decimal64::parse("0");
    const auto held_magnitude = decimal_less(held, zero) ? decimal_subtract(zero, held) : held;
    const auto traded_magnitude =
      decimal_less(traded, zero) ? decimal_subtract(zero, traded) : traded;
    if (!held_magnitude || !traded_magnitude) {
      return std::nullopt;
    }
    const auto held_cost = decimal_multiply(*held_magnitude, held_price);
    const auto traded_cost = decimal_multiply(*traded_magnitude, traded_price);
    if (!held_cost || !traded_cost) {
      return std::nullopt;
    }
    const auto total_cost = decimal_add(*held_cost, *traded_cost);
    const auto total_quantity = decimal_add(*held_magnitude, *traded_magnitude);
    if (!total_cost || !total_quantity || total_quantity->coefficient() == 0) {
      return std::nullopt;
    }
    // Four places, which holds a tick on every grid this library knows and more than a price needs.
    return decimal_divide(*total_cost, *total_quantity, 4);
  }
 
  // Writes `total` as the whole amount held in `currency`, appending the entry when there is none.
  //
  // Takes the **total** rather than a change, because the addition is the fallible half and `apply`
  // has already done it before committing anything. What is left cannot fail, which is what lets
  // `apply` promise the ledger is either wholly updated or untouched.
  static void set_amount(
    std::vector<Money>& amounts,
    const Currency& currency,
    const Decimal64& total
  ) {
    for (auto& amount : amounts) {
      if (amount.currency_ == currency) {
        amount.amount_ = total;
        return;
      }
    }
    amounts.push_back(Money{total, currency});
  }
 
  std::vector<HoldingPosition> positions_;
  std::vector<Money> cash_;
  std::vector<Money> realized_;
  std::vector<Execution> executions_;
};
 
} // namespace backtest
} // namespace algotradelib