Weight finalisers
PortfolioOptimisers.ErrorWeightFinaliser — Type
struct ErrorWeightFinaliser{__T_alg, __T_dev} <: JuMPWeightFinaliserFormulationSelects 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 aRelativeWeightDeviation, and $\boldsymbol{w} - \boldsymbol{w}_{0}$ for anAbsoluteWeightDeviation. - $\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
EuclideanWeightFinaliserfinds 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 theddofof 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()) -> ErrorWeightFinaliserKeywords correspond to the struct's fields.
Validation
- If
algis anLpNorm:alg.p > 1.
Examples
julia> ErrorWeightFinaliser()ErrorWeightFinaliser alg ┼ L1Norm │ ddof ┴ Int64: 0 dev ┴ RelativeWeightDeviation()Related
PortfolioOptimisers.RelativeWeightDeviation — Type
struct RelativeWeightDeviation <: WeightDeviationSelects 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
PortfolioOptimisers.AbsoluteWeightDeviation — Type
struct AbsoluteWeightDeviation <: WeightDeviationSelects 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
PortfolioOptimisers.WeightDeviation — Type
abstract type WeightDeviation <: AbstractAlgorithmAbstract 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 ofxagainst the targetc * w0.
Arguments
dev: The concrete subtype instance.x: The model's vector that tracks the target. It is the weights inJuMPWeightFinaliser, and the money in each position inDiscreteAllocation.w0: The target weights. The method must not change them.c: The scale that turnsw0into the units ofx. It is1inJuMPWeightFinaliser, and the cash of the side inDiscreteAllocation.
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 ofDiscreteAllocation, 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
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 turnsw0into the units ofx.
Returns
RelativeWeightDeviation: $\boldsymbol{x} \oslash (c\, \tilde{\boldsymbol{w}}_{0}) - \boldsymbol{1}$.AbsoluteWeightDeviation: $\boldsymbol{x} - c\, \boldsymbol{w}_{0}$.
Related
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
PortfolioOptimisers.IterativeWeightFinaliser — Type
struct IterativeWeightFinaliser{__T_iter} <: WeightFinaliserMoves 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.
- Return
wunchanged when it breaks no bound. - Read the budget
s1assum(w), and keep the input asw0. Read an absent bound astypeminortypemaxof the element type ofw, which must be infinite, throughabsent_weight_bound. - Clip
wto the bounds. - Mark the free entries
idx, which lie strictly inside their bounds after the clip. - Subtract the mass that the clip added below
lbfrom the mass that it removed aboveub, givingdelta. - When
deltais not zero, adddeltato the free entries, in proportion to their weights. - Multiply
wbys1 / sum(w), which restores the budget. - Stop when
wbreaks no bound. Else repeat from step 3, for at mostiterpasses. - Return
wwhen it is finite and breaks no bound. Else return the Euclidean projection ofw0,euclidean_weight_projection.
Fields
iter: Maximum number of iterations.
Constructors
IterativeWeightFinaliser(; iter::Integer = 100) -> IterativeWeightFinaliserKeywords correspond to the struct's fields.
Validation
iter > 0.
Examples
julia> IterativeWeightFinaliser()IterativeWeightFinaliser iter ┴ Int64: 100Related
PortfolioOptimisers.JuMPWeightFinaliser — Type
struct JuMPWeightFinaliser{__T_slv, __T_sc, __T_so, __T_alg} <: WeightFinaliserMoves 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()) -> JuMPWeightFinaliserKeywords correspond to the struct's fields.
Validation
- If
slvis aVecSlv:!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
PortfolioOptimisers.JuMPWeightFinaliserFormulation — Type
abstract type JuMPWeightFinaliserFormulation <: AbstractAlgorithmAbstract 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 weightsw, the budget row and the bound rows.
Arguments
model: The JuMP model thatopt_weight_boundsbuilds.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 tomodel.
Related
PortfolioOptimisers.WeightFinaliser — Type
abstract type WeightFinaliser <: AbstractAlgorithmAbstract 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: Moveswinto the boundswb, and keeps the sum ofw.
Arguments
wf: The concrete subtype instance.wb: The weight bounds. Either bound can benothing.w: The weights the optimisation produced.
Returns
w::VecNum: The repaired weight vector.finalise_weight_boundsthen pairs it with a return code.
Related
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 normalg.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_deviationforalg.dev, $\boldsymbol{w} \oslash \tilde{\boldsymbol{w}}_{0} - \boldsymbol{1}$ for aRelativeWeightDeviation, and $\boldsymbol{w} - \boldsymbol{w}_{0}$ for anAbsoluteWeightDeviation. - $\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 holdwand the two scalesscandso.alg: The deviation and its norm.wi: The weights that the optimisation produced.
Returns
nothing.
Related
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) -> VecNumMoves 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:
JuMPWeightFinaliser: the programme of itsalg, below. When the solve fails, the method logs a warning and runs the method of a defaultIterativeWeightFinaliser.IterativeWeightFinaliser: the clip and redistribution that its docstring states.EuclideanWeightFinaliser: the Euclidean projection,euclidean_weight_projection.EntropicWeightFinaliser: the entropic projection,entropic_weight_projection, or the Euclidean projection where the entropic one is not defined.
Algorithm
The steps are those of the JuMPWeightFinaliser method.
- Return
wiunchanged when it breaks no bound. - Build an empty model, and register the scales
scandsoofwf. - Add the weights
w, the budget row, and a bound row for each bound that is notnothing. - Add the objective of
wf.algwithset_clustering_weight_finaliser_alg!. - Solve with the solvers of
wf.slv. Return the values ofwwhen the solve succeeds. - Else log a warning, and return the weights of a default
IterativeWeightFinaliserforwi.
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.lbis notnothing: $s_c (\boldsymbol{w} - \boldsymbol{l}) \geq \boldsymbol{0}$. - An unnamed upper bound row, when
wb.ubis notnothing: $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 benothing.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