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 of wb.

Related

source
PortfolioOptimisers.constraint_block — Function
constraint_block(cbe::Nothing; slots...) -> ConstraintBlock
constraint_block(cbe::ConstraintBlock; slots...) -> ConstraintBlock

Returns 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

  1. cbe is nothing: build the block from slots with the keyword constructor of ConstraintBlock. A slot that slots does not name takes its default.
  2. slots is empty: return cbe.
  3. Otherwise rebuild cbe with the slots in slots replaced, with rebuild_struct.

Arguments

  • cbe: The block that the caller gives, or nothing when the caller gives none.
  • slots...: The slots that the caller names, as keywords of ConstraintBlock.

Validation

  • A name of slots that is not a slot of ConstraintBlock raises a MethodError, as an unknown keyword of a constructor does.

Returns

  • cbe::ConstraintBlock: The block of the owner.

Related

source
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 of cbe, under their field names.

Related

source
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 of a and b.

Related

source
PortfolioOptimisers.reader_frames — Method
reader_frames(cbe::ConstraintBlock, path::AbstractString, refit::Bool) -> ReturnsFrames

Walk 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: 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.

Returns

  • fr::ReturnsFrames: The frames of the slots of cbe.

Related

source
PortfolioOptimisers.AbstractResolved — Type
abstract type AbstractResolved <: AbstractResult

Abstract 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

source
PortfolioOptimisers.owner_block — Function
owner_block(cbr::ResolvedConstraintBlock) -> ResolvedConstraintBlock
owner_block(cbr::VecRcb) -> ResolvedConstraintBlock

Gives 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)true

Related

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

  • wb and lcse, because their resolvers read the rows rd.
  • gcarde, because it resolves to a LinearConstraint over the assets, and a view does not narrow its matrix. At stage 2 it resolves over the sets that carry the Non-Investable Axis.
  • cte, ple and the slots that can hold a Calibration Rule, because they read the prior.

Algorithm

  1. Resolve the thresholds lt and st with threshold_constraints.
  2. Resolve the sub-grouped cardinality constraint sgcarde with linear_constraints, with integer values. Its columns are the sub-groups and not the assets, so a view does not change it.
  3. Resolve the sub-group matrices smtx and sgmtx with asset_sets_matrix, and the sub-group thresholds slt, sst, sglt and sgst with threshold_constraints. When the two slots of a pair hold one object, resolve it once with shared_pair_resolution.
  4. Resolve the turnover constraints tn with turnover_constraints.
  5. Return cbe rebuilt with the resolved slots, with rebuild_struct.

Arguments

  • cbe: The block.
  • strict: Whether to throw an error if sets does not contain the desired value in sets.dict[key].
  • datatype: The element type of the resolved values.

Returns

  • cbe'::ConstraintBlock: The block with its stage 1 slots resolved.

Related

source
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 of a and b.

Related

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

  1. Resolve the weight bounds wb with weight_bounds_constraints, with the rows rd and the N assets of pr.X.
  2. Resolve lcse with linear_constraints, with the factor regression pr.rr and the rows, and gcarde with integer values. Check the width of both results with assert_investable_constraint_width.
  3. Fit the centrality rows ctr with centrality_constraints and the phylogeny result plr with phylogeny_constraints. Each reads the prior, the rows and the implied volatilities rd.iv and rd.ivpa. A reader that cannot estimate an asset raises a DistanceReaderRefusalError, which the caller catches.
  4. Resolve each Calibration Rule against the prior and the solver slv. The norm ceilings l2c and linfc state their norm order in a CalibrationContext, and lpc goes through norm_ceiling_factory. The penalties l1 and linf go through resolve_calibration_slot, and l2 and lp through their own factory.
  5. Check the four slots that hold a number, l2c, linfc, l1 and linf, with assert_nonempty_gt0_finite_val. A rule states no number at construction, so this is the first point that knows the number.
  6. Return the Result, with the stage 1 slots and the settings of cbe, pr and rd.

Arguments

  • cbe: The block, after stage 1 and the view at the mask.
  • pr: The prior result of the block, or nothing when the block reads no rows.
  • rd: The rows of the block. The method for pr = nothing reads only their element type and their width, and it takes nothing outside an Online Update.
  • slv: The solver of the owner, which a Calibration Rule resolves against.
  • strict: Whether to throw an error if sets does not contain the desired value in sets.dict[key].
  • kwargs...: Passed to centrality_constraints and phylogeny_constraints.

Validation

  • The rules of assert_investable_constraint_width for lcsr and gcardr. The method for pr = nothing checks them when it has rows.
  • l2c, linfc, l1 and linf are nothing or finite and > 0 after the resolution. A DomainError or an IsNonFiniteError is thrown otherwise.
  • A prior result with no rows. An IsNothingError is 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

source
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 when rd is nothing.

Related

source
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

Returns

  • nothing.

Related

source
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 of cbr in its slots.

Related

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

Add 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:

  1. When prefix is not empty, register the weights of the model under it, with the owner Symbol(""). Add the weight bounds, the net budget bgt, and the short and gross budgets of the block. set_block_weight_constraints! does both.
  2. Mark sdp_phylogeny on the owner of the weights when cbr.plr holds a semidefinite phylogeny, with mark_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.
  3. Add the linear rows lcsr, then the centrality rows ctr, with set_linear_weight_constraints!.
  4. Add the MIP kinds with set_mip_constraints!, the exact cost budget of a BudgetCosts whose xbgt is true with set_cost_budget_mip_constraints!, then the sub-group MIP kinds with set_smip_constraints!.
  5. Add the turnover ceilings with set_turnover_constraints!.
  6. Add the tracking errors tr with set_tracking_error_constraints!, on the prior of the block.
  7. Add the norm ceilings l2c, lpc and linfc, then the penalties l1, l2, lp and linf.

Phase 2:

  1. Add the integer phylogeny rows with set_iplg_constraints!, then the semidefinite phylogeny rows with set_sdp_phylogeny_constraints!.
  2. Add the custom constraints ccnt with add_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 a ProgrammeAllocationSet. The tracking errors and the custom constraints dispatch on it.
  • bgt: The net budget of the owner of the block, or nothing.
  • fees: The fees of the owner of the block, or nothing.
  • tr: The tracking errors of the owner, bound to its rows, or nothing.
  • 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.
  • attrs: The bundle that the custom constraints read, or nothing.
  • 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 to set_tracking_error_constraints!. A JuMP head passes its rows as rd.

Returns

  • nothing.

Related

source
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

  1. When prefix is not empty, register the weights of the model under it, with the owner Symbol(""), so weights_prefix keeps the parts and the marks with the weights.
  2. Add the weight bounds cbr.wb, the net budget bgt, and the short and gross budgets cbr.sbgt and cbr.gbgt with set_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, or nothing.
  • 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.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

  1. Add the integer phylogeny rows with set_iplg_constraints!, then the semidefinite phylogeny rows with set_sdp_phylogeny_constraints!, under prefix.
  2. Add the custom constraints ccnt with add_custom_constraint!, with owner and attrs.

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, or nothing.
  • 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.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) -> Nothing

Add 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, or nothing when 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

source