Allocation risk ceiling: private API

PortfolioOptimisers.assert_risk_ceiling — Function
assert_risk_ceiling(r::Nothing)
assert_risk_ceiling(r::RiskMeasure)
assert_risk_ceiling(rs::VecRM)

Refuses a risk measure that cannot be the ceiling of a ProgrammeAllocationSet.

The ceiling of a measure is its settings.ub, and a one-step projection can bound the measure by one number only. The function refuses a measure with no ub, with a Frontier or with a per-asset vector, and it refuses an empty vector of measures. A set with no measure passes.

The ceiling reads every row that the head holds, and those rows change at every step. A ReturnsTracking series is fixed at construction, so it cannot follow them, and the function refuses a measure that holds one. A WeightsTracking benchmark reads the rows themselves and passes.

Arguments

  • r: The set's risk measure, nothing, or a vector of measures.

Validation

  • settings.ub of a measure is not a finite non-negative number. An ArgumentError is thrown.
  • No field of a measure holds a ReturnsTracking. An ArgumentError that names the field is thrown otherwise.
  • rs is empty. An IsEmptyError is thrown.

Returns

  • nothing.

Related

source
PortfolioOptimisers.risk_reads_rows — Function
risk_reads_rows(r::Nothing)
risk_reads_rows(r::Variance)
risk_reads_rows(r::StandardDeviation)
risk_reads_rows(r::RiskMeasure)
risk_reads_rows(rs::VecRM)

Tells whether a programme set's ceiling reads the head's rows.

A Variance or a StandardDeviation that holds its covariance matrix reads no rows. A variance with risk-contribution rows in rc is the exception: the shared semidefinite builder resolves those rows against a prior, so it reads them. Every other measure is built on a prior fitted on the rows, so it reads them too. A vector reads the rows when one of its members does.

Arguments

  • r: The set's risk measure, nothing, or a vector of measures.

Returns

  • flag::Bool: true when the ceiling reads the head's rows.

Related

source
PortfolioOptimisers.allocation_set_prior — Function
allocation_set_prior(set::ProgrammeAllocationSet, X::Option{<:ReturnsResult})

Fits the prior result that a programme set's row-reading slots are built on.

The set fits its pe on the rows that the head holds, the same way a batch head fits a prior on any returns data. The prior reads its own source, whatever the source of the head's step is. When it states x_src = ExcessSource() the fit reads X - B, which benchmark_relative_returns gives. The fit reads the Asset Panel beside the rows, so the result answers NaN at an asset outside the prior's Coverage Universe. A set that reads no rows fits nothing. A BoundedAllocationSet reads no rows, so no caller asks it for a prior.

Algorithm

  1. Ask rows_needed whether the set reads the head's rows. It answers nothing when a slot reads them.
  2. If no slot reads them, return nothing.
  3. Check that X is not nothing.
  4. Fit set.pe on X with prior, and return the result.

Arguments

  • set: The resolved Allocation Set.
  • X: The rows that the head holds, a ReturnsResult, or nothing outside an Online Update.

Validation

  • A slot reads the rows and X is nothing. An ArgumentError is thrown.
  • The rules of benchmark_relative_returns, under the source of set.pe.

Returns

  • pr::Option{<:AbstractPriorResult}: The fitted prior result, or nothing.

Related

source
PortfolioOptimisers.assert_set_prior_priced — Function
assert_set_prior_priced(pr::Nothing, X)
assert_set_prior_priced(pr::AbstractPriorResult, X::Nothing)
assert_set_prior_priced(pr::AbstractPriorResult, X::ReturnsResult)

Refuses a programme set prior that cannot price an asset the model trades, and names the asset.

The direct call of set_allocation_set_constraints! calls it, because its model has a fixed width. A young asset that the model trades can have no price in the set's prior, when the set's pe is plain. Its ceiling would then carry NaN, so the check refuses it here, before the model reaches the solver. The projection programme and the leader re-solve of FollowTheLeader do not call it. Each one resolves the set through the shared entry, which drops such an asset with the warning of allocation_set_priced_mask.

