MIP indicators: private API

PortfolioOptimisers.AbstractMIPIndicators — Type
abstract type AbstractMIPIndicators

Abstract supertype for a declared set of MIP binary indicators.

A MIP space (AbstractMIPSpace) says which weights the indicators gate; an indicator bundle says which bits exist and what they mean. The two are independent axes: the declaration step picks the bundle from the features the model needs, and every emitter is written once against the bundle's accessors rather than reading binaries back out of the model by key.

The bits divide into two kinds, and conflating them is a bug — a held bit says an asset is in the portfolio (what cardinality counts), a sign bit says which side it is on. Bundles differ in which of the two they carry:

bundlebinariesstates
HeldIndicatorsibheld / not
LongShortIndicatorsilb,isblong / short / inactive
SignIndicatorsxblong / short

Related

source
PortfolioOptimisers.AssetMIPSpace — Type
struct AssetMIPSpace <: AbstractMIPSpace

Asset-space MIP constraints: indicators gate the portfolio weights w directly.

The space carries two Model State namespaces. The rows of one call, such as the gates of its bounds, its thresholds and its cardinality, take prefix. The bits of the weights take owner, the namespace that owns the weights under prefix (weights_prefix), because one bit for each asset is a fact of the weights and not of one call. mip_bit_space gives the space of the bits. With the empty prefix of a head, both are empty, and the model keys are the bare names (:ib, :i_mip, :w_mip_lt, ...).

Fields

  • prefix::Symbol: Model State namespace of the rows of the call.
  • owner::Symbol: Model State namespace of the bits of the weights.

Related

source
PortfolioOptimisers.SubsetMIPSpace — Type
struct SubsetMIPSpace{__T_smtx, __T_i} <: AbstractMIPSpace

Sub-group MIP constraints: indicators gate the sub-group weights smtx * w and weight bounds map through the selection matrix. Model keys are namespaced as Symbol(pfx, name, :_, i, :_) under prefix, so multiple sub-groups (and the cardinality/group-cardinality variants) do not collide, and neither do two calls under two prefixes. A sub-group bit is a fact of one call, so the bits take prefix too.

Fields

  • smtx::Option{<:MatNum}: Selection matrix mapping assets to sub-groups.
  • pfx::Symbol: Key prefix; :s for cardinality sub-groups, :sg for group-cardinality sub-groups.
  • i::Integer: Index of the selection matrix, used in key naming.
  • prefix::Symbol: Model State namespace of the call. The weights are read under it.

Related

source
PortfolioOptimisers.HeldIndicators — Type
struct HeldIndicators{__T_ib, __T_i_mip} <: AbstractMIPIndicators

Long-only indicators: one held bit per asset, and no sign.

Fields

  • ib: Binary held bit.
  • i_mip: Held gate — ib itself, or its continuous relaxation ibf when the budget is free.

Related

source
PortfolioOptimisers.LongShortIndicators — Type
struct LongShortIndicators{__T_ilb, __T_isb, __T_il, __T_is, __T_i_mip} <: AbstractMIPIndicators

Long-short indicators: a long bit and a short bit per asset, mutually exclusive, so an asset is long, short, or inactive. Carries both a sign (which of ilb/isb) and a held indicator (i_mip = ilb + isb), which is why this bundle can serve cardinality and exact budgets at once.

Fields

  • ilb, isb: Binary long and short bits.
  • il, is: Long and short gates — the bits themselves, or their continuous relaxations ilf/isf when the budget is free.
  • i_mip: Held gate, ilb + isb.

Related

source
PortfolioOptimisers.SignIndicators — Type
struct SignIndicators{__T_xb} <: AbstractMIPIndicators

Sign-only indicators: one sign bit per asset and no held indicator, for when nothing in the model needs to know whether an asset is held.

The sign split is total — w_i = 0 satisfies both w_i >= 0 and w_i <= 0 and is picked up by either branch — so one bit per asset suffices and the inactive state of LongShortIndicators is pure redundancy. This is what lets a model that only pins the decomposition use N binaries rather than 2N.

Fields

  • xb: Binary sign bit; 1 selects w_i >= 0, 0 selects w_i <= 0.

Related

source
PortfolioOptimisers.get_mip_ss — Function
get_mip_ss(ss::Number, args...) -> Number

Return the big-M style scaling constant used by MIP constraints.

