reconcile.hpp

Go to the documentation of this file.

#pragma once
 
#include "./intent.hpp"
#include "./portfolio.hpp"
 
#include <algotradelib/core>
 
#include <optional>
#include <string>
#include <utility>
#include <vector>
 
namespace algotradelib {
namespace strategy {


enum class RejectReason {
  NO_REFERENCE_DATA,
  UNKNOWN_PRICE_GRID,
  NO_PRICE_AVAILABLE,
  NO_PORTFOLIO_VALUE,
  QUANTITY_ROUNDS_TO_ZERO,
  NOT_REPRESENTABLE,
  NO_PERMITTED_PRICE,
  BROKER_REFUSED,
  BINDING_REFUSED,
  TRIGGER_OFF_GRID,
  STOP_ORDER_RESTING,
  UNSUPPORTED_WEIGHT,
  NEGATIVE_SIZE,
};

inline constexpr std::string_view reject_reason_name(RejectReason reason) noexcept {
  switch (reason) {
    case RejectReason::NO_REFERENCE_DATA:
      return "no_reference_data";
    case RejectReason::UNKNOWN_PRICE_GRID:
      return "unknown_price_grid";
    case RejectReason::NO_PRICE_AVAILABLE:
      return "no_price_available";
    case RejectReason::NO_PORTFOLIO_VALUE:
      return "no_portfolio_value";
    case RejectReason::QUANTITY_ROUNDS_TO_ZERO:
      return "quantity_rounds_to_zero";
    case RejectReason::NOT_REPRESENTABLE:
      return "not_representable";
    case RejectReason::NO_PERMITTED_PRICE:
      return "no_permitted_price";
    case RejectReason::BROKER_REFUSED:
      return "broker_refused";
    case RejectReason::BINDING_REFUSED:
      return "binding_refused";
    case RejectReason::TRIGGER_OFF_GRID:
      return "trigger_off_grid";
    case RejectReason::STOP_ORDER_RESTING:
      return "stop_order_resting";
    case RejectReason::UNSUPPORTED_WEIGHT:
      return "unsupported_weight";
    case RejectReason::NEGATIVE_SIZE:
      return "negative_size";
  }
  return "unknown";
}

struct Rejection {
  RejectReason reason_{RejectReason::NO_REFERENCE_DATA};
  InstrumentId instrument_;
  std::string tag_;
};

struct PlannedOrder {
  InstrumentId instrument_;
  OrderSide side_{OrderSide::BUY};
  OrderType type_{OrderType::LIMIT};
  TimeInForce time_in_force_{TimeInForce::DAY};
  OrderSession session_{OrderSession::REGULAR};
  Venue venue_{Venue::UNSPECIFIED};
  Decimal64 quantity_;
  std::optional<Decimal64> price_;
  std::optional<Decimal64> trigger_price_;
  std::string tag_;
  std::optional<std::string> client_order_id_;

  bool price_rounded_{false};
  bool price_clamped_{false};
  bool price_would_have_been_clamped_{false};
  bool quantity_rounded_{false};
};

template <typename Broker>
struct Plan {
  std::vector<OrderRef<Broker>> cancel_;
  std::vector<PlannedOrder> place_;
  std::vector<Rejection> rejected_;

  bool empty() const noexcept {
    return cancel_.empty() && place_.empty() && rejected_.empty();
  }
};

struct TradeTolerance {
  std::optional<Decimal64> minimum_quantity_;
  std::optional<Decimal64> minimum_notional_;
  std::optional<Decimal64> minimum_fraction_of_working_;

  bool stated() const noexcept {
    return minimum_quantity_.has_value() || minimum_notional_.has_value() ||
      minimum_fraction_of_working_.has_value();
  }
};

struct ReconcileInputs {
  const Instrument* instrument_{nullptr};
  std::optional<Decimal64> reference_price_;
  std::optional<PriceLimits> limits_;
  std::optional<Decimal64> portfolio_value_;