Algorithm

  1. Read the Investable Mask of pr, imsk.
  2. If imsk is nothing, the prior prices every asset: return.
  3. Otherwise, throw an error that names the assets of X.nx outside imsk.

Arguments

  • pr: The set's prior result, or nothing when the set fitted none.
  • X: The rows that the head holds, or nothing.

Validation

  • pr carries an Investable Mask. An ArgumentError is thrown, and it names the assets the prior cannot price.

Returns

  • nothing.

Related

source
PortfolioOptimisers.allocation_set_priced_mask — Function
allocation_set_priced_mask(imsk::Option{BitVector}, pmsk::Nothing, X::ReturnsResult, strict::Bool)
allocation_set_priced_mask(imsk::Option{BitVector}, pmsk::BitVector, X::ReturnsResult, strict::Bool)

Intersects the Investable Mask of a JuMP head with the assets that the prior of a block of a set prices.

The prior of a set reads the rows of the online head, and the prior of the head reads its own rows. A young asset that the head keeps can then have no price in the prior of the set, when the pe of the set is plain and the prior of the head is mask-aware. A ceiling, a floor or a tracking error of the set would read NaN at that asset. So the asset departs from every block, as an asset that a distance reader refuses departs, see distance_reader_refusal_mask. The function warns once, and it names the assets and the remedies. Under strict it refuses them. An asset that the head already left out raises no warning.

Algorithm

  1. When pmsk is nothing, the prior of the set prices every asset. Return imsk.
  2. Find the assets that imsk keeps and pmsk leaves out. A nothing mask keeps every asset. When there is none, return the intersection of the two masks.
  3. Refuse the assets under strict. Otherwise warn, and name them from X.nx, or by their indices when X has no names.
  4. Return the intersection of the two masks.

Arguments

  • imsk: The Investable Mask of the head and of the blocks before this one, or nothing when every asset is investable.
  • pmsk: The Investable Mask of the prior of the set, investable_mask.
  • X: The rows of the set, read for the asset names.
  • strict: The strict flag of the online head that holds the set, projection_step_strict.

Validation

  • Under strict = true, the prior of the set prices every asset that imsk keeps. Raises an IsNonFiniteError.
  • At least one asset stays. Raises an IsEmptyError.

Returns

  • imsk::Option{BitVector}: The intersected mask.

Related

source
PortfolioOptimisers.allocation_set_entry_mask — Function
allocation_set_entry_mask(imsk::Option{BitVector}, b::Tuple{ProgrammeAllocationSet, ReturnsResult, Nothing})
allocation_set_entry_mask(imsk::Option{BitVector}, b::Tuple{ProgrammeAllocationSet, ReturnsResult, AbstractPriorResult})

Intersects the Investable Mask of a JuMP head with the mask of a block of a set, at the entry of the head.

The shared entry resolve_block_entry folds the function over the entries of its blocks. A JuMP head first composes the mask of its own block with distance_reader_entry_mask, in resolve_jump_optimiser. The bare head of the projection programme of project starts from the mask of the prior of its set, so the set prices every asset that the bare head keeps, and no asset raises the warning of allocation_set_priced_mask. The mask of the block of a set follows the same rules as the mask of the head, on the prior and the rows of the set. So an asset that one block cannot read departs from every block. A set that reads no rows fits no prior and has no distance reader, so its block keeps the mask.

Algorithm

  1. When the prior pr of the entry is nothing, return imsk.
  2. Read the strict flag of the online head with projection_step_strict.
  3. Intersect imsk with the assets that pr prices, with allocation_set_priced_mask.
  4. Compose the result with the assets that a FeatureDistance of the readers ple and cte of the set can read, feature_readable_mask, on X.
  5. Compose the result with the assets that a plain graph reader of the set can read, graph_reader_mask, on pr and X, and return it. Its warning names the Allocation Set as the owner of the reader.

Arguments

  • imsk: The Investable Mask of the head and of the blocks before this one, or nothing when every asset is investable.
  • b: The fitted entry (set, X, pr), from fit_allocation_set_block.

