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

  1. When the type of x has a field named target, return x with v in that field.
  2. When the block of x accepts target, return x with the block rebuilt by this function.
  3. 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 of PIPELINE_ROUTING_TARGETS.
  • v: The value to put into x.

Returns

  • x′: The rebuilt optimiser.

Related

source
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

source
PortfolioOptimisers.pipe_accepts — Function
pipe_accepts(x, ::Val{target}) -> Bool

Returns 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

source
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

source
PortfolioOptimisers.@pipe_delegates — Macro
@pipe_delegates T field

Declares 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 opt

Related

source
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

  1. Read the field r of x.
  2. Replace the ucs of each UncertaintySetVariance with sig. When r is a vector, do this for each element, and keep the other elements.
  3. Check that the new r holds at least one UncertaintySetVariance.
  4. Return x with the new r.

Arguments

  • x: The optimiser. It must have a field r.
  • sig: The covariance uncertainty set.

Validation

Returns

  • x′: The rebuilt optimiser.

Related

source
PortfolioOptimisers.@pipe_route_sigma_ucs — Macro
@pipe_route_sigma_ucs T

Declares 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

source
PortfolioOptimisers.@pipe_route_rkb — Macro
@pipe_route_rkb T

Declares 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 rba of the optimiser has a field rkb, else pipe_route throws an ArgumentError that names the type of rba.

Related

source