When ss is a number it is returned directly. When nothing, the value is derived from the largest finite bound magnitude in wb multiplied by 1000, defaulting to 1000.0 when all bounds are infinite. The optimiser expands an absent bound to a vector before the MIP builders run, so both sides of wb are vectors.

Arguments

  • ss::Number: Scaling constant. Returned as-is.

Returns

  • ss::Number: The scaling constant.

Related

source
PortfolioOptimisers.set_mip_ss_expr! — Function
set_mip_ss_expr!(
    model::Model,
    ss::Union{Nothing, Number},
    wb::WeightBounds
) -> Any

Register the big-M scaling constant as the model expression :ss and return it.

Asset-space and sub-group MIP builders share the single :ss key; the first caller registers it via get_mip_ss, subsequent callers reuse the registered expression.

Arguments

  • model::JuMP.Model: The JuMP optimisation model.
  • ss::Option{<:Number}: Big-M scaling constant (computed via get_mip_ss when nothing).
  • wb::WeightBounds: Weight bound specification containing lower and upper bounds.

Returns

  • ss: The registered scaling-constant expression.

Related

source
PortfolioOptimisers.mip_key — Function
mip_key(sp::AssetMIPSpace, name::Symbol) -> Symbol

Map a logical MIP builder name to the model key for the given space.

Asset space returns the name under the prefix of the space; sub-group space returns Symbol(pfx, name, :_, i, :_) under its prefix; factor space (FactorMIPSpace) returns Symbol(:frc_, name). state_key joins the prefix, so the empty prefix gives the names of a head.

Related

source
PortfolioOptimisers.mip_bit_space — Function
mip_bit_space(sp::AbstractMIPSpace)
mip_bit_space(sp::AssetMIPSpace)

Return the space whose keys name the bits of sp and the rows that define them.

The bits of the asset space belong to the weights, so the method for AssetMIPSpace returns the space of sp.owner. Two calls on one weight vector under two prefixes then read one bit for each asset. The bits of every other space belong to the call, so the general method returns sp.

Related

source
PortfolioOptimisers.mip_wx! — Function
mip_wx!(model::Model, sp::AssetMIPSpace) -> Any

Return the weight expression the MIP indicators gate.

Asset space returns the portfolio weights w under its prefix; sub-group space registers and returns the sub-group weight expression smtx * w under the space's :mtx_expr key; factor space returns the factor weights w1.

Related

source
PortfolioOptimisers.mip_bounds — Function
mip_bounds(
    _::AssetMIPSpace,
    b::AbstractVector{<:Union{Number, AbstractJuMPScalar}}
) -> AbstractVector{<:Union{Number, AbstractJuMPScalar}}

Map a weight bound vector into the MIP space.

Asset space returns the bounds unchanged; sub-group space maps them through the selection matrix, smtx * b; factor space returns them unchanged, because factor_weight_bounds states them on the factor axis already.

Related

source
PortfolioOptimisers.use_direct_mip_indicators — Function
use_direct_mip_indicators(
    model::Model,
    _::AssetMIPSpace,
    k
) -> Bool

Whether the binary indicators can gate the weights directly, without the continuous big-M relaxation of indicator * k.

True when the budget k is a constant, in every space. The asset space additionally accepts a unit budget (is_unit_budget): the head has normalised the scale, so the indicators may gate the weights directly even though k is still a free variable.

Related

source
PortfolioOptimisers.held — Function
held(ind::HeldIndicators) -> Any

Return the held indicator — the per-asset quantity that is 1 when the asset is in the portfolio. This is what cardinality counts and what integer phylogeny gates on.

Only HeldIndicators has a method. The threshold and fixed-fee constraints of LongShortIndicators read its long and short bits, and cardinality reads held_bin. SignIndicators carries no held bit, and the declaration step only chooses it when nothing in the model consumes one. A caller that would need a held indicator of another bundle therefore fails at the call of held with a MethodError, rather than reading a sign bit and silently miscounting.

Related

source
PortfolioOptimisers.held_bin — Function
held_bin(ind::HeldIndicators) -> Any

Return the held binary — the 0/1 per-asset quantity that cardinality sums, group cardinality gates, and integer phylogeny multiplies.

Unlike held, which returns the held gate (i_mip, the continuous relaxation ibf when the budget is free), this is always the raw binary: ib for the long-only bundle, ilb + isb for the long-short one. Counting must key on a bit that is exactly 0 or 1 even when the budget is free and the gate relaxes — the same reason long_bin exists alongside long_gate.

