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} <: AbstractEstimatorHolds 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 aBudgetRangebounds it. The realised short exposure is only bounded by default, sosbgt = 0.3means at most 30% short unlessxbgtpins the long/short decomposition. Withbgt, it fixes the net and gross exposures only together. To constrain the gross exposure alone, seegbgt.
gbgt: Gross budget (leverage) constraint,sum(lw) + sum(sw). A number pins the gross exposure, and aBudgetRangebounds it. For example,BudgetRange(; lb = nothing, ub = 2.0)caps leverage at 2x.bgtandsbgtpin the net and gross exposures only together, butgbgtconstrains 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 unlessxbgtis 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 anExposureConstraintEstimator, 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-spaceLinearConstrainteither way.
cte: Centrality constraint(s). ACentralityConstraint, a vector of them, or an already-generatedLinearConstraint. Resolved bycentrality_constraintsinto thectrslot ofResolvedJuMPOptimiser.
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: CustomJuMPconstraint.
cobj: CustomJuMPobjective.
ss: Optional scalar shrinkage parameter.
card: Global cardinality constraint.
scard: Sub-group cardinality constraint(s).
l2c: 2-norm ceiling on the weights. It boundsnorm(w, 2) <= l2c * k, wherekis the homogenisation variable, so the ceiling holds on the weights the result reports and the budget does not scale it. Smallerl2cforces a more evenly spread portfolio. Used as a diversification floor via the reciprocal:l2c = 1 / sqrt(m)requires at leastmeffective assets (inv(norm(w, 2)^2) >= m). Norm-constraint family withlpcandlinfc. The bound isNum_NormCeilCalunder the time-dependent wrapper, so the slot takes the ceiling itself, anAbstractNormCeilingCalibrationAlgorithmthat 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. EachLpRegularisationsupplies a norm orderpand a boundval, enforcingnorm(w, p) <= val * k. Smallervalforces a more evenly spread portfolio. Used as a diversification floor via the reciprocal:val = m^(1/p - 1)requires at leastmorder-peffective assets (sum(abs.(w) .^ p)^inv(1 - p) >= m). On weights whose absolute values sum to one, this count isnumber_effective_assetstaken to an arbitrary order. Norm-constraint family withl2candlinfc.
linfc: ∞-norm ceiling on the weights. It caps the largest absolute weight,norm(w, Inf) <= linfc * k. Solinfc = 0.2caps the largest weight at 20% of a fully invested portfolio. Used as a diversification floor via the reciprocal:linfc = 1 / mspreads the portfolio across at leastmassets. Norm-constraint family withl2candlpc. The bound isNum_NormCeilCalunder the time-dependent wrapper, so the slot takes the ceiling itself, anAbstractNormCeilingCalibrationAlgorithmthat 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 isNum_AmbRadCalunder the time-dependent wrapper and the slot takes anAbstractAmbiguityRadiusCalibrationAlgorithmthat 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 isNum_AmbRadCalunder the time-dependent wrapper and the slot takes anAbstractAmbiguityRadiusCalibrationAlgorithmthat computes it from the prior result, or a plain function of the same five arguments.
xbgt: Whether to pin the long/short decomposition exactly. Whenfalse(the default),lwandsware upper bounds on the positive and negative parts ofw, sobgt,sbgtandgbgtbound the realised exposures and do not pin them. A short budget of0.3then means at most 30% short. Whentrue, the long/short binary indicators forcelw == max(w, 0)andsw == 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 (seeshort_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,) -> ConstraintBlockKeywords 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
- If
sbgtorgbgtis a number: it is finite and>= 0. - If
lcse,cte,smtx,sgmtx,tn,tr,ple,l2,lporlpcis a vector:!isempty. - If
card,l2c,linfc,l1orlinfis a number: it is finite and> 0. lpholds no norm-ceiling rule, andlpcholds no ambiguity-radius rule, seeassert_penalty_coefficient_roleandassert_norm_ceiling_role.- The shapes of
scard,smtx,sltandsstagree, seeassert_subgroup_mip_fields. The shapes ofsgcarde,sgmtx,sgltandsgstagree, seeassert_subgrouped_mip_fields. - If a slot holds an estimator keyed by name (
name_keyed):!isnothing(sets). - If a slot holds a
TimeDependent: the constructor runs again once for each entry of the schedule, seeassert_time_dependent_substitution.
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
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} <: AbstractResolvedHolds 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:
- The prior result
prand the rowsrdof its block. A block that reads no rows holdsnothingin both. - The resolved slots. Each field holds the result of the slot of the block, and the five slots that change their name take the
rof a result:lcsegiveslcsr,ctegivesctr,gcardegivesgcardr,sgcardegivessgcardrandplegivesplr. A Calibration Rule inl2c,lpc,linfc,l1,l2,lporlinfis resolved to its value. - The settings that need no resolution:
card,scard,ss,xbgt,sbgt,gbgt,ccntandcobj.
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, ornothingwhen the block reads no rows.
rd: The returns result to use. The rows of the block, ornothingwhen 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. TheLinearConstraintthe 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 boundsnorm(w, 2) <= l2c * k, wherekis the homogenisation variable, so the ceiling holds on the weights the result reports and the budget does not scale it. Smallerl2cforces a more evenly spread portfolio. Used as a diversification floor via the reciprocal:l2c = 1 / sqrt(m)requires at leastmeffective assets (inv(norm(w, 2)^2) >= m). Norm-constraint family withlpcandlinfc. The bound isNum_NormCeilCalunder the time-dependent wrapper, so the slot takes the ceiling itself, anAbstractNormCeilingCalibrationAlgorithmthat 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. EachLpRegularisationsupplies a norm orderpand a boundval, enforcingnorm(w, p) <= val * k. Smallervalforces a more evenly spread portfolio. Used as a diversification floor via the reciprocal:val = m^(1/p - 1)requires at leastmorder-peffective assets (sum(abs.(w) .^ p)^inv(1 - p) >= m). On weights whose absolute values sum to one, this count isnumber_effective_assetstaken to an arbitrary order. Norm-constraint family withl2candlinfc.
linfc: ∞-norm ceiling on the weights. It caps the largest absolute weight,norm(w, Inf) <= linfc * k. Solinfc = 0.2caps the largest weight at 20% of a fully invested portfolio. Used as a diversification floor via the reciprocal:linfc = 1 / mspreads the portfolio across at leastmassets. Norm-constraint family withl2candlpc. The bound isNum_NormCeilCalunder the time-dependent wrapper, so the slot takes the ceiling itself, anAbstractNormCeilingCalibrationAlgorithmthat 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 isNum_AmbRadCalunder the time-dependent wrapper and the slot takes anAbstractAmbiguityRadiusCalibrationAlgorithmthat 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 isNum_AmbRadCalunder the time-dependent wrapper and the slot takes anAbstractAmbiguityRadiusCalibrationAlgorithmthat 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. Whenfalse(the default),lwandsware upper bounds on the positive and negative parts ofw, sobgt,sbgtandgbgtbound the realised exposures and do not pin them. A short budget of0.3then means at most 30% short. Whentrue, the long/short binary indicators forcelw == max(w, 0)andsw == 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 (seeshort_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 aBudgetRangebounds it. The realised short exposure is only bounded by default, sosbgt = 0.3means at most 30% short unlessxbgtpins the long/short decomposition. Withbgt, it fixes the net and gross exposures only together. To constrain the gross exposure alone, seegbgt.
gbgt: Gross budget (leverage) constraint,sum(lw) + sum(sw). A number pins the gross exposure, and aBudgetRangebounds it. For example,BudgetRange(; lb = nothing, ub = 2.0)caps leverage at 2x.bgtandsbgtpin the net and gross exposures only together, butgbgtconstrains 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 unlessxbgtis set.
ccnt: CustomJuMPconstraint.
cobj: CustomJuMPobjective.
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}) -> ResolvedConstraintBlockKeywords 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) -> ResolvedConstraintBlockBuilds 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
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 forw.
Related
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
- View at
ithe slots that can hold a value for each asset:wb,lt,st,smtx,sgmtx,slt,sst,sglt,sgst,tn,lcse,sets,ccntandcobj. Whensmtxandsgmtxhold the same object, view it once, so that the two views are one object too. The same holds forsltandsglt, and forsstandsgst. - View
tratiwithargs. A tracking measure gives the returns matrixXinargsto the risk measure that it tracks. - Keep every other slot. An estimator in
cte,gcardeorsgcarderesolves its names against the viewedsets. A precomputed constraint in one of them keeps its width, because no view can narrow its matrix, seeport_opt_view(::LinearConstraint, i).plereads the viewed prior of the owner. The other slots hold no value for each asset. - 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 errorstrread, such as the returns matrixXof the full universe, with one column for each asset.
Returns
ConstraintBlock: The block restricted to the assets ati.
Related
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:trueif one of these slots reads the previous weights, andfalseotherwise.
Related
PortfolioOptimisers.obs_weights_view — Method
obs_weights_view(cbe::ConstraintBlock, i) -> ConstraintBlockReturn 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
- Cut every slot of
cbewithobs_weights_view, and rebuild the block with its keyword constructor, throughobs_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