Regularisation Constraints: private API

PortfolioOptimisers.AbstractRegularisationEstimator — Type
abstract type AbstractRegularisationEstimator <: AbstractEstimator

Abstract supertype for all portfolio weight regularisation estimators.

A regularisation term penalises the norm of the weight vector, which is the Lagrangian form of a constraint on that norm.

Related

References

  • [240] V. DeMiguel, L. Garlappi, F. J. Nogales and R. Uppal. A Generalized Approach to Portfolio Optimization: Improving Performance by Constraining Portfolio Norms. Management Science 55, 798–812 (2009). Pages 798-812. The original source of this formulation was not found. The formulation follows this work and is not checked against the original.
source
PortfolioOptimisers.set_l1_regularisation! — Function
set_l1_regularisation!(model::JuMP.Model, l1_val::Number; prefix::Symbol = Symbol(""))
set_l1_regularisation!(model::JuMP.Model, ::Nothing; prefix::Symbol = Symbol(""))

Add an L1 penalty on the portfolio weights to the objective penalty.

The objective takes the penalty in its own units, so l1_val is a price in those units. With no short positions and a budget of one, $\lVert \boldsymbol{w} \rVert_1 = 1$ at every feasible point, so the penalty is a constant and moves no weight. It acts on the gross exposure of a portfolio that can hold short positions. Under MaximumRatio the model's w is the homogenised vector $k \boldsymbol{w}$, so the penalty acts on $k \boldsymbol{w}$. The method on nothing does nothing, and it runs when no L1 coefficient is set. Any other type or arity is a MethodError.

Mathematical definition

\[\begin{align} \text{penalty} &= \lambda_1 \lVert \boldsymbol{w} \rVert_1\,. \end{align}\]

Where:

  • $\lambda_1$: L1 penalty coefficient, l1_val.
  • $\boldsymbol{w}$: Portfolio weights vector $N \times 1$.

JuMP formulation

Variables

  • w: read from the model.
  • t_l1: created, the epigraph variable of the 1-norm.

Expressions

Constraints

  • cl1_noc: $\left(s_c t_{1},\, s_c \boldsymbol{w}\right)$ lies in the 1-norm cone, which is $t_{1} \geq \lVert \boldsymbol{w} \rVert_1$. The objective penalty always makes the objective worse, and $\lambda_1 > 0$, so at the optimum $t_{1}$ equals the norm.

Where:

  • $t_{1}$: The epigraph variable t_l1.
  • $\lambda_1$: L1 penalty coefficient, l1_val.
  • $s_c$: Constraint scale. It multiplies both sides of a row, so a positive value leaves the feasible set unchanged.
  • $\boldsymbol{w}$: Portfolio weights vector $N \times 1$.

Arguments

  • model::JuMP.Model: The JuMP optimisation model.
  • l1_val::Number: L1 penalty coefficient. resolve_constraint_block checks that it is finite and > 0, so the builder checks 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.

Returns

  • nothing.

Related

source
PortfolioOptimisers.squared_norm_over_k! — Function
squared_norm_over_k!(model::JuMP.Model, i::Integer, x, k::Number, sc::Number; prefix::Symbol = Symbol(""))
squared_norm_over_k!(model::JuMP.Model, i::Integer, x, k, sc::Number; prefix::Symbol = Symbol(""))

Return a term equal to the squared 2-norm of x divided by the homogenisation variable k, for the squared L2 penalty at position i.

Under MaximumRatio the model's weights are the homogenised vector $\boldsymbol{y} = k \boldsymbol{w}$, so for $\boldsymbol{x} = \boldsymbol{y}$ the term is $k \lVert \boldsymbol{w} \rVert_2^2$. It has degree one in $k$, as the other penalties have, so it does not change the balance of the ratio when the normalisation ohf changes. When k is a number, the term is the quadratic $\boldsymbol{x}^\intercal \boldsymbol{x} / k$, and every objective except MaximumRatio sets $k = 1$. When k is a variable, the quotient is not quadratic, and the function states it as a rotated second-order cone.

Mathematical definition

\[\begin{align} \text{term} &= \frac{\lVert \boldsymbol{x} \rVert_2^2}{k}\,. \end{align}\]

Where:

  • $\boldsymbol{x}$: The vector argument x. A scalar x is the vector of one entry.
  • $k$: Variable that scales the budget in the homogenised problem.

JuMP formulation

