Constraint Block

PortfolioOptimisers.ConstraintBlock — Type
struct ConstraintBlock{__T_wb, __T_sbgt, __T_gbgt, __T_lt, __T_st, __T_lcse, __T_cte, __T_gcarde, __T_sgcarde, __T_smtx, __T_sgmtx, __T_slt, __T_sst, __T_sglt, __T_sgst, __T_tn, __T_sets, __T_tr, __T_ple, __T_ccnt, __T_cobj, __T_ss, __T_card, __T_scard, __T_l2c, __T_lpc, __T_linfc, __T_l1, __T_l2, __T_lp, __T_linf, __T_xbgt} <: AbstractEstimator

Holds the feasible set of the weights of a programme, and the terms that the programme adds to the Objective Penalty.

The block is the Constraint Block of the glossary. It holds the slots that a JuMP optimiser and a programme Allocation Set share: the weight bounds, the leverage caps, the linear, cardinality, threshold and phylogeny constraints, the turnover and tracking constraints, the norm ceilings, the custom constraints and the four regularisation penalties. A slot never writes the objective. The owner of the block holds the net budget, the fees, the return term and the scalariser.

JuMPOptimiser and ProgrammeAllocationSet each hold a block in their field cbe. The keyword constructor of each owner takes each slot of the block as a flat keyword, and opt.wb reads the slot of the block. So build a block directly only to give one feasible set to more than one owner.

Fields

  • wb: Weight bounds estimator or weight bounds.
  • sbgt: Short-side budget, sum(sw). A number pins it, and a BudgetRange bounds it. The realised short exposure is only bounded by default, so sbgt = 0.3 means at most 30% short unless xbgt pins the long/short decomposition. With bgt, it fixes the net and gross exposures only together. To constrain the gross exposure alone, see gbgt.
  • gbgt: Gross budget (leverage) constraint, sum(lw) + sum(sw). A number pins the gross exposure, and a BudgetRange bounds it. For example, BudgetRange(; lb = nothing, ub = 2.0) caps leverage at 2x. bgt and sbgt pin the net and gross exposures only together, but gbgt constrains the gross exposure alone and leaves the net exposure free. It needs weight bounds that admit short positions. The realised gross exposure is only bounded unless xbgt is set.
  • lt: Long-side minimum holding threshold.
  • st: Short-side minimum holding threshold.
  • lcse: Linear constraint set estimator(s). This is the one constraint slot that also admits an ExposureConstraintEstimator, so a row can name the members of another basis, such as factors. The generator writes the row again in asset space through the loadings of the prior. What reaches the model is an ordinary asset-space LinearConstraint either way.
  • cte: Centrality constraint(s). A CentralityConstraint, a vector of them, or an already-generated LinearConstraint. Resolved by centrality_constraints into the ctr slot of ResolvedJuMPOptimiser.
  • gcarde: Grouped cardinality constraint estimator.
  • sgcarde: Sub-grouped cardinality constraint estimator(s).
  • smtx: Sub-group selection matrix or estimator.
  • sgmtx: Sub-grouped selection matrix or estimator.
  • slt: Sub-group long threshold.
  • sst: Sub-group short threshold.
  • sglt: Sub-grouped long threshold.
  • sgst: Sub-grouped short threshold.
  • tn: Turnover constraint estimator(s).
  • sets: Sets used to map estimator values to assets.
  • tr: Tracking error constraint(s).
  • ple: Phylogeny constraint estimator(s).
  • ccnt: Custom JuMP constraint.
  • cobj: Custom JuMP objective.
  • ss: Optional scalar shrinkage parameter.
  • card: Global cardinality constraint.
  • scard: Sub-group cardinality constraint(s).
  • l2c: 2-norm ceiling on the weights. It bounds norm(w, 2) <= l2c * k, where k is the homogenisation variable, so the ceiling holds on the weights the result reports and the budget does not scale it. Smaller l2c forces a more evenly spread portfolio. Used as a diversification floor via the reciprocal: l2c = 1 / sqrt(m) requires at least m effective assets (inv(norm(w, 2)^2) >= m). Norm-constraint family with lpc and linfc. The bound is Num_NormCeilCal under the time-dependent wrapper, so the slot takes the ceiling itself, an AbstractNormCeilingCalibrationAlgorithm that computes it from the prior result, or a plain function of the same five arguments.
  • lpc: p-norm ceiling(s) on the weights at an arbitrary norm order. Each LpRegularisation supplies a norm order p and a bound val, enforcing norm(w, p) <= val * k. Smaller val forces a more evenly spread portfolio. Used as a diversification floor via the reciprocal: val = m^(1/p - 1) requires at least m order-p effective assets (sum(abs.(w) .^ p)^inv(1 - p) >= m). On weights whose absolute values sum to one, this count is number_effective_assets taken to an arbitrary order. Norm-constraint family with l2c and linfc.
  • linfc: ∞-norm ceiling on the weights. It caps the largest absolute weight, norm(w, Inf) <= linfc * k. So linfc = 0.2 caps the largest weight at 20% of a fully invested portfolio. Used as a diversification floor via the reciprocal: linfc = 1 / m spreads the portfolio across at least m assets. Norm-constraint family with l2c and lpc. The bound is Num_NormCeilCal under the time-dependent wrapper, so the slot takes the ceiling itself, an AbstractNormCeilingCalibrationAlgorithm that computes it from the prior result, or a plain function of the same five arguments.
  • l1: L1 regularisation coefficient. It is the ambiguity radius of a type-$\infty$ Wasserstein ground metric, whose dual norm is the 1-norm, so the bound is Num_AmbRadCal under the time-dependent wrapper and the slot takes an AbstractAmbiguityRadiusCalibrationAlgorithm that computes it from the prior result, or a plain function of the same five arguments.
  • l2: L2 regularisation term(s).
  • lp: Lp regularisation specification(s).
  • linf: L∞ regularisation coefficient. It is the ambiguity radius of a type-1 Wasserstein ground metric, whose dual norm is the $\infty$-norm, so the bound is Num_AmbRadCal under the time-dependent wrapper and the slot takes an AbstractAmbiguityRadiusCalibrationAlgorithm that computes it from the prior result, or a plain function of the same five arguments.
  • xbgt: Whether to pin the long/short decomposition exactly. When false (the default), lw and sw are upper bounds on the positive and negative parts of w, so bgt, sbgt and gbgt bound the realised exposures and do not pin them. A short budget of 0.3 then means at most 30% short. When true, the long/short binary indicators force lw == max(w, 0) and sw == max(-w, 0), so the budgets hold exactly, at the cost of turning the problem into a mixed-integer program. It reuses the indicators the cardinality, threshold and fee builders already create (see short_mip_threshold_constraints) rather than adding its own, and is ignored when the weight bounds admit no shorts.

