Cardinality Constraints: private API

PortfolioOptimisers.set_card_constraints! — Function
set_card_constraints!(
    model::Model,
    sp::AbstractMIPSpace,
    ind::AbstractMIPIndicators,
    card::Integer
)

Add the cardinality row, which caps the number of positions that the space sp holds.

The row sums the held binary of the bundle ind, which held_bin returns, so it counts held positions and reads no sign. mip_key names the row for sp, so one method serves the asset space and every sub-group. The method for card = nothing adds nothing, so it never reads a held binary that the bundle does not carry.

JuMP formulation

Variables

  • The held binary of ind, read through held_bin. The MIP builder that returned ind created it.

Constraints

  • card in the asset space, and scard_i_ in a sub-group space: $s_c \left(\sum_{j=1}^{M} b_j - c\right) \leq 0$.

Where:

  • $s_c$: Constraint scale. It multiplies both sides of a row, so a positive value leaves the feasible set unchanged.
  • $\boldsymbol{b} \in \{0, 1\}^{M}$: Held binary, one entry for each of the $M$ assets, sub-groups or factors that a MIP space gates. A position can be non-zero only when its entry is one. Under the long-short bundle it is the sum of the long and the short binary, which are never both one.
  • $c$: The largest number of held positions, card.
  • $i$: Index of a sub-group selection matrix, its position in the vector of matrices, or 1 for a single matrix. mip_key writes it into the name of each sub-group row.

Arguments

  • model::JuMP.Model: The JuMP optimisation model.
  • sp::AbstractMIPSpace: The weight space that the row acts on.
  • ind::AbstractMIPIndicators: The indicator bundle that the MIP builder returned.
  • card::Option{<:Integer}: The largest number of held positions, or nothing.

Returns

  • nothing.

Related

source
PortfolioOptimisers.set_gcard_constraints! — Function
set_gcard_constraints!(
    model::Model,
    sp::AbstractMIPSpace,
    ind::AbstractMIPIndicators,
    gcard::LinearConstraint
)

Add the group-cardinality rows, which bound the number of held positions in each group.

gcard states each group as a row of a linear constraint on the held binary of the bundle ind, which held_bin returns. An inequality row caps a count, and an equality row fixes it. mip_key names the rows for sp, so one method serves the asset space and every sub-group. The method for gcard = nothing adds nothing, so it never reads a held binary that the bundle does not carry.

JuMP formulation

Variables

  • The held binary of ind, read through held_bin. The MIP builder that returned ind created it.

Constraints

  • gcard_ineq, when gcard.ineq is not nothing: $s_c \left(\mathbf{A}_{\mathrm{ineq}} \boldsymbol{b} - \boldsymbol{B}_{\mathrm{ineq}}\right) \leq 0$.
  • gcard_eq, when gcard.eq is not nothing: $s_c \left(\mathbf{A}_{\mathrm{eq}} \boldsymbol{b} - \boldsymbol{B}_{\mathrm{eq}}\right) = 0$.

In a sub-group space, mip_key adds the prefix and the index of the space to each name. set_smip_constraints! states the names that each sub-group path writes.

Where:

  • $s_c$: Constraint scale. It multiplies both sides of a row, so a positive value leaves the feasible set unchanged.
  • $\boldsymbol{b} \in \{0, 1\}^{M}$: Held binary, one entry for each of the $M$ assets, sub-groups or factors that a MIP space gates. A position can be non-zero only when its entry is one. Under the long-short bundle it is the sum of the long and the short binary, which are never both one.
  • $\mathbf{A}$: Constraint coefficient matrix.
  • $\boldsymbol{B}$: Constraint response vector.
  • $\text{ineq}$: Subscript for inequality constraints.
  • $\text{eq}$: Subscript for equality constraints.