Validation

Returns

  • imsk::Option{BitVector}: The intersected mask.

Related

source
PortfolioOptimisers.fit_allocation_set_block — Function
fit_allocation_set_block(b::Tuple{ProgrammeAllocationSet, ReturnsResult})
fit_allocation_set_block(b::Tuple{ProgrammeAllocationSet, ReturnsResult, Option{<:AbstractPriorResult}})

Fits the prior of an entry of the keyword blocks of resolve_jump_optimiser, and gives the entry with its prior.

An entry is the block of a ProgrammeAllocationSet beside the block of a JuMP head, or the one block of the bare head of the projection programme of project. It is the set after stage 1, resolve_allocation_set, and after factory(set, w), with the rows X that the online head holds. The set reads its risk ceilings r, its return floor ret and the slots of its block against its own prior on X, so the entry carries the rows and no Result of a step lives in an estimator. An entry with a third value carries the prior result of the set already. The entry of a fit again after a refusal has one, and so has an entry for a sub-problem, from allocation_set_block_step. The function fits nothing for such an entry.

Arguments

  • b: The entry, (set, X) or (set, X, pr).

Returns

  • (set, X, pr)::Tuple: The entry with the prior result of the set, allocation_set_prior of the set on X. pr is nothing when the set reads no rows.

Related