Constructors

ConstraintBlock(;    wb::TD_Option{<:WbE_Wb} = WeightBounds(),    sbgt::TD_Option{<:Num_BgtRg} = nothing,    gbgt::TD_Option{<:Num_BgtRg} = nothing,    lt::TD_Option{<:BtE_Bt} = nothing,    st::TD_Option{<:BtE_Bt} = nothing,    lcse::TD_Option{<:Union{EcE_LcE_Lc, AbstractVector}} = nothing,    cte::TD_Option{<:Lc_CC_VecCC} = nothing,    gcarde::TD_Option{<:LcE_Lc} = nothing,    sgcarde::TD_Option{<:Union{LcE_Lc, AbstractVector}} = nothing,    smtx::TD_Option{<:Union{MatNum_ASetMatE, AbstractVector}} = nothing,    sgmtx::TD_Option{<:Union{MatNum_ASetMatE, AbstractVector}} = nothing,    slt::TD_Option{<:Union{BtE_Bt, AbstractVector}} = nothing,    sst::TD_Option{<:Union{BtE_Bt, AbstractVector}} = nothing,    sglt::TD_Option{<:Union{BtE_Bt, AbstractVector}} = nothing,    sgst::TD_Option{<:Union{BtE_Bt, AbstractVector}} = nothing,    tn::TD_Option{<:Union{TnE_Tn, AbstractVector}} = nothing,    sets::TD_Option{<:UniverseSets} = nothing,    tr::TD_Option{<:Tr_VecTr} = nothing,    ple::TD_Option{<:Union{PlCE_PlC, AbstractVector}} = nothing,    ccnt::TD_Option{<:JuMPConstr_VecJuMPConstr} = nothing,    cobj::TD_Option{<:JuMPObj_VecJuMPObj} = nothing,    ss::TD_Option{<:Number} = nothing,    card::TD_Option{<:Integer} = nothing,    scard::TD_Option{<:Int_VecInt} = nothing,    l2c::TD_Option{<:Num_NormCeilCal} = nothing,    lpc::TD_Option{<:LpReg_VecLpReg} = nothing,    linfc::TD_Option{<:Num_NormCeilCal} = nothing,    l1::TD_Option{<:Num_AmbRadCal} = nothing,    l2::TD_Option{<:L2Reg_VecL2Reg} = nothing,    lp::TD_Option{<:LpReg_VecLpReg} = nothing,    linf::TD_Option{<:Num_AmbRadCal} = nothing,    xbgt::Bool = false,) -> ConstraintBlock