SignIndicators deliberately has no method, for the same reason held does not: it carries no held bit, so a caller that would count one fails at the call of held_bin with a MethodError rather than miscounting a sign bit.

Related

source
PortfolioOptimisers.set_mip_indicators! — Function
set_mip_indicators!(model::JuMP.Model, prefix::Symbol, ind::AbstractMIPIndicators)

Register the asset-space MIP indicator bundle as the Model-State entry :mip_indicators under prefix.

This is what lets a late emitter — integer phylogeny, applied after the fact in assemble_jump_model! — reach the held indicator through mip_indicators and the typed accessors (held_bin) rather than having it hand-threaded back as a return value. With the bundle in Model State, the per-builder raw keys (:ib, :ilb/:isb, ...) stay private to the bundle: nothing outside a builder reaches an indicator by key.

Only the asset space registers a bundle. Sub-group builders consume theirs immediately, in the same call, and never pass them to a late emitter. mip_indicators! registers the bundle of the weights under their owner, and a bundle that one call declares for itself under the prefix of that call.

Validation

  • The entry is free under prefix. Otherwise state_set! raises an ArgumentError.

Related

source
PortfolioOptimisers.mip_indicators — Function
mip_indicators(model::JuMP.Model, prefix::Symbol = Symbol(""))

Return the asset-space MIP indicator bundle of a call under prefix, or nothing when no MIP builder ran.

The bundle of the call is the one registered under prefix, when that call declared its own. Otherwise it is the bundle of the weights, registered under their owner, weights_prefix. nothing means the model has no MIP features, so there is no held indicator for a late emitter to gate on.

Related

source
PortfolioOptimisers.serves_mip_kind — Function
serves_mip_kind(ind::AbstractMIPIndicators, kind::Type{<:AbstractMIPIndicators})

Return true when the bundle ind can serve a call whose features ask for a bundle of type kind.

A bundle serves a call of its own kind. A LongShortIndicators bundle serves every call: its held indicator is ilb + isb, its long and short bits give the sign, and its gates carry each threshold. A HeldIndicators bundle has no sign, and a SignIndicators bundle has no held bit, so neither serves a call of another kind.

Related

source
PortfolioOptimisers.declare_mip_indicators! — Function
declare_mip_indicators!(
    model::Model,
    sp::AbstractMIPSpace,
    _::Type{HeldIndicators},
    wb::WeightBounds,
    wx::AbstractVector{<:Union{Number, AbstractJuMPScalar}},
    ss::Union{Nothing, Number}
) -> HeldIndicators

Declare the long-only held indicators and the constraints that give them meaning.

Creates one binary per asset and, when the budget k is a free variable, the continuous relaxation ibf = ib * k with its big-M linking constraints. The caller then applies mip_wb, which is what forces w = 0 for an unheld asset and so makes the bit mean held. Each call that reads the bundle applies its own mip_wb, with its own bounds, so the declaration writes none.

Emits no feature constraints — thresholds, fees, cardinality, phylogeny, and budgets are the business of their own emitters, which take the returned bundle.

Arguments

  • model::JuMP.Model: The JuMP optimisation model.
  • sp::AbstractMIPSpace: Weight space the indicators act on.
  • wb::WeightBounds: Weight bound specification containing lower and upper bounds.
  • wx::VecNum: Weight expression from mip_wx!.
  • ss::Option{<:Number}: Big-M scaling constant (computed via get_mip_ss when nothing).

Returns

  • ind::HeldIndicators: The declared indicator bundle.

Related

source
declare_mip_indicators!(
    model::Model,
    sp::AbstractMIPSpace,
    _::Type{LongShortIndicators},
    wb::WeightBounds,
    wx::AbstractVector{<:Union{Number, AbstractJuMPScalar}},
    ss::Union{Nothing, Number}
) -> LongShortIndicators

Declare the long-short indicators and the constraints that give them meaning.

Creates a long and a short binary per asset, forces them mutually exclusive (ilb + isb <= 1, so an asset is long, short, or inactive), and builds the continuous relaxations ilf/isf with their big-M linking constraints when the budget is free. Each call that reads the bundle applies its own mip_wb.

Emits no feature constraints; see the HeldIndicators method.

Arguments

  • model::JuMP.Model: The JuMP optimisation model.
  • sp::AbstractMIPSpace: Weight space the indicators act on.
  • wb::WeightBounds: Weight bound specification containing lower and upper bounds.
  • wx::VecNum: Weight expression from mip_wx!.
  • ss::Option{<:Number}: Big-M scaling constant (computed via get_mip_ss when nothing).

