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

Where:

  • $f_r$: Per period fee, the model's :fees expression. 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 of set_liquidation_fees! does not depend on the decision variables, and it is a number when k is a constant.

Returns

  • nothing.

Related

source
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_fees expression. 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 when k is a constant.

Returns

  • nothing.

Related

source
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 nothing or FirstObservationFees clock $c_1 = 1$ and $c_t = 0$ for $t > 1$. Under an AmortisedFees clock $c_t = 1 / T$.
  • $f_o$: One-off fee, the model's :one_time_fees expression. The holding period pays it one time.
  • $T$: Number of observations.

Algorithm

  1. On a nothing or FirstObservationFees fa, subtract one_time from the first entry of net in place, and leave the other entries.
  2. On an AmortisedFees fa, build share = one_time / T one time, and subtract it from every entry of net in place.

JuMP formulation

Expressions

  • share, not registered: $f_o / T$. Only the AmortisedFees method builds it.

Where:

  • $f_o$: One-off fee, the model's :one_time_fees expression. 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, from get_T.
  • fa: The clock of the fee, from :fee_fa.

Returns

  • net, charged the one-off fee.

Related

source
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 val of tn. A scalar applies to every asset.
  • $w_{\text{tn},i}$: Reference weight of asset $i$, the w of tn.
  • $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 val of tn.
  • $\boldsymbol{w}_{\text{tn}}$: Reference weight vector, the w of tn.
  • $f_r$: Per period fee, the model's :fees expression. 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 ftn lies at or above $\boldsymbol{v}^\intercal \lvert \boldsymbol{w} - \boldsymbol{w}_{\text{tn}} k \rvert$.
  • The bound is tight when the model pulls :fees down. 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_ftn can lie above the distance, and the weights do not depend on it.

Arguments

  • model::JuMP.Model: The JuMP optimisation model.
  • tn::Turnover: The reference weights w and the fee rate val.

Returns

  • nothing.

Related

source
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

  1. Charge fees.l and fees.s through set_proportional_fees!. It charges the parts of the weights, or the weights themselves when fees.s is a credit on a model with a short part.
  2. Charge fees.tn through set_turnover_fees!.
  3. Charge fees.lq through set_liquidation_fees!.
  4. Charge fees.flq through set_fixed_liquidation_fees!, with fees.kwargs.
  5. When the model holds no :fee_fa, register fees.fa under 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

source
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 :fees expression. 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 PartsBoundWeights head, lw lies at or above the long part of w, so fl lies at or above $F_l$.
  • The bound is tight when the decomposition is pinned, which xbgt = true on JuMPOptimiser does, and under a WeightsFromParts head with a sign pattern. The budget pins sum(lw) and sum(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

source
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 :fees expression. 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 PartsBoundWeights head, sw lies at or above the short part of w, so fs lies 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 slack sw then only overpays. A negative fs is a credit, and a slack sw would earn it on an exposure the model does not hold. So set_proportional_fees! never calls this builder with a negative entry on a model that registers sw: 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

source
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

  1. With a nothing rate on either side, charge fl and fs through the two part builders. A nothing l keeps s non-negative, so no credit reaches this method.
  2. With no negative entry in fs, or no sw in the model, charge them through the two part builders. A long-only model holds no sw and no short position.
  3. 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, fl and fs.
  • $\odot$: Elementwise (Hadamard) product.
  • $f_r$: Per period fee, the model's :fees expression. 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 fp lies at or above $F_p$.
  • The bound is tight when the model pulls :fees down, under the conditions that set_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

source
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, ffl and ffs. 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

Expressions

  • ffl, under the key that mip_key gives in sp: $\boldsymbol{f}_{\text{fl}}^\intercal \boldsymbol{g}^{l}$, when ffl_flag is set. add_to_one_time_fees! adds it to $f_o$.
  • ffs, under the key that mip_key gives in sp: $\boldsymbol{f}_{\text{fs}}^\intercal \boldsymbol{g}^{s}$, when ffs_flag is 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_fees expression. 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. HeldIndicators does not read it.
  • ffl_flag::Bool: Whether to charge ffl.
  • ffs_flag::Bool: Whether to charge ffs. HeldIndicators does not read it.

Returns

  • nothing.

Related

source
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 val of lq. A scalar applies to every such asset.
  • $w_{\text{lq},i}$: Previous weight of the $i$-th asset that left, the w of lq. A forced exit sells each position to zero, so the trade is its absolute value.

Algorithm

  1. On a nothing lq, do nothing. No asset left the universe.
  2. Otherwise read k.
  3. Compute $F_{\text{lq}}$ through calc_liquidation_fees.
  4. 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 :fees expression. 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, or nothing.

Returns

  • nothing.

Related

source
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 val of flq. A scalar applies to every such asset.
  • $w_{\text{flq},i}$: Previous weight of the $i$-th asset that left, the w of flq. A long and a short position both pay.
  • $1\left\{\cdot\right\}$: Indicator function. $w \neq 0$ is !isapprox(w, 0; kwargs...).

Algorithm

  1. On a nothing flq, do nothing.
  2. Otherwise read k.
  3. Compute $F_{\text{flq}}$ through calc_fixed_liquidation_fees.
  4. 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_fees expression. 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, or nothing.
  • kwargs: Forwarded to isapprox, to decide how near zero a weight counts as zero.

Returns

  • nothing.

Related

source