source
PortfolioOptimisers.resolve_allocation_set_block — Function
resolve_allocation_set_block(
    b::Tuple{ProgrammeAllocationSet, ReturnsResult, Union{Nothing, AbstractPriorResult}},
    imsk::Union{Nothing, BitVector}
) -> Union{DistanceReaderRefusalError, 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 the block of a set at the Investable Mask of a head, to its ResolvedConstraintBlock, or to the refusal of one of its distance readers.

The shared entry resolve_block_entry calls it for each entry of its blocks, after the mask holds the masks of every block. The head is a JuMP head, resolve_jump_optimiser, or the bare head of the projection programme of project. The block resolves against the prior of the set on the rows of the set, and not against the prior of the head. A distance reader of the set can still refuse an asset that the prior of the set keeps. The function then returns the DistanceReaderRefusalError, and the one refusal branch of the entry fits again without the asset.

Algorithm

  1. Reduce the set, its rows X and its prior pr to imsk with programme_investable_reduction. The reduction declares the Non-Investable Axis on the sets of the set.
  2. Resolve stage 2 of the reduced block with resolve_constraint_block, through distance_reader_call. The block reads the solver of the set, and the strict flag of the online head, projection_step_strict.
  3. Return the block Result, or the refusal.

Arguments

  • b: The fitted entry (set, X, pr), from fit_allocation_set_block.
  • imsk: The Investable Mask of the entry, or nothing when every asset is investable.

Validation

Returns

  • cbr::Union{ResolvedConstraintBlock, DistanceReaderRefusalError}: The block Result, or the refusal of a distance reader.

Related

source
PortfolioOptimisers.resolve_block_entry — Function
resolve_block_entry(f, args::Tuple, imsk::Option{BitVector}, blocks::Tuple,
                    rd::ReturnsResult, strict::Bool;
                    rmsk::Option{BitVector} = nothing) -> Tuple

Resolves every block of a head at its entry, with one refusal branch for the readers of every block. This is the shared entry for a list of blocks.

Two heads call it. resolve_jump_optimiser passes the block of a JuMP head as the first block, and the blocks of the sets after it. The projection programme of project is a bare head: it holds no block of its own, and it passes the block of its set alone, on the rows of the step. The function f resolves the block of the head at a mask. It takes the mask and args..., and it returns the values of the head and a Tuple of the Results of its blocks, one Result or none. no_head_block is the f of a bare head. The function takes f and its arguments, not a closure, as distance_reader_call does, so a variable of the entry that it reads is not boxed.

A distance reader of a block, its cte or its ple, can refuse an asset that its prior keeps, see DistanceReaderRefusalError. The function then fits again without that asset, with the mask of distance_reader_refusal_mask in rmsk, from the same prior results. That mask already holds the masks of every block, so no mask warns a second time. Two readers can refuse different assets, and the fit again meets the refusal of the other one. The first refusal in the order of the blocks wins.

Algorithm

  1. On the first fit, intersect imsk with the mask of each entry of blocks, allocation_set_entry_mask. On a fit again, take rmsk.
  2. Resolve the block of the head with f(imsk, args...). Resolve each entry of blocks at the mask with resolve_allocation_set_block.
  3. If a block gives a DistanceReaderRefusalError, take the strict flag of its owner: strict for the block of the head, and projection_step_strict for the block of a set. The message of the refusal names the owner, the optimiser or the Allocation Set. Fit again from step 1 with the mask of distance_reader_refusal_mask, and return its value.
  4. Return the mask, the values of the head and the Results of every block.

Arguments

  • f: The resolver of the block of the head, f(imsk, args...) -> (head, cbrs::Tuple).
  • args: The arguments of f after the mask.
  • imsk: The Investable Mask of the head, or nothing when every asset is investable.
  • blocks: The fitted entries (set, X, pr) of the sets, from fit_allocation_set_block.
  • rd: The rows of the head on its full universe, read for the asset names of a refusal.
  • strict: The strict flag of the readers of the block of the head.
  • rmsk: The mask of a fit again after a refusal, or nothing on the first fit.

Validation

Returns

  • (imsk, head, cbrs)::Tuple: The Investable Mask of the entry, the values that f gave for the head, and the Tuple of the block Results, the block of the head first.

Related

source
PortfolioOptimisers.allocation_set_block_step — Function
allocation_set_block_step(
    b::Tuple{ProgrammeAllocationSet, ReturnsResult, Vararg},
    cbr::ResolvedConstraintBlock,
    imsk::Union{Nothing, BitVector}
) -> Tuple{Any, ReturnsResult, Any}

Gives an entry of the keyword blocks for a sub-problem on the reduced universe, from the block Result that the entry resolved to.

constraint_block_steps calls it for each block after the first of a bundle. A sub-problem of NearOptimalCentering solves on the reduced prior and rows of the head. So its entry holds the set and the rows viewed at the Investable Mask, the reduced prior of the block, and the resolved slots of the block. The entry then fits no prior again, its mask keeps every asset, and its readers hold their results, so no reader runs again. The risk ceilings r and the return floor ret of the set are viewed at the mask with the rest of the set.

Algorithm

  1. View the set and its rows X at imsk with programme_investable_reduction, with no prior. The block Result already holds the reduced prior.
  2. Put the resolved slots of cbr into the block of the viewed set with constraint_block_from_resolved.
  3. Return the set, the viewed rows and the prior of cbr.

Arguments

  • b: The entry that the bundle resolved, (set, X) or (set, X, pr).
  • cbr: The block Result of the entry.
  • imsk: The Investable Mask of the bundle, or nothing when every asset is investable.

Returns

  • (set, X, pr)::Tuple: The entry for the sub-problem.

Related

source
PortfolioOptimisers.set_allocation_risk_ceiling! — Function
set_allocation_risk_ceiling!(model::JuMP.Model, r::Nothing, set::ProgrammeAllocationSet, pr, pl; prefix::Symbol = Symbol(""))
set_allocation_risk_ceiling!(model::JuMP.Model, r::RiskMeasure, set::ProgrammeAllocationSet, pr, pl; prefix::Symbol = Symbol(""))
set_allocation_risk_ceiling!(model::JuMP.Model, rs::VecRM, set::ProgrammeAllocationSet, pr::Nothing, pl; prefix::Symbol = Symbol(""))
set_allocation_risk_ceiling!(model::JuMP.Model, rs::VecRM, set::ProgrammeAllocationSet, pr::AbstractPriorResult, pl; prefix::Symbol = Symbol(""))

Adds a programme set's risk ceilings to the model, one row block for each measure, at the measure's index.

Each ceiling goes through the measure's own JuMP builder, set_risk_constraints!, with the set as the RiskConstraintOwner. The builder bounds each measure at its settings.ub through set_risk_upper_bound!, and its own # JuMP formulation names the rows. So the set writes the rows that a JuMP optimiser writes for the same bound. A Variance takes the semidefinite formulation under the conditions that select it in a head, sdp_variance_flag!: risk-contribution rows, an earlier variance with such rows on the same weights, or a semidefinite phylogeny of any block on the same weights, which phase 1 of the block marks. Otherwise it takes the second-order cone. The variance marks variance_flag, so a semidefinite phylogeny on the same weights adds no p · tr(W) penalty, as in a head.

The source of the covariance matrix does not change the formulation. With a prior result, each measure is resolved against it first. Without one, every ceiling is a Variance or a StandardDeviation that holds its matrix, on a set that reads no rows, and the builder reads that matrix with pr = nothing.

Under a prefix, the builders put their entries in that namespace. The block builder set_block_constraints! registers the head's w under the prefix before any builder runs. This keeps the ceiling's entries apart from the entries of the head's own measures. The lifted matrix $\mathbf{W}$ and the marks belong to the weights, weights_prefix, so in a leader's model the ceiling, the set's phylogeny and the leader's measures read one $\mathbf{W}$.

Algorithm

For one measure:

  1. Wrap r in a vector and call the vector method.

For a vector and a prior result:

  1. Resolve each measure against pr with factory and set.slv. A moment that the measure holds, such as its own covariance, stays. A cache that the head filled from another prior is not read.
  2. Clear the measure's rke with no_risk_expr_risk_measure, so its expression joins no objective. The measure's scale weights its expression only in the objective, so a ceiling ignores it.
  3. Call set_risk_constraints! on the vector of ceilings, with the set as owner, pr, pl and prefix.

For a vector and no prior result:

  1. For each measure at index i, clear its rke, as above.
  2. Call the index-aware set_risk_constraints! at i, with the set as owner, pr = nothing, pl and prefix.

Arguments

  • model::JuMP.Model: The JuMP optimisation model.
  • r: The set's risk measure, nothing, or a vector of measures.
  • set: The resolved programme Allocation Set.
  • pr: The set's prior result, or nothing when the set reads no rows.
  • pl: The set's resolved phylogeny constraints, or nothing.
  • prefix: The Model State namespace of the entries, Symbol("") on the bare projection model.

Returns

  • nothing.

Related

source
PortfolioOptimisers.set_allocation_risk_return_bounds! — Function
set_allocation_risk_return_bounds!(
    model::Model,
    set::ProgrammeAllocationSet,
    cbr::ResolvedConstraintBlock;
    prefix
)

Adds the risk ceilings r and the return floor ret of a programme set to a model. This is the bounds builder of the set.

r and ret are flat fields of the set and not slots of its ConstraintBlock, because a JuMPOptimiser holds no bound that stands alone. So the block builder set_block_constraints! does not add them, and this builder reads them beside the ResolvedConstraintBlock of the set: its prior cbr.pr, its rows cbr.rd and its phylogeny cbr.plr. The set must come after factory(set, w), so a WeightsTracking benchmark or a TurnoverRiskMeasure reference that is not fixed holds the Price-Adjusted Allocation of the step.

A JuMP head calls it after mark_risk_minimised!, and the projection calls it between the two phases of the block of its set, with no mark. A ceiling clears its rke and a floor clears its rte, so neither joins the risk expression or the return expression of the objective of the owner. The set stays the RiskConstraintOwner of its ceilings. nothing in a field adds nothing.

Algorithm

  1. Bind each DataBenchmarkTracking of the ceilings to the benchmark of the rows cbr.rd, and add the ceilings with set_allocation_risk_ceiling!.
  2. Resolve the floor against the prior cbr.pr with factory, and add it with set_allocation_return_floor!, with the rows.

Arguments

  • model::JuMP.Model: The JuMP optimisation model.
  • set: The programme set, after factory(set, w).
  • cbr: The Result of the block of the set.
  • prefix::Symbol = Symbol(""): Model State namespace of the call. The builder reads the weights under it, and every entry that it registers takes it, so two calls under two prefixes add two sets of rows to one model. The empty default gives the bare names.

Returns

  • nothing.

Related

source
PortfolioOptimisers.risk_contribution_constraints — Method
risk_contribution_constraints(r::Variance, set::ProgrammeAllocationSet, pr::AbstractPriorResult)
risk_contribution_constraints(r::Variance, set::ProgrammeAllocationSet, pr::Nothing)

Resolves the risk-contribution rows of a Variance ceiling on a programme set.

The set resolves r.rc over its own sets, under the strict of the head that runs the step, the same way an optimiser resolves its own rows. When there are rows, the shared builder takes the semidefinite formulation.

Without a prior result the set reads no rows. risk_reads_rows sends a variance with rows to the prior, so r.rc is nothing here, and the method returns it.

Arguments

  • r: The variance ceiling.
  • set: The programme Allocation Set.
  • pr: The set's prior result, or nothing when the set reads no rows.

Returns

  • rc::Option{<:LinearConstraint}: The resolved rows, or nothing when r.rc is nothing.

Related

source
PortfolioOptimisers.clip_at_zero — Function
clip_at_zero(w::AbstractVector, lb = zero(eltype(w)))

Sets every entry of a projection programme's answer at or below the tolerance of its element type to its floor lb, which is zero unless the set states a positive floor.

A geometry whose domain is the non-negative orthant needs this. The solver meets a zero lower bound only to within its tolerance, so a leg that the programme closes comes back slightly above or slightly below zero. The next step forms its raw step multiplicatively from the allocation it holds. It would take log w of a negative number, and an exact zero of the raw step keeps the weight at zero. So the clip reads every entry within the tolerance as zero, whatever the sign of the rounding, and a weight that the set forces to zero is zero after the clip. The tolerance is weights_bound_tolerance: $\sqrt{\epsilon}$ for a floating-point type, which is above the default feasibility tolerance of Clarabel, and zero for a Rational. The clip does not renormalise, so the sum moves by the clipped mass, which is at most $N \tau$. An entry whose floor is positive goes to that floor and not to zero, so the clip keeps a floor at or below $\tau$ that the set states.

Mathematical definition

\[\begin{align} w'_i &= \begin{cases} l_i & w_i \leq \tau\,, \\ w_i & w_i > \tau\,. \end{cases} \end{align}\]

Where:

  • $w_i$: Entry $i$ of the programme's answer.
  • $w'_i$: Entry $i$ of the clipped answer.
  • $l_i$: Entry $i$ of the floor lb, non-negative.
  • $\tau$: The tolerance that weights_bound_tolerance gives for the element type of $\boldsymbol{w}$, which is $\sqrt{\epsilon}$ for a floating-point type and zero for an exact type such as Rational.
  • $N$: Number of assets.

Arguments

  • w: The programme's answer.
  • lb: The floor of the set, a number or a vector, non-negative. A caller's project checks the sign.

Returns

  • w'::Vector: w with every entry at or below $\tau$ set to its floor, in the element type of w when lb has that type.

Related

source
PortfolioOptimisers.assert_return_floor — Function
assert_return_floor(ret::Nothing)
assert_return_floor(ret::JuMPReturnsEstimator)
assert_return_floor(rets::VecJRE)

Refuses a return term whose floor a ProgrammeAllocationSet cannot hold.

The floor of a term is its settings.lb. A Frontier or a vector of floors asks for one allocation at each floor, and a one-step projection returns one allocation. The model would hold the floors in :ret_frontier, and no solve would read them. So the function refuses both forms, as assert_risk_ceiling refuses them for a ceiling. A floor that is nothing or a number passes.

Arguments

  • ret: The return floor of the set, nothing, or a vector of return terms.

Validation

  • settings.lb of a term is nothing or a number. An ArgumentError is thrown otherwise.

Returns

  • nothing.

Related

source