Returns

  • ind::LongShortIndicators: The declared indicator bundle.

Related

source
declare_mip_indicators!(
    model::Model,
    sp::AbstractMIPSpace,
    _::Type{SignIndicators},
    wb::WeightBounds,
    wx::AbstractVector{<:Union{Number, AbstractJuMPScalar}},
    ss::Union{Nothing, Number}
) -> SignIndicators

Declare a single sign binary per asset.

Unlike the held and long-short declarations there is no mip_wb here and no held indicator: a sign bit needs no weight-bound gating to mean what it means, and this bundle is only chosen when nothing in the model consumes a held indicator.

Arguments

  • model::JuMP.Model: The JuMP optimisation model.
  • sp::AbstractMIPSpace: Weight space the indicators act on.
  • wb::WeightBounds: Weight bound specification containing lower and upper bounds.
  • wx::VecNum: Weight expression from mip_wx!.
  • ss::Option{<:Number}: Big-M scaling constant (computed via get_mip_ss when nothing).

Returns

  • ind::SignIndicators: The declared indicator bundle.

Related

source
PortfolioOptimisers.mip_indicators! — Function
mip_indicators!(model::JuMP.Model, sp::AbstractMIPSpace, kind::Type{<:AbstractMIPIndicators}, wb::WeightBounds, wx::VecNum, ss::Option{<:Number})
mip_indicators!(model::JuMP.Model, sp::AssetMIPSpace, kind::Type{<:AbstractMIPIndicators}, wb::WeightBounds, wx::VecNum, ss::Option{<:Number})

Return the indicator bundle that a MIP builder of the kind kind gates on, and declare it when the model has none to give.

The bits of a sub-group belong to the call, so the general method declares a new bundle each time. The bits of the asset space belong to the weights. So the method for AssetMIPSpace returns the bundle of the weights when serves_mip_kind states that it can serve kind. Two calls under two prefixes then add their rows on one bit for each asset, and their rows intersect exactly.

Algorithm

The method for AssetMIPSpace:

  1. Read the bundle of the weights, registered under sp.owner, with mip_indicators.
  2. When it serves kind, return it.
  3. When the weights hold no bundle, declare one of the kind kind in the space of the bits, mip_bit_space, and register it under sp.owner.
  4. Otherwise the bundle of the weights is of a kind that cannot serve the call. Declare a bundle of the kind kind under sp.prefix, and register it there. The rows of each call still hold on the weights, because each bit states a fact of the weights. The model then carries more binaries than one bundle needs.

Related

source
PortfolioOptimisers.long_gate — Function
long_gate(ind::HeldIndicators) -> Any

Return the gates and binaries the exact-decomposition constraints key on.

long_gate/short_gate bound lw/sw and may be continuous relaxations; long_bin/short_bin are always the binaries themselves, because the slack-closing constraints must key on a bit that is exactly 0 or 1 even when the budget is free and the gates relax.

For HeldIndicators the held bit doubles as the sign. This bundle is asked for a decomposition only under a WeightsFromParts head, whose sign pair reads the gates alone, so the bundle has gates and no binaries.

Related

source
PortfolioOptimisers.long_bin — Function
long_bin(ind::LongShortIndicators) -> Any

Return the long binary the slack-closing exact-decomposition constraints key on — always the bit itself, never a continuous relaxation (see long_gate for why the binaries and gates differ).

Only the long-short and the sign bundles have a method. The slack-closing rows belong to a PartsBoundWeights head, and the held builder pins the decomposition only for a WeightsFromParts head, see set_exact_budget_constraints!.

Related

source
PortfolioOptimisers.mip_wb — Function
mip_wb(
    model::Model,
    sp::AbstractMIPSpace,
    wb::WeightBounds,
    wx::AbstractVector{<:Union{Number, AbstractJuMPScalar}},
    ind::AbstractMIPIndicators
)

Add MIP-compatible weight bound constraints using binary selection variables.

The method reads the upper gate il and the lower gate is of the bundle ind with ub_gate and lb_gate. It adds wx ≥ is ⊙ lb and wx ≤ il ⊙ ub constraints when the respective finite bounds are present, where wx and the bounds live in the space selected by sp (mip_wx!, mip_bounds).

Mathematical definition

\[\begin{align} \boldsymbol{i}_s \odot \boldsymbol{\ell} \leq \boldsymbol{w} \leq \boldsymbol{i}_l \odot \boldsymbol{u}\,. \end{align}\]

