JuMP Optimiser (b): private API

PortfolioOptimisers.resolve_jump_optimiser — Function
resolve_jump_optimiser(
    opt::JuMPOptimiser,
    rd::ReturnsResult;
    blocks::Tuple = (),
    kwargs...
) -> ResolvedJuMPOptimiser

Resolves 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

  1. Fit the prior pr of opt.pe on rd. Fit the prior of each entry of blocks on its rows with fit_allocation_set_block.
  2. Compose the Investable Mask imsk of the head with distance_reader_entry_mask.
  3. Resolve the fees on the universe of the caller with fees_constraints.
  4. Resolve stage 1 of the block of opt over the universe of the caller, with resolve_constraint_block_names.
  5. Resolve every block through the shared entry resolve_block_entry. The entry intersects the mask with the mask of each entry of blocks. The resolver of the head, resolve_jump_head_block, places the fees on the axes that the mask leaves, reduces the prior, the optimiser and rd to the mask, and resolves stage 2 of the block of opt. The entry resolves each entry of blocks at the mask, and it fits again on a refusal.
  6. 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 with factory, and return the bundle. Its cbr is the block Result of opt when blocks is 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 of opt. Each entry is a Tuple (set, X) or (set, X, pr), as fit_allocation_set_block states. The empty Tuple gives one block.
  • kwargs...: Keyword arguments passed to the centrality and phylogeny constraint estimators of opt.

Validation

Returns

  • jor::ResolvedJuMPOptimiser: The resolved bundle.

Related

source
PortfolioOptimisers.resolve_jump_head_block — Function
resolve_jump_head_block(imsk::Option{BitVector}, opt::JuMPOptimiser,
                        pr::AbstractPriorResult, rd::ReturnsResult, fees, kwargs) -> Tuple

Resolves 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

  1. Reduce the prior, the optimiser and rd to the mask with investable_reduction. The reduction views the block of stage 1, and it declares the Non-Investable Axis on its sets.
  2. Resolve stage 2 of the reduced block with resolve_constraint_block, through distance_reader_call, under the solver and the strict flag of the head.
  3. Place the fees on the axes that the mask leaves with investable_fees_view, and return them with the reduced prior, optimiser and rd.

Arguments

  • imsk: The Investable Mask of the fit, or nothing when 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 of opt, resolved on the universe of the caller, or nothing.
  • kwargs: The keyword arguments of the centrality and phylogeny constraint estimators of opt.

Returns

  • ((fees, pr, opt, rd), (cbr,))::Tuple: The fees, the prior, the optimiser and the returns data at the mask, and the block Result of opt, or the DistanceReaderRefusalError of one of its readers. The builder of the model reads the same returns data, so resolve_jump_optimiser fits the sets of the return terms on them.

Related

source
PortfolioOptimisers.processed_jump_optimiser — Function
processed_jump_optimiser(
    opt::JuMPOptimiser,
    rd::ReturnsResult;
    kwargs...
) -> JuMPOptimiser

Build 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 to resolve_jump_optimiser.

Returns

  • JuMPOptimiser: Optimiser with all estimator slots populated from processed results.

Related

source
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 = ()
) -> Nothing

Run 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.

  1. Each block after the first marks sdp_phylogeny on the weights of the head when its phylogeny plr holds 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 dependent Variance tracking error then takes the semidefinite formulation, as it does under a phylogeny of the head, and it solves.
  2. 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 budget opt.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.
  3. 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 phylogeny plr of the block of the head. A variance also reads the mark sdp_phylogeny that phase 1 of any block sets, mark_sdp_phylogeny!.
  4. The bounds builder set_allocation_risk_return_bounds! adds the risk ceilings r and the return floor ret of each set.
  5. 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 with add_custom_objective_term!, with obj. The block of the head gives the head and attrs, 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 errors tr, which the head binds to its rows, and the scalariser sca of the risk step.
  • attrs::ResolvedJuMPOptimiser: The resolved bundle of resolve_jump_optimiser. The builders read the prior, the fees and the return terms of the bundle, and every constraint, setting and calibrated slot of the ResolvedConstraintBlock in attrs.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), or nothing to skip risk constraints and scalarisation (the RelaxedRiskBudgeting path).
  • 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 of FactorRiskContribution, which maps it to the asset weights: the pseudoinverse of the transposed loadings, followed by the off-factor basis when flag = true. nothing for all other optimisers.
  • blocks: The blocks after the block of the head, the keyword blocks of resolve_jump_optimiser that gave attrs. The empty Tuple gives one block.

Returns

  • nothing. Mutates model in place.

Related

source
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), or nothing to skip this step entirely.
  • optimiser: Dispatch object for set_risk_constraints!.
  • opt::JuMPOptimiser: Supplies the scalariser opt.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 of FactorRiskContribution, which maps it to the asset weights: the pseudoinverse of the transposed loadings, followed by the off-factor basis when flag = true. nothing for all other optimisers.
  • rd: Returns result forwarded as a keyword argument to risk builders.

Returns

  • nothing.

Related

source
PortfolioOptimisers.jump_optimiser_from_attributes — Function
jump_optimiser_from_attributes(
    opt::JuMPOptimiser,
    attrs::ResolvedJuMPOptimiser
) -> JuMPOptimiser

Repackages 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 in attrs.
  • attrs::ResolvedJuMPOptimiser: Pre-computed constraint and prior bundle.

Returns

  • JuMPOptimiser: Optimiser with all estimator slots populated from attrs.

Related

source
PortfolioOptimisers.constraint_block_steps — Function
constraint_block_steps(blocks::Tuple{}, attrs::ResolvedJuMPOptimiser) -> Tuple{}
constraint_block_steps(blocks::Tuple, attrs::ResolvedJuMPOptimiser) -> Tuple

Gives 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 keyword blocks of resolve_jump_optimiser.
  • attrs: The bundle. Its cbr holds the block Result of each entry after the block of the owner.

Returns

  • steps::Tuple: One entry (set, X, pr) for each entry of blocks, or the empty Tuple.

Related

source
PortfolioOptimisers.later_constraint_blocks — Function
later_constraint_blocks(blocks::Tuple{}, attrs::ResolvedJuMPOptimiser) -> Tuple{}
later_constraint_blocks(blocks::Tuple, attrs::ResolvedJuMPOptimiser) -> Tuple

Gives 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 keyword blocks of resolve_jump_optimiser.
  • attrs: The bundle. Its cbr holds the block Result of each entry after the block of the owner.

Returns

  • later::Tuple: One entry (set, cbr, prefix) for each entry of blocks, or the empty Tuple.

Related

source
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.

Each rebuilds through its keyword constructor only when a field changes, so a head with no data benchmark comes back as itself.

Algorithm

  1. A JuMPOptimiser binds opt.tr to rd with bind_data_benchmark, giving tr.
  2. A head binds its est.opt with step 1, giving opt. A RiskJuMPOptimisationEstimator also binds est.r, giving r.
  3. Return the object itself when every bound field is the field it replaces, by ===.
  4. 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

source
PortfolioOptimisers.reader_frames — Method
reader_frames(opt::JuMPOptimiser, path::AbstractString, refit::Bool) -> ReturnsFrames
group_frames(opt::JuMPOptimiser) -> ReturnsFrames
group_frames(est::JuMPOptimisationEstimator) -> ReturnsFrames

Walk 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: true when a regression reader at x_src = nothing in the group fits its regression on the raw returns data. refits_regression finds the value.
  • est: The JuMP head.

Returns

  • fr::ReturnsFrames: The frames of the slots of opt, at path or from the configuration itself, or of the group of est.

Related

source