Weight finalisers

PortfolioOptimisers.ErrorWeightFinaliser — Type
struct ErrorWeightFinaliser{__T_alg, __T_dev} <: JuMPWeightFinaliserFormulation

Selects the norm of a weight deviation as the objective of a JuMP weight finaliser.

The field alg is the norm, and the field dev states whether the deviation is relative to the target weights or absolute.

Mathematical definition

\[\begin{align} \underset{\boldsymbol{w}}{\min} &\quad \left\lVert \boldsymbol{d}(\boldsymbol{w},\, \boldsymbol{w}_{0}) \right\rVert\,, \\ \textrm{s.t.} &\quad \boldsymbol{1}^\intercal \boldsymbol{w} = \boldsymbol{1}^\intercal \boldsymbol{w}_{0}\,, \\ &\quad \boldsymbol{l} \leq \boldsymbol{w} \leq \boldsymbol{u}\,. \end{align}\]

Where:

  • $\boldsymbol{w}$: Portfolio weights vector $N \times 1$.
  • $\boldsymbol{w}_{0}$: Portfolio weights vector $N \times 1$ that the optimisation produced, which the finaliser repairs.
  • $\boldsymbol{l}$, $\boldsymbol{u}$: Lower and upper weight bounds. An absent bound is dropped from the programme rather than set to an infinity.
  • $\boldsymbol{d}$: The deviation of dev, $\boldsymbol{w} \oslash \boldsymbol{w}_{0} - \boldsymbol{1}$ for a RelativeWeightDeviation, and $\boldsymbol{w} - \boldsymbol{w}_{0}$ for an AbsoluteWeightDeviation.
  • $\lVert \cdot \rVert$: The norm of alg.
  • $\oslash$: Element-wise division.
  • $\boldsymbol{1}$: Vector of ones.

The programme bounds the norm itself. It does not divide the norm by norm_factor, so the ddof of alg has no effect. A SquaredL2Norm and an L2Norm give the same programme, because the square increases on non-negative values and so does not move the minimiser.

Each pair of a norm and a deviation has its own minimiser:

  • The L1 norm of the relative deviation weighs a change to a small weight more than the same change to a large weight. So the finaliser moves mass to the largest free weights first.
  • The L2 norm of the relative deviation has the minimiser $w_{i} = w_{0,i} + c\, w_{0,i}^{2}$ where the bounds bind none of the free weights, with one $c$ that restores the budget.
  • The L1 norm of the absolute deviation costs the same for every transfer of mass between two weights, so its minimiser is often not unique. The value of the objective is twice the mass that the finaliser moves.
  • The L2 norm of the absolute deviation has the Euclidean projection of $\boldsymbol{w}_{0}$ onto the feasible set as its minimiser, which EuclideanWeightFinaliser finds with no solver. Where the bounds bind none of the free weights, the minimiser is $w_{i} = w_{0,i} + c$, with one $c$ that restores the budget.

Fields

  • alg: Norm of the deviation from the target weights. The programme bounds the norm itself and does not divide it, so the ddof of the norm has no effect.
  • dev: Whether the deviation is relative to the target weights or absolute.

Constructors

ErrorWeightFinaliser(;    alg::NormError = L1Norm(),    dev::WeightDeviation = RelativeWeightDeviation()) -> ErrorWeightFinaliser

Keywords correspond to the struct's fields.

Validation

  • If alg is an LpNorm: alg.p > 1.

Examples

julia> ErrorWeightFinaliser()ErrorWeightFinaliser  alg ┼ L1Norm      │   ddof ┴ Int64: 0  dev ┴ RelativeWeightDeviation()

Related

source
PortfolioOptimisers.RelativeWeightDeviation — Type
struct RelativeWeightDeviation <: WeightDeviation

Selects the deviation relative to the target weights, $\boldsymbol{x} \oslash (c\, \tilde{\boldsymbol{w}}_{0}) - \boldsymbol{1}$.

A relative deviation weighs a change to a small weight more than the same change to a large weight. The deviation is defined only where every entry of $\boldsymbol{w}_{0}$ is not zero, so weight_deviation replaces each zero entry of a copy of the target with eps. The deviation has no unit, so DiscreteAllocation prices it in money as $c\, u$.

Where:

  • $\boldsymbol{x}$: The model's vector that tracks the target.
  • $c$: The scale of the target.
  • $\tilde{\boldsymbol{w}}_{0}$: The target weights with each zero entry replaced by eps.
  • $\oslash$: Element-wise division.
  • $\boldsymbol{1}$: Vector of ones.

Examples

