JuMP Optimiser (b): private API
PortfolioOptimisers.resolve_jump_optimiser — Function
resolve_jump_optimiser(
opt::JuMPOptimiser,
rd::ReturnsResult;
blocks::Tuple = (),
kwargs...
) -> ResolvedJuMPOptimiserResolves a JuMPOptimiser against the returns data rd, to the ResolvedJuMPOptimiser that a JuMP model reads.
The function fits the prior, resolves the fees and the return terms, and resolves the ConstraintBlock of opt in two stages. Stage 1, resolve_constraint_block_names, resolves the names of the block over the universe of the caller. The reduction to the Investable Mask then views the block, the prior and the rows. Stage 2, resolve_constraint_block, resolves the block against the reduced prior and rows, to its ResolvedConstraintBlock. assemble_jump_model! reads the bundle, and the Result of the head stores it in jor, so the resolution runs once for each optimise call.
The entry takes a list of blocks. The block of opt is the first, and the keyword blocks gives the others. Each entry of blocks is the ProgrammeAllocationSet of an online head and the rows X that the head holds, see fit_allocation_set_block. Each block resolves against its own prior on its own rows, because a merge of two blocks changes the moments that their readers and their ceilings read. The Investable Mask of the bundle is the intersection of the masks of every block, so an asset that one block cannot read departs from all of them. The bundle then holds the vector of the block Results in cbr, the block of opt first. The entry takes blocks by name, so the keyword does not reach the readers through kwargs....
A distance reader of a block, its cte or its ple, can refuse an asset that its prior keeps, see DistanceReaderRefusalError. The shared entry resolve_block_entry holds one refusal branch for every reader of every block. The projection programme of a ProgrammeAllocationSet uses the same entry as a bare head. On a refusal, the entry fits again from the same prior results, without that asset. The readers of opt refuse under opt.strict, and the readers of a set refuse under the strict flag of the online head that holds the set, projection_step_strict.
Algorithm
- Fit the prior
profopt.peonrd. Fit the prior of each entry ofblockson its rows withfit_allocation_set_block. - Compose the Investable Mask
imskof the head withdistance_reader_entry_mask. - Resolve the fees on the universe of the caller with
fees_constraints. - Resolve stage 1 of the block of
optover the universe of the caller, withresolve_constraint_block_names. - Resolve every block through the shared entry
resolve_block_entry. The entry intersects the mask with the mask of each entry ofblocks. The resolver of the head,resolve_jump_head_block, places the fees on the axes that the mask leaves, reduces the prior, the optimiser andrdto the mask, and resolves stage 2 of the block ofopt. The entry resolves each entry ofblocksat the mask, and it fits again on a refusal. - Fit the uncertainty set of each return term on the reduced prior and returns data with
ucs_returns_estimator. Resolve the return terms against the prior withfactory, and return the bundle. Itscbris the block Result ofoptwhenblocksis empty, and the vector of every block Result otherwise.
Arguments
opt::JuMPOptimiser: JuMP optimiser configuration.rd: The returns result to use.blocks: The blocks after the block ofopt. Each entry is aTuple(set, X)or(set, X, pr), asfit_allocation_set_blockstates. The emptyTuplegives one block.kwargs...: Keyword arguments passed to the centrality and phylogeny constraint estimators ofopt.
Validation
- The rules of
resolve_constraint_block, such asassert_investable_constraint_widthfor a precomputed constraint. - Under
opt.strict, no distance reader ofoptrefuses an asset. Underprojection_step_strict, no distance reader of a set refuses an asset, and the prior of a set prices every asset that the head keeps. The rules ofdistance_reader_refusal_maskandallocation_set_entry_maskraise otherwise.
Returns
jor::ResolvedJuMPOptimiser: The resolved bundle.
Related
PortfolioOptimisers.resolve_jump_head_block — Function
resolve_jump_head_block(imsk::Option{BitVector}, opt::JuMPOptimiser,
pr::AbstractPriorResult, rd::ReturnsResult, fees, kwargs) -> TupleResolves the block of a JuMP head at the Investable Mask imsk. This is the resolver of the block of the head that resolve_jump_optimiser gives to the shared entry resolve_block_entry.
The entry calls it once on the first fit, and once more on each fit again after a refusal, with the mask of that fit. The block of opt already holds the values of stage 1.
Algorithm
- Reduce the prior, the optimiser and
rdto the mask withinvestable_reduction. The reduction views the block of stage 1, and it declares the Non-Investable Axis on itssets. - Resolve stage 2 of the reduced block with
resolve_constraint_block, throughdistance_reader_call, under the solver and thestrictflag of the head. - Place the fees on the axes that the mask leaves with
investable_fees_view, and return them with the reduced prior, optimiser andrd.
Arguments
imsk: The Investable Mask of the fit, ornothingwhen every asset is investable.opt: The JuMP optimiser, with its block after stage 1.pr: Prior result.rd: The returns result to use.fees: The fees ofopt, resolved on the universe of the caller, ornothing.kwargs: The keyword arguments of the centrality and phylogeny constraint estimators ofopt.
Returns
((fees, pr, opt, rd), (cbr,))::Tuple: The fees, the prior, the optimiser and the returns data at the mask, and the block Result ofopt, or theDistanceReaderRefusalErrorof one of its readers. The builder of the model reads the same returns data, soresolve_jump_optimiserfits the sets of the return terms on them.
Related
PortfolioOptimisers.processed_jump_optimiser — Function
processed_jump_optimiser(
opt::JuMPOptimiser,
rd::ReturnsResult;
kwargs...
) -> JuMPOptimiserBuild a fully-processed JuMPOptimiser from raw configuration and returns data.
Calls resolve_jump_optimiser then repackages the result via jump_optimiser_from_attributes. Used where a processed optimiser is needed for inner sub-problems (e.g. NearOptimalCentering) while the attrs bundle is reused directly by assemble_jump_model!.
Arguments
opt::JuMPOptimiser: Raw optimiser configuration.rd: The returns result to use.kwargs...: Keyword arguments passed toresolve_jump_optimiser.
Returns
JuMPOptimiser: Optimiser with all estimator slots populated from processed results.
Related
PortfolioOptimisers.assemble_jump_model! — Function
assemble_jump_model!(
model::JuMP.Model,
optimiser::JuMPOptimisationEstimator,
opt::JuMPOptimiser,
attrs::ResolvedJuMPOptimiser,
rd::ReturnsResult,
r::Option{<:RM_VecRM} = nothing,
obj::ObjectiveFunction = MinimumRisk(),
b1::Option{<:MatNum} = nothing;
blocks::Tuple = ()
) -> NothingRun the invariant model-assembly sequence shared by all single-JuMP-model optimisers.
Executes the constraint-builder pipeline that sits between the per-optimiser head (weight variables) and tail (objective + solve). The head must have populated Model State (w/k variables) before calling this function. See Model Assembly in GLOSSARY.md and 0008-jump-model-assembly.md.
The middle runs once for each block, through the block builder. The block of the head is the first, and the keyword blocks gives the others, as the head gave them to resolve_jump_optimiser. Each block after the first takes its own namespace, and its owner is its ProgrammeAllocationSet, see later_constraint_blocks.
- Each block after the first marks
sdp_phylogenyon the weights of the head when its phylogenyplrholds a semidefinite phylogeny,mark_sdp_phylogeny!. The mark comes before phase 1 of the head, because a tracking error of the head builds a variance in that phase. A dependentVariancetracking error then takes the semidefinite formulation, as it does under a phylogeny of the head, and it solves. - Phase 1 of each block,
set_block_constraints!, adds the weight bounds, the budgets and every row before the risk step. The block of the head takes the net budgetopt.bgt, the fees and the tracking errors of the head. A block of a set takes no net budget and no fees, and its own tracking errors. - The head adds its fees, its risk measures and its return terms, and marks the objective with
mark_risk_minimised!. The risk measures get the phylogenyplrof the block of the head. A variance also reads the marksdp_phylogenythat phase 1 of any block sets,mark_sdp_phylogeny!. - The bounds builder
set_allocation_risk_return_bounds!adds the risk ceilingsrand the return floorretof each set. - Phase 2 of each block,
set_block_post_risk_constraints!, adds the phylogeny rows and the custom constraints. Each block then adds its custom objective terms withadd_custom_objective_term!, withobj. The block of the head gives the head andattrs, and a block of a set gives the set and the Result of its block.
A frontier corner solves this model again with another objective. Every custom objective term keeps the obj of the assembly, as the penalties do, and counts once in each solve.
The tail of the sequence is assert_frontier_sweep_cap: both frontier registries are complete here and no sweep solve has started, so this is the one point at which the total sweep — the product across every swept return term and every swept risk measure — is in hand and can be capped. assert_frontier_sweep_owner follows it, and refuses a frontier when the optimiser solves its model once.
Arguments
model::JuMP.Model: The JuMP optimisation model.optimiser::JuMPOptimisationEstimator: Dispatch object for risk, tracking, and custom constraint builders, and the owner that the custom objective terms of the head get.opt::JuMPOptimiser: Supplies the tracking errorstr, which the head binds to its rows, and the scalariserscaof the risk step.attrs::ResolvedJuMPOptimiser: The resolved bundle ofresolve_jump_optimiser. The builders read the prior, the fees and the return terms of the bundle, and every constraint, setting and calibrated slot of theResolvedConstraintBlockinattrs.cbr. A Calibration Rule in a norm ceiling or a penalty resolved at stage 2 of the block,resolve_constraint_block, so no builder resolves it here.rd: The returns result to use.r::Option{<:RM_VecRM} = nothing: Risk measure(s), ornothingto skip risk constraints and scalarisation (theRelaxedRiskBudgetingpath).obj::ObjectiveFunction = MinimumRisk(): Objective used by the return constraints, and by the custom objective terms of every block.b1::Option{<:MatNum} = nothing: Basis of the decision vector ofFactorRiskContribution, which maps it to the asset weights: the pseudoinverse of the transposed loadings, followed by the off-factor basis whenflag = true.nothingfor all other optimisers.blocks: The blocks after the block of the head, the keywordblocksofresolve_jump_optimiserthat gaveattrs. The emptyTuplegives one block.
Returns
nothing. Mutatesmodelin place.
Related
PortfolioOptimisers.set_risk_and_scalarise! — Function
set_risk_and_scalarise!(
::Model,
::Nothing,
optimiser,
opt,
pr,
pl,
fees::Union{Nothing, Fees};
...
)
set_risk_and_scalarise!(
::Model,
::Nothing,
optimiser,
opt,
pr,
pl,
fees::Union{Nothing, Fees},
b1::Union{Nothing, AbstractMatrix{<:Union{Number, AbstractJuMPScalar}}};
kwargs...
)
Add risk-measure constraints and scalarise the combined risk expression in model.
One step of assemble_jump_model!, dispatched on r: when r is nothing (e.g. RelaxedRiskBudgeting, whose risk lives in its head) this is a no-op.
This is the one place the fee argument is positional. Every head reaches set_risk_constraints! through it, so a head cannot mis-order the list and lose the fees: unconstrained NearOptimalCentering did exactly that while it inlined the step.
Arguments
model::JuMP.Model: JuMP optimisation model (mutated in place).r: Risk measure(s), ornothingto skip this step entirely.optimiser: Dispatch object forset_risk_constraints!.opt::JuMPOptimiser: Supplies the scalariseropt.sca.pr: Prior result passed to risk builders.pl: Phylogeny result passed to risk builders.fees: Fees result passed to risk builders.b1::Option{<:MatNum} = nothing: Basis of the decision vector ofFactorRiskContribution, which maps it to the asset weights: the pseudoinverse of the transposed loadings, followed by the off-factor basis whenflag = true.nothingfor all other optimisers.rd: Returns result forwarded as a keyword argument to risk builders.
Returns
nothing.
Related
PortfolioOptimisers.jump_optimiser_from_attributes — Function
jump_optimiser_from_attributes(
opt::JuMPOptimiser,
attrs::ResolvedJuMPOptimiser
) -> JuMPOptimiserRepackages a ResolvedJuMPOptimiser into a JuMPOptimiser.
The function maps the fields of the bundle onto the fields of the optimiser: pr onto pe, and fees, ret and sca onto the fields of the same name. It maps the block Result of the owner, owner_block of cbr, onto the block cbe with constraint_block_from_resolved, which holds the rename table of the block (lcsr to lcse, ctr to cte, …). Every other field of opt keeps its value. The list of fields comes from the fields of the bundle, so the function drops no field. The Investable Mask imsk has no field on the optimiser, and the function leaves it out.
near_optimal_centering_setup calls it to build the optimiser of its sub-problems, while it gives the same attrs to assemble_jump_model!. So the resolution runs once, and no sub-problem resolves a slot again. An optimiser holds one block, so the blocks after the first reach a sub-problem as the keyword blocks of the entry, from constraint_block_steps.
Arguments
opt::JuMPOptimiser: Source optimiser supplying solver, scalar settings, and any fields not present inattrs.attrs::ResolvedJuMPOptimiser: Pre-computed constraint and prior bundle.
Returns
JuMPOptimiser: Optimiser with all estimator slots populated fromattrs.
Related
PortfolioOptimisers.constraint_block_steps — Function
constraint_block_steps(blocks::Tuple{}, attrs::ResolvedJuMPOptimiser) -> Tuple{}
constraint_block_steps(blocks::Tuple, attrs::ResolvedJuMPOptimiser) -> TupleGives the blocks after the first of a resolved bundle, as the keyword blocks of a sub-problem on the reduced universe.
A sub-problem of NearOptimalCentering solves on the prior and the rows that the bundle reduced, and its optimiser comes from jump_optimiser_from_attributes. An optimiser holds one block, so this function gives the other blocks to the sub-problem through the keyword of the entry. Each entry holds the set viewed at the Investable Mask, its rows on the mask, and the prior Result of its block, as allocation_set_block_step gives them. So a sub-problem reads the reduced blocks, and it fits no prior of a set again.
Arguments
blocks: The entries that the bundle resolved, in the keywordblocksofresolve_jump_optimiser.attrs: The bundle. Itscbrholds the block Result of each entry after the block of the owner.
Returns
steps::Tuple: One entry(set, X, pr)for each entry ofblocks, or the emptyTuple.
Related
PortfolioOptimisers.later_constraint_blocks — Function
later_constraint_blocks(blocks::Tuple{}, attrs::ResolvedJuMPOptimiser) -> Tuple{}
later_constraint_blocks(blocks::Tuple, attrs::ResolvedJuMPOptimiser) -> TupleGives each block after the first of a resolved bundle, with the set that owns it and the namespace of the block in the model of the head.
A JuMP head adds every block of its bundle to its model, in assemble_jump_model!. The block of the head is the first, and it takes the empty prefix. Block i after it takes the Model State namespace blk_i_, from nested_prefix, so the second block registers its rows under blk_2_. The owner of a later block is its ProgrammeAllocationSet, viewed at the Investable Mask of the bundle with constraint_block_steps. The set holds the risk ceilings r and the return floor ret that the bounds builder adds, the tracking errors of the block, and the owner that its custom constraints and its custom objective terms get.
Arguments
blocks: The entries that the bundle resolved, in the keywordblocksofresolve_jump_optimiser.attrs: The bundle. Itscbrholds the block Result of each entry after the block of the owner.
Returns
later::Tuple: One entry(set, cbr, prefix)for each entry ofblocks, or the emptyTuple.
Related
PortfolioOptimisers.bind_data_benchmark — Method
bind_data_benchmark(opt::JuMPOptimiser, rd::ReturnsResult)
bind_data_benchmark(est::JuMPOptimisationEstimator, rd::ReturnsResult)
bind_data_benchmark(est::RiskJuMPOptimisationEstimator, rd::ReturnsResult)Bind every DataBenchmarkTracking of a JuMP optimiser to the benchmark of the rows it fits on.
Each head calls this function after investable_view, so the benchmark has the rows and the investable columns of the model. Every builder, every corner solve and every risk of a frontier then reads the bound benchmark. The constructor of each holder already refused a data benchmark beside a prior that states x_src = ExcessSource(), see assert_data_benchmark_prior.
- A
JuMPOptimiserbinds its tracking errorstr. - A head binds its
opt. A head with risk measures, aRiskJuMPOptimisationEstimator, also binds itsr.
Each rebuilds through its keyword constructor only when a field changes, so a head with no data benchmark comes back as itself.
Algorithm
- A
JuMPOptimiserbindsopt.trtordwithbind_data_benchmark, givingtr. - A head binds its
est.optwith step 1, givingopt. ARiskJuMPOptimisationEstimatoralso bindsest.r, givingr. - Return the object itself when every bound field is the field it replaces, by
===. - Otherwise rebuild the object with the bound fields through its keyword constructor, with
rebuild_struct.
Arguments
opt,est: The optimiser or the head.rd: The returns result to use.
Returns
- The optimiser or the head with its data benchmarks bound, or itself when it holds none.
Related
PortfolioOptimisers.reader_frames — Method
reader_frames(opt::JuMPOptimiser, path::AbstractString, refit::Bool) -> ReturnsFrames
group_frames(opt::JuMPOptimiser) -> ReturnsFrames
group_frames(est::JuMPOptimisationEstimator) -> ReturnsFramesWalk the readers of a JuMP head, for the warning of a forgotten raw reader and the gap rule of the head.
The group of a JuMP head is the head, the configuration that it holds in opt, and every reader in their slots: the prior opt.pe, the graph readers opt.cte and opt.ple, the regressions of opt.lcse, and the readers inside the risk measures, the tracking errors and the return terms. field_frames walks every field. The walk stops at a fallback, because it is a head with its own group. A configuration that takes an online step with no head answers for its own slots. A regression reader at x_src = nothing counts as raw only when the prior opt.pe gives no loadings, see refits_regression.
Arguments
opt: The configuration of a JuMP head.path: The path of the value from the head, for example"pe","cle"or"r[2].pe". A warning names a reader by its path.refit:truewhen a regression reader atx_src = nothingin the group fits its regression on the raw returns data.refits_regressionfinds the value.est: The JuMP head.
Returns
fr::ReturnsFrames: The frames of the slots ofopt, atpathor from the configuration itself, or of the group ofest.
Related