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 throughheld_bin. The MIP builder that returnedindcreated it.
Constraints
cardin the asset space, andscard_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
1for a single matrix.mip_keywrites 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, ornothing.
Returns
nothing.
Related
set_gcard_constraints!set_mip_constraints!: Calls it in the asset space.set_scardmip_constraints!: Calls it in a sub-group space.held_binmip_key
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 throughheld_bin. The MIP builder that returnedindcreated it.
Constraints
gcard_ineq, whengcard.ineqis notnothing: $s_c \left(\mathbf{A}_{\mathrm{ineq}} \boldsymbol{b} - \boldsymbol{B}_{\mathrm{ineq}}\right) \leq 0$.gcard_eq, whengcard.eqis notnothing: $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 ofsp, ornothing.
Returns
nothing.
Related
set_card_constraints!set_mip_constraints!: Calls it in the asset space.set_sgcardmip_constraints!: Calls it in a sub-group space.held_binmip_key
PortfolioOptimisers.subgroup_entry — Function
subgroup_entry(x, i)Return the entry of a sub-group slot that belongs to the i-th selection matrix.
A vector slot holds one entry for each selection matrix, so the method for a vector returns x[i]. Any other value, a scalar or nothing, applies to every selection matrix, so the other method returns it unchanged.
Related
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
- Return
nothingwhencard,gcard,ltandstare allnothing. - Make
sp, aSubsetMIPSpaceoversmtxwith the prefix:sand the indexi. - Run
run_mip_builder!onsp, which givessib, the indicator bundle of the sub-group weights. The builder adds the rows of the long thresholdltand of the short thresholdst. - Add the cardinality row of
cardwithset_card_constraints!. - Add the group-cardinality rows of
gcardwithset_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 ofset_card_constraints!on the held binary ofsib, whencardis notnothing.sgcard_ineq_i_andsgcard_eq_i_: The rows ofset_gcard_constraints!on the held binary ofsib, whengcardis notnothing.
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
1for a single matrix.mip_keywrites 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, ornothing.gcard: The group-cardinality constraint on the held sub-groups, one for each matrix in the vector method, ornothing. 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 viaget_mip_sswhennothing).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
set_smip_constraints!: Calls it when the two kinds of row share a matrix and a threshold.set_scardmip_constraints!set_sgcardmip_constraints!run_mip_builder!WeightBounds
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
- Return
nothingwhencard,ltandstare allnothing. - Make
sp, aSubsetMIPSpaceoversmtxwith the prefix:sand the indexi. - Run
run_mip_builder!onsp, which givessib, the indicator bundle of the sub-group weights. The builder adds the rows of the long thresholdltand of the short thresholdst. - Add the cardinality row of
cardwithset_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
scard_i_: The row ofset_card_constraints!on the held binary ofsib, whencardis notnothing.
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
1for a single matrix.mip_keywrites 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, ornothing.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 viaget_mip_sswhennothing).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
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
- Return
nothingwhengcard,ltandstare allnothing. - Make
sp, aSubsetMIPSpaceoversgmtxwith the prefix:sgand the indexi. - Run
run_mip_builder!onsp, which givessib, the indicator bundle of the sub-group weights. The builder adds the rows of the long thresholdltand of the short thresholdst. - Add the group-cardinality rows of
gcardwithset_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_andsggcard_eq_i_: The rows ofset_gcard_constraints!on the held binary ofsib, whengcardis notnothing.
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
1for a single matrix.mip_keywrites 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, ornothing. 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 viaget_mip_sswhennothing).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
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
- When
smtx === sgmtx,lt === gltandst === gst, callset_all_smip_constraints!withsmtx,ltandst. - Otherwise, call
set_scardmip_constraints!withsmtx,ltandst, then callset_sgcardmip_constraints!withsgmtx,gltandgst.
JuMP formulation
Constraints
- Step 1:
scard_i_fromcard, andsgcard_ineq_i_andsgcard_eq_i_fromgcard, whichset_all_smip_constraints!adds. - Step 2:
scard_i_fromcard, whichset_scardmip_constraints!adds, andsggcard_ineq_i_andsggcard_eq_i_fromgcard, whichset_sgcardmip_constraints!adds.
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
1for a single matrix.mip_keywrites 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 ofsmtx, one for each matrix whensmtxis a vector, ornothing.gcard: The group-cardinality constraint on the held sub-groups ofsgmtx, one for each matrix whensgmtxis a vector, ornothing.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 ofsmtx.st: The short threshold of the sub-group weights ofsmtx.glt: The long threshold of the sub-group weights ofsgmtx.gst: The short threshold of the sub-group weights ofsgmtx.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 viaget_mip_sswhennothing).
Returns
nothing.
Related
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
scardis anInteger, it is finite andscard > 0.smtxis a matrix or anAssetSetsMatrixEstimator, andsltandsstare each a scalar ornothing. - When
scardis a vector, it is not empty and each entry is finite and> 0.smtxis a vector of the same length, and a vectorsltorsstis not empty and has that length too. - When
scardisnothingandsltorsstis a scalar,smtxis a matrix or an estimator. - When
scardisnothingandsltorsstis a vector,smtxis 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
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
sgcthat is notnothinghassize(A, 2) == size(smt, 1). ADimensionMismatchis thrown otherwise.
Related
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
sgcardeis a scalar,sgmtxis a matrix or anAssetSetsMatrixEstimator, andsgltandsgstare each a scalar ornothing. ALinearConstraintwith a matrixsgmtxpassesassert_subgrouped_constraint_width. - When
sgcardeis a vector, it is not empty.sgmtxis a vector of the same length that is not empty, a vectorsgltorsgstis not empty and has that length too, and each pair of a constraint and a matrix passesassert_subgrouped_constraint_width. - When
sgcardeisnothingandsgltorsgstis a scalar,sgmtxis a matrix or an estimator. - When
sgcardeisnothingandsgltorsgstis a vector,sgmtxis 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