Arguments

  • model::JuMP.Model: The JuMP optimisation model.
  • sp::AbstractMIPSpace: The weight space that the rows act on.
  • ind::AbstractMIPIndicators: The indicator bundle that the MIP builder returned.
  • gcard::Option{<:LinearConstraint}: The group-cardinality constraint, with one column for each position of sp, or nothing.

Returns

  • nothing.

Related

source
PortfolioOptimisers.set_all_smip_constraints! — Function
set_all_smip_constraints!(
    model::Model,
    wb::WeightBounds,
    card::Union{Nothing, Integer},
    gcard::Union{Nothing, LinearConstraint},
    smtx::Union{Nothing, AbstractMatrix{<:Union{Number, AbstractJuMPScalar}}},
    lt::Union{Nothing, Threshold},
    st::Union{Nothing, Threshold},
    ss::Union{Nothing, Number};
    ...
)
set_all_smip_constraints!(
    model::Model,
    wb::WeightBounds,
    card::Union{Nothing, Integer},
    gcard::Union{Nothing, LinearConstraint},
    smtx::Union{Nothing, AbstractMatrix{<:Union{Number, AbstractJuMPScalar}}},
    lt::Union{Nothing, Threshold},
    st::Union{Nothing, Threshold},
    ss::Union{Nothing, Number},
    i::Integer;
    prefix
)

Add the sub-group cardinality and group-cardinality rows when both kinds of row read one selection matrix.

The rows act on the sub-group weights smtx * w, so a held position is a held sub-group. One indicator builder serves both kinds of row. The vector method runs the single-matrix method once for each matrix, with the position of the matrix as the index i.

Algorithm

  1. Return nothing when card, gcard, lt and st are all nothing.
  2. Make sp, a SubsetMIPSpace over smtx with the prefix :s and the index i.
  3. Run run_mip_builder! on sp, which gives sib, the indicator bundle of the sub-group weights. The builder adds the rows of the long threshold lt and of the short threshold st.
  4. Add the cardinality row of card with set_card_constraints!.
  5. Add the group-cardinality rows of gcard with set_gcard_constraints!.

The vector method gives the i-th entry of each vector slot to the i-th matrix, through subgroup_entry. A slot that is not a vector applies to every matrix.

JuMP formulation

Constraints

  • scard_i_: The row of set_card_constraints! on the held binary of sib, when card is not nothing.
  • sgcard_ineq_i_ and sgcard_eq_i_: The rows of set_gcard_constraints! on the held binary of sib, when gcard is not nothing.

run_mip_builder! states the indicator and threshold rows that step 3 adds.

Where:

  • $i$: Index of a sub-group selection matrix, its position in the vector of matrices, or 1 for a single matrix. mip_key writes it into the name of each sub-group row.

Arguments

  • model::JuMP.Model: The JuMP optimisation model.
  • wb::WeightBounds: Weight bound specification containing lower and upper bounds.
  • card: The largest number of held sub-groups, one for each matrix in the vector method, or nothing.
  • gcard: The group-cardinality constraint on the held sub-groups, one for each matrix in the vector method, or nothing. It has one column for each row of its matrix.
  • smtx: The selection matrix, or a vector of them. Each row selects the assets of one sub-group.
  • lt: The long threshold of the sub-group weights, or a vector with one entry for each matrix.
  • st: The short threshold of the sub-group weights, or a vector with one entry for each matrix.
  • ss::Option{<:Number}: Big-M scaling constant (computed via get_mip_ss when nothing).
  • i::Integer = 1: The index of the matrix, which names the rows. The single-matrix method only.
  • 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

source
PortfolioOptimisers.set_scardmip_constraints! — Function
set_scardmip_constraints!(
    model::Model,
    wb::WeightBounds,
    card::Union{Nothing, Integer},
    smtx::Union{Nothing, AbstractMatrix{<:Union{Number, AbstractJuMPScalar}}},
    lt::Union{Nothing, Threshold},
    st::Union{Nothing, Threshold},
    ss::Union{Nothing, Number};
    ...
)
set_scardmip_constraints!(
    model::Model,
    wb::WeightBounds,
    card::Union{Nothing, Integer},
    smtx::Union{Nothing, AbstractMatrix{<:Union{Number, AbstractJuMPScalar}}},
    lt::Union{Nothing, Threshold},
    st::Union{Nothing, Threshold},
    ss::Union{Nothing, Number},
    i::Integer;
    prefix
)

