Constraint Block: private API
PortfolioOptimisers.constraint_block_td_defaults — Function
constraint_block_td_defaults(
) -> @NamedTuple{wb::WeightBounds{Float64, Float64}}
Returns the static defaults of the ConstraintBlock slots that can hold a TimeDependent.
The constructor of the block reads them when it checks each entry of a schedule, and jump_optimiser_td_defaults adds them to the defaults of the owner. A slot whose static default is nothing is not in the tuple.
Returns
NamedTuple: The default ofwb.
Related
PortfolioOptimisers.constraint_block — Function
constraint_block(cbe::Nothing; slots...) -> ConstraintBlock
constraint_block(cbe::ConstraintBlock; slots...) -> ConstraintBlockReturns the ConstraintBlock that the keyword constructor of an owner holds, from the block that the caller gives and the slots that the caller names as flat keywords.
The keyword constructors of JuMPOptimiser and ProgrammeAllocationSet call it. A flat keyword replaces that slot of a given block, and a slot that the caller does not name keeps its value. So the default of a flat keyword never overwrites a slot of a given block. rebuild_struct and Accessors.set pass the block and a new slot in one call, and they rely on this rule.
Algorithm
cbeisnothing: build the block fromslotswith the keyword constructor ofConstraintBlock. A slot thatslotsdoes not name takes its default.slotsis empty: returncbe.- Otherwise rebuild
cbewith the slots inslotsreplaced, withrebuild_struct.
Arguments
cbe: The block that the caller gives, ornothingwhen the caller gives none.slots...: The slots that the caller names, as keywords ofConstraintBlock.
Validation
- A name of
slotsthat is not a slot ofConstraintBlockraises aMethodError, as an unknown keyword of a constructor does.
Returns
cbe::ConstraintBlock: The block of the owner.
Related
PortfolioOptimisers.constraint_block_slots — Function
constraint_block_slots(
cbe::ConstraintBlock
) -> NamedTuple{(:wb, :sbgt, :gbgt, :lt, :st, :lcse, :cte, :gcarde, :sgcarde, :smtx, :sgmtx, :slt, :sst, :sglt, :sgst, :tn, :sets, :tr, :ple, :ccnt, :cobj, :ss, :card, :scard, :l2c, :lpc, :linfc, :l1, :l2, :lp, :linf, :xbgt), <:NTuple{32, Any}}
Returns every slot of a ConstraintBlock as a NamedTuple, in the order of the fields.
The constructor of JuMPOptimiser merges this tuple with its own fields, and checks the schedules of the owner and of its block as flat keywords, see assert_time_dependent_substitution. So a check that reads a field of the owner and a slot of the block runs once for each entry of a schedule in either.
Arguments
cbe::ConstraintBlock: The block.
Returns
NamedTuple: The slots ofcbe, under their field names.
Related
PortfolioOptimisers.shared_pair_view — Function
shared_pair_view(a, b, i) -> Tuple{Any, Any}
Returns the views at i of two slots of a ConstraintBlock that can hold the same object.
A subgroup slot and its subgrouped twin, such as smtx and sgmtx, often hold one object. When they do, the function views it once, so that the two views are one object too, and the check of the shapes of the two slots sees one object.
Arguments
a,b: The values of the two slots.i: The indices of the assets that the view keeps.
Returns
(va, vb)::Tuple: The views ofaandb.
Related
port_opt_view(cbe::ConstraintBlock, i, X)port_opt_view
PortfolioOptimisers.reader_frames — Method
reader_frames(cbe::ConstraintBlock, path::AbstractString, refit::Bool) -> ReturnsFramesWalk the readers in the slots of a ConstraintBlock, for the frame walk of the head that holds it.
The graph readers cte and ple, the regressions of lcse and the readers inside the tracking errors tr belong to the group of the head. So the walk of field_frames enters the block, at the path of its field cbe, as it enters every other field of the owner.
Arguments
cbe::ConstraintBlock: The block.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.
Returns
fr::ReturnsFrames: The frames of the slots ofcbe.
Related
PortfolioOptimisers.AbstractResolved — Type
abstract type AbstractResolved <: AbstractResultAbstract supertype of the data that a resolver gives once for each optimise call.
A subtype holds the results that a configuration resolves to against the prior and the rows of one fit. A builder of the model reads them, and no builder resolves the configuration again. ResolvedConstraintBlock is the Result of one ConstraintBlock, ResolvedJuMPOptimiser is the Result of a JuMP head, and the subtypes of AbstractResolvedRiskBudgeting hold the resolved budget of a risk budgeting model.
Related
PortfolioOptimisers.VecRcb — Type
const VecRcb = AbstractVector{<:ResolvedConstraintBlock}Every abstract vector whose elements are ResolvedConstraintBlocks. A programme with more than one Constraint Block holds one Result for each block.
Related
PortfolioOptimisers.Rcb_VecRcb — Type
const Rcb_VecRcb = Union{ResolvedConstraintBlock, VecRcb}One ResolvedConstraintBlock, or a vector of them. The field cbr of ResolvedJuMPOptimiser takes this type, as plr takes one phylogeny Result or a vector.
Related
PortfolioOptimisers.owner_block — Function
owner_block(cbr::ResolvedConstraintBlock) -> ResolvedConstraintBlock
owner_block(cbr::VecRcb) -> ResolvedConstraintBlockGives the block Result of the owner of a programme, the first block of the programme.
The field cbr of ResolvedJuMPOptimiser holds one block Result, or one for each block when the head has more than one block. The block of the owner is the first. The readers of the bundle that mean the block of the head read it through this function: the forward rule of the bundle, jor.wb, the builders of assemble_jump_model!, and jump_optimiser_from_attributes.
Arguments
cbr: One block Result, or a vector of them with the block of the owner first.
Returns
cbr::ResolvedConstraintBlock: The block Result of the owner.
Examples
julia> pr = prior(EmpiricalPrior(), ReturnsResult(; nx = ["a", "b"], X = [0.1 -0.2; -0.1 0.2; 0.05 0.1]));julia> cbr = PortfolioOptimisers.resolve_constraint_block(ConstraintBlock(), pr, ReturnsResult(; nx = ["a", "b"], X = pr.X); slv = nothing);julia> PortfolioOptimisers.owner_block([cbr, cbr]) === PortfolioOptimisers.owner_block(cbr)trueRelated
PortfolioOptimisers.resolve_constraint_block_names — Function
resolve_constraint_block_names(
cbe::ConstraintBlock,
strict::Bool,
datatype::DataType
) -> ConstraintBlock{_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, _Z2, _Z3, _Z4, _Z5, 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, _Z2, _Z3, _Z4, _Z5}
Resolves the slots of a ConstraintBlock that hold a name or an estimator over sets. This is stage 1 of the resolution.
Stage 1 is configuration. It gives the block with values in its slots, and it holds no Result. It runs before the reduction to the Investable Mask, over the universe of the caller, where every name of sets is an asset of the caller. The reduction then views each value at the mask, see port_opt_view(cbe::ConstraintBlock, i, args...). A JuMP head runs it once for each optimise call, and an online head runs it once for each fold, in resolve_allocation_set.
A slot is a stage 1 slot when its value follows a view at the mask, so the two orders of the names and the reduction give one value. The other slots resolve at stage 2, in resolve_constraint_block, after the reduction:
wbandlcse, because their resolvers read the rowsrd.gcarde, because it resolves to aLinearConstraintover the assets, and a view does not narrow its matrix. At stage 2 it resolves over thesetsthat carry the Non-Investable Axis.cte,pleand the slots that can hold a Calibration Rule, because they read the prior.
Algorithm
- Resolve the thresholds
ltandstwiththreshold_constraints. - Resolve the sub-grouped cardinality constraint
sgcardewithlinear_constraints, with integer values. Its columns are the sub-groups and not the assets, so a view does not change it. - Resolve the sub-group matrices
smtxandsgmtxwithasset_sets_matrix, and the sub-group thresholdsslt,sst,sgltandsgstwiththreshold_constraints. When the two slots of a pair hold one object, resolve it once withshared_pair_resolution. - Resolve the turnover constraints
tnwithturnover_constraints. - Return
cberebuilt with the resolved slots, withrebuild_struct.
Arguments
cbe: The block.strict: Whether to throw an error ifsetsdoes not contain the desired value insets.dict[key].datatype: The element type of the resolved values.
Returns
cbe'::ConstraintBlock: The block with its stage 1 slots resolved.
Related
PortfolioOptimisers.shared_pair_resolution — Function
shared_pair_resolution(f, a, b) -> Tuple{Any, Any}
Resolves two slots of a ConstraintBlock that can hold the same object, with one resolver.
When the two slots hold one object, the function resolves it once, so the two results are one object too. The check of the shapes of a sub-group slot and its sub-grouped twin then sees one object, as shared_pair_view keeps it for a view.
Arguments
f: The resolver of one slot.a,b: The values of the two slots.
Returns
(ra, rb)::Tuple: The results ofaandb.
Related
PortfolioOptimisers.resolve_constraint_block — Function
resolve_constraint_block(cbe::ConstraintBlock, pr::AbstractPriorResult, rd::ReturnsResult;
slv, strict::Bool = false, kwargs...) -> ResolvedConstraintBlock
resolve_constraint_block(cbe::ConstraintBlock, pr::Nothing, rd::Option{<:ReturnsResult};
strict::Bool = false, kwargs...) -> ResolvedConstraintBlock
resolve_constraint_block(cbe::ConstraintBlock, pr::AbstractPriorResult, rd::Nothing;
kwargs...)Resolves a ConstraintBlock against its own prior and rows, to its ResolvedConstraintBlock. This is stage 2 of the resolution.
Both owners of a block call it. The shared entry of every head, resolve_block_entry, calls it for each block. resolve_jump_optimiser runs the entry once for each optimise call, also for the set in the leader re-solve of an online head. The projection programme runs it at each step of an online head, through resolve_projection_entry. A direct call of set_allocation_set_constraints! calls it through resolve_allocation_set_step. The block must hold the result of stage 1, resolve_constraint_block_names, viewed at the Investable Mask of pr. So pr, rd and the block are on the investable assets. A slot that still holds an estimator of stage 1 raises a TypeError in the constructor of the Result.
One rule orders the names and the reduction for every block. Stage 1 resolves before the reduction, and a view at the mask follows its values. This function resolves after the reduction, over the sets of the block, which carry the Non-Investable Axis. So a name that left the investable universe drops its row and is not refused, and a precomputed constraint keeps its width. assert_investable_constraint_width then refuses a precomputed lcse or gcarde whose width is not the number of assets of the block.
The method for pr = nothing is the method of a programme set that reads no rows, see rows_needed. Its prior-reading slots hold values that read no prior, so it resolves the slots that read names alone, and keeps every other slot. Its Result holds no prior and no rows.
Algorithm
The method on a prior result runs these steps.
- Resolve the weight bounds
wbwithweight_bounds_constraints, with the rowsrdand theNassets ofpr.X. - Resolve
lcsewithlinear_constraints, with the factor regressionpr.rrand the rows, andgcardewith integer values. Check the width of both results withassert_investable_constraint_width. - Fit the centrality rows
ctrwithcentrality_constraintsand the phylogeny resultplrwithphylogeny_constraints. Each reads the prior, the rows and the implied volatilitiesrd.ivandrd.ivpa. A reader that cannot estimate an asset raises aDistanceReaderRefusalError, which the caller catches. - Resolve each Calibration Rule against the prior and the solver
slv. The norm ceilingsl2candlinfcstate their norm order in aCalibrationContext, andlpcgoes throughnorm_ceiling_factory. The penaltiesl1andlinfgo throughresolve_calibration_slot, andl2andlpthrough their ownfactory. - Check the four slots that hold a number,
l2c,linfc,l1andlinf, withassert_nonempty_gt0_finite_val. A rule states no number at construction, so this is the first point that knows the number. - Return the Result, with the stage 1 slots and the settings of
cbe,prandrd.
Arguments
cbe: The block, after stage 1 and the view at the mask.pr: The prior result of the block, ornothingwhen the block reads no rows.rd: The rows of the block. The method forpr = nothingreads only their element type and their width, and it takesnothingoutside an Online Update.slv: The solver of the owner, which a Calibration Rule resolves against.strict: Whether to throw an error ifsetsdoes not contain the desired value insets.dict[key].kwargs...: Passed tocentrality_constraintsandphylogeny_constraints.
Validation
- The rules of
assert_investable_constraint_widthforlcsrandgcardr. The method forpr = nothingchecks them when it has rows. l2c,linfc,l1andlinfarenothingor finite and> 0after the resolution. ADomainErroror anIsNonFiniteErroris thrown otherwise.- A prior result with no rows. An
IsNothingErroris thrown. The prior of a block is fitted on its rows, so this pair does not occur in the library.
Returns
cbr::ResolvedConstraintBlock: The Result of the block.
Related
PortfolioOptimisers.rows_datatype — Function
rows_datatype(rd::Nothing)
rows_datatype(rd::ReturnsResult)Returns the element type of the rows of a block that reads no prior, as a keyword of a resolver.
A block with no prior and no rows passes no keyword, so the resolver takes its own default.
Returns
kw::NamedTuple:(; datatype = eltype(rd.X)), or an empty tuple whenrdisnothing.
Related
PortfolioOptimisers.assert_rows_constraint_width — Function
assert_rows_constraint_width(lcsr, gcardr, rd::Nothing)
assert_rows_constraint_width(lcsr, gcardr, rd::ReturnsResult)Checks the width of the linear constraints of a block that reads no prior, against the columns of its rows.
A block with no rows has no width to check against, and the model refuses a wrong width.
Validation
- The rules of
assert_investable_constraint_width, withN = size(rd.X, 2).
Returns
nothing.
Related
PortfolioOptimisers.constraint_block_from_resolved — Function
constraint_block_from_resolved(
cbe::ConstraintBlock,
cbr::ResolvedConstraintBlock
) -> ConstraintBlock{_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, _Z2, _Z3, _Z4, _Z5, 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, _Z2, _Z3, _Z4, _Z5}
Returns a copy of cbe whose slots hold the values of its ResolvedConstraintBlock.
jump_optimiser_from_attributes calls it to build the optimiser of a sub-problem from the Result of a fit. The Result holds no estimator, so the sub-problem resolves no slot again: the resolvers of both stages give a resolved value back.
The function maps each field of the Result onto the slot of the same name, and five fields onto a slot with another name: lcsr onto lcse, ctr onto cte, gcardr onto gcarde, sgcardr onto sgcarde and plr onto ple. It derives the list from the fields of the Result, so it drops no field. A field with no slot raises a MethodError in the keyword constructor of the block. The prior pr and the rows rd have no slot, and the function leaves them out. A slot with no field, tr or sets, keeps its value in cbe.
Arguments
cbe: The block of the optimiser that the sub-problem copies.cbr: The Result of the block.
Returns
cbe'::ConstraintBlock: The block with the values ofcbrin its slots.
Related
PortfolioOptimisers.set_block_constraints! — Function
set_block_constraints!(model::JuMP.Model, cbr::ResolvedConstraintBlock, owner, bgt, fees;
tr = nothing, b1::Option{<:MatNum} = nothing,
prefix::Symbol = Symbol(""), kwargs...) -> Nothing
set_block_post_risk_constraints!(model::JuMP.Model, cbr::ResolvedConstraintBlock, owner,
attrs; prefix::Symbol = Symbol("")) -> NothingAdd a ResolvedConstraintBlock to a model, in its own namespace and in two phases. This is the block builder.
Every programme that holds a block adds it through these two functions: a JuMP head in assemble_jump_model! for its own block and for each later block, such as the set in the model of a leader, and the projection of a ProgrammeAllocationSet in set_allocation_set_constraints!. So the order of the Model Assembly is written once. A JuMP head runs its own steps between the two phases: the fees, the risk step, the return terms and mark_risk_minimised!, then the bounds builder set_allocation_risk_return_bounds! of each later block. The projection minimises no risk, so it runs the bounds builder of its set alone between the two phases, and sets no mark.
Phase 1, set_block_constraints!, adds the rows that come before the risk step of the owner. Phase 2, set_block_post_risk_constraints!, adds the rows that read the marks of the objective of the owner, risk_minimised and variance_flag: the semidefinite phylogeny reads them. The integer phylogeny and the custom constraints come after them too.
The first block of a model takes the empty prefix, so its rows have the names of a model with one block. Each block after the first takes a Model State namespace. In the model of a JuMP head, block i takes blk_i_, see later_constraint_blocks. Phase 1 registers the weights of the model under it, with the owner w_owner = Symbol(""), so weights_prefix keeps the lifted matrix and the marks with the weights. Every builder then registers its entries under the prefix. A kind on two blocks gives two sets of rows and no name collision. The MIP bits, the long and short parts of the weights and the pin of xbgt belong to the weights, so the blocks share them. The penalties of each block add to the one Objective Penalty.
The block reads its own prior cbr.pr and its own phylogeny cbr.plr. The builder takes the values of the owner that the block cannot hold: the net budget bgt, for the long-short and gross budgets, the fees, for the MIP kinds and the tracking errors, the tracking errors tr that the owner bound to its rows, and the factor loadings b1 of a factor head. The custom constraints get the owner and the bundle attrs that the owner gives them. A block of a set passes the set as the owner, nothing as the net budget and the fees, and nothing as attrs.
Algorithm
Phase 1:
- When
prefixis not empty, register the weights of the model under it, with the ownerSymbol(""). Add the weight bounds, the net budgetbgt, and the short and gross budgets of the block.set_block_weight_constraints!does both. - Mark
sdp_phylogenyon the owner of the weights whencbr.plrholds a semidefinite phylogeny, withmark_sdp_phylogeny!. Every variance on the weights then takes the semidefinite formulation, so a variance of the owner that the objective minimises holds down the lift that the rows of phase 2 bind. - Add the linear rows
lcsr, then the centrality rowsctr, withset_linear_weight_constraints!. - Add the MIP kinds with
set_mip_constraints!, the exact cost budget of aBudgetCostswhosexbgtistruewithset_cost_budget_mip_constraints!, then the sub-group MIP kinds withset_smip_constraints!. - Add the turnover ceilings with
set_turnover_constraints!. - Add the tracking errors
trwithset_tracking_error_constraints!, on the prior of the block. - Add the norm ceilings
l2c,lpcandlinfc, then the penaltiesl1,l2,lpandlinf.
Phase 2:
- Add the integer phylogeny rows with
set_iplg_constraints!, then the semidefinite phylogeny rows withset_sdp_phylogeny_constraints!. - Add the custom constraints
ccntwithadd_custom_constraint!.
Arguments
model::JuMP.Model: The JuMP optimisation model.cbr: The Result of the block.owner: The owner of the block: a JuMP head, or aProgrammeAllocationSet. The tracking errors and the custom constraints dispatch on it.bgt: The net budget of the owner of the block, ornothing.fees: The fees of the owner of the block, ornothing.tr: The tracking errors of the owner, bound to its rows, ornothing.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.attrs: The bundle that the custom constraints read, ornothing.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...: Passed toset_tracking_error_constraints!. A JuMP head passes its rows asrd.
Returns
nothing.
Related
PortfolioOptimisers.set_block_weight_constraints! — Function
set_block_weight_constraints!(
model::Model,
cbr::ResolvedConstraintBlock,
bgt::Union{Nothing, Number, BudgetConstraintEstimator};
prefix
)
Add the weight bounds and the budgets of a ResolvedConstraintBlock to a model, under the namespace of the block.
This is the first step of the block builder, set_block_constraints!. The centring solve of UnconstrainedNearOptimalCentering also calls it for each block after the first, because that solve keeps the bounds and the budgets of every block and no other row of a block.
Algorithm
- When
prefixis not empty, register the weights of the model under it, with the ownerSymbol(""), soweights_prefixkeeps the parts and the marks with the weights. - Add the weight bounds
cbr.wb, the net budgetbgt, and the short and gross budgetscbr.sbgtandcbr.gbgtwithset_weight_constraints!.
Arguments
model::JuMP.Model: The JuMP optimisation model.cbr: The Result of the block.bgt: The net budget of the owner of the block, ornothing.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.set_block_post_risk_constraints! — Function
set_block_post_risk_constraints!(
model::Model,
cbr::ResolvedConstraintBlock,
owner,
attrs;
prefix
)
Add phase 2 of a ResolvedConstraintBlock to a model: the rows that come after the risk step and the marks of the owner.
A JuMP head calls it after mark_risk_minimised!, because the semidefinite phylogeny reads the marks risk_minimised and variance_flag of the weights. The projection calls it after the bounds builder, with no mark, so the phylogeny keeps its penalty. set_block_constraints! states both phases, their order and their arguments.
Algorithm
- Add the integer phylogeny rows with
set_iplg_constraints!, then the semidefinite phylogeny rows withset_sdp_phylogeny_constraints!, underprefix. - Add the custom constraints
ccntwithadd_custom_constraint!, withownerandattrs.
Arguments
model::JuMP.Model: The JuMP optimisation model.cbr: The Result of the block.owner: The owner of the block.attrs: The bundle that the custom constraints read, ornothing.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.set_block_objective_terms! — Function
set_block_objective_terms!(model::JuMP.Model, cbr::Nothing, obj, owner) -> Nothing
set_block_objective_terms!(model::JuMP.Model, cbr::ResolvedConstraintBlock, obj, owner) -> NothingAdd the custom objective terms cobj of a ResolvedConstraintBlock to the Objective Penalty of a model. This is the step of the block builder for the objective.
A term of a block gets the objective obj of the model, the owner of its block and the Result of its block, through add_custom_objective_term!. The term adds to the Objective Penalty, and the objective builder of the owner adds the penalty to its objective. So the owner calls this function after the two phases of the block, set_block_constraints! and set_block_post_risk_constraints!, and before it sets the objective. The projection programme of a ProgrammeAllocationSet calls it with its Projection Geometry as obj. A nothing block, the block of a BoundedAllocationSet, adds no term.
Arguments
model::JuMP.Model: The JuMP optimisation model.cbr: The Result of the block, ornothingwhen the owner holds no block.obj: The objective of the model, such as a Projection Geometry.owner: The owner of the block.
Returns
nothing.
Related