Keywords correspond to the struct's fields. A slot typed TD_Option can hold a TimeDependent schedule in place of a static value, as the slot of the same name in JuMPOptimiser can.

lcse, sgcarde, smtx, sgmtx, slt, sst, sglt, sgst, tn and ple take a vector that mixes the members of their element type. The keyword constructor narrows it through narrow_mixed_vector.

Validation

The checks that read a field of the owner as well, such as assert_gross_budget_admissible, run in the constructor of the owner.

Examples

julia> cbe = ConstraintBlock(; wb = WeightBounds(; lb = 0.0, ub = 0.4), card = 3);julia> opt = JuMPOptimiser(; slv = Solver(; solver = nothing), cbe = cbe, card = 4);julia> (opt.wb.ub, opt.card, opt.cbe.card)(0.4, 4, 4)

Related

source
PortfolioOptimisers.ResolvedConstraintBlock — Type
struct ResolvedConstraintBlock{__T_pr, __T_rd, __T_wb, __T_lt, __T_st, __T_lcsr, __T_ctr, __T_gcardr, __T_sgcardr, __T_smtx, __T_sgmtx, __T_slt, __T_sst, __T_sglt, __T_sgst, __T_tn, __T_plr, __T_l2c, __T_lpc, __T_linfc, __T_l1, __T_l2, __T_lp, __T_linf, __T_card, __T_scard, __T_ss, __T_xbgt, __T_sbgt, __T_gbgt, __T_ccnt, __T_cobj} <: AbstractResolved

Holds the Resolved Constraint Block of the glossary: the data that a ConstraintBlock gives when it resolves against its own prior and rows.

resolve_constraint_block makes it at stage 2 of the resolution, and a builder adds it to a programme. The block builder set_block_constraints! reads it for both owners: a JuMP head in assemble_jump_model!, and a ProgrammeAllocationSet in add_allocation_set_block!. So no builder resolves a slot again.

The Result holds three kinds of data:

  1. The prior result pr and the rows rd of its block. A block that reads no rows holds nothing in both.
  2. The resolved slots. Each field holds the result of the slot of the block, and the five slots that change their name take the r of a result: lcse gives lcsr, cte gives ctr, gcarde gives gcardr, sgcarde gives sgcardr and ple gives plr. A Calibration Rule in l2c, lpc, linfc, l1, l2, lp or linf is resolved to its value.
  3. The settings that need no resolution: card, scard, ss, xbgt, sbgt, gbgt, ccnt and cobj.

The tracking errors tr and the names sets are not fields. The builder of the tracking errors binds them to the rows of the Result, and no builder reads sets.

