Discrete finite allocation: private API

PortfolioOptimisers.finite_sub_allocation — Function
finite_sub_allocation(w::VecNum, p::VecNum, lu::Num_VecNum, cash::Number, bgt::Number,
                      sf::Option{<:SideFees}, da::DiscreteAllocation,
                      str_names::Bool = false)

Build and solve the discrete allocation MIP for one side, long or short, of the book.

This is the sub-problem of DiscreteAllocation. The lot count vector is integer and non-negative, so a short side must come in with its weights already negated.

Algorithm

  1. On an empty w, return three empty vectors, cash less the fee of the empty book, that fee, and nothing for the return code and for the model. The fee is allocation_fee of the empty book, because a side that buys nothing can still owe a turnover fee or the forced exit.
  2. Normalise w to sum to one. A side whose weights sum to zero keeps them.
  3. Build the model of the # JuMP formulation below, and solve it with da.slv.
  4. Read the lot count vector back with round(Int, ...), because a MIP solver returns an integer only to within its own tolerance, and multiply it by lu to get the share vector. A model that holds no finite value gives an empty book. A solver that never ran holds no value, and a fee larger than the cash makes the budget infeasible, so neither model has a finite value.
  5. Make the cost shares .* p, and the realised weights cost / sum(cost) * bgt. The realised weights are all zero when nothing was bought.
  6. Price the fee with allocation_fee of the realised shares, and not with the value of model[:fee], which can lie above it. See the ## Relaxation of set_allocation_fees!.
  7. Make the leftover cash, cash less the cost and the fee.

JuMP formulation

Variables

  • z: Lot count vector, integer and non-negative.
  • u: Allocation error bound.

Expressions

  • x: $\boldsymbol{l} \odot \boldsymbol{z}$, the share count vector.
  • sc: $s_c$, da.sc.
  • so: $s_o$, da.so.
  • r: $r$.

set_allocation_fees! registers fee and the entries behind it, and set_discrete_error! registers the row on $u$ and returns the error term $e$.

Constraints

  • cr: $s_c (r - F(\boldsymbol{x})) \geq 0$.

Objective

  • Min: $s_o (e + r)$.

Where:

  • $\boldsymbol{z} \in \mathbb{Z}_{\geq 0}^{N}$: Lot count vector of one side of a finite allocation, the number of whole lots of each asset, the model variable z.
  • $\boldsymbol{l}$: Lot unit of each asset of one side of a finite allocation, the number of shares in one lot. A scalar applies to every asset.
  • $\boldsymbol{x}$: Share count vector of one side of a finite allocation, the model expression x. Each entry is a non-negative integer multiple of the lot unit of its asset.
  • $u$: Allocation error bound, the model variable u that bounds the deviation of the book from its target.
  • $r = C - \boldsymbol{x}^{\intercal} \boldsymbol{p}$: Leftover cash of one side, before the fee.
  • $F(\boldsymbol{x})$: Side fee, the fee that one side pays over the whole horizon. It is zero when the input states no fee.
  • $e$: Error term of da.wf, $u$ under an absolute formulation and $C u$ under a relative one.
  • $C$: Side cash, the cash that one side of a finite allocation can spend.
  • $\boldsymbol{p}$: Asset price vector of one side of a finite allocation.
  • $s_c$: Constraint scale. It multiplies both sides of a row, so a positive value leaves the feasible set unchanged.
  • $s_o$: Objective scale. It multiplies the objective, so a positive value leaves the argument of the optimum unchanged.

Arguments

  • w::VecNum: Target weights of this side, non-negative.
  • p::VecNum: Asset prices of this side, in the same order as w.
  • lu::Num_VecNum: Lot unit of this side, one scalar for every asset or one value for each asset in the order of w.
  • cash::Number: Cash of this side.
  • bgt::Number: Budget of this side, used to rescale the realised weights.
  • sf::Option{<:SideFees}: This side's charge, of allocation_side_fees, or nothing.
  • da::DiscreteAllocation: Allocator carrying the solvers, the scales and the formulation wf.
  • str_names::Bool = false: Whether the JuMP variables get string names.

Returns

  • shares::VecNum: Share count per asset, a whole number of lots of its lot unit.
  • cost::VecNum: shares .* p.
  • aw::VecNum: Realised weights, rescaled to sum to bgt.
  • acash::Number: Cash left over, cash less the cost of the shares and the fee.
  • fee::Number: The fee this side paid over the whole horizon.
  • res::OptimisationReturnCode: An OptimisationSuccess or an OptimisationFailure carrying the solver trials.
  • model::JuMP.Model: The solved model.

Related

source
PortfolioOptimisers.set_discrete_error! — Function
set_discrete_error!(model::JuMP.Model, w::VecNum, p::VecNum, cash::Number,
                    wf::ErrorWeightFinaliser)

Bound the model's error variable u by the allocation error that wf selects, and return the error term of the objective.

This row is the one part of the model that the error of DiscreteAllocation changes. finite_sub_allocation creates x and u before it calls this method, and it builds the objective from the term this method returns.

