Pipe routing: private API
PortfolioOptimisers.pipe_route — Function
pipe_route(x, ::Val{target}, v)Puts the value of a Routing Target into an optimiser, and returns the rebuilt optimiser.
This is the optimiser half of the routing of a Pipeline slot into an optimiser. inject_context divides a slot of the PipelineContext into Routing Targets, and gives each of them to this function. It does not know which field receives the value.
A target has the name of the field that receives it, for example :pe, :cle, :wb, :lcse or :ple. These names are the field names that the whole package uses, see field_dict, and not the private layout of one optimiser. So the fallback method is the routing rule: a target goes into the field of the same name in each optimiser that has one. No type declares its targets, so no declaration can become wrong.
Two targets have methods of their own, because they check their value and name no plain field. :mu_ucs needs an ArithmeticReturn, and goes into ret.ucs. :sigma_ucs goes into the UncertaintySetVariance measures of r, see @pipe_route_sigma_ucs.
An optimiser that holds its configuration in a field declares @pipe_delegates. An optimiser that holds a ConstraintBlock names its field with pipe_block_field, and a target that is a slot of the block goes into the block. The optimiser keeps its own fields, pe among them. A target with no field in x or in its block goes to unroutable_target, which ignores the optional targets and throws for the others.
Algorithm
- When the type of
xhas a field namedtarget, returnxwithvin that field. - When the block of
xacceptstarget, returnxwith the block rebuilt by this function. - Else return
unroutable_target(x, Val(target), v).
The test is hasfield and not hasproperty, because the rebuild writes the field. A name that only property forwarding reaches can be read but not written.
Arguments
x: The optimiser or the optimiser configuration.::Val{target}: One ofPIPELINE_ROUTING_TARGETS.v: The value to put intox.
Returns
x′: The rebuilt optimiser.
Related
pipe_route(cfg::JuMPOptimiser, _::Val{:mu_ucs}, v) -> Any
Route a mean uncertainty set into a JuMPOptimiser's return estimator.
One of the two Routing Targets that names no plain field: the set lands in ret.ucs, and only an ArithmeticReturn can bound expected returns, so any other return estimator is an error rather than a silent drop.
A vector of return terms is refused for the same reason, from the other side: one set is a neighbourhood of one quantity, so broadcasting it across k terms would apply a ball fitted on one fit to every other one. Name the set on the term it belongs to instead.
Internal machinery — not part of the user-facing API.
Related
PortfolioOptimisers.pipe_accepts — Function
pipe_accepts(x, ::Val{target}) -> BoolReturns true if x has a field for a Routing Target.
For a target that has the name of a field, the answer is hasfield, which is the test of pipe_route. A target that is a slot of the ConstraintBlock of x also gives true, see pipe_block_field. So pipe_accepts returns true exactly for the targets that pipe_route puts into a field. The targets :mu_ucs, :sigma_ucs and :rkb, and the optimisers that declare @pipe_delegates, have methods of their own.
Related
PortfolioOptimisers.pipe_config_field — Function
pipe_config_field(x) -> Union{Nothing, Symbol}Returns the name of the field that holds the optimiser configuration of x, or nothing when x has none.
@pipe_delegates declares the field, and no code guesses it from the field types. So an estimator whose field opt holds an inner estimator, such as SubsetResampling, is not taken for an estimator whose opt holds a JuMPOptimiser.
Related
PortfolioOptimisers.pipe_block_field — Function
pipe_block_field(x) -> Union{Nothing, Symbol}Returns the name of the field that holds the ConstraintBlock of x, or nothing when x holds none.
pipe_route, pipe_accepts and the walks of the paths of a Pipeline read the slots of the block through this field. The slots of a block are properties of its owner and not fields, so hasfield on the owner does not find them. JuMPOptimiser names its field cbe.
Related
PortfolioOptimisers.pipe_block_accepts — Function
pipe_block_accepts(x, t::Val) -> BoolReturns true when x holds a ConstraintBlock and the block accepts the Routing Target t.
Related
PortfolioOptimisers.@pipe_delegates — Macro
@pipe_delegates T fieldDeclares that the optimiser type T gives every Routing Target to the configuration in field.
The macro makes a method of pipe_config_field, and methods of pipe_route and pipe_accepts that call the same function on the configuration. A target for which the configuration has no field goes to the unroutable_target of the configuration, so the error names the configuration.
A type that puts a target into its own field, and not into its configuration, declares that target on the concrete type, see @pipe_route_sigma_ucs. That method is more specific than the methods of this macro.
Examples
@pipe_delegates MeanRisk optRelated
PortfolioOptimisers.route_sigma_ucs — Function
route_sigma_ucs(x, sig::AbstractUncertaintySetResult) -> Any
Puts a covariance uncertainty set into the UncertaintySetVariance risk measures in the field r of an optimiser.
A field r that holds no such measure is an error. Else the computed uncertainty set reaches no risk measure, and no message tells the caller.
Algorithm
- Read the field
rofx. - Replace the
ucsof eachUncertaintySetVariancewithsig. Whenris a vector, do this for each element, and keep the other elements. - Check that the new
rholds at least oneUncertaintySetVariance. - Return
xwith the newr.
Arguments
x: The optimiser. It must have a fieldr.sig: The covariance uncertainty set.
Validation
- The field
rholds anUncertaintySetVariance, or a vector with one, else anArgumentErroris thrown.
Returns
x′: The rebuilt optimiser.
Related
PortfolioOptimisers.@pipe_route_sigma_ucs — Macro
@pipe_route_sigma_ucs TDeclares that the optimiser type T puts the Routing Target :sigma_ucs into its own field r, with route_sigma_ucs.
The covariance uncertainty set goes into the risk measures of the estimator, and every other target goes to its configuration. So this method must be more specific than the method of @pipe_delegates on the same type, and each concrete type declares it. A type declares it only when it has risk measures, because a configuration does not bring them. RelaxedRiskBudgeting has no field r.
Related
PortfolioOptimisers.@pipe_route_rkb — Macro
@pipe_route_rkb TDeclares that the optimiser type T puts the Routing Target :rkb into the field rkb of its risk budgeting algorithm.
:rkb is the one target that names a field one level down. A risk budget belongs to the algorithm, because AssetRiskBudgeting budgets assets and FactorRiskBudgeting budgets factors. So the budget goes into rba.rkb, which the rule of hasfield does not reach.
The answer of pipe_accepts reads the algorithm that the optimiser holds. A TimeDependent in rba has no field rkb, so such an optimiser refuses the target. Then the constructor of a pipeline that computes a budget for it refuses the pipeline, before the fold loop runs.
Each concrete type declares it, for the reason that @pipe_route_sigma_ucs states: it must be more specific than the method of @pipe_delegates on the same type.
Validation
- The field
rbaof the optimiser has a fieldrkb, elsepipe_routethrows anArgumentErrorthat names the type ofrba.
Related