The number method registers no entry. The variable method registers these entries, and each name ends in i.

Variables

  • t_l2_sq_i: the epigraph variable $s$ of the term.

Constraints

  • cl2_sq_rsoc_i: $\left(s_c s,\, s_c k / 2,\, s_c \boldsymbol{x}\right)$ lies in the rotated second-order cone, which is $s k \geq \lVert \boldsymbol{x} \rVert_2^2$. The penalty makes the objective worse as $s$ rises, so at the optimum $s$ equals its bound $\lVert \boldsymbol{x} \rVert_2^2 / k$.

Where:

  • $s_c$: Constraint scale. It multiplies both sides of a row, so a positive value leaves the feasible set unchanged.

Arguments

  • model::JuMP.Model: The JuMP optimisation model.
  • i::Integer: Position of the term, which ends the name of each entry it registers.
  • x: The vector, or the scalar, whose squared norm the term measures.
  • k: The homogenisation variable from effective_k, or the number that stands for it.
  • sc::Number: Constraint scale. The number method registers no row and ignores it.
  • 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

  • The quadratic expression $\boldsymbol{x}^\intercal \boldsymbol{x} / k$ when k is a number, else the epigraph variable t_l2_sq_i.

Related

source
PortfolioOptimisers._set_l2_regularisation! — Function
_set_l2_regularisation!(model::JuMP.Model, i::Integer, w::VecNum,
                        l2::L2Regularisation{<:Any, <:SOCRiskExpr}, sc::Number; prefix::Symbol = Symbol(""))
_set_l2_regularisation!(model::JuMP.Model, i::Integer, w::VecNum,
                        l2::L2Regularisation{<:Any, <:SquaredSOCRiskExpr}, sc::Number; prefix::Symbol = Symbol(""))
_set_l2_regularisation!(model::JuMP.Model, i::Integer, w::VecNum,
                        l2::L2Regularisation{<:Any, <:QuadRiskExpr}, sc::Number; prefix::Symbol = Symbol(""))
_set_l2_regularisation!(model::JuMP.Model, i::Integer, w::VecNum,
                        l2::L2Regularisation{<:Any, <:RSOCRiskExpr}, sc::Number; prefix::Symbol = Symbol(""))

Add the penalty of the L2 term at position i to the objective penalty, in the formulation that l2.alg selects.

SOCRiskExpr penalises $\lVert \boldsymbol{w} \rVert_2$, and SquaredSOCRiskExpr, QuadRiskExpr and RSOCRiskExpr penalise $\lVert \boldsymbol{w} \rVert_2^2$, so one val gives a different penalty under each. Under MaximumRatio the model's w is the homogenised vector $k \boldsymbol{w}$, so the penalty acts on $k \boldsymbol{w}$. The three squared formulations divide the square by $k$, so every penalty has degree one in $k$. Under every other objective $k = 1$: QuadRiskExpr and SquaredSOCRiskExpr then give a quadratic penalty, and add_to_objective_penalty! promotes an affine objective penalty to a JuMP.QuadExpr to hold it. Under MaximumRatio the quotient is not quadratic, so squared_norm_over_k! states it as a rotated second-order cone.

Mathematical definition

\[\begin{align} \text{penalty} &= \lambda_2 \lVert \boldsymbol{w} \rVert_2^{q}\,. \end{align}\]

Where:

JuMP formulation

Each name ends in i, so the entries of two terms do not collide.

Variables

Expressions

Constraints

  • cl2_soc_i, under SOCRiskExpr and SquaredSOCRiskExpr: $\left(s_c t_2,\, s_c \boldsymbol{w}\right)$ lies in the second-order cone, which is $t_2 \geq \lVert \boldsymbol{w} \rVert_2$.
  • cl2_rsoc_i, under RSOCRiskExpr: $\left(s_c t_2,\, s_c k / 2,\, s_c \boldsymbol{w}\right)$ lies in the rotated second-order cone, which is $t_2 \geq \lVert \boldsymbol{w} \rVert_2^2 / k$.
  • cl2_sq_rsoc_i, under SquaredSOCRiskExpr and QuadRiskExpr when $k$ is a variable: the row of squared_norm_over_k!.

QuadRiskExpr registers no row when $k$ is a number. The objective penalty always makes the objective worse, $\lambda_2 > 0$, and $t_2^2$ rises with $t_2 \geq 0$, so at the optimum $t_2$ equals its bound.