JuMP formulation

Variables

  • x: Share count vector, read from the model.
  • u: Allocation error bound, read from the model.

Constraints

  • cerr: The tuple (cone, csum, z) of rows and variables that set_norm_error_epigraph! returns for the norm wf.alg, which bound the norm of the residual $\boldsymbol{d}$ by $u$.

The rows are the epigraph of a norm. The objective of finite_sub_allocation minimises $u$ with a positive coefficient, so $u$ equals the norm at the optimum.

Where:

  • $\boldsymbol{x}$: Share count vector of one side of a finite allocation, the model expression x. Each entry is a non-negative integer multiple of the lot unit of its asset.
  • $u$: Allocation error bound, the model variable u that bounds the deviation of the book from its target.
  • $\boldsymbol{d}$: The residual of weight_deviation for wf.dev, $(\boldsymbol{x} \odot \boldsymbol{p}) \oslash (C \tilde{\boldsymbol{w}}) - \boldsymbol{1}$ for a RelativeWeightDeviation, and $\boldsymbol{x} \odot \boldsymbol{p} - C \boldsymbol{w}$ for an AbsoluteWeightDeviation.
  • $\boldsymbol{w}$: Side target weights, the weights of one side of a finite allocation normalised to sum to one. The short side is negated first, so every entry is non-negative.
  • $\tilde{\boldsymbol{w}}$: $\boldsymbol{w}$ with each zero entry replaced by eps(eltype(w)), so that the division is defined.
  • $C$: Side cash, the cash that one side of a finite allocation can spend.
  • $\boldsymbol{p}$: Asset price vector of one side of a finite allocation.
  • $\odot$: Element-wise (Hadamard) product.
  • $\oslash$: Element-wise division.
  • $\boldsymbol{1}$: Vector of ones.

Arguments

  • model::JuMP.Model: The JuMP optimisation model.
  • w::VecNum: Side target weights, normalised to sum to one. The relative deviation replaces a zero entry on a copy, so the caller's vector does not change.
  • p::VecNum: Asset prices of this side, in the same order as w.
  • cash::Number: Cash of this side.
  • wf::ErrorWeightFinaliser: Selects the error. See the table in DiscreteAllocation.

Returns

  • err: The error term of the objective, in money, from deviation_error_term: u under an absolute deviation, and cash * u under a relative one, whose error has no unit.

Related

source
PortfolioOptimisers.set_allocation_fees! — Function
set_allocation_fees!(model::JuMP.Model, p::VecNum, lu::Num_VecNum, cash::Number,
                     sf::Option{<:SideFees})

Write one side's fee in the allocation model's own variables, and return it.

A fee is a cost of the book the allocator buys. The model holds the share vector x and the prices p, so x .* p is the money in each position exactly. Every term is written against that money, and no weight and no price appears on its own.

sf is one side's charge, of allocation_side_fees. A nothing sf registers only a zero fee, so the caller needs no branch.

Mathematical definition

\[\begin{align} F(\boldsymbol{x}) &= T \left( \boldsymbol{f}_{\text{p}}^\intercal \boldsymbol{m} + \boldsymbol{f}_{\text{Tn}}^\intercal \lvert \boldsymbol{m} - \boldsymbol{m}_{0} \rvert \right) + \boldsymbol{f}_{\text{f}}^\intercal \mathbf{1}[\boldsymbol{x} > 0] + F_{\text{lq}}\,. \end{align}\]

Where:

  • $F(\boldsymbol{x})$: Side fee, the fee that one side pays over the whole horizon. It is zero when the input states no fee.
  • $\boldsymbol{m} = \boldsymbol{x} \odot \boldsymbol{p}$: Position money vector, the money in each position of one side.
  • $\boldsymbol{m}_{0}$: Money in each position before the trade, sf.prev_money.
  • $\mathbf{1}[\boldsymbol{x} > 0]$: Indicator vector of a held position.
  • $T$: Horizon, in periods.
  • $\boldsymbol{f}_{\text{p}},\, \boldsymbol{f}_{\text{Tn}},\, \boldsymbol{f}_{\text{f}}$: Proportional, turnover and fixed rates of this side.
  • $F_{\text{lq}}$: Forced exit of allocation_liquidation_fee, sf.liq.

The rates l, s and tn charge on each of the T periods, and the fixed amounts fl and fs charge one time for the whole horizon. That is the rule calc_total_fees states, written in the money of the book.

JuMP formulation

Variables

  • z: Lot count vector, read from the model.
  • t_ftn: Epigraph of the money traded, created when sf states a turnover rate.
  • b: Binary indicator of a held position, created when sf states a fixed fee.

