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
- On an empty
w, return three empty vectors,cashless the fee of the empty book, that fee, andnothingfor the return code and for the model. The fee isallocation_feeof the empty book, because a side that buys nothing can still owe a turnover fee or the forced exit. - Normalise
wto sum to one. A side whose weights sum to zero keeps them. - Build the model of the
# JuMP formulationbelow, and solve it withda.slv. - 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 byluto 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. - Make the cost
shares .* p, and the realised weightscost / sum(cost) * bgt. The realised weights are all zero when nothing was bought. - Price the fee with
allocation_feeof the realised shares, and not with the value ofmodel[:fee], which can lie above it. See the## Relaxationofset_allocation_fees!. - Make the leftover cash,
cashless 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
uthat 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 asw.lu::Num_VecNum: Lot unit of this side, one scalar for every asset or one value for each asset in the order ofw.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, ofallocation_side_fees, ornothing.da::DiscreteAllocation: Allocator carrying the solvers, the scales and the formulationwf.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 tobgt.acash::Number: Cash left over,cashless the cost of the shares and the fee.fee::Number: The fee this side paid over the whole horizon.res::OptimisationReturnCode: AnOptimisationSuccessor anOptimisationFailurecarrying the solver trials.model::JuMP.Model: The solved model.
Related
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 thatset_norm_error_epigraph!returns for the normwf.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
uthat bounds the deviation of the book from its target. - $\boldsymbol{d}$: The residual of
weight_deviationforwf.dev, $(\boldsymbol{x} \odot \boldsymbol{p}) \oslash (C \tilde{\boldsymbol{w}}) - \boldsymbol{1}$ for aRelativeWeightDeviation, and $\boldsymbol{x} \odot \boldsymbol{p} - C \boldsymbol{w}$ for anAbsoluteWeightDeviation. - $\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 asw.cash::Number: Cash of this side.wf::ErrorWeightFinaliser: Selects the error. See the table inDiscreteAllocation.
Returns
err: The error term of the objective, in money, fromdeviation_error_term:uunder an absolute deviation, andcash * uunder a relative one, whose error has no unit.
Related
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 whensfstates a turnover rate.b: Binary indicator of a held position, created whensfstates a fixed fee.
Expressions
x: Share count vector, read from the model.money: $\boldsymbol{m}$.fee_prop: $\boldsymbol{f}_{\text{p}}^\intercal \boldsymbol{m}$, whensfstates a proportional rate.fee_tn: $\boldsymbol{f}_{\text{Tn}}^\intercal \boldsymbol{t}$, whensfstates a turnover rate.fee_fixed: $\boldsymbol{f}_{\text{f}}^\intercal \boldsymbol{b}$, whensfstates a fixed fee.fee: $T (f_{\text{p}} + f_{\text{Tn}}) + f_{\text{f}} + F_{\text{lq}}$ over the termssfstates, stored undermodel[:fee]. It is a zero expression whensfisnothing.
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
DomainErrorotherwise. 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, ornothing.
Returns
fee: The fee expression, also stored undermodel[:fee].
Related