Where:

  • $\boldsymbol{w}$: Portfolio weights vector $N \times 1$.
  • $\boldsymbol{i}_l$, $\boldsymbol{i}_s$: Long and short binary indicator vectors.
  • $\boldsymbol{\ell}$, $\boldsymbol{u}$: Lower and upper bound vectors from wb, mapped into the space of sp.

Arguments

  • model::JuMP.Model: The JuMP optimisation model.
  • sp::AbstractMIPSpace: Weight space the constraints act on.
  • wb::WeightBounds: Weight bound specification containing lower and upper bounds.
  • wx::VecNum: Weight expression from mip_wx!.
  • ind::AbstractMIPIndicators: Indicator bundle that holds the gates.

Returns

  • nothing.

Related

source
PortfolioOptimisers.short_mip_threshold_constraints — Function
short_mip_threshold_constraints(
    model::Model,
    sp::AbstractMIPSpace,
    wb::WeightBounds,
    lt::Union{Nothing, Threshold},
    st::Union{Nothing, Threshold},
    ffl::Union{Nothing, Number, AbstractVector{<:Union{Number, AbstractJuMPScalar}}},
    ffs::Union{Nothing, Number, AbstractVector{<:Union{Number, AbstractJuMPScalar}}},
    ss::Union{Nothing, Number},
    lt_flag::Bool,
    st_flag::Bool,
    ffl_flag::Bool,
    ffs_flag::Bool
) -> LongShortIndicators
short_mip_threshold_constraints(
    model::Model,
    sp::AbstractMIPSpace,
    wb::WeightBounds,
    lt::Union{Nothing, Threshold},
    st::Union{Nothing, Threshold},
    ffl::Union{Nothing, Number, AbstractVector{<:Union{Number, AbstractJuMPScalar}}},
    ffs::Union{Nothing, Number, AbstractVector{<:Union{Number, AbstractJuMPScalar}}},
    ss::Union{Nothing, Number},
    lt_flag::Bool,
    st_flag::Bool,
    ffl_flag::Bool,
    ffs_flag::Bool,
    xbgt_flag::Bool
) -> LongShortIndicators

Add MIP binary selection variables and threshold constraints for long-short portfolios.

Creates long/short binary indicator variables (or their continuous relaxations when k is a JuMP variable), enforces that each position is either long or short but not both, and applies long/short minimum-holding threshold, fixed-fee, and rebalancing constraints based on the flags provided. The weight expression, bound mapping, and model key naming are selected by sp, so the same builder serves asset-space and sub-group constraints.

Mathematical definition

Mutual-exclusivity and big-M linearisation:

\[\begin{align} ilb_i + isb_i \leq 1, \quad ilf_i &= ilb_i \cdot k, \quad isf_i = isb_i \cdot k\,. \end{align}\]

Where:

  • $ilb_i$, $isb_i$: Long and short binary indicator variables for position $i$.
  • $ilf_i$, $isf_i$: Continuous relaxations of $ilb_i \cdot k$ and $isb_i \cdot k$.
  • $k$: Variable that scales the budget in the homogenised problem.

Minimum-holding thresholds:

\[\begin{align} w_i &\geq ilf_i\, \ell_i - M(1 - ilb_i)\,, \\ w_i &\leq -isf_i\, u_i + M(1 - isb_i)\,. \end{align}\]

Where:

  • $w_i$: Weight expression for position $i$ in the space of sp.
  • $ilf_i$, $isf_i$: Long and short continuous indicator expressions.
  • $ilb_i$, $isb_i$: Long and short binary indicator variables for position $i$.
  • $\ell_i$, $u_i$: Long and short minimum-holding thresholds for position $i$.
  • $M$: Big-M constant.

