Fees Constraints: private API
PortfolioOptimisers.add_to_fees! — Function
add_to_fees!(
model::Model,
expr::Union{Number, AbstractJuMPScalar}
)
Add a term to the per period fee of the JuMP model.
The first call registers :fees as an affine expression equal to expr, so a number can take a later term. Each later call adds expr to it in place. :fees is a shared entry, so a nested build reads it under the bare key.
JuMP formulation
Expressions
fees: $f_r = \sum_j e_j$, the sum of the terms that the builders pass.set_net_portfolio_returns!subtracts it from every observation, andadd_fees_to_ret!subtracts it from the expected return.
Where:
- $f_r$: Per period fee, the model's
:feesexpression. Each observation of the net return series pays it in full. - $e_j$: The $j$-th term passed in,
expr.
Arguments
model::JuMP.Model: The JuMP optimisation model.expr: The term to add. A plain number is accepted beside a JuMP scalar, because the forced liquidation ofset_liquidation_fees!does not depend on the decision variables, and it is a number whenkis a constant.
Returns
nothing.
Related
add_to_one_time_fees!: The twin for the terms that the holding period pays one time.set_long_non_fixed_fees!set_short_non_fixed_fees!set_turnover_fees!set_liquidation_fees!Fees
PortfolioOptimisers.add_to_one_time_fees! — Function
add_to_one_time_fees!(
model::Model,
expr::Union{Number, AbstractJuMPScalar}
)
Add a term to the one-off fee of the JuMP model.
The holding period pays these terms one time, and each observation does not. The three fixed fees reach it: fl and fs through set_fixed_fees!, and flq through set_fixed_liquidation_fees!. set_net_portfolio_returns! charges it on the clock of the fee, and add_fees_to_ret! divides it by the observation count, because an expected return is a per period number. The first call registers :one_time_fees as an affine expression equal to expr, and each later call adds expr to it in place. It is a shared entry, so a nested build reads it under the bare key.
JuMP formulation
Expressions
one_time_fees: $f_o = \sum_j e_j$, the sum of the terms that the builders pass.
Where:
- $f_o$: One-off fee, the model's
:one_time_feesexpression. The holding period pays it one time. - $e_j$: The $j$-th term passed in,
expr.
Arguments
model::JuMP.Model: The JuMP optimisation model.expr: The term to add. A plain number is accepted beside a JuMP scalar, because the fixed liquidation charge is a number whenkis a constant.
Returns
nothing.
Related
add_to_fees!: The twin for the terms that each observation pays.set_fixed_fees!set_fixed_liquidation_fees!charge_one_time_feesset_net_portfolio_returns!add_fees_to_ret!
PortfolioOptimisers.charge_one_time_fees — Function
charge_one_time_fees(model::JuMP.Model, net, one_time, T::Number,
fa::Option{<:AbstractFeeAmortisation})Charge the one-off fee of the JuMP model to a net return series, on the clock of the fee.
It is the model's twin of charge_fees, and it states the same rule. A nothing or FirstObservationFees clock charges the whole fee to the first observation. An AmortisedFees clock charges an equal part of it to every observation of the fit.
Mathematical definition
\[\begin{align} \hat{r}^{\prime}_t &= \hat{r}_t - c_t f_o\,. \end{align}\]
Where:
- $\hat{r}^{\prime}_t$: Entry $t$ of the returned series.
- $\hat{r}_t$: Net portfolio return at observation $t$, $\boldsymbol{x}_t^\intercal \boldsymbol{w}$ less the fees charged at $t$.
- $c_t$: Charge fraction of observation $t$, the part of $f_o$ that the observation pays. Under a
nothingorFirstObservationFeesclock $c_1 = 1$ and $c_t = 0$ for $t > 1$. Under anAmortisedFeesclock $c_t = 1 / T$. - $f_o$: One-off fee, the model's
:one_time_feesexpression. The holding period pays it one time. - $T$: Number of observations.
Algorithm
- On a
nothingorFirstObservationFeesfa, subtractone_timefrom the first entry ofnetin place, and leave the other entries. - On an
AmortisedFeesfa, buildshare = one_time / Tone time, and subtract it from every entry ofnetin place.
JuMP formulation
Expressions
share, not registered: $f_o / T$. Only theAmortisedFeesmethod builds it.
Where:
- $f_o$: One-off fee, the model's
:one_time_feesexpression. The holding period pays it one time. - $T$: Number of observations.
Arguments
model::JuMP.Model: The JuMP optimisation model.net: The net return series, already charged $f_r$. The function changes its entries.one_time: The one-off fee:one_time_fees.T: Observation count of the fit, fromget_T.fa: The clock of the fee, from:fee_fa.
Returns
net, charged the one-off fee.
Related
PortfolioOptimisers.set_turnover_fees! — Function
set_turnover_fees!(model::JuMP.Model, tn::Turnover)
set_turnover_fees!(model::JuMP.Model, ::Nothing)Add the turnover fee to the per period fee of the JuMP model.
The fee charges the rate of each asset on the distance of its weight from the reference weight of tn. The model holds each distance in an epigraph variable, so the charge is linear. The reference weight is multiplied by k, so under MaximumRatio the fee acts on the homogenised weights $k \boldsymbol{w}$ and scales with them. The method on nothing does nothing, and it runs when the fee states no turnover term. Any other type or arity is a MethodError.
Mathematical definition
\[\begin{align} F_{\text{tn}} &= \sum_{i = 1}^{N} v_i \left\lvert w_i - w_{\text{tn},i} \right\rvert\,. \end{align}\]
Where:
- $F_{\text{tn}}$: Turnover fee.
- $v_i$: Fee rate of asset $i$, the
valoftn. A scalar applies to every asset. - $w_{\text{tn},i}$: Reference weight of asset $i$, the
woftn. - $w_i$: Weight of asset $i$.
- $N$: Number of assets.
JuMP formulation
Variables
w,k: read from the model.t_ftn: created, one epigraph entry for each asset.
Expressions
x_ftn: $\boldsymbol{x} = \boldsymbol{w} - \boldsymbol{w}_{\text{tn}} k$.ftn: $\boldsymbol{v}^\intercal \boldsymbol{t}$.add_to_fees!adds it to $f_r$.
Constraints
cftn[i]: $\left(s_c t_i,\, s_c x_i\right)$ lies in the 1-norm cone of dimension two, which is $t_i \geq \lvert x_i \rvert$.
Where:
- $\boldsymbol{t}$: The epigraph variable
t_ftn. - $\boldsymbol{x}$: The deviation
x_ftn. - $\boldsymbol{v}$: Fee rate vector, the
valoftn. - $\boldsymbol{w}_{\text{tn}}$: Reference weight vector, the
woftn. - $f_r$: Per period fee, the model's
:feesexpression. Each observation of the net return series pays it in full. - $s_c$: Constraint scale. It multiplies both sides of a row, so a positive value leaves the feasible set unchanged.
- $k$: Variable that scales the budget in the homogenised problem.
- $\boldsymbol{w}$: Portfolio weights vector $N \times 1$.
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.
- The rows give $t_i \geq \lvert x_i \rvert$, so
ftnlies at or above $\boldsymbol{v}^\intercal \lvert \boldsymbol{w} - \boldsymbol{w}_{\text{tn}} k \rvert$. - The bound is tight when the model pulls
:feesdown. An objective that maximises a return net of the fee does, and so do a binding return floor and a risk measure that reads the net return series. When nothing reads the fee,t_ftncan lie above the distance, and the weights do not depend on it.
Arguments
model::JuMP.Model: The JuMP optimisation model.tn::Turnover: The reference weightswand the fee rateval.
Returns
nothing.
Related
add_to_fees!set_non_fixed_fees!set_turnover_constraints!: Reads the sameTurnoveras a bound on each distance.TurnoverFees
PortfolioOptimisers.set_non_fixed_fees! — Function
set_non_fixed_fees!(model::JuMP.Model, fees::Fees)
set_non_fixed_fees!(model::JuMP.Model, ::Nothing)Add every fee of fees that needs no binary to the JuMP model.
These are the proportional fees l and s, the turnover fee tn, and the two liquidation charges lq and flq. The fixed fees fl and fs need a binary for each asset, so the MIP builder charges them through set_fixed_fees! before this builder runs. The method on nothing does nothing, and it runs when the optimisation states no fee. Any other type or arity is a MethodError.
Algorithm
- Charge
fees.landfees.sthroughset_proportional_fees!. It charges the parts of the weights, or the weights themselves whenfees.sis a credit on a model with a short part. - Charge
fees.tnthroughset_turnover_fees!. - Charge
fees.lqthroughset_liquidation_fees!. - Charge
fees.flqthroughset_fixed_liquidation_fees!, withfees.kwargs. - When the model holds no
:fee_fa, registerfees.faunder it.set_net_portfolio_returns!reads it as the clock of the one-off fee.
Arguments
model::JuMP.Model: The JuMP optimisation model.fees::Fees: The fee of the optimisation.
Returns
nothing.
Related
PortfolioOptimisers.set_long_non_fixed_fees! — Function
set_long_non_fixed_fees!(model::JuMP.Model, fl::Num_VecNum)
set_long_non_fixed_fees!(model::JuMP.Model, ::Nothing)Add the proportional fee of the long positions to the per period fee of the JuMP model.
The fee charges the model's long part lw, and not the weights. lw holds the homogenised long part, so under MaximumRatio the fee scales with the weights. The method on nothing does nothing, and it runs when the fee states no l. Any other type or arity is a MethodError.
Mathematical definition
\[\begin{align} F_l &= \sum_{i = 1}^{N} f_{l,i} \max\left(w_i, 0\right)\,. \end{align}\]
Where:
- $F_l$: Proportional long fee.
- $f_{l,i}$: Fee rate of asset $i$,
fl. A scalar applies to every asset. - $w_i$: Weight of asset $i$.
- $N$: Number of assets.
JuMP formulation
Variables
lw: read from the model.
Expressions
fl: $\boldsymbol{f}_l^\intercal \boldsymbol{w}^{l}$.add_to_fees!adds it to $f_r$.
Where:
- $\boldsymbol{f}_l$: Fee rate vector,
fl. - $\boldsymbol{w}^{l}$: Long part of the weights,
lw. - $f_r$: Per period fee, the model's
:feesexpression. Each observation of the net return series pays it in full.
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.
- Under a
PartsBoundWeightshead,lwlies at or above the long part ofw, sofllies at or above $F_l$. - The bound is tight when the decomposition is pinned, which
xbgt = trueonJuMPOptimiserdoes, and under aWeightsFromPartshead with a sign pattern. The budget pinssum(lw)andsum(sw)whether or not the weights reach them, so without the pin a long-short model can pay the fee on an exposure that it does not hold.
Arguments
model::JuMP.Model: The JuMP optimisation model.fl::Num_VecNum: Fee rate of each asset, or one rate for every asset.
Returns
nothing.
Related
PortfolioOptimisers.set_short_non_fixed_fees! — Function
set_short_non_fixed_fees!(model::JuMP.Model, fs::Num_VecNum)
set_short_non_fixed_fees!(model::JuMP.Model, ::Nothing)Add the proportional fee of the short positions to the per period fee of the JuMP model.
The fee charges the model's short part sw, and not the weights. A long-only model registers no sw, and then the method does nothing. The method on nothing does nothing, and it runs when the fee states no s. Any other type or arity is a MethodError.
Mathematical definition
\[\begin{align} F_s &= \sum_{i = 1}^{N} f_{s,i} \max\left(-w_i, 0\right)\,. \end{align}\]
Where:
- $F_s$: Proportional short fee.
- $f_{s,i}$: Fee rate of asset $i$,
fs. A scalar applies to every asset. - $w_i$: Weight of asset $i$.
- $N$: Number of assets.
JuMP formulation
Variables
sw: read from the model.
Expressions
fs: $\boldsymbol{f}_s^\intercal \boldsymbol{w}^{s}$.add_to_fees!adds it to $f_r$.
Where:
- $\boldsymbol{f}_s$: Fee rate vector,
fs. - $\boldsymbol{w}^{s}$: Short part of the weights,
sw. It is non-negative. - $f_r$: Per period fee, the model's
:feesexpression. Each observation of the net return series pays it in full.
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.
- Under a
PartsBoundWeightshead,swlies at or above the short part ofw, sofslies at or above $F_s$. - The bound is tight under the conditions that
set_long_non_fixed_fees!states. Without the pin, a model that holds no short position still pays the fee on the whole short budget. - The bound is safe only for a non-negative
fs, because a slackswthen only overpays. A negativefsis a credit, and a slackswwould earn it on an exposure the model does not hold. Soset_proportional_fees!never calls this builder with a negative entry on a model that registerssw: it charges the whole proportional fee against the weights instead, which is exact.
Arguments
model::JuMP.Model: The JuMP optimisation model.fs::Num_VecNum: Fee rate of each asset, or one rate for every asset.
Returns
nothing.
Related
PortfolioOptimisers.set_proportional_fees! — Function
set_proportional_fees!(model::JuMP.Model, fl::Option{<:Num_VecNum}, fs::Option{<:Num_VecNum})
set_proportional_fees!(model::JuMP.Model, fl::Num_VecNum, fs::Num_VecNum)Add the long and the short proportional fees to the per period fee of the JuMP model.
A non-negative short rate goes to the two part builders, set_long_non_fixed_fees! and set_short_non_fixed_fees!, which charge the parts lw and sw. A negative short rate is a credit. Under a PartsBoundWeights head sw only bounds the short part of the weights. With a non-negative rate a slack sw only overpays, but with a credit it earns on an exposure the model does not hold. So when fs holds a negative entry and the model registers sw, this builder charges the whole proportional fee against w and no part, and the charge is exact whether or not the decomposition is pinned.
Algorithm
- With a
nothingrate on either side, chargeflandfsthrough the two part builders. Anothinglkeepssnon-negative, so no credit reaches this method. - With no negative entry in
fs, or noswin the model, charge them through the two part builders. A long-only model holds noswand no short position. - Otherwise write the epigraph below.
Mathematical definition
\[\begin{align} F_p &= \sum_{i = 1}^{N} \left(f_{l,i} \max\left(w_i, 0\right) - f_{s,i} \min\left(w_i, 0\right)\right) = \sum_{i = 1}^{N} \max\left(f_{l,i} w_i,\, -f_{s,i} w_i\right)\,. \end{align}\]
The second form holds because Fees keeps $f_{s,i} \geq -f_{l,i}$: for $w_i > 0$ the long slope is the larger, and for $w_i < 0$ the short one is.
Where:
- $F_p$: Proportional fee, long and short.
- $f_{l,i}$: Long fee rate of asset $i$,
fl. A scalar applies to every asset. - $f_{s,i}$: Short fee rate of asset $i$,
fs. A scalar applies to every asset. - $w_i$: Weight of asset $i$.
- $N$: Number of assets.
JuMP formulation
Variables
w: read from the model.t_fp: created when the epigraph is written, one entry for each asset.
Expressions
fp: $\sum_i t_i$, when the epigraph is written.add_to_fees!adds it to $f_r$.
Constraints
cfp_l: $s_c \left(\boldsymbol{f}_l \odot \boldsymbol{w} - \boldsymbol{t}\right) \leq 0$.cfp_s: $s_c \left(\boldsymbol{f}_s \odot \boldsymbol{w} + \boldsymbol{t}\right) \geq 0$, which is $t_i \geq -f_{s,i} w_i$.
Where:
- $\boldsymbol{t}$: The epigraph variable
t_fp. - $\boldsymbol{f}_l,\, \boldsymbol{f}_s$: Fee rate vectors,
flandfs. - $\odot$: Elementwise (Hadamard) product.
- $f_r$: Per period fee, the model's
:feesexpression. Each observation of the net return series pays it in full. - $s_c$: Constraint scale. It multiplies both sides of a row, so a positive value leaves the feasible set unchanged.
- $\boldsymbol{w}$: Portfolio weights vector $N \times 1$.
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.
- The rows give $t_i \geq \max(f_{l,i} w_i, -f_{s,i} w_i)$, so
fplies at or above $F_p$. - The bound is tight when the model pulls
:feesdown, under the conditions thatset_turnover_fees!states. It does not depend on a pinned decomposition.
Arguments
model::JuMP.Model: The JuMP optimisation model.fl::Num_VecNum: Long fee rate of each asset, or one rate for every asset.fs::Num_VecNum: Short fee rate of each asset, or one rate for every asset.
Returns
nothing.
Related
PortfolioOptimisers.set_fixed_fees! — Function
set_fixed_fees!(model::JuMP.Model, sp::AbstractMIPSpace, ind::HeldIndicators,
ffl::Option{<:Num_VecNum}, ffs::Option{<:Num_VecNum},
ffl_flag::Bool, ffs_flag::Bool)
set_fixed_fees!(model::JuMP.Model, sp::AbstractMIPSpace, ind::LongShortIndicators,
ffl::Option{<:Num_VecNum}, ffs::Option{<:Num_VecNum},
ffl_flag::Bool, ffs_flag::Bool)Add the fixed fees of the held positions to the one-off fee of the JuMP model.
A fixed fee charges each position that the portfolio holds, whatever its size. So it cannot be written against the weights, and it reads the held binaries of ind. That is the reason a MIP builder calls it.
The fee charges the gate of each binary, which is the binary times k, and not the binary. Under MaximumRatio the weights are the homogenised $k \boldsymbol{w}$ and k is a variable, so the fee scales with the weights, as every other fee does, and the weights do not depend on ohf. When k is a constant, or the long-short asset space runs on a unit budget, the gate is the binary itself. HeldIndicators has no short side, so it charges ffl alone. Each method writes the charge of ffl in the same form from the gate of its bundle, so the two methods agree on the long side.
Mathematical definition
\[\begin{align} F_{\text{f}} &= \boldsymbol{f}_{\text{fl}}^\intercal \boldsymbol{b}^{l} + \boldsymbol{f}_{\text{fs}}^\intercal \boldsymbol{b}^{s}\,. \end{align}\]
Where:
- $F_{\text{f}}$: Fixed fee.
- $\boldsymbol{f}_{\text{fl}}$, $\boldsymbol{f}_{\text{fs}}$: Long and short fixed fee of each position,
fflandffs. A scalar applies to every position. - $\boldsymbol{b}^{l}$, $\boldsymbol{b}^{s}$: Long and short held binaries. Under
HeldIndicators$\boldsymbol{b}^{l}$ is the held binary and $\boldsymbol{b}^{s} = \boldsymbol{0}$.
JuMP formulation
Variables
- The long gate $\boldsymbol{g}^{l}$: read from
ind. It isi_mipofHeldIndicators, andilofLongShortIndicators. - The short gate $\boldsymbol{g}^{s}$: read from
ind. It isisofLongShortIndicators.
Expressions
ffl, under the key thatmip_keygives insp: $\boldsymbol{f}_{\text{fl}}^\intercal \boldsymbol{g}^{l}$, whenffl_flagis set.add_to_one_time_fees!adds it to $f_o$.ffs, under the key thatmip_keygives insp: $\boldsymbol{f}_{\text{fs}}^\intercal \boldsymbol{g}^{s}$, whenffs_flagis set.add_to_one_time_fees!adds it to $f_o$.
Where:
- $\boldsymbol{g}^{l} = k \boldsymbol{b}^{l}$, $\boldsymbol{g}^{s} = k \boldsymbol{b}^{s}$: Long and short gates. The big-M rows of the declaration make each entry equal to $k$ or to zero, when the big-M is not below $k$.
- $\boldsymbol{f}_{\text{fl}}$, $\boldsymbol{f}_{\text{fs}}$: Long and short fixed fee of each position.
- $f_o$: One-off fee, the model's
:one_time_feesexpression. The holding period pays it one time. - $k$: Variable that scales the budget in the homogenised problem.
Arguments
model::JuMP.Model: The JuMP optimisation model.sp::AbstractMIPSpace: Weight space of the positions.ind: Indicator bundle that holds the gates.ffl::Option{<:Num_VecNum}: Long fixed fee of each position.ffs::Option{<:Num_VecNum}: Short fixed fee of each position.HeldIndicatorsdoes not read it.ffl_flag::Bool: Whether to chargeffl.ffs_flag::Bool: Whether to chargeffs.HeldIndicatorsdoes not read it.
Returns
nothing.
Related
PortfolioOptimisers.set_liquidation_fees! — Function
set_liquidation_fees!(::JuMP.Model, ::Nothing)
set_liquidation_fees!(model::JuMP.Model, lq::Turnover)Add the proportional cost of a forced exit to the per period fee of the JuMP model.
lq prices the positions that leave the Investable Mask. Those assets are not in the model's w, because the optimisation removed them before it built the model. So the charge is a constant of the model, and it needs no epigraph variable and no row. The constant is multiplied by k, as the turnover term is, so a ratio objective sees it in the units of every other fee. lq is a rate per period, so the charge joins $f_r$ beside l, s and tn.
Mathematical definition
\[\begin{align} F_{\text{lq}} &= \sum_{i} v_i \left\lvert w_{\text{lq},i} \right\rvert\,. \end{align}\]
Where:
- $F_{\text{lq}}$: Proportional liquidation fee.
- $v_i$: Fee rate of the $i$-th asset that left, the
valoflq. A scalar applies to every such asset. - $w_{\text{lq},i}$: Previous weight of the $i$-th asset that left, the
woflq. A forced exit sells each position to zero, so the trade is its absolute value.
Algorithm
- On a
nothinglq, do nothing. No asset left the universe. - Otherwise read
k. - Compute $F_{\text{lq}}$ through
calc_liquidation_fees. - Register $F_{\text{lq}} k$ and add it to $f_r$ through
add_to_fees!.
JuMP formulation
Variables
k: read from the model.
Expressions
flq_prop: $F_{\text{lq}} k$.
Where:
- $F_{\text{lq}}$: Proportional liquidation fee.
- $f_r$: Per period fee, the model's
:feesexpression. Each observation of the net return series pays it in full. - $k$: Variable that scales the budget in the homogenised problem.
Arguments
model::JuMP.Model: The JuMP optimisation model.lq: The proportional liquidation rate, ornothing.
Returns
nothing.
Related
Feesset_non_fixed_fees!set_turnover_fees!: Charges a distance that depends onw, so it needs an epigraph variable.add_to_fees!calc_liquidation_feesset_fixed_liquidation_fees!
PortfolioOptimisers.set_fixed_liquidation_fees! — Function
set_fixed_liquidation_fees!(::JuMP.Model, ::Nothing, ::NamedTuple)
set_fixed_liquidation_fees!(model::JuMP.Model, flq::Turnover, kwargs::NamedTuple)Add the fixed cost of a forced exit to the one-off fee of the JuMP model.
It is the fixed twin of set_liquidation_fees!, and it is a constant of the model for the same reason. set_fixed_fees! needs a binary for each asset, because the model decides which positions it holds. This charge needs none, because the positions that the exit sold are known from flq.w. The holding period pays it one time, so it joins $f_o$ beside fl and fs, and charge_one_time_fees puts it on the clock of the fee.
Mathematical definition
\[\begin{align} F_{\text{flq}} &= \sum_{i} v_i\, 1\left\{w_{\text{flq},i} \neq 0\right\}\,. \end{align}\]
Where:
- $F_{\text{flq}}$: Fixed liquidation fee.
- $v_i$: Fixed fee of the $i$-th asset that left, the
valofflq. A scalar applies to every such asset. - $w_{\text{flq},i}$: Previous weight of the $i$-th asset that left, the
wofflq. A long and a short position both pay. - $1\left\{\cdot\right\}$: Indicator function. $w \neq 0$ is
!isapprox(w, 0; kwargs...).
Algorithm
- On a
nothingflq, do nothing. - Otherwise read
k. - Compute $F_{\text{flq}}$ through
calc_fixed_liquidation_fees. - Register $F_{\text{flq}} k$ and add it to $f_o$ through
add_to_one_time_fees!.
JuMP formulation
Variables
k: read from the model.
Expressions
flq_fixed: $F_{\text{flq}} k$.
Where:
- $F_{\text{flq}}$: Fixed liquidation fee.
- $f_o$: One-off fee, the model's
:one_time_feesexpression. The holding period pays it one time. - $k$: Variable that scales the budget in the homogenised problem.
Arguments
model::JuMP.Model: The JuMP optimisation model.flq: The fixed liquidation charge, ornothing.kwargs: Forwarded toisapprox, to decide how near zero a weight counts as zero.
Returns
nothing.
Related