julia> RelativeWeightDeviation()RelativeWeightDeviation()

Related

source
PortfolioOptimisers.AbsoluteWeightDeviation — Type
struct AbsoluteWeightDeviation <: WeightDeviation

Selects the deviation from the target weights, $\boldsymbol{x} - c\, \boldsymbol{w}_{0}$.

The deviation has the units of $\boldsymbol{x}$. So DiscreteAllocation uses its norm $u$ as the money term of the objective.

Where:

  • $\boldsymbol{x}$: The model's vector that tracks the target.
  • $c$: The scale of the target.
  • $\boldsymbol{w}_{0}$: Portfolio weights vector $N \times 1$ that the optimisation produced, which the finaliser repairs.

Examples

julia> AbsoluteWeightDeviation()AbsoluteWeightDeviation()

Related

source
PortfolioOptimisers.WeightDeviation — Type
abstract type WeightDeviation <: AbstractAlgorithm

Abstract supertype for the forms of the deviation of a vector from its target weights.

A subtype is the field dev of an ErrorWeightFinaliser. It states the residual whose norm the programme minimises.

Interfaces

To add a deviation, subtype WeightDeviation and implement the two methods below.

weight_deviation

  • weight_deviation(dev::MyDeviation, x, w0::VecNum, c::Number) -> AbstractVector: Returns the residual of x against the target c * w0.

Arguments

Returns

  • The residual, a vector of the length of x.

deviation_error_term

  • deviation_error_term(dev::MyDeviation, u, c::Number): Returns the error term of the objective of DiscreteAllocation, in money.

Arguments

  • dev: The concrete subtype instance.
  • u: The model's bound on the norm of the residual.
  • c: The cash of the side.

Returns

  • The term that the objective adds to the cash left over.

Related

source
PortfolioOptimisers.weight_deviation — Function
weight_deviation(dev::RelativeWeightDeviation, x, w0::VecNum, c::Number)
weight_deviation(dev::AbsoluteWeightDeviation, x, w0::VecNum, c::Number)

Returns the residual of x against the target c * w0 that dev selects.

The relative method replaces each zero entry of a copy of w0 with eps(eltype(w0)) before it multiplies by c. It does not change w0.

Arguments

  • dev: The deviation.
  • x: The model's vector that tracks the target.
  • w0: The target weights.
  • c: The scale that turns w0 into the units of x.

Returns

Related

source
PortfolioOptimisers.deviation_error_term — Function
deviation_error_term(dev::RelativeWeightDeviation, u, c::Number)
deviation_error_term(dev::AbsoluteWeightDeviation, u, ::Number)

Returns the error term of the objective of DiscreteAllocation, in money.

The cash left over is money. An absolute deviation is money too, so the term is $u$. A relative deviation has no unit, so the term is $c\, u$, and a relative deviation of one over the whole side is worth the cash of the side.

Arguments

  • dev: The deviation.
  • u: The model's bound on the norm of the residual.
  • c: The cash of the side.

Returns

  • The error term of the objective.

Related

source
PortfolioOptimisers.IterativeWeightFinaliser — Type
struct IterativeWeightFinaliser{__T_iter} <: WeightFinaliser

Moves the weights into their bounds by a repeated clip and a proportional redistribution of the clipped mass.

The redistribution keeps the ratios of the free weights, so the answer differs from the Euclidean projection of EuclideanWeightFinaliser. The loop stops at no answer when no weight lies strictly inside its bounds, for example [0.6, 0.4, 0.0] under ub = 0.4. It can also diverge on long-short bounds. In both cases step 9 returns the Euclidean projection, which is [0.4, 0.4, 0.2] in the example.

A set of bounds that cannot hold the budget has no feasible vector. Four weights that sum to 1 under lb = 0.3 become their lower bounds, and finalise_weight_bounds reports an OptimisationFailure.

Algorithm

The steps are those of opt_weight_bounds for this type.

  1. Return w unchanged when it breaks no bound.
  2. Read the budget s1 as sum(w), and keep the input as w0. Read an absent bound as typemin or typemax of the element type of w, which must be infinite, through absent_weight_bound.
  3. Clip w to the bounds.
  4. Mark the free entries idx, which lie strictly inside their bounds after the clip.
  5. Subtract the mass that the clip added below lb from the mass that it removed above ub, giving delta.
  6. When delta is not zero, add delta to the free entries, in proportion to their weights.
  7. Multiply w by s1 / sum(w), which restores the budget.
  8. Stop when w breaks no bound. Else repeat from step 3, for at most iter passes.
  9. Return w when it is finite and breaks no bound. Else return the Euclidean projection of w0, euclidean_weight_projection.