Arguments

  • model::JuMP.Model: The JuMP optimisation model.
  • sp::AbstractMIPSpace: Weight space the constraints act on.
  • wb::WeightBounds: Weight bound specification containing lower and upper bounds.
  • lt::Option{<:Threshold}: Long-side minimum-holding threshold.
  • st::Option{<:Threshold}: Short-side minimum-holding threshold.
  • ffl::Option{<:Num_VecNum}: Long-side fixed fee rate(s).
  • ffs::Option{<:Num_VecNum}: Short-side fixed fee rate(s).
  • ss::Option{<:Number}: Big-M scaling constant (computed via get_mip_ss when nothing).
  • lt_flag::Bool: Whether to apply the long-side threshold.
  • st_flag::Bool: Whether to apply the short-side threshold.
  • ffl_flag::Bool: Whether to add long fixed fee expressions. Emitted by set_fixed_fees! against ilb.
  • ffs_flag::Bool: Whether to add short fixed fee expressions. Emitted by set_fixed_fees! against isb.
  • xbgt_flag::Bool: Whether to pin the long/short decomposition, so the budgets built on lw/sw hold exactly (see set_exact_budget_constraints!). Served by set_exact_budget_constraints!, which reuses this builder's ilb/isb rather than introducing a sign indicator of its own — they already mean long and short here, and i_mip = ilb + isb remains the held indicator that cardinality counts.

Returns

  • ind::LongShortIndicators: The declared indicator bundle.

Related

source
PortfolioOptimisers.mip_constraints — Function
mip_constraints(
    model::Model,
    sp::AbstractMIPSpace,
    wb::WeightBounds,
    ffl::Union{Nothing, Number, AbstractVector{<:Union{Number, AbstractJuMPScalar}}},
    lt::Union{Nothing, Threshold},
    ss::Union{Nothing, Number},
    lt_flag::Bool,
    ffl_flag::Bool,
    xbgt_flag::Bool
) -> Union{HeldIndicators, LongShortIndicators}

Add a long-only MIP binary indicator variable and associated constraints to the JuMP optimisation model.

Creates a binary variable per position indicating whether it is held. When k is a JuMP variable, introduces a continuous relaxation with big-M linking constraints. Optionally applies minimum-holding threshold, fixed-fee, and rebalancing constraints. The weight expression, bound mapping, and model key naming are selected by sp, so the same builder serves asset-space and sub-group constraints.

Mathematical definition

Big-M linearisation of $ibf_i = ib_i \cdot k$:

\[\begin{align} ibf_i &\leq k, \quad ibf_i \leq M\, ib_i, \quad ibf_i + M(1 - ib_i) \geq k\,. \end{align}\]

Where:

  • $ib_i$: Binary inclusion indicator for position $i$.
  • $ibf_i$: Continuous relaxation of $ib_i \cdot k$.
  • $k$: Variable that scales the budget in the homogenised problem.
  • $M$: Big-M constant.

Minimum-holding threshold and cardinality:

\[\begin{align} w_i &\geq ibf_i\, \ell_i\,, \\ \sum_i ib_i &\leq \mathrm{card}\,. \end{align}\]

Where:

  • $w_i$: Weight expression for position $i$ in the space of sp.
  • $ibf_i$: Continuous relaxation of $ib_i \cdot k$.
  • $\ell_i$: Minimum-holding threshold for position $i$.
  • $\mathrm{card}$: Maximum number of non-zero positions (cardinality bound).

Arguments

  • model::JuMP.Model: The JuMP optimisation model.
  • sp::AbstractMIPSpace: Weight space the constraints act on.
  • wb::WeightBounds: Weight bound specification containing lower and upper bounds.
  • ffl::Option{<:Num_VecNum}: Long-side fixed fee rate(s).
  • lt::Option{<:Threshold}: Long-side minimum-holding threshold.
  • ss::Option{<:Number}: Big-M scaling constant (computed via get_mip_ss when nothing).
  • lt_flag::Bool: Whether to apply the long-side threshold.
  • ffl_flag::Bool: Whether to add fixed fee expressions. Emitted by set_fixed_fees! against ib.
  • xbgt_flag::Bool: Whether to pin the long/short decomposition, so the budgets built on lw/sw hold exactly (see set_exact_budget_constraints!). run_mip_builder! sets it here only for a WeightsFromParts head, whose sign pair this builder's ib serves.

Returns

  • ind::HeldIndicators: The declared indicator bundle.

Related

source
PortfolioOptimisers.sign_mip_constraints — Function
sign_mip_constraints(
    model::Model,
    sp::AbstractMIPSpace,
    wb::WeightBounds,
    ss::Union{Nothing, Number}
) -> Union{LongShortIndicators, SignIndicators}

Pin the long/short decomposition using a single binary sign indicator per asset.

This is the lean alternative to running a whole long-short builder just to get a sign, for when nothing else in the model needs binaries. It produces N of them rather than 2N.

The long-short builder splits each asset three ways — long, short, or inactive — because a threshold has to tell w_i = 0 apart from w_i >= lt_i, and cardinality has to count the assets that are held. Pinning the decomposition needs neither: the sign split is total, since w_i = 0 satisfies both w_i >= 0 and w_i <= 0 and is picked up by either branch. One bit per asset therefore suffices, and the inactive state is pure redundancy.