Where:

  • $t_2$: The epigraph variable t_l2_i.
  • $k$: Variable that scales the budget in the homogenised problem.
  • $\lambda_2$: L2 penalty coefficient, the val field of an L2Regularisation.
  • $s_c$: Constraint scale. It multiplies both sides of a row, so a positive value leaves the feasible set unchanged.
  • $\boldsymbol{w}$: Portfolio weights vector $N \times 1$.

Arguments

  • model::JuMP.Model: The JuMP optimisation model.
  • i::Integer: Position of the term, which ends the name of each entry it registers.
  • w::VecNum: The weights variable of the model.
  • l2::L2Regularisation: The L2 term.
  • sc::Number: Constraint scale. The QuadRiskExpr method uses it only when $k$ is a variable.
  • 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_l2_regularisation! — Function
set_l2_regularisation!(model::JuMP.Model, l2s::L2Reg_VecL2Reg; prefix::Symbol = Symbol(""))
set_l2_regularisation!(model::JuMP.Model, ::Nothing; prefix::Symbol = Symbol(""))

Add the penalty of each L2 term to the objective penalty.

Each L2Regularisation carries its own coefficient and formulation, and the penalties of several terms add. The objective takes each penalty in its own units, and the formulation sets the power of the norm, so one val gives a different penalty under each formulation. The method on nothing does nothing, and it runs when no L2 term is set. Any other type or arity is a MethodError.

Mathematical definition

Each term adds

\[\begin{align} \text{penalty} &= \lambda_2 \lVert \boldsymbol{w} \rVert_2^{q}\,. \end{align}\]

Where:

Algorithm

  1. Read the weights w and the constraint scale sc from the model.
  2. For the term at position i, call _set_l2_regularisation!, which registers the rows and the penalty of that term under names that end in i.

Arguments

  • model::JuMP.Model: The JuMP optimisation model.
  • l2s::L2Reg_VecL2Reg: One L2 term, or a vector of them.
  • 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_lp_regularisation! — Function
set_lp_regularisation!(model::JuMP.Model, lps::LpReg_VecLpReg; prefix::Symbol = Symbol(""))
set_lp_regularisation!(model::JuMP.Model, ::Nothing; prefix::Symbol = Symbol(""))

Add the penalty of each Lp term to the objective penalty.

Each LpRegularisation carries its own norm order and coefficient, and the penalties of several terms add. The objective takes each penalty in its own units. Under MaximumRatio the model's w is the homogenised vector $k \boldsymbol{w}$, so the penalty acts on $k \boldsymbol{w}$. The method on nothing does nothing, and it runs when no Lp term is set. Any other type or arity is a MethodError.

The same estimator in the lpc field of JuMPOptimiser is a norm constraint, and set_weight_norm_p_constraints! reads its val as a ceiling on the norm.

Mathematical definition

Each term adds

\[\begin{align} \text{penalty} &= \lambda_p \lVert \boldsymbol{w} \rVert_p\,. \end{align}\]

Where:

  • $\lambda_p$: Lp penalty coefficient, the val field of an LpRegularisation in the lp field of JuMPOptimiser.
  • $p$: Norm order.
  • $\boldsymbol{w}$: Portfolio weights vector $N \times 1$.

JuMP formulation

The entries below belong to the term at position $i$. Each name ends in $i$, so the entries of two terms do not collide.

Variables

  • w: read from the model.
  • t_lp_i: created, the epigraph variable of the p-norm.
  • r_lp_i: created, one entry for each asset.

Expressions

Constraints

  • clp_i: one row for each asset $j$, $\left(s_c r_j,\, s_c t_p,\, s_c w_j\right)$ lies in the power cone of exponent $1/p$, which is $r_j^{1/p} t_p^{1 - 1/p} \geq \lvert w_j \rvert$.
  • cslp_i: $s_c \left(\sum_{j=1}^{N} r_j - t_p\right) = 0$.

The two rows together give $t_p \geq \lVert \boldsymbol{w} \rVert_p$. The objective penalty always makes the objective worse, and $\lambda_p > 0$, so at the optimum $t_p$ equals the norm.

Where:

  • $t_p$: The epigraph variable t_lp_i.
  • $r_j$: Entry $j$ of r_lp_i.
  • $\lambda_p$: Lp penalty coefficient, the val field of an LpRegularisation in the lp field of JuMPOptimiser.
  • $p$: Norm order.
  • $s_c$: Constraint scale. It multiplies both sides of a row, so a positive value leaves the feasible set unchanged.
  • $\boldsymbol{w}$: Portfolio weights vector $N \times 1$.
  • $N$: Number of assets.

