JuMP Optimiser (a)
PortfolioOptimisers.ResolvedJuMPOptimiser — Type
struct ResolvedJuMPOptimiser{__T_pr, __T_fees, __T_imsk, __T_cbr} <: AbstractResolvedHolds the Result of the resolution of a JuMP head: the prior result, the fees, the return terms, the scalariser, the Investable Mask and the Resolved Constraint Block.
resolve_jump_optimiser makes the bundle once for each optimise call, and assemble_jump_model! reads it. So each builder of the model reads a result, and no builder resolves an estimator again. The constraints of the feasible set are in the ResolvedConstraintBlock in cbr. The owner keeps the fees, the return terms and the scalariser, because the objective reads them.
cbr holds the block Result of the head, or a vector of block Results when the head has more than one block. The block of the head is then the first, and owner_block gives it.
A named forward rule keeps the reads of the resolved constraints on the bundle, so jor.wb reads owner_block(jor.cbr).wb. The rule forwards wb, lt, st, lcsr, ctr, gcardr, sgcardr, smtx, sgmtx, slt, sst, sglt, sgst, tn and plr, the constraint fields that the bundle held before it held the block. Every other field of the block is read through cbr.
Every JuMP optimisation Result holds the bundle. So the types of ret and sca are not type parameters of the bundle, and the Results of two returns estimators or of two scalarisers have one type. A verb that reads them compiles one time.
Fields
pr: Prior result.
fees: Fees result.
ret: Return term, or vector of return terms, for theJuMPmodel. Several terms are weighted-summed into the model's single scalar return expression, in the same wayMeanRisk'srtakes several risk measures.
sca: The scalariser the optimisation ran under, taken fromopt.sca. Pass it back asexpected_risk(res.r, res.w, res.pr; sca = res.sca)so the reported figure matches the optimised one. The type ofscais not a type parameter, so the Results of two scalarisers have one type, and a verb that reads them compiles one time.
imsk: The Investable Mask the optimisation reduced on:trueat every asset whose prior moments were finite. It isnothingwhen every asset was investable, and that sentinel is what skips both the reduction and the expansion.investable_maskderives it once from the full-universe prior result, and the result carries it, because the reduced prior can no longer yield it.
cbr: The Resolved Constraint Block of the fit, aResolvedConstraintBlock, or a vector of them.
Constructors
ResolvedJuMPOptimiser(; pr::AbstractPriorResult, fees::Option{<:Fees}, ret::JRE_VecJRE, sca::Option{<:Scalariser}, imsk::Option{<:BitVector} = nothing, cbr::Rcb_VecRcb) -> ResolvedJuMPOptimiserKeywords correspond to the struct's fields. Make the bundle with resolve_jump_optimiser. The constructor checks the types of the fields and no value, because the resolution checked the values.
ret is a returns estimator and not a result, because a returns estimator has no result form. Before the bundle held the block, it held one field for each resolved constraint. Those fields are now fields of cbr, and the forward rule reads them.
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> jor = ResolvedJuMPOptimiser(; pr = pr, fees = nothing, ret = ArithmeticReturn(), sca = nothing, cbr = cbr);julia> jor.wb === jor.cbr.wbtrueRelated
PortfolioOptimisers.JuMPOptimisationResult — Type
struct JuMPOptimisationResult{__T_jor, __T_retcode, __T_sol, __T_model} <: BaseJuMPOptimisationResultHolds the fields that every JuMP optimisation result shares.
Each concrete JuMP result holds it as its first field, jr, as each JuMP optimiser holds a JuMPOptimiser as opt. The concrete result adds its own fields and the last field fb.
The result holds the weights on the full asset universe of the caller. The solver solves over the investable assets alone, and model keeps that reduced problem when the head saves the model. The property w reads the weights of sol, and a vector of solutions gives a vector of weight vectors. A property name that is neither w nor a field reads the field of jor of the same name.
Fields
jor: TheResolvedJuMPOptimiserof the fit: its prior result, fees, return terms, scalariser, Investable Mask and the Resolved Constraint Block incbr.
retcode: Optimisation return code.
sol: Optimisation solution.
model: :JuMP.Model`: The JuMP optimisation model.
Constructors
JuMPOptimisationResult(; jor::ResolvedJuMPOptimiser, retcode::OptRetCode_VecOptRetCode, sol::JuMPOptSol_VecJuMPOptSol, model::Option{<:JuMP.Model}) -> JuMPOptimisationResultKeywords correspond to the struct's fields. The keyword constructor expands the weights of sol from the investable assets to the full asset universe with expand_investable_weights, at the mask jor.imsk. An asset outside the mask gets the weight zero. When jor.imsk is nothing, sol is kept unchanged.
Validation
- When
jor.imskis a mask, each weight vector ofsolholds one weight for eachtrueentry of the mask. Otherwise the constructor raises aDimensionMismatch.
Related
BaseJuMPOptimisationResultRiskJuMPOptimisationResultJuMPOptimiserset_retcode: Rebuilds the result with a new return code, and does not expand the weights again.
PortfolioOptimisers.JuMPOptimiser — Type
struct JuMPOptimiser{__T_pe, __T_slv, __T_cbe, __T_bgt, __T_fees, __T_ret, __T_sca, __T_sc, __T_so, __T_strict, __T_cache} <: BaseJuMPOptimisationEstimatorHolds the problem definition and the solver settings that every JuMP optimiser shares.
It holds the prior estimator, the solvers, the net budget, the fees, the return term, the scalariser and the execution settings. The ConstraintBlock in its field cbe holds the feasible set of the weights: the bounds, the leverage caps, the constraints, the tracking and the regularisation. Give it to a JuMP optimiser such as MeanRisk or RiskBudgeting, which adds the objective and the risk measure.
Each slot of the block is a property of the optimiser, so opt.wb reads opt.cbe.wb. Accessors.set(opt, @optic(_.wb), v) and a search key such as "opt.wb" replace that slot of the block, and a Pipeline routes a target such as :wb into the block, see pipe_block_field.
Fields
pe: Prior estimator.
slv: Solver or vector of solvers.
cbe: Constraint Block that holds the feasible set of the weights and the terms of the Objective Penalty, seeConstraintBlock. Its slots are flat keywords and properties of the owner.
bgt: Net budget,1ᵀw. A number pins it, aBudgetRangebounds it. By default a budget bounds the realised exposure and does not pin it, seexbgt. Withsbgt, it fixes the net and gross exposures only together. To constrain the gross exposure alone, seegbgt.
fees: Fee estimator or fee structure.
ret: Return term, or vector of return terms, for theJuMPmodel. Several terms are weighted-summed into the model's single scalar return expression, in the same wayMeanRisk'srtakes several risk measures.
sca: Scalariser for combining multiple risk measures.nothinggives the sum ofSumScalariser.
sc: Constraint scale factor.
so: Objective scale factor.
strict: Whether a constraint that names an asset or a group thatsetsdoes not hold raises an error. When it isfalse, the constraint generator warns and skips the entry. Undertruethe fit also refuses an asset with a gap in the rows that a plain graph reader reads, which it otherwise drops with a warning, seegraph_reader_mask. It also refuses an asset that a distance reader of the fit cannot estimate, which it otherwise drops with a warning, seedistance_reader_refusal_mask.
cache: OptionalReturnsBufferState, the fold context of the online step. It isnothinguntilpartial_fit!writes one, andoptimise(opt)with no returns reads it. The returns themselves are carried by the prior, which owns the rows once; this holds every other column of the returns data and the context pinned at the first step.factorycarries it unchanged andport_opt_viewslices it to the selected assets.
Constructors
JuMPOptimiser(; pe::Onl{<:TD{<:PrE_Pr}} = EmpiricalPrior(), slv::Slv_VecSlv, cbe::Option{<:ConstraintBlock} = nothing, bgt::TD_Option{<:Num_BgtCE} = 1.0, fees::TD_Option{<:FeesE_Fees} = nothing, ret::TD{<:JRE_VecJRE} = ArithmeticReturn(), sca::TD_Option{<:NonHierarchicalScalariser} = nothing, sc::Number = 1, so::Number = 1, strict::Bool = false, cache::Option{<:ReturnsBufferState} = nothing, slots...,) -> JuMPOptimiserKeywords correspond to the struct's fields and to the slots of ConstraintBlock. slots... takes each keyword of the block with its type and its default: 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 and xbgt. The constructor builds the block in cbe from these flat keywords, with the defaults of the block. When the caller gives cbe, a flat keyword replaces that slot of the given block, and a slot that the caller does not name keeps its value, see constraint_block. So the default of a flat keyword never overwrites a slot of a given block. A name that is neither a field nor a slot raises a MethodError.
A field or a slot typed TD_Option or TD can hold a TimeDependent schedule in place of a static value. A cross-validation fold loop resolves the schedule at each fold, and an optimise call outside a fold loop reads the static default of the field. So the prior estimator, the returns model, the scalariser, the asset sets and the constraints can change from fold to fold. The execution settings slv, sc, so and strict are static.
lcse, sgcarde, smtx, sgmtx, slt, sst, sglt, sgst, tn and ple take a vector that mixes the members of their element type, such as [Turnover(…), TurnoverEstimator(…)]. Such a literal infers an element type that the positional constructor refuses, so the keyword constructor of the block narrows it through narrow_mixed_vector, and the caller writes no concrete_typed_array.
The positional constructor takes the fields in the order of the struct: pe, slv, cbe, bgt, fees, ret, sca, sc, so, strict and cache. Before the block, it took one argument for each slot.
Validation
The constructor of ConstraintBlock checks each slot on its own. This constructor checks the fields and the rules that read a field and a slot together.
- If
slvis a vector:!isempty(slv). - If
bgtis a number:isfinite(bgt). - If
bgtis aBudgetCostEstimator:isnothing(sbgt). Otherwise the constructor raises aConflictingArgumentError. - If
sbgtorgbgtis a number: it is finite and>= 0. - If
gbgtis notnothing:bgtandsbgtare not both numbers, seeassert_gross_budget_admissible. Two numbers fix the gross budget of the model atbgt + 2 * sbgt, which is the row thatgbgtwrites. The realised gross exposurenorm(w, 1)equals this budget whenxbgtistrue, and it can be smaller whenxbgtisfalse. - If
gbgtis notnothingandwbis aWeightBounds:wbadmits a negative weight. The check of anAbstractWeightBoundsEstimatorwaits for the solve. - If
gbgthas an upper end: it is non-negative, and it is at least the least magnitude thatbgtadmits, seeassert_gross_budget_reaches_net. The gross exposure is at leastabs(sum(w)), so a smaller gross budget leaves no feasible weights. AnArgumentErroris thrown otherwise. - If
lcse,cte,smtx,sgmtx,tn,tr,ple,l2,lporlpcis a vector:!isempty. An emptyl2,lporlpcbuilds no term, which is whatnothingstates. - If
card,l2c,linfc,l1orlinfis a number: it is finite and> 0.l1andlinfalso take an ambiguity-radius rule, andl2candlinfca norm-ceiling rule. A rule states no number at construction, so stage 2 of the block,resolve_constraint_block, checks the number that the rule returns. - The rule in each
LpRegularisationagrees with the field that holds it.lpis a penalty, so it refuses a norm-ceiling rule, andlpcis a constraint, so it refuses an ambiguity-radius rule. The term has one field for both readings, so the constructor of the block is the first point that knows the reading. The constructors ofL2RegularisationandLpRegularisationcheck the other values ofl2,lpandlpc. - 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), orfeesis aFeesEstimator:!isnothing(sets). - If
trholds aDataBenchmarkTracking:pedoes not statex_src = ExcessSource(), seeassert_data_benchmark_prior. - If a field or a slot holds a
TimeDependent: the constructor runs again once for each entry of the schedule, with the other schedules at their static defaults, seeassert_time_dependent_substitution. So a type error or a conflict between two fields shows at construction. A check that couples a schedule to a static field runs again when each fold rebuilds the optimiser.
A value outside its bound raises an IsEmptyError, an IsNonFiniteError, a DomainError, an IsNothingError, an ArgumentError or a DimensionMismatch, as the helper that checks it states.
Related
PortfolioOptimisers.factory — Method
factory(
opt::JuMPOptimiser,
w::AbstractVector
) -> JuMPOptimiser
Returns a copy of opt whose fields that read previous weights hold the weights w.
The function calls factory(x, w) on bgt and fees, and on the ConstraintBlock in cbe, whose method rebuilds tn, tr, ccnt and cobj. It keeps every other field. So a cost budget on bgt measures its cost from w, unless it is fixed, see factory(bgt::BudgetCosts, w::VecNum). A TimeDependent in one of these fields applies factory to each of its entries. The keyword constructor of JuMPOptimiser checks the new fields.
Arguments
opt::JuMPOptimiser: The JuMP optimiser.w::AbstractVector: The new portfolio weights.
Returns
JuMPOptimiser: The optimiser with the two fields and the block rebuilt forw.
Examples
julia> opt = JuMPOptimiser(; slv = Solver(; solver = nothing));julia> PortfolioOptimisers.factory(opt, fill(0.1, 10)) isa JuMPOptimisertrueRelated
PortfolioOptimisers.port_opt_view — Method
port_opt_view(
opt::JuMPOptimiser,
i,
X::AbstractMatrix{<:Union{Number, AbstractJuMPScalar}},
args...
) -> JuMPOptimiser
Returns a copy of opt restricted to the assets at the indices i.
A hierarchical optimiser calls it to build the optimiser of one cluster, and the entry of a fit calls it to restrict the optimiser to the Investable Mask.
Algorithm
- When
opt.peis a prior result, replaceXwithopt.pe.X. - View at
ithe fields that can hold a value for each asset:pe,bgt,retandcache. - View
feesatiwithX. A fee finds the assets outsidei, which its liquidation charges read, from the width ofX. - View the
ConstraintBlockincbeatiwithX, through its own method,port_opt_view(cbe::ConstraintBlock, i, X). It views the slots that hold a value for each asset, and its tracking errors readX. - Keep every other field. They hold no value for each asset.
- Rebuild the optimiser with its keyword constructor, which checks the viewed fields again.
Arguments
opt::JuMPOptimiser: The JuMP optimiser.i: The indices of the assets that the view keeps.X::MatNum: The returns matrix of the full universe, with one column for each asset. A prior result inopt.pegives its ownXin its place.
Returns
JuMPOptimiser: The optimiser restricted to the assets ati.
Examples
julia> opt = JuMPOptimiser(; slv = Solver(; solver = nothing));julia> X = rand(50, 5);julia> PortfolioOptimisers.port_opt_view(opt, 1:3, X) isa JuMPOptimisertrueRelated
PortfolioOptimisers.needs_previous_weights — Method
needs_previous_weights(opt::JuMPOptimiser) -> Any
Returns true if a field of opt reads the portfolio weights of the previous fold.
The function asks bgt and fees, and the ConstraintBlock in cbe through its own method, which asks tn, tr, ccnt and cobj. It also asks every field and every slot that holds a TimeDependent that the fold loop resolves, see time_dependent_fields. A schedule reads the previous weights when it holds a PreviousWeightsFunction or an entry that reads them.
Arguments
opt::JuMPOptimiser: The JuMP optimiser.
Returns
Bool:trueif one of these fields reads the previous weights, andfalseotherwise.
Examples
julia> PortfolioOptimisers.needs_previous_weights(JuMPOptimiser(; slv = Solver(; solver = nothing)))falseRelated
PortfolioOptimisers.obs_weights_view — Method
obs_weights_view(opt::JuMPOptimiser, i) -> JuMPOptimiserReturn a copy of opt whose fields hold their observation weights cut to the observations i.
The optimiser is not @propagatable, so it needs this method of obs_weights_view. Its prior, its phylogeny and centrality estimators, its tracking measure and its returns estimator all read the observations of the sample, and each can hold fixed observation weights. A cut of the observations of a solve, such as the drop of a Shared Series gap, must reach each of them, see shared_series_estimator.
Algorithm
- Cut every field of
optwithobs_weights_view, and rebuild the optimiser with its keyword constructor, throughobs_weights_fields. A field that holds no estimator, such as a solver, a bound or a set of names, comes back with no change, and a partial-fit state incachecomes back asnothing. The constructor checks the cut fields again.
Arguments
opt::JuMPOptimiser: The JuMP optimiser.i: The observations to keep: a mask of the full sample, or their positions.
Validation
- The rules of
obs_weights_indexfor each weights field in the tree ofopt.
Returns
JuMPOptimiser: The optimiser at the kept observations.
Related