JuMP Optimiser (a)

PortfolioOptimisers.ResolvedJuMPOptimiser — Type
struct ResolvedJuMPOptimiser{__T_pr, __T_fees, __T_imsk, __T_cbr} <: AbstractResolved

Holds 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 the JuMP model. Several terms are weighted-summed into the model's single scalar return expression, in the same way MeanRisk's r takes several risk measures.
  • sca: The scalariser the optimisation ran under, taken from opt.sca. Pass it back as expected_risk(res.r, res.w, res.pr; sca = res.sca) so the reported figure matches the optimised one. The type of sca is 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: true at every asset whose prior moments were finite. It is nothing when every asset was investable, and that sentinel is what skips both the reduction and the expansion. investable_mask derives it once from the full-universe prior result, and the result carries it, because the reduced prior can no longer yield it.

Constructors

ResolvedJuMPOptimiser(;    pr::AbstractPriorResult, fees::Option{<:Fees}, ret::JRE_VecJRE, sca::Option{<:Scalariser},    imsk::Option{<:BitVector} = nothing, cbr::Rcb_VecRcb) -> ResolvedJuMPOptimiser

Keywords 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.wbtrue

Related

source
PortfolioOptimisers.JuMPOptimisationResult — Type
struct JuMPOptimisationResult{__T_jor, __T_retcode, __T_sol, __T_model} <: BaseJuMPOptimisationResult

Holds 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: The ResolvedJuMPOptimiser of the fit: its prior result, fees, return terms, scalariser, Investable Mask and the Resolved Constraint Block in cbr.
  • 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}) -> JuMPOptimisationResult

Keywords 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.imsk is a mask, each weight vector of sol holds one weight for each true entry of the mask. Otherwise the constructor raises a DimensionMismatch.

Related

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

Holds 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, see ConstraintBlock. Its slots are flat keywords and properties of the owner.
  • bgt: Net budget, 1ᵀw. A number pins it, a BudgetRange bounds it. By default a budget bounds the realised exposure and does not pin it, see xbgt. With sbgt, it fixes the net and gross exposures only together. To constrain the gross exposure alone, see gbgt.
  • fees: Fee estimator or fee structure.
  • ret: Return term, or vector of return terms, for the JuMP model. Several terms are weighted-summed into the model's single scalar return expression, in the same way MeanRisk's r takes several risk measures.
  • sca: Scalariser for combining multiple risk measures. nothing gives the sum of SumScalariser.
  • sc: Constraint scale factor.
  • so: Objective scale factor.
  • strict: Whether a constraint that names an asset or a group that sets does not hold raises an error. When it is false, the constraint generator warns and skips the entry. Under true the fit also refuses an asset with a gap in the rows that a plain graph reader reads, which it otherwise drops with a warning, see graph_reader_mask. It also refuses an asset that a distance reader of the fit cannot estimate, which it otherwise drops with a warning, see distance_reader_refusal_mask.
  • cache: Optional ReturnsBufferState, the fold context of the online step. It is nothing until partial_fit! writes one, and optimise(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. factory carries it unchanged and port_opt_view slices 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...,) -> JuMPOptimiser

Keywords 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 slv is a vector: !isempty(slv).
  • If bgt is a number: isfinite(bgt).
  • If bgt is a BudgetCostEstimator: isnothing(sbgt). Otherwise the constructor raises a ConflictingArgumentError.
  • If sbgt or gbgt is a number: it is finite and >= 0.
  • If gbgt is not nothing: bgt and sbgt are not both numbers, see assert_gross_budget_admissible. Two numbers fix the gross budget of the model at bgt + 2 * sbgt, which is the row that gbgt writes. The realised gross exposure norm(w, 1) equals this budget when xbgt is true, and it can be smaller when xbgt is false.
  • If gbgt is not nothing and wb is a WeightBounds: wb admits a negative weight. The check of an AbstractWeightBoundsEstimator waits for the solve.
  • If gbgt has an upper end: it is non-negative, and it is at least the least magnitude that bgt admits, see assert_gross_budget_reaches_net. The gross exposure is at least abs(sum(w)), so a smaller gross budget leaves no feasible weights. An ArgumentError is thrown otherwise.
  • If lcse, cte, smtx, sgmtx, tn, tr, ple, l2, lp or lpc is a vector: !isempty. An empty l2, lp or lpc builds no term, which is what nothing states.
  • If card, l2c, linfc, l1 or linf is a number: it is finite and > 0. l1 and linf also take an ambiguity-radius rule, and l2c and linfc a 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 LpRegularisation agrees with the field that holds it. lp is a penalty, so it refuses a norm-ceiling rule, and lpc is 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 of L2Regularisation and LpRegularisation check the other values of l2, lp and lpc.
  • The shapes of scard, smtx, slt and sst agree, see assert_subgroup_mip_fields. The shapes of sgcarde, sgmtx, sglt and sgst agree, see assert_subgrouped_mip_fields.
  • If a slot holds an estimator keyed by name (name_keyed), or fees is a FeesEstimator: !isnothing(sets).
  • If tr holds a DataBenchmarkTracking: pe does not state x_src = ExcessSource(), see assert_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, see assert_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

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

Examples

julia> opt = JuMPOptimiser(; slv = Solver(; solver = nothing));julia> PortfolioOptimisers.factory(opt, fill(0.1, 10)) isa JuMPOptimisertrue

Related

source
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

  1. When opt.pe is a prior result, replace X with opt.pe.X.
  2. View at i the fields that can hold a value for each asset: pe, bgt, ret and cache.
  3. View fees at i with X. A fee finds the assets outside i, which its liquidation charges read, from the width of X.
  4. View the ConstraintBlock in cbe at i with X, 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 read X.
  5. Keep every other field. They hold no value for each asset.
  6. 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 in opt.pe gives its own X in its place.

Returns

  • JuMPOptimiser: The optimiser restricted to the assets at i.

Examples

julia> opt = JuMPOptimiser(; slv = Solver(; solver = nothing));julia> X = rand(50, 5);julia> PortfolioOptimisers.port_opt_view(opt, 1:3, X) isa JuMPOptimisertrue

Related

source
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: true if one of these fields reads the previous weights, and false otherwise.

Examples

julia> PortfolioOptimisers.needs_previous_weights(JuMPOptimiser(;                                                                slv = Solver(; solver = nothing)))false

Related

source
PortfolioOptimisers.obs_weights_view — Method
obs_weights_view(opt::JuMPOptimiser, i) -> JuMPOptimiser

Return 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

  1. Cut every field of opt with obs_weights_view, and rebuild the optimiser with its keyword constructor, through obs_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 in cache comes back as nothing. 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

Returns

  • JuMPOptimiser: The optimiser at the kept observations.

Related

source