  TradeTolerance tolerance_;
  std::optional<Currency> portfolio_value_currency_;
  bool reserved_rows_are_unconfirmed_{false};
};
 
namespace reconcile_detail {

inline std::optional<Decimal64> lot_of(const Instrument& instrument) {
  if (!instrument.lot_size_) {
    return std::nullopt;
  }
  if (instrument.lot_size_->coefficient() <= 0) {
    return std::nullopt;
  }
  return instrument.lot_size_;
}

inline std::optional<Decimal64> round_to_lot(
  const Decimal64& quantity,
  const std::optional<Decimal64>& lot,
  bool& adjusted
) {
  adjusted = false;
  if (!lot) {
    return quantity;
  }
  const auto rounded = decimal_floor_to_multiple(quantity, *lot);
  if (!rounded) {
    return std::nullopt;
  }
  adjusted = !(*rounded == quantity);
  return rounded;
}

inline std::optional<Decimal64> clamp_to_limits(
  const Decimal64& price,
  OrderSide side,
  const std::optional<PriceLimits>& limits,
  bool& adjusted
) {
  adjusted = false;
  if (!limits) {
    return price;
  }
  if (side == OrderSide::BUY && limits->upper_ && decimal_less(*limits->upper_, price)) {
    adjusted = true;
    return limits->upper_;
  }
  if (side == OrderSide::SELL && limits->lower_ && decimal_less(price, *limits->lower_)) {
    adjusted = true;
    return limits->lower_;
  }
  return price;
}

inline std::optional<Decimal64> prepare_price(
  const Decimal64& wanted,
  OrderSide side,
  const PriceRule& rule,
  const std::optional<PriceLimits>& limits,
  bool& clamped,
  bool& rounded
) {
  const auto within = clamp_to_limits(wanted, side, limits, clamped);
  if (!within) {
    return std::nullopt;
  }
  const auto on_grid = rule.round_to_tick(*within, side);
  if (!on_grid) {
    return std::nullopt;
  }
  rounded = !(*on_grid == *within);
  return on_grid;
}

inline bool rounded_out_of_band(
  const Decimal64& wanted,
  const Decimal64& priced,
  OrderSide side,
  const std::optional<PriceLimits>& limits
) {
  if (!limits) {
    return false;
  }
  if (side == OrderSide::BUY) {
    return limits->lower_ && decimal_less(priced, *limits->lower_) && !decimal_less(wanted, *limits->lower_);
  }
  return limits->upper_ && decimal_less(*limits->upper_, priced) && !decimal_less(*limits->upper_, wanted);
}

inline bool below_tolerance(
  const Decimal64& drift,
  const Decimal64& already_working,
  const ReconcileInputs& inputs
) {
  const auto& tolerance = inputs.tolerance_;
 
  if (tolerance.minimum_quantity_ && decimal_less(drift, *tolerance.minimum_quantity_)) {
    return true;
  }
 
  if (tolerance.minimum_notional_ && inputs.reference_price_) {
    const auto value = decimal_multiply(drift, *inputs.reference_price_);
    if (value && decimal_less(*value, *tolerance.minimum_notional_)) {
      return true;
    }
  }
 
  // Only meaningful against something resting: with nothing working there is no queue position to
  // give up, so a drift is simply a new order and this floor has nothing to say about it.
  if (tolerance.minimum_fraction_of_working_ && already_working.coefficient() > 0) {
    // Six places, which resolves a fraction far finer than any threshold an operator would state.
    const auto fraction = decimal_divide(drift, already_working, 6);
    if (fraction && decimal_less(*fraction, *tolerance.minimum_fraction_of_working_)) {
      return true;
    }
  }
 
  return false;
}
 
} // namespace reconcile_detail

inline bool is_stop_order(const OrderSnapshot& order) {
  return carries_trigger_price(order.type_) || order.trigger_price_.has_value();
}

template <typename Broker>
Plan<Broker> reconcile(
  const TargetPosition& target,
  const Portfolio<Broker>& portfolio,
  const ReconcileInputs& inputs
) {
  Plan<Broker> plan;
  const auto reject = [&](RejectReason reason) {
    plan.cancel_.clear();
    plan.place_.clear();
    plan.rejected_.push_back(Rejection{reason, target.instrument_, target.tag_});
    return plan;
  };
 
  if (inputs.instrument_ == nullptr) {
    return reject(RejectReason::NO_REFERENCE_DATA);
  }
 
  const auto zero = Decimal64::parse("0");
  // Net across every position row, as the guards read it: a holding can be split across lots.
  const auto net = portfolio.net_quantity_of(target.instrument_);
  if (!net) {
    // A snapshot whose own rows will not add up cannot say what reaching a target would take, and
    // `value_or(zero)` here would read a broken listing as flat and order the whole target.
    return reject(RejectReason::NOT_REPRESENTABLE);
  }
  const auto held = *net;
  const auto needed = decimal_subtract(target.target_quantity_, held);
  if (!needed) {
    return reject(RejectReason::NOT_REPRESENTABLE);
  }
 
  const bool buying = decimal_less(zero, *needed);
  const bool selling = decimal_less(*needed, zero);
 
  // **Stops first; see `RejectReason::STOP_ORDER_RESTING`.** A row is a stop when its basis says so
  // or it carries a trigger -- an adapter records a positive trigger even on a row whose basis reads
  // otherwise, and that row may be a released stop.
  const auto is_stop = [](const OrderSnapshot& order) { return is_stop_order(order); };
  bool stop_resting = false;
  for (const auto& working : portfolio.working_) {
    if (working.order_.instrument_ == target.instrument_ &&
        order_is_open(working.order_.status_) && is_stop(working.order_)) {
      stop_resting = true;
    }
  }
  if (stop_resting) {
    const bool met = !buying && !selling;
    for (const auto& working : portfolio.working_) {
      if (!(working.order_.instrument_ == target.instrument_) ||
          !order_is_open(working.order_.status_)) {
        continue;
      }
      if (is_stop(working.order_)) {
        // Withdrawn only when a trade is needed, and not again once its withdrawal is pending: a
        // second request for an order already on its way out can only fail.
        if (!met && !order_status_cancel_pending(working.order_.status_)) {
          plan.cancel_.push_back(working.ref_);
        }
      } else if (met) {
        // The holding meets the target, so every *other* working order is unwanted, as before.
        plan.cancel_.push_back(working.ref_);
      }
    }
    if (!met) {
      plan.rejected_.push_back(
        Rejection{RejectReason::STOP_ORDER_RESTING, target.instrument_, target.tag_}
      );
    }
    return plan;
  }
 
  // Step 2: withdraw what works against the target. With nothing needed, that is everything.
  //
  // Only orders that can still trade are withdrawn. A snapshot may carry an order that has since
  // filled or been cancelled, and asking a broker to cancel one of those is a request that can
  // only fail -- noise on a path where a real cancellation failure has to be noticed.
  for (const auto& working : portfolio.working_) {
    if (!(working.order_.instrument_ == target.instrument_) ||
        !order_is_open(working.order_.status_)) {
      continue;
    }
    const bool opposes = (buying && working.order_.side_ == OrderSide::SELL) ||
      (selling && working.order_.side_ == OrderSide::BUY) || (!buying && !selling);
    if (opposes) {
      plan.cancel_.push_back(working.ref_);
    }
  }
  if (!buying && !selling) {
    return plan;
  }
 
  const OrderSide side = buying ? OrderSide::BUY : OrderSide::SELL;
  const auto magnitude = buying ? *needed : decimal_subtract(zero, *needed).value_or(zero);
  const auto already = portfolio.working_quantity(target.instrument_, side);
 
  // Step 3: only the part not already in the market.
  auto remaining = decimal_subtract(magnitude, already);
  if (!remaining) {
    return reject(RejectReason::NOT_REPRESENTABLE);
  }
 
  // Step 3a: a drift smaller than the tolerance is not worth an instruction.
  //
  // Measured on the *drift* -- how far the in-flight position is from the target -- and not on what
  // would be sent. Those differ exactly in the case the tolerance exists for: 100 working against a
  // target of 99 would withdraw the side and re-place 99, so the quantity sent is 99 while the drift
  // is one share.
  //
  // Suppressed only when nothing has already been queued for cancellation. An order working the
  // *wrong way* still has to be withdrawn however small the drift, because leaving it resting works
  // against the target rather than merely failing to reach it. And returning an empty plan rather
  // than the accumulated one matters for the same reason: withdrawing a working order and then
  // declining to replace it would leave the position further from the target than doing nothing.
  if (inputs.tolerance_.stated() && plan.cancel_.empty()) {
    const auto drift = decimal_less(*remaining, zero) ?
      decimal_subtract(zero, *remaining) :
      std::optional<Decimal64>(*remaining);
    if (drift && reconcile_detail::below_tolerance(*drift, already, inputs)) {
      return Plan<Broker>{};
    }
  }
 
  // Step 4: more working than wanted, so withdraw the side and send the whole remainder -- net of what
  // this runner reserved for its own orders not yet shown by holdings, when those may have filled
  // (`ReconcileInputs::reserved_rows_are_unconfirmed_`): their withdrawal is refused if they did, and a
  // whole remainder beside them traded twice. One genuinely resting is withdrawn all the same;
  // its history settles what it filled, and a later pass places the rest.
  if (decimal_less(*remaining, zero)) {
    Decimal64 reserved = zero;
    for (const auto& working : portfolio.working_) {
      if (working.order_.instrument_ == target.instrument_ &&
          working.order_.side_ == side && order_is_open(working.order_.status_)) {
        plan.cancel_.push_back(working.ref_);
        if (inputs.reserved_rows_are_unconfirmed_ && working.reserved_) {
          // A sum that will not compute refuses: undercounted, it would size the replacement larger.
          const auto left = decimal_subtract(working.order_.quantity_, working.order_.execution_.filled_quantity_);
          if (!left) {
            return reject(RejectReason::NOT_REPRESENTABLE);
          }
          if (decimal_less(zero, *left)) {
            const auto sum = decimal_add(reserved, *left);
            if (!sum) {
              return reject(RejectReason::NOT_REPRESENTABLE);
            }
            reserved = *sum;
          }
        }
      }
    }
    remaining = decimal_subtract(magnitude, reserved);
    if (!remaining) {
      return reject(RejectReason::NOT_REPRESENTABLE);
    }
    if (!decimal_less(zero, *remaining)) {
      return plan;
    }
  }
  if (remaining->coefficient() == 0) {
    return plan;
  }
 
  PlannedOrder order;
  order.instrument_ = target.instrument_;
  order.side_ = side;
  order.time_in_force_ = TimeInForce::DAY;
  order.tag_ = target.tag_;
 
  const auto lot = reconcile_detail::lot_of(*inputs.instrument_);
  const auto sized = reconcile_detail::round_to_lot(*remaining, lot, order.quantity_rounded_);
  if (!sized) {
    return reject(RejectReason::NOT_REPRESENTABLE);
  }
  if (sized->coefficient() == 0) {
    // Rounded away entirely. A rejection rather than an empty plan, because the strategy asked
    // for something and is getting nothing; silence here would look like a met target.
    return reject(RejectReason::QUANTITY_ROUNDS_TO_ZERO);
  }
  order.quantity_ = *sized;
 
  if (target.limit_) {
    const auto priced = reconcile_detail::prepare_price(
      target.limit_->value(),
      side,
      inputs.instrument_->price_rule_,
      inputs.limits_,
      order.price_clamped_,
      order.price_rounded_
    );
    if (!priced) {
      return reject(RejectReason::UNKNOWN_PRICE_GRID);
    }
    if (reconcile_detail::rounded_out_of_band(target.limit_->value(), *priced, side, inputs.limits_)) {
      return reject(RejectReason::NO_PERMITTED_PRICE);
    }
    order.type_ = OrderType::LIMIT;
    order.price_ = priced;
  } else {
    order.type_ = OrderType::MARKET;
  }
 
  plan.place_.push_back(std::move(order));
  return plan;
}

template <typename Broker>
Plan<Broker> reconcile(
  const OrderIntent& intent,
  const Portfolio<Broker>& portfolio,
  const ReconcileInputs& inputs
) {
  (void)portfolio;
  Plan<Broker> plan;
  const auto reject = [&](RejectReason reason) {
    plan.place_.clear();
    plan.rejected_.push_back(Rejection{reason, intent.instrument(), intent.tag()});
    return plan;
  };
 
  if (inputs.instrument_ == nullptr) {
    return reject(RejectReason::NO_REFERENCE_DATA);
  }
 
  // A price to size against: the limit if there is one, otherwise whatever the runner supplied.
  const auto sizing_price = intent.limit() ?
    std::optional<Decimal64>(intent.limit()->value()) :
    inputs.reference_price_;
 
  Decimal64 wanted;
  switch (intent.size().kind()) {
    case SizeKind::QUANTITY:
      if (intent.size().as_quantity().coefficient() < 0) {
        return reject(RejectReason::NEGATIVE_SIZE);
      }
      wanted = intent.size().as_quantity();
      break;
    case SizeKind::NOTIONAL: {
      if (intent.size().as_notional().amount_.coefficient() < 0) {
        return reject(RejectReason::NEGATIVE_SIZE);
      }
      // Not positive is no price to size by: divided by a negative one, a buy became a negative quantity.
      if (!sizing_price || sizing_price->coefficient() <= 0) {
        return reject(RejectReason::NO_PRICE_AVAILABLE);
      }
      const auto shares =
        decimal_divide(intent.size().as_notional().amount_, *sizing_price, 0);
      if (!shares) {
        return reject(RejectReason::NOT_REPRESENTABLE);
      }
      wanted = *shares;
      break;
    }
    case SizeKind::TARGET_WEIGHT: {
      // The guards `weight_target` applies: a weight states a holding, which cannot be negative, and is
      // a fraction of a value and sized by a price that must both be positive.
      if (intent.size().as_target_weight().coefficient() < 0) {
        return reject(RejectReason::UNSUPPORTED_WEIGHT);
      }
      if (!inputs.portfolio_value_ || inputs.portfolio_value_->coefficient() <= 0) {
        return reject(RejectReason::NO_PORTFOLIO_VALUE);
      }
      if (!sizing_price || sizing_price->coefficient() <= 0) {
        return reject(RejectReason::NO_PRICE_AVAILABLE);
      }
      const auto allocation = decimal_multiply(
        inputs.portfolio_value_.value(), intent.size().as_target_weight()
      );
      if (!allocation) {
        return reject(RejectReason::NOT_REPRESENTABLE);
      }
      const auto shares = decimal_divide(*allocation, *sizing_price, 0);
      if (!shares) {
        return reject(RejectReason::NOT_REPRESENTABLE);
      }
      wanted = *shares;
      break;
    }
  }
 
  PlannedOrder order;
  order.instrument_ = intent.instrument();
  order.side_ = intent.side();
  order.time_in_force_ = intent.time_in_force();
  order.tag_ = intent.tag();
  order.client_order_id_ = intent.client_order_id();
 
  const auto lot = reconcile_detail::lot_of(*inputs.instrument_);
  const auto sized = reconcile_detail::round_to_lot(wanted, lot, order.quantity_rounded_);
  if (!sized) {
    return reject(RejectReason::NOT_REPRESENTABLE);
  }
  if (sized->coefficient() == 0) {
    return reject(RejectReason::QUANTITY_ROUNDS_TO_ZERO);
  }
  order.quantity_ = *sized;
 
  if (intent.limit()) {
    const auto priced = reconcile_detail::prepare_price(
      intent.limit()->value(),
      intent.side(),
      inputs.instrument_->price_rule_,
      inputs.limits_,
      order.price_clamped_,
      order.price_rounded_
    );
    if (!priced) {
      return reject(RejectReason::UNKNOWN_PRICE_GRID);
    }
    if (reconcile_detail::rounded_out_of_band(intent.limit()->value(), *priced, intent.side(), inputs.limits_)) {
      return reject(RejectReason::NO_PERMITTED_PRICE);
    }
    order.type_ = OrderType::LIMIT;
    order.price_ = priced;
  } else {
    order.type_ = OrderType::MARKET;
  }
 
  if (intent.trigger()) {
    // Checked, never moved; see `RejectReason::TRIGGER_OFF_GRID`. An unknown grid answers neither
    // way and is refused as it is for a limit.
    const auto aligned = inputs.instrument_->price_rule_.on_tick(intent.trigger()->value());
    if (!aligned) {
      return reject(RejectReason::UNKNOWN_PRICE_GRID);
    }
    if (!*aligned) {
      return reject(RejectReason::TRIGGER_OFF_GRID);
    }
    order.type_ = OrderType::STOP_LIMIT;
    order.trigger_price_ = intent.trigger()->value();
  }
 
  plan.place_.push_back(std::move(order));
  return plan;
}

struct WeightTarget {
  std::optional<TargetPosition> target_;
  std::optional<RejectReason> refused_;
};

inline WeightTarget weight_target(const OrderIntent& intent, const ReconcileInputs& inputs) {
  WeightTarget out;
  const auto refuse = [&](RejectReason reason) {
    out.refused_ = reason;
    return out;
  };
  const auto& weight = intent.size().as_target_weight();
  if (intent.side() != OrderSide::BUY || decimal_less(weight, Decimal64::parse("0")) ||
      intent.trigger() || intent.time_in_force() != TimeInForce::DAY || intent.client_order_id()) {
    return refuse(RejectReason::UNSUPPORTED_WEIGHT);
  }
  if (inputs.instrument_ == nullptr) {
    return refuse(RejectReason::NO_REFERENCE_DATA);
  }
  // A value of zero or less is not one a holding can be a fraction of: sized against it, a weight
  // would become a liquidation (zero) or a short (negative) -- an account whose read failed and came
  // back empty, or a replay that borrowed below zero equity, must not sell on that.
  if (!inputs.portfolio_value_ || inputs.portfolio_value_->coefficient() <= 0 ||
      (inputs.portfolio_value_currency_ &&
       !(*inputs.portfolio_value_currency_ == inputs.instrument_->currency_))) {
    return refuse(RejectReason::NO_PORTFOLIO_VALUE);
  }
  const auto price = intent.limit() ?
    std::optional<Decimal64>(intent.limit()->value()) :
    inputs.reference_price_;
  if (!price || price->coefficient() <= 0) {
    return refuse(RejectReason::NO_PRICE_AVAILABLE);
  }
  const auto allocation = decimal_multiply(*inputs.portfolio_value_, weight);
  const auto shares = allocation ? decimal_divide(*allocation, *price, 0) : std::nullopt;
  bool adjusted = false;
  const auto wanted = shares ?
    reconcile_detail::round_to_lot(*shares, reconcile_detail::lot_of(*inputs.instrument_), adjusted) :
    std::nullopt;
  if (!wanted) {
    return refuse(RejectReason::NOT_REPRESENTABLE);
  }
  TargetPosition target;
  target.instrument_ = intent.instrument();
  target.target_quantity_ = *wanted;
  target.limit_ = intent.limit();
  target.tag_ = intent.tag();
  out.target_ = std::move(target);
  return out;
}
 
} // namespace strategy
} // namespace algotradelib