Fields

  • iter: Maximum number of iterations.

Constructors

IterativeWeightFinaliser(;    iter::Integer = 100) -> IterativeWeightFinaliser

Keywords correspond to the struct's fields.

Validation

  • iter > 0.

Examples

julia> IterativeWeightFinaliser()IterativeWeightFinaliser  iter ┴ Int64: 100

Related

source
PortfolioOptimisers.JuMPWeightFinaliser — Type
struct JuMPWeightFinaliser{__T_slv, __T_sc, __T_so, __T_alg} <: WeightFinaliser

Moves the weights into their bounds with the solution of a JuMP programme.

The programme keeps the sum of the input weights and holds every weight between its bounds. The field alg selects the deviation from the input that the programme minimises. An absent bound adds no row. When the solve fails, the finaliser logs a warning and uses a default IterativeWeightFinaliser.

Fields

  • slv: Solver or vector of solvers.
  • sc: Constraint scale factor.
  • so: Objective scale factor.
  • alg: Weight finaliser error formulation algorithm.

Constructors

JuMPWeightFinaliser(;    slv::Slv_VecSlv,    sc::Number = 1.0,    so::Number = 1.0,    alg::JuMPWeightFinaliserFormulation = ErrorWeightFinaliser()) -> JuMPWeightFinaliser

Keywords correspond to the struct's fields.

Validation

  • If slv is a VecSlv: !isempty(slv).
  • sc > 0, so > 0.

Examples

julia> JuMPWeightFinaliser(; slv = Solver(; solver = nothing))JuMPWeightFinaliser  slv ┼ Solver      │          name ┼ String: ""      │        solver ┼ nothing      │      settings ┼ nothing      │     check_sol ┼ @NamedTuple{}: NamedTuple()      │   add_bridges ┴ Bool: true   sc ┼ Float64: 1.0   so ┼ Float64: 1.0  alg ┼ ErrorWeightFinaliser      │   alg ┼ L1Norm      │       │   ddof ┴ Int64: 0      │   dev ┴ RelativeWeightDeviation()

Related

source
PortfolioOptimisers.JuMPWeightFinaliserFormulation — Type
abstract type JuMPWeightFinaliserFormulation <: AbstractAlgorithm

Abstract supertype for the deviations that a JuMP weight finaliser can minimise.

A subtype is the field alg of a JuMPWeightFinaliser, and the field wf of a DiscreteAllocation. It selects the deviation from the target weights that the programme minimises. ErrorWeightFinaliser is the library's subtype.

Interfaces

To add a deviation, subtype JuMPWeightFinaliserFormulation and implement the method below.

set_clustering_weight_finaliser_alg!

  • set_clustering_weight_finaliser_alg!(model::JuMP.Model, alg::MyFormulation, wi::VecNum) -> Nothing: Adds the deviation objective to a model that already holds the weights w, the budget row and the bound rows.

Arguments

  • model: The JuMP model that opt_weight_bounds builds.
  • alg: The concrete subtype instance.
  • wi: The weights that the optimisation produced. The method must not change them.

Returns

  • nothing. The method adds variables, rows and the objective to model.

Related

source
PortfolioOptimisers.WeightFinaliser — Type
abstract type WeightFinaliser <: AbstractAlgorithm

Abstract supertype for the methods that move the weights of an optimisation into their weight bounds.

A subtype runs after the optimisation. It keeps the sum of the weights, and it changes weights that already lie in the bounds not at all.

Interfaces

To add a method, subtype WeightFinaliser and implement the method below.

opt_weight_bounds

  • opt_weight_bounds(wf::MyFinaliser, wb::WeightBounds, w::VecNum) -> VecNum: Moves w into the bounds wb, and keeps the sum of w.

Arguments

  • wf: The concrete subtype instance.
  • wb: The weight bounds. Either bound can be nothing.
  • w: The weights the optimisation produced.

Returns

  • w::VecNum: The repaired weight vector. finalise_weight_bounds then pairs it with a return code.

Related

source
PortfolioOptimisers.set_clustering_weight_finaliser_alg! — Function
set_clustering_weight_finaliser_alg!(model::JuMP.Model,
                                     alg::ErrorWeightFinaliser,
                                     wi::VecNum)

Adds the deviation objective of alg to the weight finalisation model.

opt_weight_bounds adds the weights w, the budget row and the bound rows before it calls this function. A RelativeWeightDeviation divides by wi, so weight_deviation replaces each zero entry of a copy of wi with eps(eltype(wi)). It does not change wi.