Fields

  • pr: Prior result. The prior of the block, or nothing when the block reads no rows.
  • rd: The returns result to use. The rows of the block, or nothing when the block reads no rows.
  • wb: Weight bounds.
  • lt: Long-side minimum holding threshold.
  • st: Short-side minimum holding threshold.
  • lcsr: Processed linear constraint set result.
  • ctr: Centrality constraint result. The LinearConstraint the centrality constraints resolve to.
  • gcardr: Processed grouped cardinality constraint result.
  • sgcardr: Processed sub-grouped cardinality constraint result.
  • smtx: Sub-group selection matrix or estimator.
  • sgmtx: Sub-grouped selection matrix or estimator.
  • slt: Sub-group long threshold.
  • sst: Sub-group short threshold.
  • sglt: Sub-grouped long threshold.
  • sgst: Sub-grouped short threshold.
  • tn: Turnover result.
  • plr: Phylogeny result.
  • l2c: 2-norm ceiling on the weights. It bounds norm(w, 2) <= l2c * k, where k is the homogenisation variable, so the ceiling holds on the weights the result reports and the budget does not scale it. Smaller l2c forces a more evenly spread portfolio. Used as a diversification floor via the reciprocal: l2c = 1 / sqrt(m) requires at least m effective assets (inv(norm(w, 2)^2) >= m). Norm-constraint family with lpc and linfc. The bound is Num_NormCeilCal under the time-dependent wrapper, so the slot takes the ceiling itself, an AbstractNormCeilingCalibrationAlgorithm that computes it from the prior result, or a plain function of the same five arguments.
  • lpc: p-norm ceiling(s) on the weights at an arbitrary norm order. Each LpRegularisation supplies a norm order p and a bound val, enforcing norm(w, p) <= val * k. Smaller val forces a more evenly spread portfolio. Used as a diversification floor via the reciprocal: val = m^(1/p - 1) requires at least m order-p effective assets (sum(abs.(w) .^ p)^inv(1 - p) >= m). On weights whose absolute values sum to one, this count is number_effective_assets taken to an arbitrary order. Norm-constraint family with l2c and linfc.
  • linfc: ∞-norm ceiling on the weights. It caps the largest absolute weight, norm(w, Inf) <= linfc * k. So linfc = 0.2 caps the largest weight at 20% of a fully invested portfolio. Used as a diversification floor via the reciprocal: linfc = 1 / m spreads the portfolio across at least m assets. Norm-constraint family with l2c and lpc. The bound is Num_NormCeilCal under the time-dependent wrapper, so the slot takes the ceiling itself, an AbstractNormCeilingCalibrationAlgorithm that computes it from the prior result, or a plain function of the same five arguments.
  • l1: L1 regularisation coefficient. It is the ambiguity radius of a type-$\infty$ Wasserstein ground metric, whose dual norm is the 1-norm, so the bound is Num_AmbRadCal under the time-dependent wrapper and the slot takes an AbstractAmbiguityRadiusCalibrationAlgorithm that computes it from the prior result, or a plain function of the same five arguments.
  • l2: L2 regularisation term(s).
  • lp: Lp regularisation specification(s).
  • linf: L∞ regularisation coefficient. It is the ambiguity radius of a type-1 Wasserstein ground metric, whose dual norm is the $\infty$-norm, so the bound is Num_AmbRadCal under the time-dependent wrapper and the slot takes an AbstractAmbiguityRadiusCalibrationAlgorithm that computes it from the prior result, or a plain function of the same five arguments.
  • card: Global cardinality constraint.
  • scard: Sub-group cardinality constraint(s).
  • ss: Optional scalar shrinkage parameter.
  • xbgt: Whether to pin the long/short decomposition exactly. When false (the default), lw and sw are upper bounds on the positive and negative parts of w, so bgt, sbgt and gbgt bound the realised exposures and do not pin them. A short budget of 0.3 then means at most 30% short. When true, the long/short binary indicators force lw == max(w, 0) and sw == max(-w, 0), so the budgets hold exactly, at the cost of turning the problem into a mixed-integer program. It reuses the indicators the cardinality, threshold and fee builders already create (see short_mip_threshold_constraints) rather than adding its own, and is ignored when the weight bounds admit no shorts.
  • sbgt: Short-side budget, sum(sw). A number pins it, and a BudgetRange bounds it. The realised short exposure is only bounded by default, so sbgt = 0.3 means at most 30% short unless xbgt pins the long/short decomposition. With bgt, it fixes the net and gross exposures only together. To constrain the gross exposure alone, see gbgt.
  • gbgt: Gross budget (leverage) constraint, sum(lw) + sum(sw). A number pins the gross exposure, and a BudgetRange bounds it. For example, BudgetRange(; lb = nothing, ub = 2.0) caps leverage at 2x. bgt and sbgt pin the net and gross exposures only together, but gbgt constrains the gross exposure alone and leaves the net exposure free. It needs weight bounds that admit short positions. The realised gross exposure is only bounded unless xbgt is set.
  • ccnt: Custom JuMP constraint.
  • cobj: Custom JuMP objective.

Constructors

ResolvedConstraintBlock(; pr::Option{<:AbstractPriorResult},                        rd::Option{<:ReturnsResult}, wb::Option{<:WeightBounds},                        lt::Option{<:Threshold}, st::Option{<:Threshold},                        lcsr::Option{<:Lc_VecLc}, ctr::Option{<:Lc_CC_VecCC},                        gcardr::Option{<:LinearConstraint},                        sgcardr::Option{<:Lc_VecLc},                        smtx::Option{<:MatNum_VecMatNum},                        sgmtx::Option{<:MatNum_VecMatNum},                        slt::Option{<:Bt_VecOptBt}, sst::Option{<:Bt_VecOptBt},                        sglt::Option{<:Bt_VecOptBt}, sgst::Option{<:Bt_VecOptBt},                        tn::Option{<:Tn_VecTn}, plr::Option{<:PlC_VecPlC},                        l2c::Option{<:Number}, lpc::Option{<:LpReg_VecLpReg},                        linfc::Option{<:Number}, l1::Option{<:Number},                        l2::Option{<:L2Reg_VecL2Reg}, lp::Option{<:LpReg_VecLpReg},                        linf::Option{<:Number}, card::Option{<:Integer},                        scard::Option{<:Int_VecInt}, ss::Option{<:Number},                        xbgt::Bool, sbgt::Option{<:Num_BgtRg},                        gbgt::Option{<:Num_BgtRg},                        ccnt::Option{<:JuMPConstr_VecJuMPConstr},                        cobj::Option{<:JuMPObj_VecJuMPObj}) -> ResolvedConstraintBlock

