Allocation Set programme: private API
PortfolioOptimisers.calibrated — Function
calibrated(x)
calibrated(x::AbstractVector)Whether a penalty slot or a norm-ceiling slot holds a Calibration Rule.
A Calibration Rule resolves against the prior result, so a calibrated slot reads the head's rows. The test reads the slot itself and every slot of the term it holds, which calibration_slots lists. A vector is calibrated when one of its entries is.
Returns
::Bool:truewhen the slot, or a slot of its term, holds a Calibration Rule.
Related
PortfolioOptimisers.resolve_allocation_set_step — Function
resolve_allocation_set_step(
set::ProgrammeAllocationSet,
w::AbstractVector,
X::Union{Nothing, ReturnsResult},
pr::Union{Nothing, AbstractPriorResult}
) -> Tuple{ProgrammeAllocationSet, ResolvedConstraintBlock{_A, _B, _C, _D, _E, _F, _G, _H, _I, _J, _K, _L, _M, _N, _O, _P, _Q, _R, _S, _T, _U, _V, _W, _X, _Y, _Z, _Z1, Bool} where {_A, _B, _C, _D, _E, _F, _G, _H, _I, _J, _K, _L, _M, _N, _O, _P, _Q, _R, _S, _T, _U, _V, _W, _X, _Y, _Z, _Z1}}
Resolves a programme set for one step of an online head, to the set after factory(set, w) and the ResolvedConstraintBlock of its block.
The direct call of set_allocation_set_constraints! has a model of a fixed width, so it resolves the step here and does not drop an asset. Then add_allocation_set_block! adds the Result with the block builder. The projection programme of project does not call it. It resolves the block through the shared entry of a bare head, resolve_projection_entry, which drops an asset that the prior cannot price or that a reader refuses.
Algorithm
- Check that the prior prices every asset in
Xwithassert_set_prior_priced. - Give the set the Price-Adjusted Allocation
wwithfactory(set, w), so a turnover ceiling, a tracking error, a risk ceiling, a custom constraint and a custom objective term that read the previous weights read the book of the step. - Resolve stage 2 of the block of the set against
prandXwithresolve_constraint_block, under the solver of the set and thestrictflag of the currentProjectionStep. - Check the bounds of the step against the budget of one with
assert_feasible_bounds. A bound that reads the rows resolves only here (bounds_read_rows).
Arguments
set: The programme set, resolved once per fold.w: The Price-Adjusted Allocation the step trades from.X: The rows the head holds through the period, aReturnsResult, ornothing.pr: The set's prior result onX, ornothingwhen the set reads no rows.
Validation
- The rules of
assert_set_prior_priced,resolve_constraint_blockandassert_feasible_bounds.
Returns
(set', cbr)::Tuple: The set afterfactory(set, w), and the Result of its block.
Related
PortfolioOptimisers.add_allocation_set_block! — Function
add_allocation_set_block!(
model::Model,
set::ProgrammeAllocationSet,
cbr::ResolvedConstraintBlock,
prefix::Symbol
)
Adds the block of a programme set to a model with the block builder, and the set's risk ceilings and return floor with its bounds builder.
The set is the owner of its block, so the builder gets no net budget and no fees, as the set had none before the block. The owner of the model writes the budget of one. The bare projection passes the empty prefix Symbol(""). Another prefix puts the rows of the set in that namespace, beside the rows of the owner of the model, as assemble_jump_model! puts a later block under blk_i_.
Algorithm
- Add phase 1 of the block with
set_block_constraints!, with the set as the owner and its tracking errors fromallocation_set_tracking. - Add the risk ceilings and the return floor with
set_allocation_risk_return_bounds!. - Add phase 2 of the block with
set_block_post_risk_constraints!.
Arguments
model::JuMP.Model: The JuMP optimisation model.set: The programme set, afterfactory(set, w).cbr: The Result of its block, fromresolve_allocation_set_step.prefix: The Model State namespace of the block,Symbol("")on the bare projection model.
Returns
nothing.
Related
PortfolioOptimisers.allocation_set_tracking — Function
allocation_set_tracking(tr::Nothing, cbr::ResolvedConstraintBlock)
allocation_set_tracking(tr, cbr::ResolvedConstraintBlock)Binds the tracking errors of a programme set to the rows of its block.
The set comes after factory(set, w), so a benchmark that is not fixed already holds the Price-Adjusted Allocation of the step. The function cuts each benchmark series to the row count of the prior of the block with prefix_tracking_benchmark, and binds each DataBenchmarkTracking to the benchmark of the rows cbr.rd with bind_data_benchmark. The constructor of the set refuses a data benchmark under a prior of the Excess Frame, so a data benchmark binds to the raw rows that the set's prior reads.
Arguments
tr: The tracking errors of the set, ornothing.cbr: The Result of the block of the set.
Returns
tr': The bound tracking errors, ornothing.
Related
PortfolioOptimisers.prefix_tracking_benchmark — Function
prefix_tracking_benchmark(tr, T::Integer)
prefix_tracking_benchmark(tr::TrackingError{<:ReturnsTracking}, T::Integer)
prefix_tracking_benchmark(trs::AbstractVector, T::Integer)Cuts a ReturnsTracking benchmark of a programme set to its first T entries when it is longer.
The head's rows are the first rows of the fold, up to the current period, so a benchmark series stated over the whole fold aligns with them by its first T entries. A benchmark shorter than the rows goes to the builder unchanged, and tracking_benchmark refuses it with an ArgumentError that names the two lengths. A weights benchmark reads the rows themselves and is returned unchanged. A vector of tracking errors is cut entry by entry.
Arguments
tr: A tracking error, a vector of them, or any other value.T: The row count of the head's rows.
Returns
tr':trwith each returns benchmark cut toTentries.
Related
PortfolioOptimisers.set_allocation_return_floor! — Function
set_allocation_return_floor!(model::JuMP.Model, ret::Nothing, pr; prefix::Symbol = Symbol(""), kwargs...)
set_allocation_return_floor!(model::JuMP.Model, ret::JuMPReturnsEstimator, pr::AbstractPriorResult; prefix::Symbol = Symbol(""), kwargs...)
set_allocation_return_floor!(model::JuMP.Model, rets::VecJRE, pr::AbstractPriorResult; prefix::Symbol = Symbol(""), kwargs...)Adds a programme set's return floor.
For each term, the per-index arm of set_return_constraints! writes the return expression on the prior's expected returns and the row of its settings.lb. The term clears its rte first with no_return_expr_returns_estimator, as a risk ceiling clears its rke, so it adds nothing to ret_vec, the return expression of the objective of the owner. The terms take the indices one to the number of terms under prefix, so in a leader's model they do not replace the head's own. The function does not use a term in the objective, as a scalarised return or the normalisation of a ratio, because the objective of the projection is the geometry's divergence.
Arguments
model::JuMP.Model: The JuMP optimisation model.ret: The return floor, one return estimator, a vector of them, ornothing.pr: The set's prior result.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.kwargs...: Forwarded toset_return_constraints!. The rows that the head holds arrive asrd.
Returns
nothing.
Related
PortfolioOptimisers.set_allocation_set_bounds! — Function
set_allocation_set_bounds!(model::JuMP.Model, wb::WeightBounds)Adds the weight bounds and the budget of one of a BoundedAllocationSet to the bare projection model.
set_weight_constraints! writes the bounds with no net budget, and the function adds Σw = k after that, through set_budget_constraints!. A ProgrammeAllocationSet does not come here: the block builder set_block_constraints! adds its bounds and its short and gross budgets.
Algorithm
- Check the bounds against the budget with
assert_feasible_bounds. - Add the bounds with
set_weight_constraints!, with no net budget. - Add the budget
Σw = kwithset_budget_constraints!.
Arguments
model::JuMP.Model: The JuMP optimisation model.wb: The set's resolvedWeightBounds.
Validation
Σ lb ≤ 1 ≤ Σ ubover the resolved bounds, throughassert_feasible_bounds.
Related
PortfolioOptimisers.set_projection_objective! — Function
set_projection_objective!(model::JuMP.Model, proj::EuclideanProjection, q::AbstractVector)
set_projection_objective!(model::JuMP.Model, proj::EntropicProjection, q::AbstractVector)
set_projection_objective!(model::JuMP.Model, proj::GramProjection, q::AbstractVector)
set_projection_objective!(model::JuMP.Model, proj::DiagonalProjection, q::AbstractVector)
set_projection_objective!(model::JuMP.Model, proj::TsallisProjection, q::AbstractVector)
set_projection_objective!(model::JuMP.Model, proj::LogBarrierProjection, q::AbstractVector)Sets the objective of the projection programme to the geometry's divergence from the raw step q, plus the Objective Penalty.
Each arm writes its divergence $f$ as a conic model and hands it to set_divergence_objective!, which adds the penalty and sets the objective.
Mathematical definition
\[\begin{align} f_{\mathrm{E}}(\boldsymbol{w}) &= \lVert \boldsymbol{w} - \boldsymbol{q} \rVert_2\,, \\ f_{\mathrm{E}}^{\pi}(\boldsymbol{w}) &= \frac{1}{2} \lVert \boldsymbol{w} - \boldsymbol{q} \rVert_2^2\,, \\ f_{\mathrm{G}}(\boldsymbol{w}) &= \lVert \mathbf{G} (\boldsymbol{w} - \boldsymbol{q}) \rVert_2\,, \\ f_{\mathrm{G}}^{\pi}(\boldsymbol{w}) &= \frac{1}{2} \lVert \mathbf{G} (\boldsymbol{w} - \boldsymbol{q}) \rVert_2^2\,, \\ f_{\mathrm{KL}}(\boldsymbol{w}) &= \sum_{i \in P} w_i \log \frac{w_i}{q_i}\,, \\ f_{\alpha}(\boldsymbol{w}) &= \frac{1}{1 - \alpha} \sum_{i \in P} \left( q_i^{\alpha - 1} w_i - \frac{w_i^{\alpha}}{\alpha} \right)\,, \\ f_{\mathrm{IS}}(\boldsymbol{w}) &= \sum_{i \in P} \left( \frac{w_i}{q_i} - \log w_i \right)\,. \end{align}\]
Where:
- $\boldsymbol{w}$: Portfolio weights vector $N \times 1$.
- $\boldsymbol{q}$: Raw step, the vector the rule's unconstrained step gives before the projection onto the Allocation Set.
- $\pi$: Objective Penalty, the sum of the set's penalties and of the other terms added to the objective before it.
- $f_{\mathrm{E}}$, $f_{\mathrm{E}}^{\pi}$: Divergence of
EuclideanProjection, without and with an Objective Penalty. - $f_{\mathrm{G}}$, $f_{\mathrm{G}}^{\pi}$: Divergence of
GramProjectionand ofDiagonalProjection, without and with an Objective Penalty. - $\mathbf{G}$: Upper Cholesky factor of the geometry's Gram matrix $\mathbf{A}$, so $\mathbf{G}^\intercal \mathbf{G} = \mathbf{A}$. Under
DiagonalProjectionit is $\mathrm{diag}(\sqrt{\boldsymbol{h}})$ and $\mathbf{A} = \mathrm{diag}(\boldsymbol{h})$. - $f_{\mathrm{KL}}$: Relative entropy, the divergence of
EntropicProjection. - $f_{\alpha}$: Tsallis divergence, the divergence of
TsallisProjection. - $\alpha$: Power of the Tsallis potential, in $(0, 1)$.
- $f_{\mathrm{IS}}$: Itakura–Saito divergence, the divergence of
LogBarrierProjection. - $P = \{i : q_i > 0\}$: Positive entries of the raw step. Under the entropic, Tsallis and log-barrier geometries every $w_i$ with $i \notin P$ is zero.
- $\Psi$: Potential of the Projection Geometry.
- $D_\Psi$: Bregman divergence of $\Psi$.
Each $f$ differs from the Bregman divergence $D_\Psi(\boldsymbol{w}, \boldsymbol{q})$ of its geometry's potential by a term that is constant in $\boldsymbol{w}$ on the budget $\sum_i w_i = 1$, so each has the minimiser of $D_\Psi$ and a penalty added to it weighs against $D_\Psi$ itself. $f_{\mathrm{E}}^{\pi}$ and $f_{\mathrm{G}}^{\pi}$ are these Bregman divergences, of $\tfrac{1}{2} \lVert \boldsymbol{w} \rVert_2^2$ and $\tfrac{1}{2} \boldsymbol{w}^\intercal \mathbf{A} \boldsymbol{w}$. The norm $f_{\mathrm{E}}$ has the same minimiser as $f_{\mathrm{E}}^{\pi}$ when no penalty is present, and $f_{\mathrm{G}}$ has the same minimiser as $f_{\mathrm{G}}^{\pi}$. A penalty $\pi$ added to the norm does not move the minimiser off a feasible $\boldsymbol{q}$ while the dual norm of $\nabla \pi(\boldsymbol{q})$ is at most one, because the subdifferential of a norm at zero is its dual unit ball. Added to the squared norm, it gives the proximal step.
JuMP formulation
Variables
w: read from the model.t_proj: created. It is a scalar under the Euclidean, Gram, diagonal and entropic arms, and a vector with one entry for each index in $P$ under the Tsallis and log-barrier arms.
Constraints
- Euclidean, Gram and diagonal arms: the row of
set_distance_cone!on $\boldsymbol{x} = s_c (\boldsymbol{w} - \boldsymbol{q})$ or $\boldsymbol{x} = s_c \mathbf{G} (\boldsymbol{w} - \boldsymbol{q})$. - Entropic arm,
proj_zero: $s_c w_i = 0$ for each $i \notin P$, when such an $i$ exists. - Entropic arm,
proj_rec: $s_c t \geq \sum_{i \in P} s_c w_i \log (w_i / q_i)$, the relative entropy cone over $(s_c t, s_c \boldsymbol{q}_P, s_c \boldsymbol{w}_P)$. - Tsallis arm, under no name: $t_j \leq w_j^{\alpha}$ for each $j \in P$, the power cone of power $\alpha$ over $(s_c w_j, s_c, s_c t_j)$.
- Log-barrier arm, under no name: $t_j \leq \log w_j$ for each $j \in P$, the exponential cone over $(s_c t_j, s_c, s_c w_j)$.
- Tsallis and log-barrier arms: the rows of
barrier_objective_entries, which fix $w_i = 0$ for each $i \notin P$.
The divergence each arm hands to set_divergence_objective! is $t$ under the Euclidean, Gram, diagonal and entropic arms, $\frac{1}{1 - \alpha} \left( \sum_{j \in P} q_j^{\alpha - 1} w_j - \frac{1}{\alpha} \sum_{j \in P} t_j \right)$ under the Tsallis arm, and $\sum_{j \in P} w_j / q_j - \sum_{j \in P} t_j$ under the log-barrier arm.
Where:
- $s_c$: Constraint scale. It multiplies both sides of a row, so a positive value leaves the feasible set unchanged.
- $t$, $t_j$: The entries of
t_proj. - $\boldsymbol{q}_P$, $\boldsymbol{w}_P$: The entries of $\boldsymbol{q}$ and $\boldsymbol{w}$ at the indices in $P$.
Arguments
model::JuMP.Model: The JuMP optimisation model.proj: The Projection Geometry.q: The raw step.
Validation
- Under
EntropicProjection,TsallisProjectionandLogBarrierProjection:all(>= 0, q)andsum(q) > 0. ADomainErroris thrown otherwise. - Under
GramProjection:proj.Ais notnothing. AnArgumentErroris thrown otherwise: the rule binds the matrix. - Under
GramProjection:proj.Ais positive definite. ALinearAlgebra.PosDefExceptionis thrown otherwise. A singular Gram matrix states a seminorm, in which the projection is not unique.NewtonStepbinds $\mathbf{I} + \sum_{s} \boldsymbol{g}_s \boldsymbol{g}_s^\intercal$, which is positive definite.
Related
PortfolioOptimisers.set_distance_cone! — Function
set_distance_cone!(model::Model, t, x, sc)
Bounds a projection's distance variable t below by the norm of the scaled deviation x, or by half its square when the model holds an Objective Penalty.
Without a penalty the function writes the second-order cone. Its minimum is sharp, and the solver finds it to a tight tolerance. With a penalty it writes the rotated second-order cone, because a penalty added to the norm does not move the minimiser off a feasible raw step while its gradient is small, and added to half the square it gives the proximal step. The penalty is present when the set's penalties, a custom objective term or the p · tr(W) term of a semidefinite phylogeny were added before the objective. set_projection_objective! states the two divergences.
JuMP formulation
Variables
t: read. It is the caller's distance variable.
Constraints
proj_soc: $(s_c t, \boldsymbol{x}) \in \mathcal{K}_{\mathrm{SOC}}$, that is $t \geq \lVert \boldsymbol{x} \rVert_2 / s_c$, when the model holds no Objective Penalty.proj_rsoc: $(s_c t, s_c, \boldsymbol{x}) \in \mathcal{K}_{\mathrm{RSOC}}$, that is $t \geq \lVert \boldsymbol{x} \rVert_2^2 / (2 s_c^2)$, when it holds one.
Where:
- $s_c$: Constraint scale. It multiplies both sides of a row, so a positive value leaves the feasible set unchanged.
- $\boldsymbol{x}$: The scaled deviation, $s_c (\boldsymbol{w} - \boldsymbol{q})$ or $s_c \mathbf{G} (\boldsymbol{w} - \boldsymbol{q})$, so the two rows give $t \geq \lVert \boldsymbol{w} - \boldsymbol{q} \rVert_2$ and $t \geq \tfrac{1}{2} \lVert \boldsymbol{w} - \boldsymbol{q} \rVert_2^2$ in the Euclidean geometry.
- $\mathcal{K}_{\mathrm{SOC}} = \{(u, \boldsymbol{v}) : u \geq \lVert \boldsymbol{v} \rVert_2\}$: Second-order cone.
- $\mathcal{K}_{\mathrm{RSOC}} = \{(u, v, \boldsymbol{z}) : 2 u v \geq \lVert \boldsymbol{z} \rVert_2^2,\, u \geq 0,\, v \geq 0\}$: Rotated second-order cone.
Arguments
model::JuMP.Model: The JuMP optimisation model.t: The distance variable.x: The scaled deviation, a vector of affine expressions.sc: The constraint scale.
Returns
nothing.
Related
PortfolioOptimisers.set_divergence_objective! — Function
set_divergence_objective!(model::Model, div, so)
Sets the projection programme's objective to the minimum of the geometry's divergence div plus the Objective Penalty, times the objective scale.
The penalty holds the set's penalties, its custom objective terms and the p · tr(W) term of its semidefinite phylogeny. It enters through add_penalty_to_objective!, which every JuMP head's objective also uses. With no penalty the objective is the divergence alone, which is the plain projection of every published rule.
JuMP formulation
Expressions
obj_expr: $d + \pi$. The function registers $d$ first and then adds the model'sopwhen it holds one.
Objective
Min: $s_o$ timesobj_expr.
Where:
- $d$: The divergence
divof the geometry. - $\pi$: The Objective Penalty
op, zero when the model holds none. - $s_o$: Objective scale. It multiplies the objective, so a positive value leaves the argument of the optimum unchanged.
Arguments
model::JuMP.Model: The JuMP optimisation model.div: The divergence, an affine expression or a variable.so: The objective scale.
Returns
nothing.
Related
PortfolioOptimisers.barrier_objective_entries — Function
barrier_objective_entries(
model::Model,
q::AbstractVector
) -> NTuple{4, Any}
Prepares the entries that a barrier objective is written over.
It refuses a raw step with a negative entry or with no positive entry. It fixes the weight of every zero entry of q at zero. It returns the positive indices, the model's w and the two scales.
JuMP formulation
Variables
w: read from the model.
Constraints
- Under no name, one vector row: $s_c w_i = 0$ for each $i$ with $q_i = 0$. A
qwith no zero entry writes no row.
Where:
- $s_c$: Constraint scale. It multiplies both sides of a row, so a positive value leaves the feasible set unchanged.
- $\boldsymbol{q}$: Raw step, the vector the rule's unconstrained step gives before the projection onto the Allocation Set.
Arguments
model::JuMP.Model: The JuMP optimisation model.q: The raw step.
Validation
all(>= 0, q). ADomainErroris thrown otherwise.sum(q) > 0. ADomainErroris thrown otherwise.
Returns
(pos, w, sc, so)::Tuple: The indices of the positive entries ofq, the model'sw, the constraint scale and the objective scale.
Related
PortfolioOptimisers.projection_solver — Function
projection_solver(proj::AbstractProjectionGeometry, set::ProgrammeAllocationSet)
projection_solver(proj::GramProjection, set::AbstractAllocationSet)
projection_solver(proj::GramProjection, set::ProgrammeAllocationSet)
projection_solver(proj::GramProjection, set::BoundedAllocationSet)
projection_solver(proj::AbstractProjectionGeometry, set::BoundedAllocationSet)Returns the solver a projection programme runs on.
A GramProjection carries its own solver, and the programme uses it on every set. Every other geometry uses the programme set's solver. On a BoundedAllocationSet every geometry other than the Gram one is a scalar root with no programme, so the function throws an ArgumentError that names the geometry. project does not call it in that case.
Returns
slv: The solver, or a vector of solvers.
Related
PortfolioOptimisers.programme_answer — Function
programme_answer(proj::AbstractProjectionGeometry, w::AbstractVector, wb::WeightBounds)Returns the answer of a solved projection programme, on the assets of the step.
Under EntropicProjection, TsallisProjection and LogBarrierProjection, clip_at_zero sets every entry within the tolerance of its element type to its floor in wb. Every other geometry returns w. The floor is the floor of the bounds of the step, which set_allocation_set_constraints! returns, so a bound that reads the rows clips at its own floor.
Arguments
proj: The geometry, viewed at the Investable Mask.w: The weights of the solve, on the assets of the mask.wb: The weight bounds of the step, on the same assets.
Returns
w'::AbstractVector: The answer on the assets of the mask.
Related
PortfolioOptimisers.allocation_set_ready — Function
allocation_set_ready(set::ProgrammeAllocationSet, X::Option{<:ReturnsResult})Tells whether the set's constraints can be built on the rows X of the step.
A programme set that fits its prior on the rows cannot be built while the head holds fewer than two rows, because a covariance of one observation does not exist. A bounded set reads no rows, so project does not call the function for it.
Returns
reason:nothingwhen the constraints can be built, and otherwise the reason for the Held Step as aString.
Related
PortfolioOptimisers.resolve_projection_entry — Function
resolve_projection_entry(set::BoundedAllocationSet, w::AbstractVector, X)
resolve_projection_entry(set::ProgrammeAllocationSet, w::AbstractVector, X::ReturnsResult)
resolve_projection_entry(set::ProgrammeAllocationSet, w::AbstractVector, X::Nothing)Resolves the Allocation Set of a projection programme for one step, through the shared entry of a bare head.
The projection programme holds no block of its own, so it is a bare head of resolve_block_entry, with no_head_block as the resolver of its block. It passes the block of its set as the one block. The set is the owner of the prior of the step, so the mask of that prior is the mask of the bare head, and the set prices every asset that the head keeps. The entry then composes the mask with the readers of the set, resolves the block at the mask, and fits again without an asset that a distance reader of the set refuses, as for the blocks of a JuMP head. A bounded set holds no block and fits no prior, so it resolves to itself. A programme set with no rows, X === nothing outside an Online Update, fits no prior, so it has no mask and runs no reader, and stage 2 of its block resolves alone. allocation_set_prior refuses such a set when a slot reads the rows.
Algorithm
- On a bounded set, return no mask, the set and no block Result. Stop.
- Give the set the Price-Adjusted Allocation
wwithfactory(set, w), so a turnover ceiling, a tracking error, a risk ceiling, a custom constraint and a custom objective term that read the previous weights read the book of the step. - With no rows, resolve the block with
resolve_constraint_blockon no prior, check the bounds withassert_feasible_bounds, and return no mask, the set and the block Result. Stop. - Fit the prior of the set on
Xwithfit_allocation_set_block. - Resolve the block through
resolve_block_entry, from the mask of the prior,investable_mask, under thestrictflag of the step,projection_step_strict. - Check the bounds of the step against the budget of one with
assert_feasible_bounds. A bound that reads the rows resolves only at stage 2 (bounds_read_rows). - View the set at the mask with
programme_investable_reduction, for the builders. Return the mask, the viewed set and the block Result.
Arguments
set: The set, resolved once per fold.w: The Price-Adjusted Allocation the step trades from.X: The rows the head holds through the period, aReturnsResult, ornothing.
Validation
- The rules of
allocation_set_prior,resolve_block_entryandassert_feasible_bounds. - Under the
strictflag of the step, no reader of the set drops an asset. Raises anIsNonFiniteError.
Returns
(imsk, set', cbr)::Tuple: The Investable Mask of the step, the set viewed at it, and theResolvedConstraintBlockof the set, ornothingfor a bounded set.
Related
PortfolioOptimisers.programme_investable_reduction — Function
programme_investable_reduction(imsk::Nothing, set::AbstractAllocationSet, X::Option{<:ReturnsResult}, pr)
programme_investable_reduction(imsk::BitVector, set::AbstractAllocationSet, X::ReturnsResult, pr::Option{<:AbstractPriorResult})
programme_investable_reduction(imsk::BitVector, set::AbstractAllocationSet, X, pr)Reduces the set, the rows that the head holds and the set's prior to the Investable Mask of the entry, the intersection of the masks of every block.
The projection programme then runs on the assets the prior can price, as a batch head does with investable_reduction. The shared entry reduces the block of a set to the mask of every block in this way, resolve_allocation_set_block, and resolve_projection_entry views the set for the builders of the projection. The projection views the raw step at the same mask with investable_geometry_view.
Dispatch selects one of three methods. A nothing mask means that every asset is investable, which is true at every step on a static panel and at every step of a set that reads no rows. That method returns its arguments unchanged. The BitVector method takes the views at findall(imsk). A set that reads no rows has no prior, and the method views the set and the rows alone. This pair occurs at the entry of a JuMP head, whose blocks give the mask. The third method refuses a mask with no rows, because a mask is read on the rows. The set is viewed against the full returns matrix of the rows, because a view of a tracking estimator needs it. After the view, the method declares the names outside the mask on the Non-Investable Axis of the set's sets, with non_investable_universe, as investable_reduction does for a head. So a row of lcse or gcarde that names such an asset drops at stage 2 of the block, and strict does not refuse the name. The Price-Adjusted Allocation is cut to the mask and is not renormalised, as the batch reduction cuts a turnover reference. So an asset the prior cannot price leaves the reference, and the programme allocates the budget of one over the investable assets. The function writes no warning for such an asset, because the Investable Mask of the Recursion Result already shows it at every step.
Validation
- A mask with no rows. An
IsNothingErroris thrown.
Returns
(set, X, pr)::Tuple: The three reduced to the mask, or unchanged.prstaysnothingwhen the set has no prior.
Related
PortfolioOptimisers.investable_geometry_view — Function
investable_geometry_view(imsk::Nothing, proj::AbstractProjectionGeometry, q::AbstractVector)
investable_geometry_view(imsk::BitVector, proj::AbstractProjectionGeometry, q::AbstractVector)
investable_geometry_view(imsk::BitVector, proj::DiagonalProjection, q::AbstractVector)
investable_geometry_view(imsk::BitVector, proj::GramProjection{<:Any, <:AbstractMatrix}, q::AbstractVector)Reduces the Projection Geometry and the raw step q to the Investable Mask of a projection programme.
The projection programme of project solves over the assets in the mask, and gives a zero weight to every other asset. A nothing mask returns both arguments unchanged. A geometry whose divergence is a sum of one term for each asset needs only the view of q, because the term of an asset outside the mask is a constant at its zero weight. DiagonalProjection is such a sum, and its diagonal is viewed with q. The norm of a GramProjection couples the assets, so the zero weights move the point that the reduced programme projects.
Mathematical definition
Let $P$ be the assets in the mask and $Z$ the others, with $\boldsymbol{w}_Z = \boldsymbol{0}$. Then
\[\begin{align} (\boldsymbol{w} - \boldsymbol{q})^\intercal \mathbf{A} (\boldsymbol{w} - \boldsymbol{q}) &= (\boldsymbol{w}_P - \tilde{\boldsymbol{q}}_P)^\intercal \mathbf{A}_{PP} (\boldsymbol{w}_P - \tilde{\boldsymbol{q}}_P) + c\,, \\ \tilde{\boldsymbol{q}}_P &= \boldsymbol{q}_P + \mathbf{A}_{PP}^{-1} \mathbf{A}_{PZ} \boldsymbol{q}_Z\,. \end{align}\]
Where:
- $\boldsymbol{w}$: Portfolio weights vector $N \times 1$.
- $\boldsymbol{q}$: Raw step, the vector the rule's unconstrained step gives before the projection onto the Allocation Set.
- $\mathbf{A}$: Gram matrix of the geometry, positive definite.
- $\mathbf{A}_{PP}$, $\mathbf{A}_{PZ}$: Blocks of $\mathbf{A}$ at the rows $P$ and the columns $P$ and $Z$. $\mathbf{A}_{PP}$ is positive definite, because $\mathbf{A}$ is.
- $\tilde{\boldsymbol{q}}_P$: Raw step of the reduced programme.
- $c$: Term that does not depend on $\boldsymbol{w}_P$.
So the reduced Gram geometry holds $\mathbf{A}_{PP}$ and projects $\tilde{\boldsymbol{q}}_P$. The Gram method reads a bound matrix. NewtonStep, the one rule that takes a GramProjection, binds the matrix before the view through gram_geometry.
Returns
(proj, q)::Tuple: The geometry and the raw step on the assets in the mask.
Related
PortfolioOptimisers.solve_projection_programme! — Function
solve_projection_programme!(model::JuMP.Model, proj::AbstractProjectionGeometry, q::AbstractVector, slv::Slv_VecSlv)
solve_projection_programme!(model::JuMP.Model, proj::DiagonalProjection, q::AbstractVector, slv::Slv_VecSlv)Solves a projection programme, and picks one minimiser when the divergence of the geometry has many.
The projection programme of project calls it after it writes the objective. Every geometry except DiagonalProjection has one minimiser, and the function solves the model once with optimise_JuMP_model!. A diagonal with a zero entry is a seminorm, so its minimisers share their weights at the positive entries of the diagonal and differ at the zero entries. After a first solve that succeeds, the diagonal arm then solves a second stage on the same model. Its answer is the limit of the projection in $\mathrm{diag}(\boldsymbol{h} + \delta \boldsymbol{1})$ as $\delta \to 0^{+}$: the minimiser nearest $\boldsymbol{q}$ in the Euclidean norm.
When the second stage fails, the arm returns the weights of the first stage, and the result is a success that holds the trials of the second stage. Those weights are a minimiser of the projection, so the regret bound of AdaptiveSubgradient holds on them. The second stage can fail when its face is one point: under a strictly convex Objective Penalty, or when the budget pins the free weights at their bounds. That point is then the limit. On a face of more than one point, the weights of the first stage are a minimiser that need not be the limit.
JuMP formulation
The second stage of the diagonal arm, when $Z$ is not empty.
Variables
w: read from the model.t_sel: created.
Constraints
proj_face: $s_o \, (d + \pi) \leq v$, when the model holds an Objective Penalty. It keeps the objective of the first stage at its minimum, so the penalty stays at its minimum too. The point of the first stage meets it, so the second stage is feasible to the tolerance of the solver. A slack would let the free weights move along the curve of the penalty by the square root of the slack, so the bound has none.proj_fix: $s_c (w_i - w_i^{(1)}) = 0$ for each $i \in P$.proj_sel: $(s_c t, s_c (\boldsymbol{w}_Z - \boldsymbol{q}_Z)) \in \mathcal{K}_{\mathrm{SOC}}$.
Objective
Min: $s_o t$.
Where:
- $P = \{i : h_i > 0\}$, $Z = \{i : h_i = 0\}$: Assets at the positive and at the zero entries of the diagonal.
- $w_i^{(1)}$: Weight of asset $i$ at the first stage, which every minimiser shares.
- $v$: Objective value of the first stage.
- $d + \pi$: The expression
obj_exprof the first stage, the divergence and the Objective Penalty. - $t$: The variable
t_sel. - $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.
- $\mathcal{K}_{\mathrm{SOC}}$: Second-order cone.
Arguments
model::JuMP.Model: The JuMP optimisation model.proj: The geometry, reduced to the Investable Mask.q: The raw step, reduced to the Investable Mask.slv: The solver of the programme.
Returns
(res, w)::Tuple:res::JuMPResultis the result of the last solve, and a first solve that fails is the last one.w::Option{<:AbstractVector}is the solved allocation, ornothingwhen no solve gives one.
Related
PortfolioOptimisers.projection_scale — Function
projection_scale(set::ProgrammeAllocationSet, f::Symbol)
projection_scale(set::BoundedAllocationSet, f::Symbol)Returns the constraint scale :sc or the objective scale :so that a projection programme registers on its model.
A programme set gives its own field. A bounded set carries no scale, so it gives one.
Related
PortfolioOptimisers.blend_projection — Function
blend_projection(proj::EuclideanProjection, set::BoundedAllocationSet, q::AbstractVector, w::AbstractVector)
blend_projection(proj::EuclideanProjection, set::AbstractAllocationSet, q::AbstractVector, w::AbstractVector)Projects the blend of an ExpertMixture onto the head's set a second time, when the set needs it.
On a BoundedAllocationSet dispatch returns the blend unchanged. The bounds and the budget define a convex set, so a convex blend of allocations in it is in it too, and the projection is the identity. On every other set the function calls project, which gives the repair that a turnover ceiling or a MIP kind needs.
Related
PortfolioOptimisers.assert_leader_keeps_programme_set — Function
assert_leader_keeps_programme_set(opt::JuMPOptimisationEstimator, set::ProgrammeAllocationSet)
assert_leader_keeps_programme_set(opt::NearOptimalCentering, set::ProgrammeAllocationSet)
assert_leader_keeps_programme_set(opt::FactorRiskContribution, set::ProgrammeAllocationSet)Assert that one member of the fallback chain of the held JuMP estimator of a FollowTheLeader rule keeps every constraint of the head's ProgrammeAllocationSet in the model of its answer.
The re-solve passes the set as a later block of the entry, and the rule plays the optimum with no projection at gamma = 0. So the answer of each member must lie in the set. Every JuMP head adds every row of a later block to its model, and two members drop rows of it:
- The centring model of
UnconstrainedNearOptimalCenteringholds the weight bounds and the short and gross budgets of the block alone. So a linear constraint, a ceiling or a turnover of the set would not bind the leader, and the allocation of the head would leave the set. - The rows of a semidefinite phylogeny of the set bind the lift of the asset weights. A
FactorRiskContributionwrites no term on that lift, so the rows bind nothing, as its constructor states foropt.ple.
The configuration alone decides each one, so assert_rule_admits_set calls this function on each member of the chain, and the head refuses the pair at construction, as it refuses the solver-free leader under a programme set. A BoundedAllocationSet holds bounds alone, so it admits every member.
Arguments
opt: The held estimator, or a member of its fallback chain.set: The head's Allocation Set.
Validation
optis not aNearOptimalCenteringunderUnconstrainedNearOptimalCentering. AnArgumentErroris thrown otherwise. UseConstrainedNearOptimalCentering, which adds every row of the set.optis not aFactorRiskContributionwhen thepleofsetholds a semidefinite phylogeny. AnArgumentErroris thrown otherwise.
Returns
nothing.
Related