JuMP formulation

Variables

  • w: The weights, read from the model.
  • t: The bound on the deviation, created.

Constraints

  • The rows of set_norm_error_epigraph! for the norm alg.alg, which bound the norm of the residual $\boldsymbol{d}$ by $t$. They are unnamed.

Objective

  • Min: $s_o t$. The objective pulls $t$ down, so $t$ equals the norm at the optimum.

Where:

  • $\boldsymbol{w}$: Portfolio weights vector $N \times 1$.
  • $\boldsymbol{w}_{0}$: Portfolio weights vector $N \times 1$ that the optimisation produced, which the finaliser repairs.
  • $\boldsymbol{d}$: The residual of weight_deviation for alg.dev, $\boldsymbol{w} \oslash \tilde{\boldsymbol{w}}_{0} - \boldsymbol{1}$ for a RelativeWeightDeviation, and $\boldsymbol{w} - \boldsymbol{w}_{0}$ for an AbsoluteWeightDeviation.
  • $\tilde{\boldsymbol{w}}_{0}$: $\boldsymbol{w}_{0}$ with each zero entry replaced by eps(eltype(wi)), so that the division is defined.
  • $t$: Bound on the norm of the deviation.
  • $s_o$: Objective scale. It multiplies the objective, so a positive value leaves the argument of the optimum unchanged.
  • $\oslash$: Element-wise division.
  • $\boldsymbol{1}$: Vector of ones.

Arguments

  • model: The JuMP model. It must already hold w and the two scales sc and so.
  • alg: The deviation and its norm.
  • wi: The weights that the optimisation produced.

Returns

  • nothing.

Related

source
PortfolioOptimisers.opt_weight_bounds — Function
opt_weight_bounds(wf::JuMPWeightFinaliser, wb::WeightBounds, wi::VecNum) -> VecNum
opt_weight_bounds(wf::IterativeWeightFinaliser, wb::WeightBounds, w::VecNum) -> VecNum
opt_weight_bounds(wf::EuclideanWeightFinaliser, wb::WeightBounds, w::VecNum) -> VecNum
opt_weight_bounds(wf::EntropicWeightFinaliser, wb::WeightBounds, w::VecNum) -> VecNum

Moves a weight vector into the bounds wb, and keeps the sum of the vector.

Every method returns weights that break no bound unchanged, with no solve. The bounds do not change.

Each method runs the procedure of its finaliser type:

Algorithm

The steps are those of the JuMPWeightFinaliser method.

  1. Return wi unchanged when it breaks no bound.
  2. Build an empty model, and register the scales sc and so of wf.
  3. Add the weights w, the budget row, and a bound row for each bound that is not nothing.
  4. Add the objective of wf.alg with set_clustering_weight_finaliser_alg!.
  5. Solve with the solvers of wf.slv. Return the values of w when the solve succeeds.
  6. Else log a warning, and return the weights of a default IterativeWeightFinaliser for wi.

JuMP formulation

Variables

  • w: The weights, created.

Expressions

  • sc: $s_c$.
  • so: $s_o$.

Constraints

  • An unnamed budget row: $s_c (\boldsymbol{1}^\intercal \boldsymbol{w} - \boldsymbol{1}^\intercal \boldsymbol{w}_{0}) = 0$.
  • An unnamed lower bound row, when wb.lb is not nothing: $s_c (\boldsymbol{w} - \boldsymbol{l}) \geq \boldsymbol{0}$.
  • An unnamed upper bound row, when wb.ub is not nothing: $s_c (\boldsymbol{w} - \boldsymbol{u}) \leq \boldsymbol{0}$.

Where:

  • $\boldsymbol{w}$: Portfolio weights vector $N \times 1$.
  • $\boldsymbol{w}_{0}$: Portfolio weights vector $N \times 1$ that the optimisation produced, which the finaliser repairs.
  • $\boldsymbol{l}$, $\boldsymbol{u}$: Lower and upper weight bounds. An absent bound is dropped from the programme rather than set to an infinity.
  • $s_c$: Constraint scale. It multiplies both sides of a row, so a positive value leaves the feasible set unchanged.
  • $s_o$: Objective scale. It multiplies the objective, so a positive value leaves the argument of the optimum unchanged.
  • $\boldsymbol{1}$: Vector of ones.

Arguments

  • wf: The weight finaliser.
  • wb: The weight bounds. Either bound can be nothing.
  • wi, w: The weights that the optimisation produced.

Returns

  • w::VecNum: The weights in the bounds, or the input when it breaks no bound.

Related

source