Integer Phylogeny Constraints: private API
PortfolioOptimisers.set_iplg_constraints! — Function
set_iplg_constraints!(
model::Model,
plgs::Union{AbstractPhylogenyConstraintResult, AbstractVector{<:AbstractPhylogenyConstraintResult}};
prefix
)
Add the integer phylogeny rows, which cap the number of held assets in each row of an IntegerPhylogeny.
Each IntegerPhylogeny entry of plgs adds its rows on the held binary of the asset bundle. mip_indicators returns the bundle that set_mip_constraints! registered for the same prefix, which is the bundle of the weights unless that call declared its own, and held_bin returns its held binary. An entry of another kind adds no row here. The method for plgs = nothing adds nothing, and the main method adds nothing when no MIP builder ran.
set_mip_constraints! runs a builder that declares a held binary whenever plgs holds an IntegerPhylogeny, so the bundle is present whenever a row is due. The lean sign-bit builder registers a SignIndicators, which has no held binary, and it never runs beside an integer phylogeny. The head calls this function after the risk and the return rows, beside set_sdp_phylogeny_constraints!. It reads no mark that a later builder writes, so the position is a grouping and not a dependency.
JuMP formulation
Variables
- The held binary of the asset bundle, read through
held_bin. It isibof the long-only bundle, andilb + isbof the long-short bundle.
Constraints
card_plg_<i>, for thei-th entry ofplgswhen that entry is anIntegerPhylogeny: $s_c \left(\mathbf{A} \boldsymbol{b} - \boldsymbol{B}\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.
- $\mathbf{A}$: Row set of an
IntegerPhylogeny, one row for each distinct neighbourhood or cluster, with one column for each position that the MIP space gates. - $\boldsymbol{B}$: Largest number of held positions in each row of $\mathbf{A}$. A scalar applies to every row.
- $i$: Position of the entry in
plgs, or1for a single entry.
Arguments
model::JuMP.Model: The JuMP optimisation model.plgs::Option{<:PlC_VecPlC}: The phylogeny constraint result, a vector of them, 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.
Validation
- Each
IntegerPhylogenyentry has one column for each asset of the model, elseDimensionMismatch.
Returns
nothing.
Related
mip_indicatorsheld_binset_mip_constraints!: Registers the bundle that the rows read.set_frc_iplg_constraints!: Adds the same rows on the factor weights.set_sdp_phylogeny_constraints!IntegerPhylogeny
PortfolioOptimisers.FactorMIPSpace — Type
struct FactorMIPSpace <: AbstractMIPSpaceMIP space of the factor weights w1 of a FactorRiskContribution model.
mip_wx! returns w1, and mip_key writes the prefix frc_ into each model key, so the held binary of this space is frc_ib. factor_weight_bounds states the gate bounds on the factor axis, so mip_bounds returns them unchanged. This space registers no bundle in Model State. set_frc_iplg_constraints! declares the bundle and reads it in the same call, so mip_indicators still returns the asset bundle.
Related
PortfolioOptimisers.factor_weight_bounds — Function
factor_weight_bounds(
wb::Union{Nothing, WeightBounds},
Bt::AbstractMatrix{<:Union{Number, AbstractJuMPScalar}}
) -> WeightBounds
Return the bounds of the factor weights that the asset weight bounds imply, widened to hold zero.
set_factor_risk_contribution_constraints! builds the factor basis b1 as the pseudoinverse of $\mathbf{B}^\intercal$. When the loadings have full column rank, $\mathbf{B}^\intercal$ times b1 is the identity, so $\boldsymbol{w}_1 = \mathbf{B}^\intercal \boldsymbol{w}$. The off-factor block b2 * w2 adds nothing to that product, because its columns lie in the null space of $\mathbf{B}^\intercal$. Each factor weight is therefore a fixed linear combination of the asset weights, and the asset bounds bound it. The bounds gate a held bit, and a factor that is not held has a weight of zero, so the function widens each bound to hold zero.
Mathematical definition
\[\begin{align} \boldsymbol{\ell}_{f} &= \min\left(\mathbf{0},\, \mathbf{B}_{+}^\intercal \boldsymbol{\ell} + \mathbf{B}_{-}^\intercal \boldsymbol{u}\right)\,, \\ \boldsymbol{u}_{f} &= \max\left(\mathbf{0},\, \mathbf{B}_{+}^\intercal \boldsymbol{u} + \mathbf{B}_{-}^\intercal \boldsymbol{\ell}\right)\,. \end{align}\]
Where:
- $\boldsymbol{\ell}$, $\boldsymbol{u}$: Lower and upper asset weight bounds from
wb. A scalar bound applies to every asset. - $\mathbf{B}$: Loading matrix, of size $N \times N_{f}$.
- $\mathbf{B}_{+}$, $\mathbf{B}_{-}$: The positive and the negative part of $\mathbf{B}$, taken elementwise, so that $\mathbf{B} = \mathbf{B}_{+} + \mathbf{B}_{-}$.
- $\boldsymbol{\ell}_{f}$, $\boldsymbol{u}_{f}$: Factor weight bounds, the lower and the upper, one entry for each factor.
factor_weight_boundsderives them from the asset weight bounds. The minimum and the maximum are elementwise.
Before the widening, each bound is the exact extreme of $\mathbf{B}^\intercal \boldsymbol{w}$ over the box $\boldsymbol{\ell} \leq \boldsymbol{w} \leq \boldsymbol{u}$. The budget and the other rows of the model do not tighten it.
Arguments
wb::Option{<:WeightBounds}: The asset weight bounds of the optimisation.Bt::MatNum: The transposed loading matrix $\mathbf{B}^\intercal$, of size $N_{f} \times N$.
Validation
wb,wb.lbandwb.ubare notnothing, and every lower and upper bound is finite. A factor weight has no bound of its own, so an asset without a finite bound leaves the gate of each factor that loads on it without a value.
Returns
WeightBounds: The factor weight bounds, one entry for each factor.
Related
PortfolioOptimisers.set_frc_iplg_constraints! — Function
set_frc_iplg_constraints!(
model::Model,
plgs::Union{Nothing, AbstractPhylogenyConstraintResult, AbstractVector{<:AbstractPhylogenyConstraintResult}},
wb::Union{Nothing, WeightBounds},
Bt::AbstractMatrix{<:Union{Number, AbstractJuMPScalar}},
ss::Union{Nothing, Number}
)
Add the integer phylogeny rows on the factor weights of a FactorRiskContribution model.
The asset builder set_iplg_constraints! reads the held binary of the asset bundle. This builder declares a held binary of its own, one bit for each factor, through the HeldIndicators method of declare_mip_indicators! in the FactorMIPSpace. The gate rows of mip_wb on those bits force the weight of a factor to zero when its bit is zero. Each IntegerPhylogeny entry of plgs then adds its rows on the factor bits. A factor weight is free in sign, so its gate needs a bound on each side, and factor_weight_bounds derives both from the asset weight bounds.
The builder adds nothing when plgs holds no IntegerPhylogeny. The head calls it after assemble_jump_model!, beside set_sdp_frc_phylogeny_constraints!. When the budget $k$ is a variable, the gate reads the big-M constant ss. An asset MIP builder registered it if one ran. If none ran, this builder registers it from the asset weight bounds, as the asset builder does.
Mathematical definition
\[\begin{align} \boldsymbol{\ell}_{f} \odot \boldsymbol{b} \leq \boldsymbol{w}_1 &\leq \boldsymbol{u}_{f} \odot \boldsymbol{b}\,, \\ \mathbf{A} \boldsymbol{b} &\leq \boldsymbol{B}\,. \end{align}\]
Where:
- $\boldsymbol{w}_1$: Factor weights of
FactorRiskContribution, one entry for each of the $N_f$ factors. The asset weights are $\mathbf{B}_1 \boldsymbol{w}_1$, with $\mathbf{B}_1$ the pseudoinverse of $\mathbf{B}^\intercal$, plus an off-factor block whenflag = true. - $\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.
- $\boldsymbol{\ell}_{f}$, $\boldsymbol{u}_{f}$: Factor weight bounds, the lower and the upper, one entry for each factor.
factor_weight_boundsderives them from the asset weight bounds. - $\mathbf{A}$: Row set of an
IntegerPhylogeny, one row for each distinct neighbourhood or cluster, with one column for each position that the MIP space gates. - $\boldsymbol{B}$: Largest number of held positions in each row of $\mathbf{A}$. A scalar applies to every row.
JuMP formulation
Variables
w1: The factor weights, read from the model.k: The budget, read from the model.frc_ib: The held binary of the factors, created here.frc_ibf: The continuous product $\boldsymbol{f} = \boldsymbol{b} k$, created here when $k$ is a variable.
Expressions
frc_i_mip: The gate $\boldsymbol{g}$. It is $\boldsymbol{b}$ when $k$ is a number, and $\boldsymbol{f}$ when $k$ is a variable.
Constraints
frc_ibf_ub: $s_c \left(\boldsymbol{f} - k\right) \leq 0$, when $k$ is a variable.frc_ibfd_ub: $s_c \left(\boldsymbol{f} - s_s \boldsymbol{b}\right) \leq 0$, when $k$ is a variable.frc_ibfd_lb: $s_c \left(\boldsymbol{f} + s_s (\mathbf{1} - \boldsymbol{b}) - k\right) \geq 0$, when $k$ is a variable.frc_w_mip_lb: $s_c \left(\boldsymbol{w}_1 - \boldsymbol{\ell}_{f} \odot \boldsymbol{g}\right) \geq 0$.frc_w_mip_ub: $s_c \left(\boldsymbol{w}_1 - \boldsymbol{u}_{f} \odot \boldsymbol{g}\right) \leq 0$.frc_card_plg_<i>, for thei-th entry ofplgswhen that entry is anIntegerPhylogeny: $s_c \left(\mathbf{A} \boldsymbol{b} - \boldsymbol{B}\right) \leq 0$.
Where:
- $s_c$: Constraint scale. It multiplies both sides of a row, so a positive value leaves the feasible set unchanged.
- $k$: Variable that scales the budget in the homogenised problem.
- $s_s$: The big-M constant
ss. The three rows of $\boldsymbol{f}$ give $f_j = k$ when $b_j = 1$ and $f_j = 0$ when $b_j = 0$, provided that $k \leq s_s$. - $i$: Position of the entry in
plgs, or1for a single entry.
The rows frc_card_plg_<i> read the bits $\boldsymbol{b}$ and never the gate, so they count held factors when $k$ is a variable too.
Arguments
model::JuMP.Model: The JuMP optimisation model.plgs::Option{<:PlC_VecPlC}: The phylogeny constraint result on the factors, a vector of them, ornothing.wb::Option{<:WeightBounds}: The asset weight bounds of the optimisation.Bt::MatNum: The transposed loading matrix $\mathbf{B}^\intercal$.ss::Option{<:Number}: Big-M scaling constant (computed viaget_mip_sswhennothing).
Validation
- The asset weight bounds pass the check of
factor_weight_bounds. - Each
IntegerPhylogenyentry has one column for each factor,size(Bt, 1)in all, elseDimensionMismatch.
Returns
nothing.
Related
set_iplg_constraints!: Adds the same rows on the asset weights.set_sdp_frc_phylogeny_constraints!factor_weight_boundsdeclare_mip_indicators!FactorMIPSpaceIntegerPhylogeny