Arguments

  • model::JuMP.Model: The JuMP optimisation model.
  • lps::LpReg_VecLpReg: One Lp term, or a vector of them.
  • 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_linf_regularisation! — Function
set_linf_regularisation!(model::JuMP.Model, linf::Number; prefix::Symbol = Symbol(""))
set_linf_regularisation!(model::JuMP.Model, ::Nothing; prefix::Symbol = Symbol(""))

Add an L∞ penalty on the portfolio weights to the objective penalty.

The penalty prices the largest absolute weight, so it moves weight away from the largest position. The objective takes the penalty in its own units, so linf is a price in those units. Under MaximumRatio the model's w is the homogenised vector $k \boldsymbol{w}$, so the penalty acts on $k \boldsymbol{w}$. The method on nothing does nothing, and it runs when no L∞ coefficient is set. Any other type or arity is a MethodError.

Mathematical definition

\[\begin{align} \text{penalty} &= \lambda_\infty \lVert \boldsymbol{w} \rVert_\infty\,. \end{align}\]

Where:

  • $\lambda_\infty$: L∞ penalty coefficient, linf.
  • $\boldsymbol{w}$: Portfolio weights vector $N \times 1$.

JuMP formulation

Variables

  • w: read from the model.
  • t_linf: created, the epigraph variable of the ∞-norm.

Expressions

Constraints

  • clinf_nic: $\left(s_c t_\infty,\, s_c \boldsymbol{w}\right)$ lies in the ∞-norm cone, which is $t_\infty \geq \lVert \boldsymbol{w} \rVert_\infty$. The objective penalty always makes the objective worse, and $\lambda_\infty > 0$, so at the optimum $t_\infty$ equals the norm.

Where:

  • $t_\infty$: The epigraph variable t_linf.
  • $\lambda_\infty$: L∞ penalty coefficient, linf.
  • $s_c$: Constraint scale. It multiplies both sides of a row, so a positive value leaves the feasible set unchanged.
  • $\boldsymbol{w}$: Portfolio weights vector $N \times 1$.

Arguments

  • model::JuMP.Model: The JuMP optimisation model.
  • linf::Number: L∞ penalty coefficient. resolve_constraint_block checks that it is finite and > 0, so the builder checks 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.

Returns

  • nothing.

Related

source
PortfolioOptimisers.squared_norm_radius_msg — Function
squared_norm_radius_msg(alg) -> String

Build the refusal message of assert_ambiguity_radius_formulation, naming the formulation that was paired with a rule.

Every refusing method reads this one message, so every formulation that refuses a radius gives the same text. The message names the formulation and the rule family with nameof, because a printed type carries a module prefix wherever the name is not visible from Main. assert_calibrated_slots names its types the same way.

Arguments

  • alg: The formulation that penalises the squared norm.

Returns

  • msg::String: The refusal message.

Related

source
PortfolioOptimisers.assert_ambiguity_radius_formulation — Function
assert_ambiguity_radius_formulation(val, alg) -> Nothing

Refuse an ambiguity radius that was placed beside a formulation which penalises the squared norm.

L2Regularisation emits val * norm(w, 2) under SOCRiskExpr, and val * norm(w, 2)^2 under the three others. Only the first is the Wasserstein form, so only the first reads val as a radius. A plain number stays legal with every formulation, because a number is whatever coefficient the caller meant it to be. A rule of the radius family states that the number is a radius, and that statement is false beside a squared penalty.

The check is a set of methods rather than a list of types in one body, so a formulation that a later change adds refuses a radius by adding one method here. The permissive fallback is the first method, and each refusing method names one formulation of the family.

Algorithm

  1. The pair is anything but a radius rule beside a squared formulation: return nothing.
  2. A radius rule stands beside a VarianceFormulation, which covers QuadRiskExpr and SquaredSOCRiskExpr: refuse.
  3. A radius rule stands beside an RSOCRiskExpr: refuse.

Arguments

Returns

  • nothing.

Related

source
PortfolioOptimisers.assert_penalty_coefficient_role — Function
assert_penalty_coefficient_role(x) -> Nothing

