Budget Constraints: private API
PortfolioOptimisers.BudgetConstraintEstimator — Type
abstract type BudgetConstraintEstimator <: JuMPConstraintEstimatorAbstract supertype for all budget constraint estimators.
Related
PortfolioOptimisers.Num_BgtCE — Type
const Num_BgtCE = Union{Number, BudgetConstraintEstimator}Union of scalar budget values and BudgetConstraintEstimator instances.
PortfolioOptimisers.BudgetEstimator — Type
abstract type BudgetEstimator <: BudgetConstraintEstimatorAbstract supertype for estimators that specify the portfolio budget range (sum of weights).
Related
PortfolioOptimisers.BudgetCostEstimator — Type
abstract type BudgetCostEstimator <: BudgetConstraintEstimatorAbstract supertype for estimators that specify transaction cost budgets.
Each member holds a reference portfolio w and a fixed flag. factory and needs_previous_weights read both.
Related
PortfolioOptimisers.Num_BgtRg — Type
const Num_BgtRg = Union{Number, BudgetEstimator}Alias for a scalar budget value or budget range.
Matches either a plain number (fixed budget, e.g. 1.0) or a BudgetEstimator, such as a BudgetRange (interval budget constraint). Used for dispatch in budget constraint generation.
Related
PortfolioOptimisers.set_budget_constraints! — Function
set_budget_constraints!(model::JuMP.Model, ::Nothing, w::VecNum; prefix::Symbol = Symbol(""))
set_budget_constraints!(model::JuMP.Model, val::Number, w::VecNum; prefix::Symbol = Symbol(""))
set_budget_constraints!(model::JuMP.Model, bgt::BudgetRange, w::VecNum; prefix::Symbol = Symbol(""))
set_budget_constraints!(model::JuMP.Model, bgt::BudgetCosts, w::VecNum; prefix::Symbol = Symbol(""))
set_budget_constraints!(model::JuMP.Model, bgt::BudgetMarketImpact, w::VecNum; prefix::Symbol = Symbol(""))Add budget constraints to the JuMP optimisation model.
The method on nothing adds no row. The other methods add the portfolio budget constraint that the type of the budget states. Any other type or arity is a MethodError.
A number and a BudgetRange register their rows under prefix, the namespace of the block whose owner states the budget. A budget that pays costs registers its trade variables, its cost expression and its rows in the shared Model State, because they measure the trade of the one weight vector. The rows are wp_ub and wn_ub, the bounds of the trades, cost_bgt_trade, the trade of the weights from the reference, and for BudgetMarketImpact the power cones wip_pcone and win_pcone. So it goes on the first block of a model, the block of its owner, and refuses a non-empty prefix.
Mathematical definition
Fixed / range:
\[\begin{align} k \cdot \mathrm{lb} &\leq \sum_i w_i \leq k \cdot \mathrm{ub}\,. \end{align}\]
Where:
- $\boldsymbol{w}$: Portfolio weights vector $N \times 1$.
- $k$: Variable that scales the budget in the homogenised problem.
- $\mathrm{lb}$, $\mathrm{ub}$: Lower and upper budget bounds.
Linear cost budget (BudgetCosts):
\[\begin{align} \sum_i w_i + \boldsymbol{v}_p^\intercal \boldsymbol{w}_p + \boldsymbol{v}_n^\intercal \boldsymbol{w}_n \in [k\,\mathrm{lb},\; k\,\mathrm{ub}]\,. \end{align}\]
Where:
- $\boldsymbol{w}$: Portfolio weights vector $N \times 1$.
- $k$: Variable that scales the budget in the homogenised problem.
- $\boldsymbol{w}_p$, $\boldsymbol{w}_n$: Positive and negative weight increments.
- $\boldsymbol{v}_p$, $\boldsymbol{v}_n$: Cost coefficient vectors for positive and negative changes.
- $\mathrm{lb}$, $\mathrm{ub}$: Lower and upper budget bounds.
Power-law market-impact budget (BudgetMarketImpact):
\[\begin{align} \sum_i w_i + \boldsymbol{v}_p^\intercal \boldsymbol{w}_p^{1/\beta} + \boldsymbol{v}_n^\intercal \boldsymbol{w}_n^{1/\beta} \in [k\,\mathrm{lb},\; k\,\mathrm{ub}]\,. \end{align}\]
Where:
- $\boldsymbol{w}$: Portfolio weights vector $N \times 1$.
- $k$: Variable that scales the budget in the homogenised problem.
- $\boldsymbol{w}_p$, $\boldsymbol{w}_n$: Positive and negative weight increments.
- $\boldsymbol{v}_p$, $\boldsymbol{v}_n$: Market-impact cost coefficient vectors.
- $\beta \in (0, 1)$: Reciprocal of the market impact exponent, so the realised power law is $1/\beta$.
- $\mathrm{lb}$, $\mathrm{ub}$: Lower and upper budget bounds.
The power is raised through a three-dimensional power cone, one per asset per sign, so the model stays convex. BudgetMarketImpact states the full system.
Arguments
model::JuMP.Model: The JuMP optimisation model.val::Number: Fixed budget scalar.bgt: Budget constraint specification (BudgetRange,BudgetCosts, orBudgetMarketImpact), ornothingfor no budget.w: Portfolio weight vector.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.
Validation
- A
BudgetCostsor aBudgetMarketImpactunder a non-emptyprefix. AnArgumentErroris thrown.
Returns
nothing.
Related
PortfolioOptimisers.assert_cost_budget_prefix — Function
assert_cost_budget_prefix(
bgt::BudgetCostEstimator,
prefix::Symbol
)
Check that a budget that pays costs goes on the first block of a model.
A BudgetCosts or a BudgetMarketImpact registers the trade variables wp and wn and the expression cost_bgt_expr in the shared Model State, so a second one in the same model collides with the first. The net budget belongs to the owner of the model, whose block is the first, under the empty prefix.
Arguments
bgt: The budget that pays costs.prefix: The Model State namespace of the block.
Validation
prefixis empty. AnArgumentErroris thrown otherwise.
Returns
nothing.
Related
PortfolioOptimisers.set_long_short_budget_constraints! — Function
set_long_short_budget_constraints!(model::JuMP.Model, bgt::Option{<:Num_BgtRg}, sbgt::Option{<:Num_BgtRg}; prefix::Symbol = Symbol(""))
set_long_short_budget_constraints!(model::JuMP.Model, bgt::Option{<:BudgetCostEstimator}, ::Nothing; prefix::Symbol = Symbol(""))Set budget constraints for long and short portfolio positions in the JuMP model.
One method for each pair of a net budget bgt and a short budget sbgt, a number or a BudgetRange, with nothing in at most one slot. The rows go under prefix, the namespace of the block, and they read the parts that weight_parts! gives the block. The net budget is the budget of the owner of the block, so the block of a set passes nothing.
The method with no short budget and no net budget, or with a BudgetCostEstimator net budget, adds no row. A cost budget forbids a short budget, so it never meets one here. Any other type or arity is a MethodError.
Arguments
model::JuMP.Model: The JuMP optimisation model.bgt: The net budget, ornothing.sbgt: The short budget, ornothing.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
PortfolioOptimisers.set_cost_budget_constraints! — Function
set_cost_budget_constraints!(model, vp, vn, val_or_bgt, w, cp, cn, xbgt)Charge the trading costs against the portfolio budget.
Registers the cost_bgt_expr expression and the rows of the budget. Two overloads handle the two budget shapes. A fixed value writes the ceiling cost_bgt, under which the weights and their costs together must stay. A BudgetRange writes that ceiling at its ub as cost_bgt_ub, and a floor of the invested weights alone at its lb as cost_bgt_lb.
No row is an equality, and no floor holds the cost. The parts of the trade are not complementary, so a row that the cost must reach lets the solver buy and sell one asset together, charge the cost of both, and hold that charge as cash. A ceiling admits exactly the weights whose cost fits the budget. BudgetCosts gives the sources. With xbgt = true the floor is left out here, and set_cost_budget_mip_constraints! adds a floor that holds the cost, under a complementary split.
The charged quantity is a positional argument, not a field read from the model, because the two cost families charge different quantities. BudgetCosts charges the raw increments wp and wn; BudgetMarketImpact charges the power-cone variables wip and win, which bound the increments raised to 1/beta. Both pass the same coefficient vectors.
Arguments
model::JuMP.Model: The JuMP optimisation model.vp: Cost coefficients for positive trades; a vector or a scalar.vn: Cost coefficients for negative trades; a vector or a scalar.val_or_bgt: Fixed budget value orBudgetRange.w: Portfolio weight vector.cp: The positive-side quantity the coefficients charge.cn: The negative-side quantity the coefficients charge.xbgt: Thexbgtof aBudgetCosts, andfalsefor aBudgetMarketImpact. Whentrue, no floor is written here.
Returns
nothing.
Related
PortfolioOptimisers.set_cost_budget_mip_constraints! — Function
set_cost_budget_mip_constraints!(model::JuMP.Model, bgt::BudgetCosts, wb::WeightBounds, ss::Option{<:Number})
set_cost_budget_mip_constraints!(model::JuMP.Model, bgt::Option{<:Num_BgtRg}, wb::WeightBounds, ss::Option{<:Number})
set_cost_budget_mip_constraints!(model::JuMP.Model, bgt::BudgetMarketImpact, wb::WeightBounds, ss::Option{<:Number})Pin a BudgetCosts budget whose xbgt is true: keep one part of the trade of each asset at zero, and add the floor that holds the cost.
The budget builder set_budget_constraints! writes the ceiling of the weights and their costs. A ceiling is exact under any split of the trade, and a floor that holds the cost is exact only under a complementary split. So this builder adds one binary $z_i$ for each asset, keeps the buy under $z_i$ and the sale under $1 - z_i$, and then adds the floor. A scalar bgt gets its floor at bgt, so the ceiling and the floor pin the weights and their costs. It runs in the MIP step of set_block_constraints!, which holds the big-M ss and the weight bounds. A model that skips that step states the convex form of the budget, convex_budget.
The method on a number, on a BudgetRange, on nothing and on a BudgetMarketImpact adds no row, and so does a BudgetCosts whose xbgt is false. A BudgetMarketImpact has no exact form: the cone variables can exceed $w_p^{1/\beta}$ and $w_n^{1/\beta}$, and an upper bound on a convex power is not convex.
Mathematical definition
\[\begin{align} \boldsymbol{w}_p &\leq \boldsymbol{u}_p \odot \boldsymbol{g}\,, \\ \boldsymbol{w}_n &\leq \boldsymbol{u}_n \odot (k - \boldsymbol{g})\,, \\ \boldsymbol{1}^\intercal \boldsymbol{w} + \boldsymbol{v}_p^\intercal \boldsymbol{w}_p + \boldsymbol{v}_n^\intercal \boldsymbol{w}_n &\geq k\,\mathrm{lb}\,. \end{align}\]
Where:
- $\boldsymbol{w}$: Portfolio weights vector $N \times 1$.
- $k$: Variable that scales the budget in the homogenised problem.
- $\boldsymbol{w}_p$, $\boldsymbol{w}_n$, $\boldsymbol{v}_p$, $\boldsymbol{v}_n$, $\boldsymbol{u}_p$, $\boldsymbol{u}_n$: As in
BudgetCosts. - $\boldsymbol{g}$: The gate $k\,\boldsymbol{z}$ of the binaries $\boldsymbol{z}$. When $k$ is a number it is that product. Else it is a variable with $0 \leq g_i \leq k$, $g_i \leq s\,z_i$ and $g_i \geq k - s\,(1 - z_i)$, with $s$ the big-M of
set_mip_ss_expr!, asdeclare_mip_indicators!gates its bits. - $\mathrm{lb}$: The scalar
bgt, or thelbof aBudgetRange. Albofnothingadds no floor.
Arguments
model::JuMP.Model: The JuMP optimisation model.bgt: The net budget of the owner of the block.wb::WeightBounds: Weight bound specification containing lower and upper bounds.ss::Option{<:Number}: Big-M scaling constant (computed viaget_mip_sswhennothing).
Returns
nothing.
Related
BudgetCostsset_cost_budget_constraints!set_block_constraints!set_exact_budget_constraints!: Pins the long and short parts of the weights in the same way.
PortfolioOptimisers.convex_budget — Function
convex_budget(bgt::Option{<:Union{Num_BgtRg, BudgetMarketImpact}})
convex_budget(bgt::BudgetCosts)Return the net budget bgt in the form that a model with no MIP step states: a BudgetCosts with xbgt = false. A number, a BudgetRange, a BudgetMarketImpact and nothing have no MIP form, so they come back as they are. Any other type is a MethodError.
A BudgetCosts with xbgt = true leaves out the floor of its BudgetRange in set_cost_budget_constraints!, because set_cost_budget_mip_constraints! adds the floor that holds the cost, in the MIP step of set_block_constraints!. The centring model of UnconstrainedNearOptimalCentering runs no MIP step, so with that budget it would hold no floor at all. The convex form keeps the floor sum(w) >= k lb of the invested weights. The cost is not negative, so a portfolio on that floor also meets the floor that holds the cost. A scalar bgt keeps its ceiling in both forms.
Arguments
bgt: The net budget of the optimiser.
Returns
bgt, or a copy of aBudgetCostswithxbgt = false.
Related
PortfolioOptimisers.set_gross_budget_constraints! — Function
set_gross_budget_constraints!(model::JuMP.Model, gbgt::Option{<:Num_BgtRg}; prefix::Symbol = Symbol(""))Constrain the gross exposure (leverage) sum(lw) + sum(sw), independently of the net exposure.
A number pins it; a BudgetRange bounds it on either side, and nothing adds no row. Any other type or arity is a MethodError. Whether the constraint pins the realised gross exposure norm(w, 1) or merely bounds it depends on xbgt — see short_mip_threshold_constraints. The rows go under prefix, the namespace of the block, and they read the parts that weight_parts! gives the block.
Arguments
model::JuMP.Model: JuMP optimisation model.gbgt: Gross budget specification, ornothingfor no constraint.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
PortfolioOptimisers.budget_row! — Function
budget_row!(model::JuMP.Model, prefix::Symbol, name::Symbol, v::Nothing, sense, xs...)
budget_row!(model::JuMP.Model, prefix::Symbol, name::Symbol, v::Number, sense, x::AbstractVector)
budget_row!(model::JuMP.Model, prefix::Symbol, name::Symbol, v::Number, sense, lw::AbstractVector, sw::AbstractVector)Add one budget row on the sum of one vector or of two, sc * (sum(x) - k * v) against zero, under prefix and name.
sense is ==, >= or <=, the comparison of the row with zero, and the method states it as the MOI set EqualTo, GreaterThan or LessThan at zero. That set gives the row that the comparison gives. A bound v = nothing states no side, so the method adds no row. Every number and BudgetRange budget writes its rows through this function, so each such row of a block goes into the namespace of the block. A budget that pays costs writes its rows in the shared Model State and refuses a prefix, assert_cost_budget_prefix.
The method takes the vectors and not their sum, so the whole expression goes inside one JuMP.@constraint, which builds it in place. A sum built outside the macro allocates each partial expression. On 50 assets, the gross row built from s = sum(lw) + sum(sw) and e = sc * (s - k * v) outside the macro allocated 50168 bytes, and the same row inside the macro allocated 38568 bytes.
Arguments
model::JuMP.Model: The JuMP optimisation model.prefix: The Model State namespace of the block.name: The name of the row.v: The budget, a number, ornothingfor no row.sense: The comparison with zero.x, orlwandsw: The vector whose sum the budget bounds, or the two vectors whose sums it bounds together.
Returns
nothing.
Related
PortfolioOptimisers.budget_row_set — Function
budget_row_set(model::JuMP.Model, ::typeof(==))
budget_row_set(model::JuMP.Model, ::typeof(>=))
budget_row_set(model::JuMP.Model, ::typeof(<=))Return the MOI set at zero, in the value type of model, that a comparison of a budget row with zero states.
Returns
MOI.EqualTo,MOI.GreaterThanorMOI.LessThanat zero.
Related
PortfolioOptimisers.offset_bound — Function
offset_bound(b::Nothing, s)
offset_bound(b::Number, s::Nothing)
offset_bound(b::Number, s::Number)Return the bound b of the long part of the weights, offset by the short budget s on the same side.
The long part holds the net budget plus the short budget, sum(lw) = sum(w) + sum(sw). So a side of the long part is the side of the net budget plus the side of the short budget. A missing side of the net budget gives no row, and a missing side of the short budget adds nothing.
Returns
nothingwhenbisnothing,bwhensisnothing, andb + sotherwise.
Related
PortfolioOptimisers.assert_gross_budget_admissible — Function
assert_gross_budget_admissible(bgt, sbgt, gbgt, wb)
Assert that a gross budget is admissible alongside the net and short budgets.
bgt and sbgt constrain the net and gross exposures only together. When both are numbers, the long budget is sum(lw) == bgt + sbgt and the short budget is sum(sw) == sbgt, so the gross budget sum(lw) + sum(sw) is bgt + 2 * sbgt, the row that gbgt writes. The realised gross exposure norm(w, 1) equals it when xbgt is true, and it can be smaller when xbgt is false. gbgt exists for the combination they cannot reach — gross pinned with net free — so it is rejected when they already determine the gross exposure, and when the weight bounds forbid short positions (whereupon gross and net coincide and bgt already owns the constraint). A gross budget whose upper end lies below the magnitude of the net budget is rejected too, see assert_gross_budget_reaches_net.
Only the statically-decidable contradictions are caught. Ranges may still conflict at solve time, surfacing as infeasibility, and a WeightBoundsEstimator is not resolved until then. TimeDependent schedules are reached through assert_time_dependent_substitution.
A ProgrammeAllocationSet and the held optimiser of a FollowTheLeader rule pass bgt = 1, the budget of one that the online head owns.
Related
PortfolioOptimisers.assert_gross_budget_reaches_net — Function
assert_gross_budget_reaches_net(bgt, gbgt)
Assert that the gross budget gbgt can reach the magnitude of the net budget bgt.
The gross row reads the long and short parts of the weights, and each part bounds its side of the weight, lw_i >= max(w_i, 0) and sw_i >= max(-w_i, 0). This holds under both decomposition contracts. So the gross exposure is at least the magnitude of the net exposure, and a gross budget whose upper end lies below the least magnitude that the net budget admits leaves no feasible weights. The bound holds at every k, because both rows scale with it.
Mathematical definition
\[\begin{align} \sum_i lw_i + \sum_i sw_i &\geq \sum_i \lvert w_i \rvert \geq \Bigl\lvert \sum_i w_i \Bigr\rvert\,. \end{align}\]
Where:
- $lw_i$, $sw_i$: The long and short parts of weight $i$.
- $\boldsymbol{w}$: Portfolio weights vector $N \times 1$.
Validation
- The upper end of
gbgtis non-negative. AnArgumentErroris thrown otherwise. - The upper end of
gbgtis at leastnet_budget_floorofbgt. AnArgumentErroris thrown otherwise.
A gbgt with no upper end, a bgt whose interval holds zero, nothing, a BudgetCostEstimator and a TimeDependent schedule state no static floor or ceiling, so they pass.
Related
PortfolioOptimisers.net_budget_floor — Function
net_budget_floor(bgt::Number)
net_budget_floor(bgt::BudgetRange)
net_budget_floor(bgt::Option{<:UnresolvedValue})Returns the least magnitude abs(sum(w)) that the net budget bgt admits, or nothing when it states no positive floor.
A number admits its own magnitude. A BudgetRange admits the distance from zero to its interval: its lower bound when that is positive, the negative of its upper bound when that is negative, and no floor when the interval holds zero. nothing, a BudgetCostEstimator and a TimeDependent schedule are the other values that reach it, and they state no floor. Any other type is a MethodError.
Related
PortfolioOptimisers.gross_budget_ceiling — Function
gross_budget_ceiling(gbgt::Number)
gross_budget_ceiling(gbgt::BudgetRange)
gross_budget_ceiling(gbgt::Option{<:UnresolvedValue})Returns the upper end of the gross budget gbgt, or nothing when it states none.
A number is its own upper end, and a BudgetRange has its ub. nothing, a BudgetCostEstimator and a TimeDependent schedule are the other values that reach it, and they state none. Any other type is a MethodError.
Related
PortfolioOptimisers.set_exact_budget_constraints! — Function
set_exact_budget_constraints!(
model::Model,
sp::AbstractMIPSpace,
ind::AbstractMIPIndicators,
wx::AbstractVector{<:Union{Number, AbstractJuMPScalar}},
ss
)
set_exact_budget_constraints!(
model::Model,
sp::AbstractMIPSpace,
ind::AbstractMIPIndicators,
wx::AbstractVector{<:Union{Number, AbstractJuMPScalar}},
ss,
::WeightsFromParts
)
Pin the long/short decomposition, so the budgets built on lw/sw hold exactly.
lw and sw carry the long and short parts of the weights, and bgt, sbgt and gbgt are all stated in terms of them. Whether those budgets pin the realised exposure or merely bound it depends on how the head related the parts to the weights, so this dispatches on the head's AbstractDecompositionContract. Both methods take the sign from ind, whichever bundle carries one — a dedicated sign bit, or the long/short bits of a builder that already needed them for thresholds or cardinality.
Mathematical definition
Both contracts emit the sign pair, which forces sw = 0 on the long side and lw = 0 on the short side:
\[\begin{align} lw_i - M\, g^l_i &\leq 0\,, & sw_i - M\, g^s_i &\leq 0\,. \end{align}\]
Under PartsBoundWeights that leaves the held side free to overstate itself (lw_i may exceed w_i), so two more constraints close the slack:
\[\begin{align} lw_i - w_i - M(1 - b^l_i) &\leq 0\,, & sw_i + w_i - M(1 - b^s_i) &\leq 0\,. \end{align}\]
Where:
- $g^l_i$, $g^s_i$: Long and short gates (
long_gate,short_gate), which relax to continuous variables when the budget is free. - $b^l_i$, $b^s_i$: Long and short binaries (
long_bin,short_bin). The slack-closing pair keys on these rather than the gates, because it must key on a bit that is exactly 0 or 1 even when the gates relax. - $w_i$: Weight expression for position $i$ in the space of
sp. - $M$: Big-M constant.
Together they give lw_i == max(w_i, 0) and sw_i == max(-w_i, 0): b^l_i = 1 turns the first into lw_i <= w_i, which against the head's lw_i >= w_i is an equality; both bits zero gives lw_i == sw_i == 0, hence w_i == 0.
Under WeightsFromParts the pair alone is enough and the slack-closing constraints are not emitted: w = lw - sw is an identity, so sw_i = 0 already leaves lw_i == w_i.
A HeldIndicators bundle takes the WeightsFromParts method alone. The held builder pins the decomposition only for that head, because run_mip_builder! gives an explicit xbgt on a model with a short side to the sign or the long-short builder. A held bundle under any other contract is a MethodError. So the PartsBoundWeights method takes the two bundles that carry binaries: LongShortIndicators and SignIndicators.
The contract dc defaults to decomposition_contract of model, so a call with five arguments reads the contract off the model.
Arguments
model::JuMP.Model: The JuMP optimisation model.sp::AbstractMIPSpace: Weight space the constraints act on.ind::AbstractMIPIndicators: Indicator bundle supplying the sign.wx::VecNum: Weight expression in the space ofsp.ss: Big-M expression, as registered byset_mip_ss_expr!.dc::AbstractDecompositionContract: The head's contract. There is deliberately no method fornothing— a model with no head contract has no short side, so there is no decomposition to pin and a caller that got here is confused.
Returns
nothing.
Related