It declares the sign bit and hands it to set_exact_budget_constraints!, which emits the constraints; see there for the mathematical definition.

Arguments

  • model::JuMP.Model: The JuMP optimisation model.
  • sp::AbstractMIPSpace: Weight space the constraints act on.
  • wb::WeightBounds: Weight bound specification containing lower and upper bounds.
  • ss::Option{<:Number}: Big-M scaling constant (computed via get_mip_ss when nothing).

Returns

  • ind::SignIndicators: The declared indicator bundle. It carries no held indicator — held_bin has no method for it — because this builder runs only when nothing would consume one.

Related

source
PortfolioOptimisers.pin_decomposition! — Function
pin_decomposition!(model::JuMP.Model, sp::AbstractMIPSpace, ind::AbstractMIPIndicators, wx::VecNum, ss)

Pin the long/short decomposition of the weights with set_exact_budget_constraints!, once for each model.

The rows bind the shared parts lw and sw, which are facts of the weights and not of one call. So the rows take the keys of the space of the bits, mip_bit_space, and a second call that asks for the pin adds no row. The bundle ind of the first call that asks gives the gates.

Arguments

  • model::JuMP.Model: The JuMP optimisation model.
  • sp::AbstractMIPSpace: Weight space of the call.
  • ind::AbstractMIPIndicators: Indicator bundle of the call.
  • wx::VecNum: Weight expression from mip_wx!.
  • ss: Big-M expression, as registered by set_mip_ss_expr!.

Returns

  • nothing.

Related

source
PortfolioOptimisers.run_mip_builder! — Function
run_mip_builder!(
    model::Model,
    sp::AbstractMIPSpace,
    wb::WeightBounds,
    lt::Union{Nothing, Threshold},
    st::Union{Nothing, Threshold},
    ss::Union{Nothing, Number},
    lt_flag::Bool,
    st_flag::Bool;
    ffl,
    ffs,
    ffl_flag,
    ffs_flag,
    xbgt_flag,
    pin_flag,
    sign_only
) -> Union{HeldIndicators, LongShortIndicators, SignIndicators}

Run the MIP indicator builder the requested features call for and return its indicator bundle.

Selects among the three builders on flags shared by the asset space and every sub-group:

  • sign_mip_constraints when sign_only — an explicit xbgt with nothing else to consume a held indicator, so a single sign bit per asset suffices (returns a SignIndicators, which has no held indicator).
  • short_mip_threshold_constraints when a short side exists (shared_get(model, :sw)) and something needs it — a short threshold, a fixed fee, or a pinned decomposition.
  • mip_constraints otherwise — the long-only held builder.

The asset caller (set_mip_constraints!) and the sub-group callers (set_all_smip_constraints!, set_scardmip_constraints!, set_sgcardmip_constraints!) all route through here, so builder selection lives in one place. The sub-groups leave every keyword at its default — no fees, no pinning, no sign-only branch — differing from the asset space only through sp.

Arguments

  • model::JuMP.Model: The JuMP optimisation model.
  • sp::AbstractMIPSpace: Weight space the indicators act on.
  • wb::WeightBounds: Weight bound specification containing lower and upper bounds.
  • lt::Option{<:Threshold}: Long-side minimum-holding threshold.
  • st::Option{<:Threshold}: Short-side minimum-holding threshold.
  • ss::Option{<:Number}: Big-M scaling constant (computed via get_mip_ss when nothing).
  • lt_flag::Bool: Whether to apply the long-side threshold.
  • st_flag::Bool: Whether to apply the short-side threshold.
  • ffl::Option{<:Num_VecNum} = nothing: Long-side fixed fee rate(s).
  • ffs::Option{<:Num_VecNum} = nothing: Short-side fixed fee rate(s).
  • ffl_flag::Bool = false: Whether to emit long fixed fees.
  • ffs_flag::Bool = false: Whether to emit short fixed fees.
  • xbgt_flag::Bool = false: Whether an explicit xbgt asked to pin the decomposition (asset space only).
  • pin_flag::Bool = false: Whether the running builder should pin the long/short decomposition.
  • sign_only::Bool = false: Whether to use the lean sign-bit builder (asset space only).

Returns

  • ind::AbstractMIPIndicators: The indicator bundle of the builder that ran. Consumers read the held indicator through held_bin (or the gate accessors), never by key.