Add the sub-group cardinality rows, which cap the number of held sub-groups of a selection matrix.

The row acts on the sub-group weights smtx * w, so a held position is a held sub-group. The vector method runs the single-matrix method once for each matrix, with the position of the matrix as the index i.

Algorithm

  1. Return nothing when card, lt and st are all nothing.
  2. Make sp, a SubsetMIPSpace over smtx with the prefix :s and the index i.
  3. Run run_mip_builder! on sp, which gives sib, the indicator bundle of the sub-group weights. The builder adds the rows of the long threshold lt and of the short threshold st.
  4. Add the cardinality row of card with set_card_constraints!.

The vector method gives the i-th entry of each vector slot to the i-th matrix, through subgroup_entry. A slot that is not a vector applies to every matrix.

JuMP formulation

Constraints

run_mip_builder! states the indicator and threshold rows that step 3 adds.

Where:

  • $i$: Index of a sub-group selection matrix, its position in the vector of matrices, or 1 for a single matrix. mip_key writes it into the name of each sub-group row.

Arguments

  • model::JuMP.Model: The JuMP optimisation model.
  • wb::WeightBounds: Weight bound specification containing lower and upper bounds.
  • card: The largest number of held sub-groups, one for each matrix in the vector method, or nothing.
  • smtx: The selection matrix, or a vector of them. Each row selects the assets of one sub-group.
  • lt: The long threshold of the sub-group weights, or a vector with one entry for each matrix.
  • st: The short threshold of the sub-group weights, or a vector with one entry for each matrix.
  • ss::Option{<:Number}: Big-M scaling constant (computed via get_mip_ss when nothing).
  • i::Integer = 1: The index of the matrix, which names the rows. The single-matrix method only.
  • 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

source
PortfolioOptimisers.set_sgcardmip_constraints! — Function
set_sgcardmip_constraints!(
    model::Model,
    wb::WeightBounds,
    gcard::Union{Nothing, LinearConstraint},
    sgmtx::Union{Nothing, AbstractMatrix{<:Union{Number, AbstractJuMPScalar}}},
    lt::Union{Nothing, Threshold},
    st::Union{Nothing, Threshold},
    ss::Union{Nothing, Number};
    ...
)
set_sgcardmip_constraints!(
    model::Model,
    wb::WeightBounds,
    gcard::Union{Nothing, LinearConstraint},
    sgmtx::Union{Nothing, AbstractMatrix{<:Union{Number, AbstractJuMPScalar}}},
    lt::Union{Nothing, Threshold},
    st::Union{Nothing, Threshold},
    ss::Union{Nothing, Number},
    i::Integer;
    prefix
)

Add the sub-grouped group-cardinality rows, which bound the number of held sub-groups in each group of sub-groups.

The rows act on the sub-group weights sgmtx * w, so a held position is a held sub-group. The vector method runs the single-matrix method once for each matrix, with the position of the matrix as the index i.

Algorithm

  1. Return nothing when gcard, lt and st are all nothing.
  2. Make sp, a SubsetMIPSpace over sgmtx with the prefix :sg and the index i.
  3. Run run_mip_builder! on sp, which gives sib, the indicator bundle of the sub-group weights. The builder adds the rows of the long threshold lt and of the short threshold st.
  4. Add the group-cardinality rows of gcard with set_gcard_constraints!.

The vector method gives the i-th entry of each vector slot to the i-th matrix, through subgroup_entry. A slot that is not a vector applies to every matrix.

JuMP formulation

