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: true when the slot, or a slot of its term, holds a Calibration Rule.

Related

source
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

  1. Check that the prior prices every asset in X with assert_set_prior_priced.
  2. Give the set the Price-Adjusted Allocation w with factory(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.
  3. Resolve stage 2 of the block of the set against pr and X with resolve_constraint_block, under the solver of the set and the strict flag of the current ProjectionStep.
  4. 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, a ReturnsResult, or nothing.
  • pr: The set's prior result on X, or nothing when the set reads no rows.

Validation

Returns

  • (set', cbr)::Tuple: The set after factory(set, w), and the Result of its block.

Related

source
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

  1. Add phase 1 of the block with set_block_constraints!, with the set as the owner and its tracking errors from allocation_set_tracking.
  2. Add the risk ceilings and the return floor with set_allocation_risk_return_bounds!.
  3. Add phase 2 of the block with set_block_post_risk_constraints!.

Arguments

  • model::JuMP.Model: The JuMP optimisation model.
  • set: The programme set, after factory(set, w).
  • cbr: The Result of its block, from resolve_allocation_set_step.
  • prefix: The Model State namespace of the block, Symbol("") on the bare projection model.

Returns

  • nothing.

Related

source
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, or nothing.
  • cbr: The Result of the block of the set.

Returns

  • tr': The bound tracking errors, or nothing.

Related

source
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': tr with each returns benchmark cut to T entries.

Related

source
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, or nothing.
  • 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 to set_return_constraints!. The rows that the head holds arrive as rd.

Returns

  • nothing.

Related

source
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

  1. Check the bounds against the budget with assert_feasible_bounds.
  2. Add the bounds with set_weight_constraints!, with no net budget.
  3. Add the budget Σw = k with set_budget_constraints!.

Arguments

  • model::JuMP.Model: The JuMP optimisation model.
  • wb: The set's resolved WeightBounds.

Validation

Related

source
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 GramProjection and of DiagonalProjection, 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 DiagonalProjection it 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, TsallisProjection and LogBarrierProjection: all(>= 0, q) and sum(q) > 0. A DomainError is thrown otherwise.
  • Under GramProjection: proj.A is not nothing. An ArgumentError is thrown otherwise: the rule binds the matrix.
  • Under GramProjection: proj.A is positive definite. A LinearAlgebra.PosDefException is thrown otherwise. A singular Gram matrix states a seminorm, in which the projection is not unique. NewtonStep binds $\mathbf{I} + \sum_{s} \boldsymbol{g}_s \boldsymbol{g}_s^\intercal$, which is positive definite.

Related

source
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

source
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's op when it holds one.

Objective

  • Min: $s_o$ times obj_expr.

Where:

  • $d$: The divergence div of 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

source
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 q with 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). A DomainError is thrown otherwise.
  • sum(q) > 0. A DomainError is thrown otherwise.

Returns

  • (pos, w, sc, so)::Tuple: The indices of the positive entries of q, the model's w, the constraint scale and the objective scale.

Related

source
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

source
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

source
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: nothing when the constraints can be built, and otherwise the reason for the Held Step as a String.

Related

source
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

  1. On a bounded set, return no mask, the set and no block Result. Stop.
  2. Give the set the Price-Adjusted Allocation w with factory(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.
  3. With no rows, resolve the block with resolve_constraint_block on no prior, check the bounds with assert_feasible_bounds, and return no mask, the set and the block Result. Stop.
  4. Fit the prior of the set on X with fit_allocation_set_block.
  5. Resolve the block through resolve_block_entry, from the mask of the prior, investable_mask, under the strict flag of the step, projection_step_strict.
  6. 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).
  7. 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, a ReturnsResult, or nothing.

Validation

Returns

  • (imsk, set', cbr)::Tuple: The Investable Mask of the step, the set viewed at it, and the ResolvedConstraintBlock of the set, or nothing for a bounded set.

Related

source
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 IsNothingError is thrown.

Returns

  • (set, X, pr)::Tuple: The three reduced to the mask, or unchanged. pr stays nothing when the set has no prior.

Related

source
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

source
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_expr of 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::JuMPResult is the result of the last solve, and a first solve that fails is the last one. w::Option{<:AbstractVector} is the solved allocation, or nothing when no solve gives one.

Related

source
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

source
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 UnconstrainedNearOptimalCentering holds 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 FactorRiskContribution writes no term on that lift, so the rows bind nothing, as its constructor states for opt.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

Returns

  • nothing.

Related

source