Keywords correspond to the struct's fields, and each keyword has no default. Make the Result with resolve_constraint_block. The constructor checks the type of each field, so a slot that holds an estimator raises a TypeError. It checks no value, because the resolution checked the values.

ResolvedConstraintBlock(cbe::ConstraintBlock; pr, rd, wb, lcsr, gcardr, ctr, plr, l2c,                        lpc, linfc, l1, l2, lp, linf) -> ResolvedConstraintBlock

Builds the Result from the values of stage 2 and the slots of the block that stage 2 does not resolve. The keywords are the prior result, the rows and the twelve values of stage 2, and each keyword is required. The method takes the other slots and settings from cbe, with cbe.sgcarde as sgcardr. Both methods of resolve_constraint_block call it, so the list of the stage 1 slots and of the settings is written once.

Related

source
PortfolioOptimisers.factory — Method
factory(
    cbe::ConstraintBlock,
    w::AbstractVector
) -> 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 that read previous weights hold the weights w.

The function calls factory(x, w) on tn, tr, ccnt and cobj, and it keeps every other slot. A TimeDependent in one of these slots applies factory to each of its entries. The keyword constructor of ConstraintBlock checks the new slots.

Arguments

  • cbe::ConstraintBlock: The block.
  • w::AbstractVector: The new portfolio weights.

Returns

  • ConstraintBlock: The block with the four slots rebuilt for w.

Related

source
PortfolioOptimisers.port_opt_view — Method
port_opt_view(
    cbe::ConstraintBlock,
    i,
    args...
) -> 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 restricted to the assets at the indices i.

The method of the owner calls it, see port_opt_view(opt::JuMPOptimiser, i, X) and port_opt_view(set::ProgrammeAllocationSet, i, args...). A JuMPOptimiser passes the returns matrix X. A ProgrammeAllocationSet passes the arguments that it takes after i, and an online head can pass none.

Algorithm

  1. View at i the slots that can hold a value for each asset: wb, lt, st, smtx, sgmtx, slt, sst, sglt, sgst, tn, lcse, sets, ccnt and cobj. When smtx and sgmtx hold the same object, view it once, so that the two views are one object too. The same holds for slt and sglt, and for sst and sgst.
  2. View tr at i with args. A tracking measure gives the returns matrix X in args to the risk measure that it tracks.
  3. Keep every other slot. An estimator in cte, gcarde or sgcarde resolves its names against the viewed sets. A precomputed constraint in one of them keeps its width, because no view can narrow its matrix, see port_opt_view(::LinearConstraint, i). ple reads the viewed prior of the owner. The other slots hold no value for each asset.
  4. Rebuild the block with its keyword constructor, which checks the viewed slots again.

Arguments

  • cbe::ConstraintBlock: The block.
  • i: The indices of the assets that the view keeps.
  • args...: The arguments that the tracking errors tr read, such as the returns matrix X of the full universe, with one column for each asset.

Returns

  • ConstraintBlock: The block restricted to the assets at i.

Related

source
PortfolioOptimisers.needs_previous_weights — Method
needs_previous_weights(cbe::ConstraintBlock) -> Bool

Returns true if a slot of cbe reads the portfolio weights of the previous fold.

The function asks tn, tr, ccnt and cobj. It also asks every slot that holds a TimeDependent that the fold loop resolves, see time_dependent_fields.

Arguments

  • cbe::ConstraintBlock: The block.

Returns

  • Bool: true if one of these slots reads the previous weights, and false otherwise.

Related

source
PortfolioOptimisers.obs_weights_view — Method
obs_weights_view(cbe::ConstraintBlock, i) -> ConstraintBlock

Return a copy of cbe whose slots hold their observation weights cut to the observations i.

The block is not @propagatable, so it needs this method of obs_weights_view. Its phylogeny and centrality estimators and its tracking errors read the observations of the sample, and each can hold fixed observation weights. The method of its owner reaches the block through its field cbe, see obs_weights_view(opt::JuMPOptimiser, i).

Algorithm

  1. Cut every slot of cbe with obs_weights_view, and rebuild the block with its keyword constructor, through obs_weights_fields.

Arguments

  • cbe::ConstraintBlock: The block.
  • i: The observations to keep: a mask of the full sample, or their positions.

Returns

  • ConstraintBlock: The block at the kept observations.

Related

source