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 is ib of the long-only bundle, and ilb + isb of the long-short bundle.

Constraints

  • card_plg_<i>, for the i-th entry of plgs when that entry is an IntegerPhylogeny: $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, or 1 for a single entry.

Arguments

  • model::JuMP.Model: The JuMP optimisation model.
  • plgs::Option{<:PlC_VecPlC}: The phylogeny constraint result, a vector of them, or nothing.
  • 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 IntegerPhylogeny entry has one column for each asset of the model, else DimensionMismatch.

Returns

  • nothing.

Related

source
PortfolioOptimisers.FactorMIPSpace — Type
struct FactorMIPSpace <: AbstractMIPSpace

MIP 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

source
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_bounds derives 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.lb and wb.ub are not nothing, 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

source
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 when flag = 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_bounds derives 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 the i-th entry of plgs when that entry is an IntegerPhylogeny: $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, or 1 for 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, or nothing.
  • 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 via get_mip_ss when nothing).

Validation

Returns

  • nothing.

Related

source