Refuse a norm-ceiling rule that was placed in a slot which reads its number as a penalty coefficient.

The val field of LpRegularisation is the one dual-use slot in the library. JuMPOptimiser's lp field adds val * norm(w, p) to the objective, where val is an ambiguity radius, and its lpc field bounds norm(w, p) <= val * k, where val is a norm ceiling. The type bound of the field is Num_AmbRadNormCeilCal, which admits both rule families, and the field of JuMPOptimiser that holds the term decides which reading is legal.

This method checks the penalty side. A rule of the norm-ceiling family states that the number is a ceiling, and a ceiling has no reading as a penalty coefficient. Its reciprocal is a floor on the effective number of assets, which says nothing about how strongly the objective shrinks the weights. A plain number is legal on both sides, because the caller states what it means.

The check is a set of methods rather than a list of types in one body, on the same terms as assert_ambiguity_radius_formulation. It runs in JuMPOptimiser's constructor, where the caller wrote the field, and again in factory for a term that reached the objective by another route.

Algorithm

  1. The occupant is anything but a norm-ceiling role: return nothing.
  2. The occupant is an LpRegularisation: check its val.
  3. The occupant is a vector of them: check each.
  4. The occupant is an AbstractNormCeilingCalibrationAlgorithm: refuse.
  5. The occupant is a CountOf or a FractionOf: refuse. In this slot the pair states a floor of effective assets, which resolve_calibration_slot turns into a ceiling.

Arguments

  • x: A regularisation term, a vector of them, or the occupant of a val slot.

Returns

  • nothing.

Related

source
PortfolioOptimisers.assert_norm_ceiling_role — Function
assert_norm_ceiling_role(x) -> Nothing

Refuse an ambiguity-radius rule that was placed in a slot which reads its number as a norm ceiling.

This method checks the norm-constraint side, and assert_penalty_coefficient_role checks the penalty side. A rule of the ambiguity-radius family states that the number is a radius, the coefficient of a norm penalty in the objective. JuMPOptimiser.lpc bounds the norm instead, so the statement is false there.

Algorithm

  1. The occupant is anything but a radius role: return nothing.
  2. The occupant is an LpRegularisation: check its val.
  3. The occupant is a vector of them: check each.
  4. The occupant is an AbstractAmbiguityRadiusCalibrationAlgorithm: refuse.

Arguments

  • x: A norm-constraint term, a vector of them, or the occupant of a val slot.

Returns

  • nothing.

Related

source
PortfolioOptimisers.norm_ceiling_factory — Function
norm_ceiling_factory(x, pr::AbstractPriorResult, slv = nothing)

Resolve the norm ceiling in val against prior result pr, and return an LpRegularisation holding the number.

It is the norm-constraint counterpart of factory on the same type, and it is a second verb because the two routes read one field as two quantities. A factory call on the lpc field would refuse the ceiling rule that belongs there, and would resolve the rule under :lpreg_val, the key of the penalty slot.

The two verbs differ in the guard and in the key, and in nothing else. Each refuses the family that has no reading on its own route, this one through assert_norm_ceiling_role. Each states the term's own norm order in the CalibrationContext it resolves the slot against, because one rule placed in lp or in lpc serves every term and each term carries its own p.

The fallback returns its argument unchanged, so an empty lpc field, nothing, passes through it. A term whose val is already a number comes back as the same object, because the resolution returns the number it holds.

Algorithm

  1. The argument is neither a term nor a vector of them: return it unchanged.
  2. The argument is a vector of terms: resolve each of them, and return the vector of the results.
  3. The argument is one term: refuse a radius rule with assert_norm_ceiling_role.
  4. State the term's own p in a CalibrationContext, then resolve the slot under the key :lpc against it, giving val.
  5. Pair the declaration with this resolver through assert_declared_calibration_resolver, which refuses the declared slot when the resolution above did not reach it.
  6. val is the number the term already holds: return the term itself. Otherwise rebuild the term through the keyword constructor.

Arguments

  • x: The norm-constraint term, or a vector of them.
  • pr: Prior result the rule reads.
  • slv: Effective solver, or nothing.

Returns

  • The term, or the vector of terms, with each val holding a number.

Related

source

References

[240]
V. DeMiguel, L. Garlappi, F. J. Nogales and R. Uppal. A Generalized Approach to Portfolio Optimization: Improving Performance by Constraining Portfolio Norms. Management Science 55, 798–812 (2009).