Weight Constraints: private API
PortfolioOptimisers.w_neg_flag — Function
w_neg_flag(_::Nothing) -> Bool
Return true when the weight bound wb contains at least one negative value, indicating a long-short strategy is required.
Arguments
wb: Weight bound. Acceptsnothing, a scalarNumber, or aVecNum.
Returns
flag::Bool:falsewhenwbisnothing;wb < 0whenwbis a scalar;any(x -> x < 0, wb)whenwbis a vector.
Related
PortfolioOptimisers.w_finite_flag — Function
w_finite_flag(_::Nothing) -> Bool
Return true when wb contains at least one finite value, meaning a bound constraint should be added to the model.
Arguments
wb: Weight bound. Acceptsnothing, a scalarNumber, or aVecNum.
Returns
flag::Bool:falsewhenwbisnothing;isfinite(wb)whenwbis a scalar;any(isfinite, wb)whenwbis a vector.
Related
PortfolioOptimisers.set_weight_constraints! — Function
set_weight_constraints!(
model::Model,
wb::WeightBounds,
bgt::Union{Nothing, Number, BudgetConstraintEstimator},
sbgt::Union{Nothing, Number, BudgetEstimator};
gbgt,
prefix
)
Add weight bound constraints to the JuMP optimisation model.
The method on a WeightBounds adds lower-bound and upper-bound constraints on the portfolio weight vector w, handles long-short decomposition when negative bounds are present via lw/sw variables, and delegates budget constraints to set_budget_constraints!.
This is the first step of the block builder, set_block_constraints!, so each ConstraintBlock of a model adds its own bounds. The rows go under prefix, the namespace of the block, and the builder reads the weights registered under it. The long and short parts belong to the weights. The first block that admits a short position makes them, with their rows w_lw and w_sw, and a later block reads them. A later block makes parts of its own under its prefix only when the weights already have a long part and no short part, because a block before it is long-only. Its short and gross budgets then read its own parts.
The method on wb = nothing adds no row, with the same arguments and keywords. Any other type or arity is a MethodError.
Mathematical definition
\[\begin{align} k \boldsymbol{\ell} &\leq \boldsymbol{w} \leq k \boldsymbol{u}\,. \end{align}\]
Where:
- $\boldsymbol{w}$: Portfolio weights vector $N \times 1$.
- $k$: Variable that scales the budget in the homogenised problem.
- $\boldsymbol{\ell}$, $\boldsymbol{u}$: Lower and upper bound vectors from
wb.
Arguments
model::JuMP.Model: The JuMP optimisation model.wb::WeightBounds: Weight bound specification containing lower and upper bounds.bgt: Optional total budget constraint. A number, aBudgetRange, or aBudgetCostEstimator, which is the whole ofJuMPOptimiser's ownbgtbound.sbgt: Optional short-side budget constraint. ABudgetCostEstimatorbgtforbids one, so the pair never meets here.gbgt: Optional gross (leverage) budget constraint, applied only when the weight bounds admit shorts. Seeset_gross_budget_constraints!.prefix::Symbol = Symbol(""): Model State namespace of the call. The builder reads the weights under it, and every entry that it registers takes it, so two calls under two prefixes add two sets of rows to one model. The empty default gives the bare names.
Optimiser heads do not call this method directly. The block builder set_block_constraints! calls it with the net budget of the owner of the block, and with the short and gross budgets of the block, so a budget field cannot reach one head and miss the others.
The budgets set here bound the realised exposures rather than pinning them, because lw and sw are upper bounds on the parts of w. Pinning them is the xbgt option of short_mip_threshold_constraints, applied later by set_mip_constraints!.
Returns
nothing.
Related
set_weight_constraints!(
model::Model,
wb::WeightBounds,
opt::JuMPOptimiser
)
Add weight bound and budget constraints to model from the optimiser's own budget group.
UnconstrainedNearOptimalCentering reaches set_weight_constraints! through this method, because its centring solve adds the bounds of the block and no other row of it. The solve runs no MIP step, so the method passes the convex form of the net budget, convex_budget. A BudgetCosts with xbgt = true then keeps the floor of the invested weights. Every other JuMP head adds its bounds and its budgets in phase 1 of its block, set_block_constraints!, with the net budget of the head. Both routes pass the whole budget group (bgt, sbgt, gbgt) as one object, so a budget field cannot reach one head and miss the others.
Arguments
model::JuMP.Model: The JuMP optimisation model.wb::WeightBounds: Weight bound specification containing lower and upper bounds.opt::JuMPOptimiser: Optimiser supplying the budget group.
Returns
nothing.
Related
PortfolioOptimisers.set_weight_parts! — Function
set_weight_parts!(
model::Model,
w::AbstractVector,
_::Symbol
)
Add the long and short parts of the weights, lw and sw, for a block whose bounds admit a short position.
The parts belong to the weights, so they go in the shared Model State once. The first block that admits a short position makes them, or reads the parts that its head made, and adds the rows that tie them to w. A later block reads the same parts and adds no row. A head that derives w from the parts keeps its identity, because the rows here only bound the parts.
A block before this one can be long-only. Then the weights already have the long part lw = w and no short part. This block cannot change that entry, because the rows of the earlier block read it. So the function adds nothing, and a budget of the block that reads the parts makes parts of its own under prefix through weight_parts!. This is the case of a programme set that admits a short position in the model of a long-only leader.
JuMP formulation
Variables
lw,sw: $N \times 1$, each bounded below by zero, shared.
Constraints
w_lw: $s_c (\boldsymbol{w} - \boldsymbol{lw}) \leq 0$.w_sw: $s_c (\boldsymbol{w} + \boldsymbol{sw}) \geq 0$.
Where:
- $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$.
- $N$: Number of assets.
Arguments
model::JuMP.Model: The JuMP optimisation model.w: The weights registered underprefix.prefix: The Model State namespace of the block.
Returns
nothing.
Related
PortfolioOptimisers.weight_parts! — Function
weight_parts!(model::JuMP.Model, prefix::Symbol) -> TupleReturn the long and short parts of the weights that the budgets of a block read.
A block reads the shared parts of the weights when they exist, see set_weight_parts!. When a long-only block came first, the weights have the long part lw = w and no short part. Then the first budget of the block that reads the parts makes parts of its own under prefix, with their rows, and a later budget of the block reads them. So a block that states no short or gross budget makes no parts.
JuMP formulation
Variables
lw,sw: $N \times 1$, each bounded below by zero, underprefix, when the function makes parts of the block.
Constraints
w_lw: $s_c (\boldsymbol{w} - \boldsymbol{lw}) \leq 0$, underprefix.w_sw: $s_c (\boldsymbol{w} + \boldsymbol{sw}) \geq 0$, underprefix.
Where:
- $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$. It is the weights registered under
prefix. - $N$: Number of assets.
Arguments
model::JuMP.Model: The JuMP optimisation model.prefix: The Model State namespace of the block.
Returns
(lw, sw)::Tuple: The long and the short parts.
Related
PortfolioOptimisers.assert_long_only_weight_bounds — Function
assert_long_only_weight_bounds(wb::WeightBounds)
Check that weight bounds admit no short position, for a head whose formulation is long-only.
RiskBudgeting and RelaxedRiskBudgeting take the logarithm or the cone of the asset weights, which holds only for non-negative weights. The head calls this check where it builds its weights. The block builder set_block_constraints! then adds the bounds.
Arguments
wb::WeightBounds: Weight bound specification containing lower and upper bounds.
Validation
- No bound is negative. An
ArgumentErroris thrown otherwise.
Returns
nothing.
Related
PortfolioOptimisers.budget_upper_bound — Function
budget_upper_bound(bgt) -> NumberReturn the upper bound that a budget puts on a sum of weights, or Inf when it puts none.
A number pins the sum, so it is its own bound. A BudgetRange bounds the sum by its ub. nothing, a range without ub, and a budget that also pays costs give Inf.
Arguments
bgt: The budget, asset_weight_constraints!receives it.
Returns
ub::Number: The upper bound of the sum, in units of $k$.
Related
PortfolioOptimisers.gross_exposure_bound — Function
gross_exposure_bound(wb::WeightBounds, bgt, sbgt, gbgt, N::Integer) -> NumberReturn an upper bound on the gross exposure of every weight vector that the weight bounds and the budgets admit, or Inf when they admit no bound.
The bound is the smallest of the bounds below that apply.
\[\begin{align} \lVert \boldsymbol{w} \rVert_{1} &\leq \sum_{i=1}^{N} \max\left(\lvert \ell_{i} \rvert,\, \lvert u_{i} \rvert\right)\,, \\ \lVert \boldsymbol{w} \rVert_{1} &\leq \overline{B}\,, \quad \text{if } \boldsymbol{\ell} \geq \boldsymbol{0}\,, \\ \lVert \boldsymbol{w} \rVert_{1} &\leq \min\left(\overline{G},\, \overline{B} + 2 \overline{S}\right)\,, \quad \text{if a bound is negative}\,. \end{align}\]
Where:
- $\boldsymbol{w}$: Portfolio weights vector $N \times 1$.
- $\boldsymbol{\ell}$, $\boldsymbol{u}$: Lower and upper bound vectors from
wb. - $\overline{B}$, $\overline{S}$, $\overline{G}$: Upper bounds of the budget, the short budget and the gross budget, from
budget_upper_bound. - $w^{+}_{i}$, $w^{-}_{i}$: Long and short parts of weight $i$, the model's
lwandsw. - $k$: Variable that scales the budget in the homogenised problem.
- $N$: Number of assets.
The first bound holds for all weights. The second holds because non-negative weights have a gross exposure equal to their sum. The third holds because $\lvert w_{i} \rvert \leq w^{+}_{i} + w^{-}_{i}$, the long budget bounds the sum of the long parts by $\overline{B} + \overline{S}$, and the short budget bounds the sum of the short parts by $\overline{S}$. Each bound is in units of $k$, as the constraints of set_weight_constraints! are.
Arguments
wb::WeightBounds: Weight bound specification containing lower and upper bounds.bgt: The budget.sbgt: The short budget.gbgt: The gross budget.N::Integer: The number of assets.
Returns
g::Number: The bound, orInf.
Related
PortfolioOptimisers.set_gross_exposure_bound! — Function
set_gross_exposure_bound!(model::JuMP.Model, g::Number)Record g as the shared Model State entry :w_gross_ub, the bound on the gross exposure of the head's weights.
A second call keeps the smaller bound, because the constraints of both calls hold for the same weights. mip_big_m reads the entry.
Arguments
model::JuMP.Model: The JuMP optimisation model.g::Number: The bound, fromgross_exposure_bound.
Returns
g::Number: The bound that the model records.
Related
PortfolioOptimisers.non_zero_real_or_vec — Function
non_zero_real_or_vec(_::Nothing) -> Bool
Return true when x is non-zero.
Arguments
x: Value to check. Acceptsnothing, a scalarNumber, or aVecNum.
Returns
flag::Bool:falsewhenxisnothing;!iszero(x)for a scalar;any(!iszero, x)for a vector.
Related
PortfolioOptimisers.set_linear_weight_constraints! — Function
set_linear_weight_constraints!(
model::Model,
lcms::Union{LinearConstraint, AbstractVector{<:LinearConstraint}},
name_ineq::Symbol,
name_eq::Symbol;
prefix
)
Add linear inequality and equality weight constraints to the JuMP optimisation model.
The method on lcms = nothing adds no row. Any other type or arity is a MethodError. The method on a Lc_VecLc iterates over the collection of LinearConstraint objects lcms and adds A * w ≤ k * B (inequality) and A * w = k * B (equality) constraints for each entry.
Mathematical definition
\[\begin{align} \mathbf{A}_{\mathrm{ineq}} \boldsymbol{w} \leq k \boldsymbol{B}_{\mathrm{ineq}}\,, \\ \mathbf{A}_{\mathrm{eq}} \boldsymbol{w} &= k \boldsymbol{B}_{\mathrm{eq}}\,. \end{align}\]
Where:
- $\boldsymbol{w}$: Portfolio weights vector $N \times 1$.
- $k$: Variable that scales the budget in the homogenised problem.
- $\mathbf{A}_{\mathrm{ineq}}$, $\mathbf{A}_{\mathrm{eq}}$: Constraint coefficient matrices for inequality and equality constraints.
- $\boldsymbol{B}_{\mathrm{ineq}}$, $\boldsymbol{B}_{\mathrm{eq}}$: Constraint response vectors for inequality and equality constraints.
Arguments
model::JuMP.Model: The JuMP optimisation model.lcms: Collection ofLinearConstraintobjects defining the linear constraints.name_ineq::Symbol: Bare Model State entry name seeding the indexed inequality constraint entries.name_eq::Symbol: Bare Model State entry name seeding the indexed equality constraint entries.prefix::Symbol = Symbol(""): Model State namespace of the call. The builder reads the weights under it, and every entry that it registers takes it, so two calls under two prefixes add two sets of rows to one model. The empty default gives the bare names.
Returns
nothing.
Related