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.ubof a measure is not a finite non-negative number. AnArgumentErroris thrown.- No field of a measure holds a
ReturnsTracking. AnArgumentErrorthat names the field is thrown otherwise. rsis empty. AnIsEmptyErroris thrown.
Returns
nothing.
Related
ProgrammeAllocationSetset_allocation_risk_ceiling!set_risk_upper_bound!: refuses a frontier or a vector for a set that reaches the builder without this check.returns_tracking_path
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:truewhen the ceiling reads the head's rows.
Related
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
- Ask
rows_neededwhether the set reads the head's rows. It answersnothingwhen a slot reads them. - If no slot reads them, return
nothing. - Check that
Xis notnothing. - Fit
set.peonXwithprior, and return the result.
Arguments
set: The resolved Allocation Set.X: The rows that the head holds, aReturnsResult, ornothingoutside an Online Update.
Validation
- A slot reads the rows and
Xisnothing. AnArgumentErroris thrown. - The rules of
benchmark_relative_returns, under the source ofset.pe.
Returns
pr::Option{<:AbstractPriorResult}: The fitted prior result, ornothing.
Related
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
- Read the Investable Mask of
pr,imsk. - If
imskisnothing, the prior prices every asset: return. - Otherwise, throw an error that names the assets of
X.nxoutsideimsk.
Arguments
pr: The set's prior result, ornothingwhen the set fitted none.X: The rows that the head holds, ornothing.
Validation
prcarries an Investable Mask. AnArgumentErroris thrown, and it names the assets the prior cannot price.
Returns
nothing.
Related
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
- When
pmskisnothing, the prior of the set prices every asset. Returnimsk. - Find the assets that
imskkeeps andpmskleaves out. Anothingmask keeps every asset. When there is none, return the intersection of the two masks. - Refuse the assets under
strict. Otherwise warn, and name them fromX.nx, or by their indices whenXhas no names. - Return the intersection of the two masks.
Arguments
imsk: The Investable Mask of the head and of the blocks before this one, ornothingwhen 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: Thestrictflag of the online head that holds the set,projection_step_strict.
Validation
- Under
strict = true, the prior of the set prices every asset thatimskkeeps. Raises anIsNonFiniteError. - At least one asset stays. Raises an
IsEmptyError.
Returns
imsk::Option{BitVector}: The intersected mask.
Related
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
- When the prior
prof the entry isnothing, returnimsk. - Read the
strictflag of the online head withprojection_step_strict. - Intersect
imskwith the assets thatprprices, withallocation_set_priced_mask. - Compose the result with the assets that a
FeatureDistanceof the readerspleandcteof the set can read,feature_readable_mask, onX. - Compose the result with the assets that a plain graph reader of the set can read,
graph_reader_mask, onprandX, 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, ornothingwhen every asset is investable.b: The fitted entry(set, X, pr), fromfit_allocation_set_block.
Validation
- The rules of
allocation_set_priced_mask,feature_readable_maskandgraph_reader_mask, under thestrictflag of the online head.
Returns
imsk::Option{BitVector}: The intersected mask.
Related
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_priorof the set onX.prisnothingwhen the set reads no rows.
Related
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
- Reduce the set, its rows
Xand its priorprtoimskwithprogramme_investable_reduction. The reduction declares the Non-Investable Axis on thesetsof the set. - Resolve stage 2 of the reduced block with
resolve_constraint_block, throughdistance_reader_call. The block reads the solver of the set, and thestrictflag of the online head,projection_step_strict. - Return the block Result, or the refusal.
Arguments
b: The fitted entry(set, X, pr), fromfit_allocation_set_block.imsk: The Investable Mask of the entry, ornothingwhen every asset is investable.
Validation
- The rules of
resolve_constraint_block.
Returns
cbr::Union{ResolvedConstraintBlock, DistanceReaderRefusalError}: The block Result, or the refusal of a distance reader.
Related
PortfolioOptimisers.resolve_block_entry — Function
resolve_block_entry(f, args::Tuple, imsk::Option{BitVector}, blocks::Tuple,
rd::ReturnsResult, strict::Bool;
rmsk::Option{BitVector} = nothing) -> TupleResolves 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
- On the first fit, intersect
imskwith the mask of each entry ofblocks,allocation_set_entry_mask. On a fit again, takermsk. - Resolve the block of the head with
f(imsk, args...). Resolve each entry ofblocksat the mask withresolve_allocation_set_block. - If a block gives a
DistanceReaderRefusalError, take thestrictflag of its owner:strictfor the block of the head, andprojection_step_strictfor 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 ofdistance_reader_refusal_mask, and return its value. - 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 offafter the mask.imsk: The Investable Mask of the head, ornothingwhen every asset is investable.blocks: The fitted entries(set, X, pr)of the sets, fromfit_allocation_set_block.rd: The rows of the head on its full universe, read for the asset names of a refusal.strict: Thestrictflag of the readers of the block of the head.rmsk: The mask of a fit again after a refusal, ornothingon the first fit.
Validation
- The rules of
allocation_set_entry_maskanddistance_reader_refusal_mask.
Returns
(imsk, head, cbrs)::Tuple: The Investable Mask of the entry, the values thatfgave for the head, and theTupleof the block Results, the block of the head first.
Related
PortfolioOptimisers.no_head_block — Function
no_head_block(imsk::Option{BitVector}) -> TupleThe resolver of the block of a bare head, for resolve_block_entry. A bare head holds no block of its own, so the function gives no values of the head and no block Result.
Returns
(nothing, ())::Tuple.
Related
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
- View the set and its rows
Xatimskwithprogramme_investable_reduction, with no prior. The block Result already holds the reduced prior. - Put the resolved slots of
cbrinto the block of the viewed set withconstraint_block_from_resolved. - 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, ornothingwhen every asset is investable.
Returns
(set, X, pr)::Tuple: The entry for the sub-problem.
Related
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:
- Wrap
rin a vector and call the vector method.
For a vector and a prior result:
- Resolve each measure against
prwithfactoryandset.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. - Clear the measure's
rkewithno_risk_expr_risk_measure, so its expression joins no objective. The measure'sscaleweights its expression only in the objective, so a ceiling ignores it. - Call
set_risk_constraints!on the vector of ceilings, with the set as owner,pr,plandprefix.
For a vector and no prior result:
- For each measure at index
i, clear itsrke, as above. - Call the index-aware
set_risk_constraints!ati, with the set as owner,pr = nothing,plandprefix.
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, ornothingwhen the set reads no rows.pl: The set's resolved phylogeny constraints, ornothing.prefix: The Model State namespace of the entries,Symbol("")on the bare projection model.
Returns
nothing.
Related
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
- Bind each
DataBenchmarkTrackingof the ceilings to the benchmark of the rowscbr.rd, and add the ceilings withset_allocation_risk_ceiling!. - Resolve the floor against the prior
cbr.prwithfactory, and add it withset_allocation_return_floor!, with the rows.
Arguments
model::JuMP.Model: The JuMP optimisation model.set: The programme set, afterfactory(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
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, ornothingwhen the set reads no rows.
Returns
rc::Option{<:LinearConstraint}: The resolved rows, ornothingwhenr.rcisnothing.
Related
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_tolerancegives for the element type of $\boldsymbol{w}$, which is $\sqrt{\epsilon}$ for a floating-point type and zero for an exact type such asRational. - $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'sprojectchecks the sign.
Returns
w'::Vector:wwith every entry at or below $\tau$ set to its floor, in the element type ofwwhenlbhas that type.
Related
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.lbof a term isnothingor a number. AnArgumentErroris thrown otherwise.
Returns
nothing.
Related
ProgrammeAllocationSetassert_risk_ceilingset_return_bounds!assert_frontier_sweep_owner: the same refusal for an optimiser that solves its model once.