Constraints

  • sggcard_ineq_i_ and sggcard_eq_i_: The rows of set_gcard_constraints! on the held binary of sib, when gcard is not nothing.

run_mip_builder! states the indicator and threshold rows that step 3 adds.

Where:

  • $i$: Index of a sub-group selection matrix, its position in the vector of matrices, or 1 for a single matrix. mip_key writes it into the name of each sub-group row.

Arguments

  • model::JuMP.Model: The JuMP optimisation model.
  • wb::WeightBounds: Weight bound specification containing lower and upper bounds.
  • gcard: The group-cardinality constraint on the held sub-groups, one for each matrix in the vector method, or nothing. It has one column for each row of its matrix.
  • sgmtx: The selection matrix, or a vector of them. Each row selects the assets of one sub-group.
  • lt: The long threshold of the sub-group weights, or a vector with one entry for each matrix.
  • st: The short threshold of the sub-group weights, or a vector with one entry for each matrix.
  • ss::Option{<:Number}: Big-M scaling constant (computed via get_mip_ss when nothing).
  • i::Integer = 1: The index of the matrix, which names the rows. The single-matrix method only.
  • 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

source
PortfolioOptimisers.set_smip_constraints! — Function
set_smip_constraints!(
    model::Model,
    wb::WeightBounds,
    card::Union{Nothing, Integer, AbstractVector{<:Integer}},
    gcard::Union{Nothing, LinearConstraint, AbstractVector{<:LinearConstraint}},
    smtx::Union{Nothing, AbstractMatrix{<:Union{Number, AbstractJuMPScalar}}, AbstractVector{<:AbstractMatrix{<:Union{Number, AbstractJuMPScalar}}}},
    sgmtx::Union{Nothing, AbstractMatrix{<:Union{Number, AbstractJuMPScalar}}, AbstractVector{<:AbstractMatrix{<:Union{Number, AbstractJuMPScalar}}}},
    lt::Union{Nothing, Threshold, AbstractVector{<:Union{Nothing, var"#s3887"} where var"#s3887"<:Threshold}},
    st::Union{Nothing, Threshold, AbstractVector{<:Union{Nothing, var"#s3887"} where var"#s3887"<:Threshold}},
    glt::Union{Nothing, Threshold, AbstractVector{<:Union{Nothing, var"#s3887"} where var"#s3887"<:Threshold}},
    gst::Union{Nothing, Threshold, AbstractVector{<:Union{Nothing, var"#s3887"} where var"#s3887"<:Threshold}},
    ss::Union{Nothing, Number};
    prefix
)

Add every sub-group MIP row, through one indicator builder when the two kinds of row share their matrix and their thresholds.

The shared path needs smtx === sgmtx, lt === glt and st === gst, because the one indicator bundle it builds carries one pair of thresholds. When any pair differs, each kind of row gets its own builder, so each reads its own thresholds. The test is identity and not equality, so two equal matrices that are distinct objects take the separate path, which builds two indicator bundles for the same sub-groups.

Algorithm

  1. When smtx === sgmtx, lt === glt and st === gst, call set_all_smip_constraints! with smtx, lt and st.
  2. Otherwise, call set_scardmip_constraints! with smtx, lt and st, then call set_sgcardmip_constraints! with sgmtx, glt and gst.

JuMP formulation

Constraints

So the name of a group-cardinality row tells which path added it.

Where:

  • $i$: Index of a sub-group selection matrix, its position in the vector of matrices, or 1 for a single matrix. mip_key writes it into the name of each sub-group row.