Expressions

  • x: Share count vector, read from the model.
  • money: $\boldsymbol{m}$.
  • fee_prop: $\boldsymbol{f}_{\text{p}}^\intercal \boldsymbol{m}$, when sf states a proportional rate.
  • fee_tn: $\boldsymbol{f}_{\text{Tn}}^\intercal \boldsymbol{t}$, when sf states a turnover rate.
  • fee_fixed: $\boldsymbol{f}_{\text{f}}^\intercal \boldsymbol{b}$, when sf states a fixed fee.
  • fee: $T (f_{\text{p}} + f_{\text{Tn}}) + f_{\text{f}} + F_{\text{lq}}$ over the terms sf states, stored under model[:fee]. It is a zero expression when sf is nothing.

Constraints

  • cftn_ub: $s_c (\boldsymbol{m} - \boldsymbol{m}_{0} - \boldsymbol{t}) \leq \boldsymbol{0}$.
  • cftn_lb: $s_c (\boldsymbol{m}_{0} - \boldsymbol{m} - \boldsymbol{t}) \leq \boldsymbol{0}$.
  • cb_ub: $s_c (\boldsymbol{z} - \lfloor C \oslash (\boldsymbol{p} \odot \boldsymbol{c} \odot \boldsymbol{l}) \rfloor \odot \boldsymbol{b}) \leq \boldsymbol{0}$, with $c_i = 1 + T \min(f_{\text{p},i}, 0)$.
  • cb_lb: $s_c (\boldsymbol{b} - \boldsymbol{z}) \leq \boldsymbol{0}$.

z is integer and non-negative, so cb_lb holds $b_i$ at zero when $z_i = 0$, and cb_ub holds it at one when $z_i \geq 1$. The rows read the lot count and not the share count, because a held position of a lot unit below one has $x_i < 1$. cb_ub removes no book: the budget of finite_sub_allocation holds $l_i z_i p_i c_i \leq C$, so $z_i \leq \lfloor C / (p_i c_i l_i) \rfloor$. Under a non-negative rate $c_i = 1$. A negative short rate of Fees is a credit, which lowers the cost of a share to $p_i c_i$. The binary is an exact indicator.

Where:

  • $\boldsymbol{x}$: Share count vector of one side of a finite allocation, the model expression x. Each entry is a non-negative integer multiple of the lot unit of its asset.
  • $\boldsymbol{z} \in \mathbb{Z}_{\geq 0}^{N}$: Lot count vector of one side of a finite allocation, the number of whole lots of each asset, the model variable z.
  • $\boldsymbol{l}$: Lot unit of each asset of one side of a finite allocation, the number of shares in one lot. A scalar applies to every asset.
  • $\boldsymbol{m} = \boldsymbol{x} \odot \boldsymbol{p}$: Position money vector, the money in each position of one side.
  • $\boldsymbol{m}_{0}$: Money in each position before the trade, sf.prev_money.
  • $\boldsymbol{t}$: Epigraph of the money traded, t_ftn.
  • $\boldsymbol{b}$: Binary indicator of a held position.
  • $\boldsymbol{c}$: Cost of a share per unit of its price, net of the credit of a negative proportional rate over the horizon.
  • $C$: Side cash, the cash that one side of a finite allocation can spend.
  • $\boldsymbol{p}$: Asset price vector of one side of a finite allocation.
  • $T$: Horizon, in periods.
  • $\boldsymbol{f}_{\text{p}},\, \boldsymbol{f}_{\text{Tn}},\, \boldsymbol{f}_{\text{f}}$: Proportional, turnover and fixed rates of this side.
  • $F_{\text{lq}}$: Forced exit of allocation_liquidation_fee, sf.liq. It is a constant, because the assets it sells are not among the share counts this model solves for.
  • $s_c$: Constraint scale. It multiplies both sides of a row, so a positive value leaves the feasible set unchanged.
  • $\odot$: Element-wise (Hadamard) product.
  • $\oslash$: Element-wise division.

Relaxation

The encoding is not exact: the entries below bound the quantity instead of reproducing it, and the bound is tight only under the condition stated here.

model[:fee] lies at or above the fee of the book, $F(\boldsymbol{x})$, and the quantity bounded is t_ftn, which fee_tn and fee read. The bound is tight where the solver puts $\boldsymbol{t}$ at $\lvert \boldsymbol{m} - \boldsymbol{m}_{0} \rvert$, and no objective term pulls it there. The set of books the model admits is exact all the same. A book whose exact fee fits the budget admits $\boldsymbol{t} = \lvert \boldsymbol{m} - \boldsymbol{m}_{0} \rvert$. That is why finite_sub_allocation reports allocation_fee of the realised book, and not the value of fee.

Validation

  • With a fixed fee, $c_i > 0$ on every asset, which raises a DomainError otherwise. At $c_i \leq 0$ the credit over the horizon pays for the whole position, so the cash bounds no share count and the binary has no bound.

Arguments

  • model::JuMP.Model: The JuMP optimisation model.
  • p::VecNum: Asset prices of this side.
  • lu::Num_VecNum: Lot unit of this side, one scalar for every asset or one value for each asset.
  • cash::Number: Cash of this side. It bounds the lots a binary can switch on.
  • sf::Option{<:SideFees}: This side's charge, or nothing.

Returns

  • fee: The fee expression, also stored under model[:fee].

Related

source