Related

source
PortfolioOptimisers.set_mip_constraints! — Function
set_mip_constraints!(
    model::Model,
    wb::WeightBounds,
    card::Union{Nothing, Integer},
    gcard::Union{Nothing, LinearConstraint},
    pl::Union{Nothing, AbstractPhylogenyConstraintResult, AbstractVector{<:AbstractPhylogenyConstraintResult}},
    lt::Union{Nothing, Threshold},
    st::Union{Nothing, Threshold},
    fees::Union{Nothing, Fees},
    ss::Union{Nothing, Number};
    ...
)
set_mip_constraints!(
    model::Model,
    wb::WeightBounds,
    card::Union{Nothing, Integer},
    gcard::Union{Nothing, LinearConstraint},
    pl::Union{Nothing, AbstractPhylogenyConstraintResult, AbstractVector{<:AbstractPhylogenyConstraintResult}},
    lt::Union{Nothing, Threshold},
    st::Union{Nothing, Threshold},
    fees::Union{Nothing, Fees},
    ss::Union{Nothing, Number},
    xbgt::Bool;
    prefix
)

Add the asset-space MIP constraints to the JuMP optimisation model and return the held indicator.

Chooses the indicator builder the requested features need (mip_constraints, short_mip_threshold_constraints, or sign_mip_constraints), then lets each feature emit against the bundle it returns: minimum-holding thresholds and fixed fees inside the builder, then cardinality, group cardinality, and pinning the long/short decomposition here. Integer phylogeny is not emitted here — it is applied late in assemble_jump_model! beside its semidefinite sibling — but its presence still forces a builder to run, so a held indicator exists for that later call to gate on. Rather than hand the bundle back as a return value, this registers it in Model State with set_mip_indicators!; the late emitter reads it with mip_indicators.

Pinning the decomposition

Two callers want the decomposition pinned, and they are the same request:

  • xbgt, asked for explicitly by a head whose lw/sw merely bound the weights (PartsBoundWeights).
  • A WeightsFromParts head, which asks for it by construction — w = lw - sw is what its parts are for — and so passes no flag.

Both route to set_exact_budget_constraints!, which reads the contract back off the model and emits what that contract needs.

Pinning needs a per-asset sign bit, which the long-only mip_constraints does not have — its ib marks an asset as held and is what cardinality counts. So an explicit xbgt is served by sign_mip_constraints when nothing else in the model needs binaries (N of them), and otherwise routed to short_mip_threshold_constraints, whose ilb/isb it reuses for free. It is ignored when the model has no short side, there being no decomposition to pin.

Two calls on one weight vector

The bits belong to the weights, as lw, sw and the lifted matrix W do. A call under a prefix whose weights another namespace owns (weights_prefix) reads the bundle of the owner, when that bundle serves its features (serves_mip_kind). So two calls under two prefixes share one bit for each asset. Each call adds its own gates of its bounds, $w_i \leq u_i z_i$ and $w_i \geq \ell_i z_i$, its own threshold $w_i \geq t_i z_i$, and its own cardinality $\sum_i z_i \leq c$ on the shared $z$. The rows of the two calls then intersect exactly. A bundle of a kind that cannot serve the second call gives that call a bundle of its own under its prefix (mip_indicators!). The pin of the decomposition is written once, by the first call that asks for it (pin_decomposition!).

Arguments

  • model::JuMP.Model: The JuMP optimisation model.
  • wb::WeightBounds: Weight bound specification containing lower and upper bounds.
  • card::Option{<:Integer}: Optional maximum cardinality (number of non-zero assets).
  • gcard::Option{<:LinearConstraint}: Optional group cardinality constraint.
  • pl::Option{<:PlC_VecPlC}: Optional phylogeny constraint(s). Only used to detect whether an IntegerPhylogeny is present, which forces a builder to run so a held indicator is registered in Model State for the late set_iplg_constraints! call.
  • lt::Option{<:Threshold}: Long-side minimum-holding threshold.
  • st::Option{<:Threshold}: Short-side minimum-holding threshold.
  • fees::Option{<:Fees}: Optional fee specification.
  • ss::Option{<:Number}: Big-M scaling constant (computed via get_mip_ss when nothing).
  • xbgt::Bool = false: Whether to pin the long/short decomposition so the budgets hold exactly. See the section above.
  • 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. The bits take the owner of the weights instead, see the section above.

Returns

Related

source