Arguments

  • model::JuMP.Model: The JuMP optimisation model.
  • wb::WeightBounds: Weight bound specification containing lower and upper bounds.
  • card: The largest number of held sub-groups of smtx, one for each matrix when smtx is a vector, or nothing.
  • gcard: The group-cardinality constraint on the held sub-groups of sgmtx, one for each matrix when sgmtx is a vector, or nothing.
  • smtx: The selection matrix of the cardinality rows, or a vector of them.
  • sgmtx: The selection matrix of the group-cardinality rows, or a vector of them.
  • lt: The long threshold of the sub-group weights of smtx.
  • st: The short threshold of the sub-group weights of smtx.
  • glt: The long threshold of the sub-group weights of sgmtx.
  • gst: The short threshold of the sub-group weights of sgmtx.
  • 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. A sub-group bit is a fact of one call, so the bits take it too.
  • ss::Option{<:Number}: Big-M scaling constant (computed via get_mip_ss when nothing).

Returns

  • nothing.

Related

source
PortfolioOptimisers.assert_subgroup_mip_fields — Function
assert_subgroup_mip_fields(scard, smtx, slt, sst)

Refuses a set of sub-group cardinality slots whose shapes do not agree.

The constructors of JuMPOptimiser and ProgrammeAllocationSet call it, because both carry the four slots. A TimeDependent in any slot is not yet a value, so the check skips all four, and the substitution of each fold checks them.

Validation

  • When scard is an Integer, it is finite and scard > 0. smtx is a matrix or an AssetSetsMatrixEstimator, and slt and sst are each a scalar or nothing.
  • When scard is a vector, it is not empty and each entry is finite and > 0. smtx is a vector of the same length, and a vector slt or sst is not empty and has that length too.
  • When scard is nothing and slt or sst is a scalar, smtx is a matrix or an estimator.
  • When scard is nothing and slt or sst is a vector, smtx is a vector that is not empty, and each vector threshold has its length.

A value check throws an IsEmptyError or a DomainError. A type check throws an ArgumentError, a length check a DimensionMismatch, and an empty threshold or smtx an IsEmptyError.

Related

source
PortfolioOptimisers.assert_subgrouped_constraint_width — Function
assert_subgrouped_constraint_width(sgc::LinearConstraint, smt::MatNum)
assert_subgrouped_constraint_width(sgc::LcE_Lc, smt::MatNum_ASetMatE)

Refuses a precomputed sub-grouped cardinality constraint whose width is not the number of sub-groups in its selection matrix.

set_gcard_constraints! multiplies the matrix A of each half of sgc by the held binary of the sub-groups, which has one entry for each row of smt. So every half needs one column for each row of smt, and it can have any number of rows. The other method accepts a pair with an estimator in either slot, because the width of an estimator is not known until the optimiser resolves it. Any other type is a MethodError.

Validation

  • Each half of sgc that is not nothing has size(A, 2) == size(smt, 1). A DimensionMismatch is thrown otherwise.

Related

source
PortfolioOptimisers.assert_subgrouped_mip_fields — Function
assert_subgrouped_mip_fields(sgcarde, sgmtx, sglt, sgst)

Refuses a set of sub-grouped cardinality slots whose shapes do not agree.

The constructors of JuMPOptimiser and ProgrammeAllocationSet call it, because both carry the four slots. The builder pairs sgcarde with sgmtx, so a precomputed LinearConstraint needs one column for each row of sgmtx. A TimeDependent in any slot is not yet a value, so the check skips all four, and the substitution of each fold checks them.

Validation

  • When sgcarde is a scalar, sgmtx is a matrix or an AssetSetsMatrixEstimator, and sglt and sgst are each a scalar or nothing. A LinearConstraint with a matrix sgmtx passes assert_subgrouped_constraint_width.
  • When sgcarde is a vector, it is not empty. sgmtx is a vector of the same length that is not empty, a vector sglt or sgst is not empty and has that length too, and each pair of a constraint and a matrix passes assert_subgrouped_constraint_width.
  • When sgcarde is nothing and sglt or sgst is a scalar, sgmtx is a matrix or an estimator.
  • When sgcarde is nothing and sglt or sgst is a vector, sgmtx is a vector that is not empty, and each vector threshold has its length.

A type check throws an ArgumentError, a length or width check a DimensionMismatch, and an empty slot an IsEmptyError.

Related

source