GitHub

Base optimisation

All optimisers are defined as their whole names, however this can be unwieldy, so we also provide convenience aliases defined in API.

PortfolioOptimisers.AbstractOptimisationEstimator — Type
abstract type AbstractOptimisationEstimator <: AbstractEstimator

Abstract supertype for all portfolio optimisation estimators.

All optimisers and optimisation components should subtype AbstractOptimisationEstimator to participate in the optimisation dispatch system.

Interfaces

AbstractOptimisationEstimator declares no method of its own. It carries the default port_opt_view, which returns the estimator unchanged, and it splits into two halves. Subtype BaseOptimisationEstimator for a configuration an optimiser holds, and OptimisationEstimator for an estimator optimise runs.

Related

source
PortfolioOptimisers.BaseOptimisationEstimator — Type
abstract type BaseOptimisationEstimator <: AbstractOptimisationEstimator

Abstract supertype for base portfolio optimisation estimators.

BaseOptimisationEstimator is the parent for all internal optimiser components that configure the optimisation problem but are not directly invokable as top-level optimisers.

Interfaces

A subtype gains the time-dependent host methods from this supertype: is_time_dependent, update_time_dependent_estimator, reset_time_dependent_estimator and assert_time_dependent_fold_count all scan its fields generically, through time_dependent_fields. One method is worth implementing:

time_dependent_field_defaults

  • time_dependent_field_defaults(opt::MyConfiguration) -> NamedTuple: The static default of each field that may hold a TimeDependent, for those whose default is not nothing. A required field is listed with NoDefault, which declares that a schedule there must carry its own default.

Arguments

  • opt: The concrete subtype instance.

Returns

  • defaults::NamedTuple: The fold-less value of each listed field. The fallback method returns an empty tuple, which gives every scheduled field the fold-less value nothing.

Related

source
PortfolioOptimisers.OptimisationEstimator — Type
abstract type OptimisationEstimator <: AbstractOptimisationEstimator

Abstract supertype for portfolio optimisation estimators that produce portfolio weights.

Subtype OptimisationEstimator to implement concrete portfolio optimisers. All optimisers that can be invoked with optimise should subtype this.

Interfaces

In order to implement a new optimiser that works seamlessly with the library, subtype OptimisationEstimator, give it an fb field, and implement the following method:

_optimise

  • _optimise(opt::MyOptimiser, rd::ReturnsResult, args...; kwargs...) -> OptimisationResult: Solves the problem opt states over the data in rd, and returns the optimiser's own result type.

Arguments

  • opt: The concrete subtype instance.
  • rd: Returns data.
  • args..., kwargs...: Forwarded from optimise.

Returns

  • res::OptimisationResult: The result, whose retcode decides whether optimise walks on to the fallback.

The fb field

optimise reads opt.fb to walk the fallback chain, so every subtype carries one. It holds the next optimiser to try, or nothing to end the chain.

Related

source
PortfolioOptimisers.NonFiniteAllocationOptimisationEstimator — Type
abstract type NonFiniteAllocationOptimisationEstimator <: OptimisationEstimator

Abstract supertype for portfolio optimisation estimators that produce continuous (non-integer) portfolio weights.

Interfaces

NonFiniteAllocationOptimisationEstimator adds no method to OptimisationEstimator. It marks the optimisers whose weights are continuous, which is what admits them to the cross-validation and meta-optimisation entry points (see OptE_Opt).

Related

source
PortfolioOptimisers.pipe_route — Function
pipe_route(x, ::Val{target}, v)

Absorb a Routing Target's value into an optimiser, returning the rebuilt optimiser.

This is the optimiser-owned half of the Pipeline seam: inject_context fans a PipelineContext slot out into routing targets and delivers each one here, knowing nothing about where it lands.

Targets are named after the field they land in — :pe, :cle, :wb, :lcse, :ple — because those names are this package's shared vocabulary (see field_dict) rather than any one optimiser's private layout. The default method therefore is the routing rule: a target lands in the like-named field of any optimiser that has one. Nothing is declared per type, so nothing can drift.

Two targets are exceptions, because they carry validation policy and name no plain field: :mu_ucs (requires an ArithmeticReturn, lands in ret.ucs) and :sigma_ucs (lands in the UncertaintySetVariance measures of r, see @pipe_route_sigma_ucs).

Optimisers holding their configuration in a field rather than carrying the target fields themselves declare @pipe_delegates.

The lookup is hasfield rather than hasproperty, because routing rebuilds the object through the field: a name reachable only as a forwarded property could be read but not set.

A target with no home falls through to unroutable_target, which ignores the optional ones and throws for the rest.

Internal machinery — not part of the user-facing API.

Arguments

  • x: The optimiser or optimiser configuration.
  • ::Val{target}: One of PIPELINE_ROUTING_TARGETS.
  • v: The computed result to absorb.

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 (ADR 0050), so broadcasting it across k terms would apply a ball fitted on one fit to every other one — the very defect #277 removed. Name the set on the term it belongs to instead.

Internal machinery — not part of the user-facing API.

Related

source
PortfolioOptimisers.@pipe_delegates — Macro
@pipe_delegates T field

Declare that optimiser type T forwards every Routing Target to the configuration held in field.

Emits pipe_config_field plus forwarding pipe_route and pipe_accepts methods. Targets the configuration has no home for reach its own unroutable_target, so the resulting error names the configuration — matching the pre-inversion messages.

A type that absorbs a target itself rather than through its configuration declares that target on the concrete type (see @pipe_route_sigma_ucs), which out-specialises this forwarder.

Examples

@pipe_delegates MeanRisk opt

Related

source
PortfolioOptimisers.route_sigma_ucs — Function
route_sigma_ucs(x, sig::AbstractUncertaintySetResult) -> Any

Route a covariance uncertainty set into the UncertaintySetVariance risk measure(s) held in an optimiser's r field.

Each UncertaintySetVariance found — directly or inside a vector — has its ucs replaced with sig. An r field carrying no such measure is an error rather than a silent no-op: a computed uncertainty set that reaches no risk measure would be dropped.

Internal machinery — not part of the user-facing API.

Arguments

  • x: The optimiser, which must carry an r field.
  • sig: The covariance uncertainty set result.

Returns

  • x′: The rebuilt optimiser.

Related

source
PortfolioOptimisers.@pipe_route_sigma_ucs — Macro
@pipe_route_sigma_ucs T

Declare that optimiser type T absorbs the :sigma_ucs Routing Target into its own r field via route_sigma_ucs.

Declared per concrete type rather than on a supertype: the covariance uncertainty set lands in the estimator's risk measures while every other target is forwarded to its configuration, so this method must out-specialise the @pipe_delegates forwarder on the same type. It is opt-in because carrying a configuration does not imply carrying risk measures — RelaxedRiskBudgeting has no r field.

Related

source
PortfolioOptimisers.@pipe_route_rkb — Macro
@pipe_route_rkb T

Declare that optimiser type T absorbs the :rkb Routing Target into the rkb field of its risk-budgeting algorithm.

:rkb is the one target named after a field an optimiser does not carry directly. A risk budget belongs to the algorithm — AssetRiskBudgeting budgets assets, FactorRiskBudgeting budgets factors — so it lands one level down, at rba.rkb, and the derived hasfield rule cannot reach it.

Acceptance is not a constant: it asks the algorithm the optimiser is actually carrying. A TimeDependent schedule in rba has no rkb to write, so such an optimiser declines the target and a pipeline computing a budget for it is refused at construction rather than failing in the fold loop.

Declared per concrete type, for the same reason as @pipe_route_sigma_ucs: it must out-specialise the @pipe_delegates forwarder on the same type.

Related

source
PortfolioOptimisers.OptimisationAlgorithm — Type
abstract type OptimisationAlgorithm <: AbstractAlgorithm

Abstract supertype for optimisation algorithms used by portfolio optimisers.

Interfaces

A subtype is a tag that an optimiser dispatches on, so it declares no method of its own. To add a behaviour, subtype OptimisationAlgorithm and add the methods of the consuming optimiser that are specialised on it.

Related

source
PortfolioOptimisers.OptimisationResult — Type
abstract type OptimisationResult <: AbstractResult

Abstract supertype for portfolio optimisation result types.

All concrete optimisation result types should subtype OptimisationResult.

Interfaces

A subtype declares no method, but optimise and factory read three properties of it. A subtype exposes them either as its own fields or by forwarding from an embedded core, as the JuMP and hierarchical leaves do:

  • w: The portfolio weights.
  • retcode: An OptimisationReturnCode. optimise walks the fallback chain until it reads an OptimisationSuccess.
  • fb: The record of the fallbacks that ran. It must be the last field of the struct, because factory rebuilds the result by replacing its trailing field.

Related

source
PortfolioOptimisers.NonFiniteAllocationOptimisationResult — Type
abstract type NonFiniteAllocationOptimisationResult <: OptimisationResult

Abstract supertype for continuous (non-integer allocation) optimisation results.

Interfaces

The family adds no method to OptimisationResult, but it is the bound of the generic factory(res, fb) that rebuilds a result with a new fallback record, which is why the trailing fb field is required here rather than one level up.

Related

source
PortfolioOptimisers.OptimisationReturnCode — Type
abstract type OptimisationReturnCode <: AbstractResult

Abstract supertype for optimisation return codes.

Concrete subtypes indicate whether an optimisation succeeded or failed.

Interfaces

A subtype declares no method. It carries one field, res, which holds the diagnostic text of a failure or nothing. optimise tests the code by type alone: only an OptimisationSuccess ends the fallback chain, so any other subtype is read as a failure.

Related

source
PortfolioOptimisers.OptimisationModelResult — Type
abstract type OptimisationModelResult <: AbstractResult

Abstract supertype for intermediate optimisation model results.

Sits off the optimisation-result tree, like BaseHierarchicalOptimisationResult does: an intermediate record is not a thing optimise returns. Its one subtype is JuMPOptimisationSolution, the record of what a solver returned.

Interfaces

A subtype is a record of one solver attempt, and it declares no method. It is held by a result rather than returned by an optimiser.

Related

source
PortfolioOptimisers.OptimisationSuccess — Type
struct OptimisationSuccess{__T_res} <: OptimisationReturnCode

Indicates that a portfolio optimisation completed successfully.

Fields

  • res: Optional result or message from the solver.

Constructors

OptimisationSuccess(; res = nothing) -> OptimisationSuccess

Keywords correspond to the struct's fields.

Examples

julia> OptimisationSuccess()OptimisationSuccess  res ┴ nothing

Related

source
PortfolioOptimisers.OptimisationFailure — Type
struct OptimisationFailure{__T_res} <: OptimisationReturnCode

Indicates that a portfolio optimisation failed.

Fields

  • res: Optional result or message from the solver.

Constructors

OptimisationFailure(; res = nothing) -> OptimisationFailure

Keywords correspond to the struct's fields.

Examples

julia> OptimisationFailure()OptimisationFailure  res ┴ nothing

Related

source
PortfolioOptimisers.JuMPWeightFinaliserFormulation — Type
abstract type JuMPWeightFinaliserFormulation <: AbstractAlgorithm

Abstract supertype for JuMP-based weight finaliser formulations.

Defines the interface for norm types used when adjusting portfolio weights to satisfy bounds via a JuMP model.

Interfaces

In order to implement a new formulation that works seamlessly with the library, subtype JuMPWeightFinaliserFormulation and implement the following method:

set_clustering_weight_finaliser_alg!

  • set_clustering_weight_finaliser_alg!(model::JuMP.Model, alg::MyFormulation, wi::VecNum) -> Nothing: Adds the deviation objective to a model that already carries the decision vector w, the budget equality and the weight bounds.

Arguments

  • model: The JuMP model, built by opt_weight_bounds.
  • alg: The concrete subtype instance.
  • wi: The weights the optimisation produced, which the model repairs.

Returns

  • nothing. The method works by adding variables, constraints and the objective to model.

Related

source
PortfolioOptimisers.RelativeErrorWeightFinaliser — Type
struct RelativeErrorWeightFinaliser <: JuMPWeightFinaliserFormulation

Minimises the L1 norm of relative weight deviations when enforcing weight bounds.

Mathematical definition

\[\begin{align} \underset{\boldsymbol{w}}{\min} &\quad \left\lVert \boldsymbol{w} \oslash \boldsymbol{w}_{0} - \boldsymbol{1} \right\rVert_{1}\,, \\ \textrm{s.t.} &\quad \boldsymbol{1}^\intercal \boldsymbol{w} = \boldsymbol{1}^\intercal \boldsymbol{w}_{0}\,, \\ &\quad \boldsymbol{l} \leq \boldsymbol{w} \leq \boldsymbol{u}\,. \end{align}\]

Where:

  • $\boldsymbol{w}$: Portfolio weights vector $N \times 1$.
  • $\boldsymbol{w}_{0}$: Portfolio weights vector $N \times 1$ that the optimisation produced, which the finaliser repairs.
  • $\boldsymbol{l}$, $\boldsymbol{u}$: Lower and upper weight bounds. An absent bound is dropped from the programme rather than set to an infinity.
  • $\oslash$: Elementwise division. A zero entry of $\boldsymbol{w}_{0}$ is replaced by eps before the division, so the ratio stays finite.

Constructors

RelativeErrorWeightFinaliser() -> RelativeErrorWeightFinaliser

Examples

julia> RelativeErrorWeightFinaliser()RelativeErrorWeightFinaliser()

Related

source
PortfolioOptimisers.SquaredRelativeErrorWeightFinaliser — Type
struct SquaredRelativeErrorWeightFinaliser <: JuMPWeightFinaliserFormulation

Minimises the L2 norm of relative weight deviations when enforcing weight bounds.

Mathematical definition

\[\begin{align} \underset{\boldsymbol{w}}{\min} &\quad \left\lVert \boldsymbol{w} \oslash \boldsymbol{w}_{0} - \boldsymbol{1} \right\rVert_{2}\,, \\ \textrm{s.t.} &\quad \boldsymbol{1}^\intercal \boldsymbol{w} = \boldsymbol{1}^\intercal \boldsymbol{w}_{0}\,, \\ &\quad \boldsymbol{l} \leq \boldsymbol{w} \leq \boldsymbol{u}\,. \end{align}\]

Where:

  • $\boldsymbol{w}$: Portfolio weights vector $N \times 1$.
  • $\boldsymbol{w}_{0}$: Portfolio weights vector $N \times 1$ that the optimisation produced, which the finaliser repairs.
  • $\boldsymbol{l}$, $\boldsymbol{u}$: Lower and upper weight bounds. An absent bound is dropped from the programme rather than set to an infinity.
  • $\oslash$: Elementwise division. A zero entry of $\boldsymbol{w}_{0}$ is replaced by eps before the division, so the ratio stays finite.

The second-order cone bounds the norm itself, so the objective value is the L2 norm and not its square. The name records the squared-error criterion, whose minimiser is the same because the square is monotonic on a non-negative norm. RelativeErrorWeightFinaliser differs in the norm, not in the power.

Constructors

SquaredRelativeErrorWeightFinaliser() -> SquaredRelativeErrorWeightFinaliser

Examples

julia> SquaredRelativeErrorWeightFinaliser()SquaredRelativeErrorWeightFinaliser()

Related

source
PortfolioOptimisers.AbsoluteErrorWeightFinaliser — Type
struct AbsoluteErrorWeightFinaliser <: JuMPWeightFinaliserFormulation

Minimises the L1 norm of absolute weight deviations when enforcing weight bounds.

Mathematical definition

\[\begin{align} \underset{\boldsymbol{w}}{\min} &\quad \left\lVert \boldsymbol{w} - \boldsymbol{w}_{0} \right\rVert_{1}\,, \\ \textrm{s.t.} &\quad \boldsymbol{1}^\intercal \boldsymbol{w} = \boldsymbol{1}^\intercal \boldsymbol{w}_{0}\,, \\ &\quad \boldsymbol{l} \leq \boldsymbol{w} \leq \boldsymbol{u}\,. \end{align}\]

Where:

  • $\boldsymbol{w}$: Portfolio weights vector $N \times 1$.
  • $\boldsymbol{w}_{0}$: Portfolio weights vector $N \times 1$ that the optimisation produced, which the finaliser repairs.
  • $\boldsymbol{l}$, $\boldsymbol{u}$: Lower and upper weight bounds. An absent bound is dropped from the programme rather than set to an infinity.

Constructors

AbsoluteErrorWeightFinaliser() -> AbsoluteErrorWeightFinaliser

Examples

julia> AbsoluteErrorWeightFinaliser()AbsoluteErrorWeightFinaliser()

Related

source
PortfolioOptimisers.SquaredAbsoluteErrorWeightFinaliser — Type
struct SquaredAbsoluteErrorWeightFinaliser <: JuMPWeightFinaliserFormulation

Minimises the L2 norm of absolute weight deviations when enforcing weight bounds.

Mathematical definition

\[\begin{align} \underset{\boldsymbol{w}}{\min} &\quad \left\lVert \boldsymbol{w} - \boldsymbol{w}_{0} \right\rVert_{2}\,, \\ \textrm{s.t.} &\quad \boldsymbol{1}^\intercal \boldsymbol{w} = \boldsymbol{1}^\intercal \boldsymbol{w}_{0}\,, \\ &\quad \boldsymbol{l} \leq \boldsymbol{w} \leq \boldsymbol{u}\,. \end{align}\]

Where:

  • $\boldsymbol{w}$: Portfolio weights vector $N \times 1$.
  • $\boldsymbol{w}_{0}$: Portfolio weights vector $N \times 1$ that the optimisation produced, which the finaliser repairs.
  • $\boldsymbol{l}$, $\boldsymbol{u}$: Lower and upper weight bounds. An absent bound is dropped from the programme rather than set to an infinity.

The second-order cone bounds the norm itself, so the objective value is the L2 norm and not its square. The name records the squared-error criterion, whose minimiser is the same because the square is monotonic on a non-negative norm. AbsoluteErrorWeightFinaliser differs in the norm, not in the power.

Constructors

SquaredAbsoluteErrorWeightFinaliser() -> SquaredAbsoluteErrorWeightFinaliser

Examples

julia> SquaredAbsoluteErrorWeightFinaliser()SquaredAbsoluteErrorWeightFinaliser()

Related

source
PortfolioOptimisers.WeightFinaliser — Type
abstract type WeightFinaliser <: AbstractAlgorithm

Abstract supertype for weight finaliser strategies.

A WeightFinaliser enforces weight bounds after the optimisation has produced unconstrained weights.

Interfaces

In order to implement a new strategy that works seamlessly with the library, subtype WeightFinaliser and implement the following method:

opt_weight_bounds

  • opt_weight_bounds(wf::MyFinaliser, wb::WeightBounds, w::VecNum) -> VecNum: Moves w into the bounds wb, keeping the budget it already carries.

Arguments

  • wf: The concrete subtype instance.
  • wb: The weight bounds. Either bound may be nothing.
  • w: The weights the optimisation produced.

Returns

Related

source
PortfolioOptimisers.IterativeWeightFinaliser — Type
struct IterativeWeightFinaliser{__T_iter} <: WeightFinaliser

Iteratively projects weights into the feasible region defined by weight bounds.

Each pass clips the weights to the bounds, then redistributes the clipped mass over the entries that lie strictly inside the bounds, in proportion to their own weights. The pass ends by rescaling the vector to the budget it started with, so the sum is preserved. Passes run until the bounds hold or until iter passes are done. An absent bound is read as typemin or typemax of the weight element type.

The bounds are not guaranteed on exit. A bound set that no rescaled vector can satisfy exhausts the passes and returns the last vector: four assets summing to 1 under lb = 0.3 return [0.25, 0.25, 0.25, 0.25]. finalise_weight_bounds tests finiteness alone, so such a vector is reported as an OptimisationSuccess.

Fields

  • iter: Maximum number of iterations.

Constructors

IterativeWeightFinaliser(;    iter::Integer = 100) -> IterativeWeightFinaliser

Keywords correspond to the struct's fields.

Validation

  • iter > 0.

Examples

julia> IterativeWeightFinaliser()IterativeWeightFinaliser  iter ┴ Int64: 100

Related

source
PortfolioOptimisers.JuMPWeightFinaliser — Type
struct JuMPWeightFinaliser{__T_slv, __T_sc, __T_so, __T_alg} <: WeightFinaliser

Uses a JuMP optimisation model to enforce weight bounds.

The programme keeps the budget of the input weights and holds every weight between the bounds, and alg states which deviation it minimises over that set. An absent bound adds no constraint. A failed solve raises a warning and falls back to a default IterativeWeightFinaliser.

Fields

  • slv: Solver or vector of solvers.
  • sc: Constraint scale factor.
  • so: Objective scale factor.
  • alg: Weight finaliser error formulation algorithm.

Constructors

JuMPWeightFinaliser(;    slv::Slv_VecSlv,    sc::Number = 1.0,    so::Number = 1.0,    alg::JuMPWeightFinaliserFormulation = RelativeErrorWeightFinaliser()) -> JuMPWeightFinaliser

Keywords correspond to the struct's fields.

Validation

  • If slv is a VecSlv: !isempty(slv).
  • sc > 0, so > 0.

Examples

julia> JuMPWeightFinaliser(; slv = Solver(; solver = nothing))JuMPWeightFinaliser  slv ┼ Solver      │          name ┼ String: ""      │        solver ┼ nothing      │      settings ┼ nothing      │     check_sol ┼ @NamedTuple{}: NamedTuple()      │   add_bridges ┴ Bool: true   sc ┼ Float64: 1.0   so ┼ Float64: 1.0  alg ┴ RelativeErrorWeightFinaliser()

Related

source
PortfolioOptimisers._optimise — Function
_optimise(opt, rd, args...; dims, str_names, save, kwargs...)

Internal dispatch function for portfolio optimisation.

Called by optimise to perform the actual optimisation. Each optimisation estimator type implements its own overload. Returns the estimator-specific result type.

Arguments

  • opt: Optimisation estimator (e.g. MeanRisk, RiskBudgeting, etc.).
  • rd::ReturnsResult: Returns data.
  • dims::Int: Observation dimension.
  • str_names::Bool: Whether to use string names in the JuMP model.
  • save::Bool: Whether to save the JuMP model in the result.
  • kwargs...: Additional keyword arguments.

Returns

  • Estimator-specific optimisation result.

Related

source
PortfolioOptimisers.optimise — Method
optimise(opt::OptimisationEstimator, args...; kwargs...) -> OptimisationResult
optimise(opt::OptimisationResult, args...; kwargs...) -> OptimisationResult

Run portfolio optimisation using the given estimator opt and return an OptimisationResult.

If opt returns an OptimisationFailure, the fallback estimator is tried automatically until either a successful result is obtained or all fallbacks are exhausted.

Passing an OptimisationResult directly returns it unchanged (pass-through method).

Arguments

  • opt: Optimisation estimator (e.g. a JuMPOptimisationEstimator subtype).
  • args: Additional positional arguments (ignored).
  • kwargs: Additional keyword arguments (ignored).

Returns

Related

source
PortfolioOptimisers.optimise — Method
optimise(
    opt::OptimisationEstimator,
    args...;
    kwargs...
) -> Union{HierarchicalRiskParityResult{HierarchicalResult{__T_pr, __T_clr, __T_wb, __T_fees, __T_retcode, __T_w}, <:AbstractBaseRiskMeasure, <:Scalariser, Nothing} where {__T_pr, __T_clr, __T_wb, __T_fees, __T_retcode, __T_w}, HierarchicalRiskParityResult{HierarchicalResult{__T_pr, __T_clr, __T_wb, __T_fees, __T_retcode, __T_w}, <:AbstractVector{var"#s936"}, <:Scalariser, Nothing} where {__T_pr, __T_clr, __T_wb, __T_fees, __T_retcode, __T_w, var"#s936"<:AbstractBaseRiskMeasure}}

High level optimisation function that wraps around estimator-specific optimisation functions. This takes care of fallback methods if the primary optimisation fails. It returns the first successful optimisation result but stores all fallback results in the fb field of the result.

This is a fold-less entry point, so time-dependent schedules are inert here: the estimator is reset to its fold-less values (see reset_time_dependent_estimator) before the solve — in particular a scheduled fallback resets to its default, or to nothing (no fallback) when it has none, before the fallback chain is walked. Inside a fold loop this reset is a no-op, because the loop resolves every schedule before optimising.

Arguments

  • opt::OptimisationEstimator: The optimisation estimator to use.
  • args: Additional positional arguments passed to the optimisation function.
  • kwargs: Additional keyword arguments passed to the optimisation function.
source
PortfolioOptimisers.assert_special_nco_requirements — Method
assert_special_nco_requirements(opt)

Assert that the optimiser meets special requirements for Nested Clustered Optimisation (NCO).

The default implementation does nothing. Overridden for estimators (e.g. Stacking) that have requirements which must be validated before NCO can proceed.

Arguments

  • opt: Optimisation estimator, result, or vector thereof.

Returns

  • nothing.

Related

source
PortfolioOptimisers.assert_special_nco_requirements — Method
assert_special_nco_requirements(
    opt::AbstractVector{<:Union{var"#s936", var"#s935"} where {var"#s936"<:(Union{var"#s936", var"#s935"} where {var"#s936"<:NonFiniteAllocationOptimisationEstimator, var"#s935"<:NonFiniteAllocationOptimisationResult}), var"#s935"<:Union{TimeDependent{<:AbstractVector{<:Union{var"#s936", var"#s935"} where {var"#s936"<:NonFiniteAllocationOptimisationEstimator, var"#s935"<:NonFiniteAllocationOptimisationResult}}}, TimeDependent{<:TimeDependentOptimiserCallable}, TimeDependent{<:PreviousWeightsFunction}, TimeDependent{<:Union{Function, Type}}}}}
)

Assert special NCO requirements for each element of a vector of optimisation estimators or results.

Related

source
PortfolioOptimisers.needs_previous_weights — Method
needs_previous_weights(opt)

Return true if the optimiser requires the previous period's weights.

The default returns false. Overridden for optimisers that contain turnover constraints, tracking error constraints, or other time-dependent components that require the previous optimisation's weights.

Arguments

  • opt: Optimisation estimator, result, risk measure, fee structure, or vector thereof.

Returns

  • Bool: true if previous weights are needed.

Related

source
PortfolioOptimisers.needs_previous_weights — Method
needs_previous_weights(
    opt::AbstractVector{<:Union{var"#s936", var"#s935"} where {var"#s936"<:(Union{var"#s936", var"#s935"} where {var"#s936"<:NonFiniteAllocationOptimisationEstimator, var"#s935"<:NonFiniteAllocationOptimisationResult}), var"#s935"<:Union{TimeDependent{<:AbstractVector{<:Union{var"#s936", var"#s935"} where {var"#s936"<:NonFiniteAllocationOptimisationEstimator, var"#s935"<:NonFiniteAllocationOptimisationResult}}}, TimeDependent{<:TimeDependentOptimiserCallable}, TimeDependent{<:PreviousWeightsFunction}, TimeDependent{<:Union{Function, Type}}}}}
) -> Any

Return true if any element of the vector of optimisation estimators or results requires previous portfolio weights.

Related

source
PortfolioOptimisers.needs_previous_weights — Method
needs_previous_weights(td::TimeDependent) -> Bool

Return true if a time-dependent constraint requires the previous optimisation's weights.

true for a PreviousWeightsFunction value; for vector values, delegates to needs_previous_weights on entries that support it (turnover, fees, tracking), descending into per-fold vector entries. Bare callables contribute false — their output cannot be inspected.

Related

source
PortfolioOptimisers.needs_previous_weights — Method
needs_previous_weights(
    opt::AbstractVector{<:Union{var"#s936", var"#s935"} where {var"#s936"<:(Union{var"#s936", var"#s935"} where {var"#s936"<:NonFiniteAllocationOptimisationEstimator, var"#s935"<:NonFiniteAllocationOptimisationResult}), var"#s935"<:Union{TimeDependent{<:AbstractVector{<:Union{var"#s936", var"#s935"} where {var"#s936"<:NonFiniteAllocationOptimisationEstimator, var"#s935"<:NonFiniteAllocationOptimisationResult}}}, TimeDependent{<:TimeDependentOptimiserCallable}, TimeDependent{<:PreviousWeightsFunction}, TimeDependent{<:Union{Function, Type}}}}}
) -> Any

Return true if any element of the vector of optimisation estimators or results requires previous portfolio weights.

Related

source
PortfolioOptimisers.TimeDependent — Type
struct TimeDependent{T1, T2} <: AbstractEstimator

Varies one optimiser input across the folds of a cross-validation scheme.

A TimeDependent is stored directly in the optimiser field it varies — e.g. JuMPOptimiser(; lt = TimeDependent([...])) — so the field's position names the target and a field holds either a static value or a per-fold schedule, never both. It is recognised at top-level optimiser fields only, never nested inside another input (e.g. inside a Fees or a risk measure).

val is either a vector of per-fold values — entry i is the complete field value for fold i of the consuming scheme's split enumeration — or a callable evaluated per fold: a bare function f(ctx::TimeDependentContext) (optionally wrapped in PreviousWeightsFunction) or a TimeDependentCallable functor struct.

For a field that itself accepts a vector of constraints statically, a per-fold entry is that whole vector, so a schedule of per-fold constraint vectors is a vector of vectors — TimeDependent([[c₁ᵃ, c₁ᵇ], [c₂ᵃ, c₂ᵇ], …]), entry i being fold i's complete constraint vector. There is no separate "vector of TimeDependent" facility and none is needed: TimeDependent is recognised only at a top-level field, so to vary individual constraints within a vector, build the fold's vector in a callable — TimeDependent(ctx -> [dynamic(ctx), static]) — which keeps the shared static parts in one place.

The machinery imposes no ordering of its own: fold i is whatever split(cv, rd) enumerates i-th, which is chronological for walk-forward and (unshuffled) KFold schemes. For schemes whose enumeration is not a timeline (combinatorial splits, randomised paths) it is the user's responsibility to key entries off the fold's indices — a callable sees its own fold's windows via ctx.train_idx[ctx.i]/ctx.test_idx[ctx.i] and may derive any ordering from them.

A time-dependent constraint participates only where folds exist and is inert everywhere else — a fold-less optimise replaces it with the field's fold-less value (see reset_time_dependent_estimator). Vector entries must have length equal to the number of folds of the consuming cross-validation scheme, validated at split time. Entries may be nothing, giving the field nothing for that fold.

The fold-less value is the field's static default, unless default overrides it. A field with no static default — the required, optimiser-valued fields — has nothing to reset to, so a schedule there must supply default; a fold-less solve of one that does not throws a TimeDependentDefaultError.

A vector whose entries are all optimisers or precomputed results (OptE_Opt) is stored as a Vector{OptE_Opt}, so a mixed schedule — fold i optimising or predicting depending on what entry i is — is admissible in an optimiser-valued field on its element type alone (see TD_OptE_Opt) rather than falling out to a Vector{Any} the field cannot accept.

Schedules do not nest: neither val, nor a vector entry of val, nor default may be a TimeDependent. Entry i is fold i's complete field value, and the fold-less value is by definition outside every fold loop, so nesting has no meaning. An estimator swapped in by a schedule may itself carry schedules — those resolve against the same fold context after the swap — but they live in its fields, not inside this wrapper.

Recovering which entry a fold ran needs no stored provenance, because a vector schedule is keyed by the fold index and nothing else. Entry i runs at fold i of the consuming scheme's split enumeration (time_dependent_value indexes val[ctx.i]), so val[i] is fold i's value — the same index you keyed the schedule by. Under the time-ordered schemes (walk-forward, unshuffled KFold, Pipeline) fold i is also the i-th entry of the returned MultiPeriodPredictionResult; under schemes that regroup for reporting (MultipleRandomised sorts by test index, combinatorial recombines each split's test groups into paths) the prediction order no longer tracks the fold order, so re-run split(cv, rd) and read the fold→path map off its path_ids — it is keyed by the very enumeration index the schedule was, so entry k still governs enumeration fold k. A callable schedule computes its value rather than selecting an entry, so there is no index to recover: what it returned is knowable only by re-running it on the fold's TimeDependentContext, or by having it record its own choice. Recording is a logging concern the caller owns, and the TimeDependentCallable struct interface is its natural home — a functor can stash the regime it picked per fold in a field of its own.

Fields

  • bind: Which fold loop consumes the schedule: :outermost (default) binds it to the outermost fold loop processing the estimator tree; :nearest binds it to the nearest enclosing fold loop — inside a meta-optimiser's inner estimators that is the meta's own cross-validation leg, which then consumes the schedule even when the meta is backtested under an outer fold loop.
  • default: Value the field takes outside every fold loop, overriding the host's static default (see time_dependent_field_defaults). NoDefault (the default) defers to the host's static default; a field that has none requires this to be set.

Constructors

TimeDependent(val, bind::Symbol = :outermost; default = NoDefault())TimeDependent(; val::Union{<:AbstractVector, <:Base.Callable,                           <:PreviousWeightsFunction, <:TimeDependentCallable,                           <:TimeDependent}, bind::Symbol = :outermost,              default = NoDefault())

Validation

  • If val is a vector: !isempty(val), and no entry is a TimeDependent.
  • val is not a TimeDependent.
  • default is not a TimeDependent.
  • bind in (:outermost, :nearest).

Examples

julia> TimeDependent([Fees(; l = 0.001), Fees(; l = 0.002)])TimeDependent      val ┼ 2-element Vector{Fees}          │ Fees ⋯          │ Fees ⋯     bind ┼ Symbol: :outermost  default ┴ NoDefault()

Related

source
PortfolioOptimisers.factory — Method
factory(td::TimeDependent, args...) -> TimeDependent

Apply factory through a TimeDependent schedule: to each vector entry and to the default, rebuilding the schedule.

A schedule can survive a fold loop's resolution pass (a bind = :nearest element left for a meta's inner cross-validation), so the factory pass that follows resolution must see through it. Callable forms pass through unchanged — their per-fold values do not exist yet, and a callable receives the fold's context (including w_prev) when it runs.

Related

source
PortfolioOptimisers.TimeDependentContext — Type
struct TimeDependentContext{T1, T2, T3, T4, T5, T6, T7} <: AbstractResult

Describes one fold to the time-dependent constraints that resolve against it.

Carries the fold's position in the consuming scheme's split enumeration and the data needed for a callable entry to compute its value. i indexes train_idx/test_idx, so ctx.train_idx[ctx.i]/ctx.test_idx[ctx.i] are always the fold's own windows; no ordering beyond the scheme's enumeration is implied. rd is the fold loop's (possibly asset-viewed) input data, so callables see the current universe and timestamps: the returns-level data at the optimiser fold loops, or the raw, pre-preprocessing price- or returns-level input at the Pipeline fold loop — a pipeline-level callable sees the fold's data before any pipeline step has transformed it. w_prev is populated only when the fold loop runs sequentially and a previous fold exists; path_id only under multi-path schemes.

Fields

  • i: Index of the fold within the scheme's split enumeration (1-based); indexes train_idx/test_idx.
  • n: Number of folds within the path.
  • rd: The fold loop's (possibly asset-viewed) returns data.
  • train_idx: Per-path training index vectors.
  • test_idx: Per-path test index vectors.
  • w_prev: Previous fold's portfolio weights, when threaded; nothing otherwise.
  • path_id: Path identifier under multi-path schemes; nothing otherwise.

Constructors

TimeDependentContext(;    i::Integer, n::Integer, rd::Prices_RR, train_idx, test_idx,    w_prev::Option{<:VecNum} = nothing, path_id::Option{<:Integer} = nothing) -> TimeDependentContext

Keywords correspond to the struct's fields.

Validation

  • 1 <= i <= n.

Related

source
PortfolioOptimisers.TimeDependentCallable — Type
abstract type TimeDependentCallable <: AbstractEstimator

Abstract supertype for the callable structs used as time-dependent values.

A subtype is a data-carrying alternative to a bare function inside a TimeDependent: it must implement a functor (x::MySubtype)(ctx::TimeDependentContext) returning the fold's field value. Because it is a struct, it participates in a trait a bare function cannot: define needs_previous_weights(::MySubtype) = true to declare a previous-weights requirement directly (the default is false), instead of wrapping in PreviousWeightsFunction.

Being a struct also makes it the natural home for recording what a callable schedule chose: a bare ctx -> … selects nothing by index, so its per-fold decision is not otherwise recoverable (see the provenance note on TimeDependent). A functor can carry a mutable field — e.g. a vector it writes at ctx.i — and log the fold's resolved value as a side effect of computing it.

The family classifies by what the functor returns, and a subtype declares that kind in its type. Subtype TimeDependentConstraintCallable when the per-fold value is a constraint value, and TimeDependentOptimiserCallable when it is an optimiser. Only the second is statically admissible in an optimiser-valued field (see TD_OptE_Opt), so the classification is what that admissibility is read off. Do not subtype this root directly.

Interfaces

Subtype one of the two children, not this root, and implement the following:

The functor

  • (x::MySubtype)(ctx::TimeDependentContext): Returns the field value for the fold that ctx describes.

Arguments

  • x: The concrete subtype instance.
  • ctx: The fold's context, which carries the fold index, the fold loop's data and, when the loop runs sequentially, the previous fold's weights.

Returns

  • The complete field value for that fold. Its kind is the one the subtype's supertype declares.

needs_previous_weights

  • needs_previous_weights(::MySubtype) -> Bool: Declares whether the functor reads ctx.w_prev. The default is false. Define it as true to force sequential fold execution, which is what PreviousWeightsFunction does for a bare function.

Related

source
PortfolioOptimisers.TimeDependentConstraintCallable — Type
abstract type TimeDependentConstraintCallable <: TimeDependentCallable

Abstract supertype for callable structs whose per-fold value is a constraint value.

A subtype implements a functor (x::MySubtype)(ctx::TimeDependentContext) returning the fold's value for a constraint-position field — a budget, a set of weight bounds, a fee structure, a turnover limit, anything a TimeDependent may carry other than an optimiser. The value is checked when the fold loop swaps it into the field, by the host's own keyword constructor.

This is the kind to subtype for a functor whose output is not an optimiser. A functor returning an optimiser declares TimeDependentOptimiserCallable instead, which is what makes an optimiser-position schedule statically admissible (see TD_OptE_Opt).

Interfaces

The methods are those of TimeDependentCallable: the functor (x::MySubtype)(ctx::TimeDependentContext), and the optional needs_previous_weights. This child adds no method. It states what the functor returns — a constraint value — and the host's own keyword constructor checks that value when the fold loop swaps it in.

Related

source
PortfolioOptimisers.TimeDependentOptimiserCallable — Type
abstract type TimeDependentOptimiserCallable <: TimeDependentCallable

Abstract supertype for callable structs whose per-fold value is an optimiser.

A subtype implements a functor (x::MySubtype)(ctx::TimeDependentContext) returning the fold's optimiser (an OptE_Opt), so a TimeDependent holding it is admissible wherever an optimiser-valued field accepts a schedule (see TD_OptE_Opt). Declaring the functor's output kind in the type is what makes the schedule statically admissible: a bare ctx -> optimiser is admitted as a Base.Callable and checked only when the fold loop swaps its value in.

Interfaces

The methods are those of TimeDependentCallable: the functor (x::MySubtype)(ctx::TimeDependentContext), and the optional needs_previous_weights. This child adds no method. It states that the functor returns an OptE_Opt, and assert_time_dependent_optimiser checks that promise when the fold loop swaps the value in.

Related

source
PortfolioOptimisers.PreviousWeightsFunction — Type
struct PreviousWeightsFunction{T} <: AbstractAlgorithm

Declares that a callable time-dependent entry requires the previous optimisation's weights.

A bare callable inside a TimeDependent cannot be inspected for previous-weight requirements, so it contributes false to needs_previous_weights and its context's w_prev is only populated when something else makes the fold loop sequential. Wrapping the callable in PreviousWeightsFunction declares the requirement as data: it contributes true to needs_previous_weights, forcing sequential fold execution and a populated w_prev in the TimeDependentContext.

Fields

  • f: Callable evaluated per fold as f(ctx::TimeDependentContext), returning the fold's field value.

Constructors

PreviousWeightsFunction(; f) -> PreviousWeightsFunction

Keywords correspond to the struct's fields.

Examples

julia> PreviousWeightsFunction(; f = identity)PreviousWeightsFunction  f ┴ typeof(identity): identity

Related

source
PortfolioOptimisers.NoDefault — Type
struct NoDefault <: AbstractAlgorithm

States that no fold-less value exists. It stands in the two places such a value may be missing.

Constructors

NoDefault() -> NoDefault

Examples

julia> NoDefault()NoDefault()

Related

source
PortfolioOptimisers.TimeDependentDefaultError — Type
struct TimeDependentDefaultError{__T_msg} <: PortfolioOptimisersError

Exception thrown when a fold-less solve reaches a TimeDependent schedule that has no value to fall back to: the field has no static default and the schedule supplies no default.

A schedule is defined only over the folds of a cross-validation scheme. Fields with a static default reset to it silently; a required field (the optimiser-valued ones) has nothing to reset to, so the schedule must state the value a fold-less solve should use, via TimeDependent(val; default = x).

Fields

  • msg: Error message describing the condition that triggered the exception.

Constructors

TimeDependentDefaultError(msg)

Related

source
PortfolioOptimisers.TD — Type
const TD{X} = Union{<:TimeDependent, X}

Alias for a required optimiser field that accepts a static value of type X or a per-fold TimeDependent schedule, but not nothing.

The problem-definition fields that always carry a value — the prior estimator, the returns model, the scalariser, the clustering estimator, the weight finaliser — are time-dependent through this alias rather than TD_Option, so nothing stays inadmissible where it was never a legal static value. Such a field still has a static default, so a schedule in one resets to that default on a fold-less solve, unlike the optimiser-valued fields (see TD_OptE_Opt).

Related

source
PortfolioOptimisers.TD_OptE_Opt — Type
const TD_OptE_Opt = Union{TimeDependent{<:AbstractVector{<:OptE_Opt}},
                          TimeDependent{<:TimeDependentOptimiserCallable},
                          TimeDependent{<:PreviousWeightsFunction},
                          TimeDependent{<:Base.Callable}}

The TimeDependent forms admissible in an optimiser-valued field — where the scheduled thing is the optimiser itself, not one of its inputs.

Two of the four are statically checked: a vector schedule whose entries are all OptE_Opt (an optimiser or a precomputed result — a mixed schedule is allowed, fold i optimising or predicting depending on what entry i is), and a TimeDependentOptimiserCallable, which declares its output kind in its type. The other two — a bare ctx -> optimiser and a PreviousWeightsFunction wrapping one — cannot be checked before they run, so their output is checked when the fold loop swaps it into the field, by the host's own keyword constructor.

Because an optimiser-valued field is required, a schedule in one has no static default to reset to on a fold-less solve and must supply default (see NoDefault, TimeDependentDefaultError).

Related

source
PortfolioOptimisers.OptE_TD — Type
const OptE_TD = Union{<:NonFiniteAllocationOptimisationEstimator, <:TD_OptE_Opt}

Alias for an optimisation estimator, or a TimeDependent schedule standing in its place.

This is the entry-point type of the cross-validation fold loops that fit: a schedule handed straight to cross_val_predict is the optimiser, and fold i runs entry i. Precomputed results are excluded because a bare result takes the predict-only path, which has no fold loop to resolve a schedule against — but a schedule whose entries are results is admissible here, and each such entry takes the predict-only path per fold (see OptE_Opt_TD).

Related

source
PortfolioOptimisers.OptE_Opt_TD — Type
const OptE_Opt_TD = Union{<:OptE_Opt, <:TD_OptE_Opt}

Alias for an optimisation estimator or a precomputed result, or a TimeDependent schedule standing in their place.

The entry-point type of the fold loops that accept a precomputed result as well as an estimator. A schedule's entries are OptE_Opt, so a mixed schedule is admissible: fold i optimises when entry i is an estimator and predicts when it is a result, which the single-fold fit_and_predict methods already distinguish by dispatch.

Related

source
PortfolioOptimisers.VecOptE_Opt_TD — Type
const VecOptE_Opt_TD = AbstractVector{<:OptE_Opt_TD}

Alias for a vector of optimisation estimators or results in which individual elements may be TimeDependent schedules.

This is the element-level admission of schedules, needed where a vector-valued field's elements are themselves optimiser positions consumed by a fold loop one at a time — Stacking.opti, whose inner cross-validation is entered per candidate. It is a superset of VecOptE_Opt, so every method taking it continues to accept plain vectors.

Related

source
PortfolioOptimisers.TD_VecOptE_Opt — Type
const TD_VecOptE_Opt = Union{TimeDependent{<:AbstractVector{<:VecOptE_Opt_TD}},
                             TimeDependent{<:TimeDependentOptimiserCallable},
                             TimeDependent{<:PreviousWeightsFunction},
                             TimeDependent{<:Base.Callable}}

The TimeDependent forms admissible in a vector-of-optimisers field (Stacking.opti): a vector schedule whose entries are per-fold optimiser vectors, or a callable returning the fold's vector.

Entry i is fold i's complete vector of candidates, so a field-level schedule varies the whole candidate set per fold; an entry's own elements may in turn be schedules (a VecOptE_Opt_TD), which the consuming host's inner fold loop resolves as usual. Only bind = :outermost is admissible at the field level — see the host's constructor for why.

Related

source
PortfolioOptimisers.TDO_OptE_Opt — Type
const TDO_OptE_Opt = Union{<:TD_OptE_Opt,
                           <:TimeDependent{<:AbstractVector{<:Option{<:OptE_Opt}}}}

The TimeDependent forms admissible in an optional optimiser-valued field (a fallback): every TD_OptE_Opt form, plus a vector schedule whose entries may be nothing.

nothing was always a legal static value of an optional field, and the TimeDependent contract says a vector entry may be nothing, giving the field nothing for that fold — so an optional optimiser field admits TimeDependent([mr, nothing]), a fallback switched off on some folds. A required optimiser position (the optimiser itself) never admits nothing, statically or per fold, so it stays on the strict TD_OptE_Opt bound.

Related

source
PortfolioOptimisers.assert_nearest_optimiser_schedule — Function
assert_nearest_optimiser_schedule(x, field::Symbol, cv, host::Symbol)

Validate a bind = :nearest TimeDependent schedule in an optimiser-valued position that a host's inner cross-validation does consume.

Two construction-time requirements, both consequences of the position's double consumer: the inner cross-validation leg resolves the schedule per fold, while the full-sample leg (the meta's wi fit, or the per-cluster optimise) always resolves it fold-lessly to its default.

  • An explicit default is required — without one, every solve would throw a TimeDependentDefaultError when the full-sample leg reaches the schedule, so the error is moved to construction. This deliberately departs from the rule that a defaultless schedule is legal at construction, for this position only.
  • cv !== nothing is required — without an inner cross-validation there is no inner fold loop, so the schedule could only ever be its default: silently inert.

No-op for anything that is not a bind = :nearest TimeDependent.

Related

source
PortfolioOptimisers.inner_fold_fields — Function
inner_fold_fields(opt)

Field names of opt that the host hands across a fold loop it opens itself, so the loop that merely reaches the host is never the nearest one for them.

The default is the empty tuple: an ordinary host opens no inner fold loop, so the loop reaching it is both outermost and nearest for every field. A meta-optimiser whose inner cross-validation consumes a field directly declares that field here (e.g. NestedClustered's opti, entered per cluster as cross_val_predict(opti, …; cols = cl)), and every generic pass — time_dependent_fields, and through it update, reset and the fold-count assertion — then leaves a bind = :nearest schedule in that field for the host's own inner loop. Without the reset leg of this rule, the fold-less reset at the top of _optimise would replace a :nearest optimiser schedule with its default before the inner cross-validation ever saw it.

Related

source
PortfolioOptimisers.time_dependent_candidate_fields — Function
time_dependent_candidate_fields(opt)

Field names of opt whose type admits a TimeDependent value — the candidate set time_dependent_fields narrows by value.

Whether a field can hold a schedule is decidable from fieldtype alone: a host built through the widened constructor signatures (see TD_Option) records a schedule in the field's type parameter, so a field that holds no schedule cannot have a type intersecting TimeDependent. The tuple is therefore computed once per host type by a generated function, and a fold-invariant scan over a wide static host such as JuMPOptimiser, whose fields number in the dozens, folds to an empty tuple at compile time rather than walking every field dynamically on every split and _optimise.

This stays derived from the field types — no hand-maintained list — so the constructor signatures remain the single source of truth for which fields may vary over folds (ADR 0030).

Related

source
PortfolioOptimisers.time_dependent_fields — Function
time_dependent_fields(opt, all_binds::Bool = true)

Return the tuple of field names of opt whose values are TimeDependent.

The scan is generic over the host's fields, so the widened constructor signatures (see TD_Option) remain the single source of truth for which fields may vary over folds — there is no hand-maintained list. Only the fields whose type admits a schedule are visited (see time_dependent_candidate_fields); the rest are ruled out at compile time, so a static host returns an empty tuple without touching its fields.

The all_binds argument

all_binds encodes something the schedule's own bind field cannot: it is a property of the recursion position, not of the schedule. A TimeDependent's bind (:outermost / :nearest) says which fold loop the schedule wants; all_binds says whether the loop currently recursing is entitled to consume nearest-bound schedules at this depth. The second fact is not on the schedule.

Why position matters: under outer CV loop → meta → (meta's inner CV loop) → inner estimator with a :nearest field, the same :nearest field is visited by two loops. The outer loop recurses through the meta (mandatory — that recursion is how an inner estimator's :outermost field is resolved against the outer folds) and must skip the :nearest field, because it is not the nearest enclosing loop. The meta's inner CV loop drives the same estimator directly and must consume it, because it is. Same field, same bind, opposite actions — the difference is whether a nearer fold-loop boundary was crossed to reach it, which is exactly what all_binds carries.

So all_binds is true at every ordinary (outermost/standalone) fold loop — which is both outermost and nearest, and therefore takes everything remaining, including :nearest. It is forced to false only where a meta-optimiser recurses into the estimators its own inner CV owns, leaving their :nearest schedules for that inner loop. With all_binds = false, only fields with bind === :outermost are returned.

Entitlement is refined per field by inner_fold_fields: even at all_binds = true, a :nearest schedule in a field the host hands across its own inner fold loop is left alone — the host's inner loop, not the scanning one, is nearest for that field (see entitled).

Related

source
PortfolioOptimisers.assert_time_dependent_substitution — Function
assert_time_dependent_substitution(
    _::Type{T},
    args::NamedTuple,
    defaults::NamedTuple
)

Test-substitute every vector entry of the TimeDependent-valued fields in args through the keyword constructor of T.

args holds the host constructor's arguments; defaults the static defaults of the fields that may be time-dependent (see time_dependent_field_defaults). Each per-fold entry, and an explicit default, is substituted into its field — with every other time-dependent field standing at a value of its own (see time_dependent_stand_in) — and the constructor re-run, surfacing type and cross-field errors at construction time instead of mid-backtest. Substituted calls contain no TimeDependent values, so the recursion terminates.

Validation is skipped when a time-dependent field has no stand-in at all — a callable schedule in a required field, whose value only exists once a fold context does.

Related

source
PortfolioOptimisers.time_dependent_stand_in — Function
time_dependent_stand_in(
    td::TimeDependent,
    defaults::NamedTuple,
    field::Symbol
) -> Union{Nothing, Some}

Return a valid static value for a TimeDependent-valued field, wrapped in Some, or nothing if none exists.

Used by assert_time_dependent_substitution to stand the other time-dependent fields at a valid value while it test-substitutes one of them: the schedule's default, else the field's static default, else the schedule's first entry. A callable schedule in a field with no default of either kind has no stand-in — its value exists only inside a fold — so it returns nothing and validation is skipped.

Unlike time_dependent_reset_value this never throws: a schedule without a fold-less value is legitimate at construction time and only fails if it reaches a fold-less solve.

Related

source
PortfolioOptimisers.time_dependent_reset_value — Function
time_dependent_reset_value(
    td::TimeDependent,
    defaults::NamedTuple,
    field::Symbol,
    opt
) -> Any

Return the value a TimeDependent-valued field takes outside every fold loop.

The schedule's own default wins; absent one (NoDefault), the host's static default for field is used (time_dependent_field_defaults, nothing for fields it omits). Throws a TimeDependentDefaultError when neither exists — a schedule in a required field that never said what a fold-less solve should do.

Related

source
PortfolioOptimisers.assert_time_dependent_optimiser — Function
assert_time_dependent_optimiser(
    _::Union{NonFiniteAllocationOptimisationEstimator, NonFiniteAllocationOptimisationResult}
)

Assert that a TimeDependent schedule in an optimiser position resolved to something that can be optimised or predicted.

The vector and TimeDependentOptimiserCallable forms of a schedule declare their output kind in their type and are checked statically (see TD_OptE_Opt). The two callable forms — a bare ctx -> optimiser and a PreviousWeightsFunction wrapping one — cannot be, so their output is checked here, when the fold loop swaps it in.

Related

source
PortfolioOptimisers.assert_time_dependent_fold_count — Function
assert_time_dependent_fold_count(opt, n::Integer, all_binds::Bool = true)

Assert that every vector-valued time-dependent constraint in opt has exactly n entries.

Called by the cross-validation fold loops immediately after split, before any fold runs. The default is a no-op; hosts scan their time_dependent_fields and wrapper optimisers recurse. When all_binds is false, bind === :nearest schedules are skipped — they are validated by the nearest enclosing fold loop against its own fold count instead (see TimeDependent).

Related

source
PortfolioOptimisers.assert_time_dependent_fold_count — Function
assert_time_dependent_fold_count(
    td::Union{TimeDependent{<:AbstractVector{<:Union{Nothing, var"#s932"} where var"#s932"<:(Union{var"#s936", var"#s935"} where {var"#s936"<:NonFiniteAllocationOptimisationEstimator, var"#s935"<:NonFiniteAllocationOptimisationResult})}}, TimeDependent{<:TimeDependentOptimiserCallable}, TimeDependent{<:PreviousWeightsFunction}, TimeDependent{<:Union{Function, Type}}},
    n::Integer
)
assert_time_dependent_fold_count(
    td::Union{TimeDependent{<:AbstractVector{<:Union{Nothing, var"#s932"} where var"#s932"<:(Union{var"#s936", var"#s935"} where {var"#s936"<:NonFiniteAllocationOptimisationEstimator, var"#s935"<:NonFiniteAllocationOptimisationResult})}}, TimeDependent{<:TimeDependentOptimiserCallable}, TimeDependent{<:PreviousWeightsFunction}, TimeDependent{<:Union{Function, Type}}},
    n::Integer,
    all_binds::Bool
)

Assert that a TimeDependent schedule standing in for an optimiser has one entry per fold, and that the schedules within each entry are sized to the same fold loop.

Entry i runs at fold i of this loop, so its own :outermost schedules bind here too (see update_time_dependent_estimator) and are validated against this loop's fold count. The default is not — it runs only outside a fold loop, where its schedules reset instead.

Skipped when all_binds is false and the schedule is not :outermost-bound — the fold loop the host opens validates it against its own fold count instead.

Related

source
PortfolioOptimisers.assert_time_dependent_fold_count — Function
assert_time_dependent_fold_count(
    opt::AbstractVector{<:Union{var"#s936", var"#s935"} where {var"#s936"<:(Union{var"#s936", var"#s935"} where {var"#s936"<:NonFiniteAllocationOptimisationEstimator, var"#s935"<:NonFiniteAllocationOptimisationResult}), var"#s935"<:Union{TimeDependent{<:AbstractVector{<:Union{var"#s936", var"#s935"} where {var"#s936"<:NonFiniteAllocationOptimisationEstimator, var"#s935"<:NonFiniteAllocationOptimisationResult}}}, TimeDependent{<:TimeDependentOptimiserCallable}, TimeDependent{<:PreviousWeightsFunction}, TimeDependent{<:Union{Function, Type}}}}},
    n::Integer
)
assert_time_dependent_fold_count(
    opt::AbstractVector{<:Union{var"#s936", var"#s935"} where {var"#s936"<:(Union{var"#s936", var"#s935"} where {var"#s936"<:NonFiniteAllocationOptimisationEstimator, var"#s935"<:NonFiniteAllocationOptimisationResult}), var"#s935"<:Union{TimeDependent{<:AbstractVector{<:Union{var"#s936", var"#s935"} where {var"#s936"<:NonFiniteAllocationOptimisationEstimator, var"#s935"<:NonFiniteAllocationOptimisationResult}}}, TimeDependent{<:TimeDependentOptimiserCallable}, TimeDependent{<:PreviousWeightsFunction}, TimeDependent{<:Union{Function, Type}}}}},
    n::Integer,
    all_binds::Bool
)

Apply assert_time_dependent_fold_count element-wise to a vector of optimisation estimators or results.

Related

source
PortfolioOptimisers.is_time_dependent — Method
is_time_dependent(opt)

Return true if the optimiser carries time-dependent constraints.

The default returns false. Hosts return true when any of their fields holds a TimeDependent (see time_dependent_fields); wrapper optimisers recurse into their inner optimiser and fallback.

Arguments

  • opt: Optimisation estimator, result, or vector thereof.

Returns

  • Bool: true if the estimator is time-dependent.

Related

source
PortfolioOptimisers.is_time_dependent — Method
is_time_dependent(
    opt::AbstractVector{<:Union{var"#s936", var"#s935"} where {var"#s936"<:(Union{var"#s936", var"#s935"} where {var"#s936"<:NonFiniteAllocationOptimisationEstimator, var"#s935"<:NonFiniteAllocationOptimisationResult}), var"#s935"<:Union{TimeDependent{<:AbstractVector{<:Union{var"#s936", var"#s935"} where {var"#s936"<:NonFiniteAllocationOptimisationEstimator, var"#s935"<:NonFiniteAllocationOptimisationResult}}}, TimeDependent{<:TimeDependentOptimiserCallable}, TimeDependent{<:PreviousWeightsFunction}, TimeDependent{<:Union{Function, Type}}}}}
) -> Any

Return true if any element of the vector of optimisation estimators or results is time-dependent.

Related

source
PortfolioOptimisers.is_time_dependent — Method
is_time_dependent(
    opt::AbstractVector{<:Union{var"#s936", var"#s935"} where {var"#s936"<:(Union{var"#s936", var"#s935"} where {var"#s936"<:NonFiniteAllocationOptimisationEstimator, var"#s935"<:NonFiniteAllocationOptimisationResult}), var"#s935"<:Union{TimeDependent{<:AbstractVector{<:Union{var"#s936", var"#s935"} where {var"#s936"<:NonFiniteAllocationOptimisationEstimator, var"#s935"<:NonFiniteAllocationOptimisationResult}}}, TimeDependent{<:TimeDependentOptimiserCallable}, TimeDependent{<:PreviousWeightsFunction}, TimeDependent{<:Union{Function, Type}}}}}
) -> Any

Return true if any element of the vector of optimisation estimators or results is time-dependent.

Related

source
PortfolioOptimisers.update_time_dependent_estimator — Function
update_time_dependent_estimator(
    opt::BaseOptimisationEstimator,
    ctx::TimeDependentContext
) -> Any
update_time_dependent_estimator(
    opt::BaseOptimisationEstimator,
    ctx::TimeDependentContext,
    all_binds::Bool
) -> Any

Resolve the time-dependent constraints of a base optimiser configuration for the fold described by ctx.

Rebuilds the configuration through its validated keyword constructor with each TimeDependent-valued field replaced by its resolved per-fold value, so the result is an ordinary static configuration. When all_binds is false, bind === :nearest fields are left in place for the nearest enclosing fold loop to consume.

Related

source
update_time_dependent_estimator(opt, ctx::TimeDependentContext, all_binds::Bool = true)

Resolve the time-dependent constraints of opt for the fold described by ctx.

The default returns the estimator unchanged. Hosts rebuild themselves through their validated keyword constructor with each TimeDependent-valued field replaced by its resolved per-fold value, so the result is an ordinary static estimator; wrapper optimisers recurse.

Arguments

  • opt: Optimisation estimator or result.
  • ctx::TimeDependentContext: The fold's context.
  • all_binds::Bool: When false, bind === :nearest schedules are skipped, leaving them for the nearest enclosing fold loop to consume. Meta-optimisers pass false when recursing into the estimators their internal fold loop processes; fold loops call with the default true.

Returns

  • Updated estimator.

Related

source
update_time_dependent_estimator(
    td::Union{TimeDependent{<:AbstractVector{<:Union{var"#s936", var"#s935"} where {var"#s936"<:NonFiniteAllocationOptimisationEstimator, var"#s935"<:NonFiniteAllocationOptimisationResult}}}, TimeDependent{<:TimeDependentOptimiserCallable}, TimeDependent{<:PreviousWeightsFunction}, TimeDependent{<:Union{Function, Type}}},
    ctx::TimeDependentContext
) -> Any
update_time_dependent_estimator(
    td::Union{TimeDependent{<:AbstractVector{<:Union{var"#s936", var"#s935"} where {var"#s936"<:NonFiniteAllocationOptimisationEstimator, var"#s935"<:NonFiniteAllocationOptimisationResult}}}, TimeDependent{<:TimeDependentOptimiserCallable}, TimeDependent{<:PreviousWeightsFunction}, TimeDependent{<:Union{Function, Type}}},
    ctx::TimeDependentContext,
    all_binds::Bool
) -> Any

Resolve a TimeDependent schedule standing in for an optimiser to the optimiser of fold ctx.i.

Entry i may be an estimator or a precomputed result, so a mixed schedule optimises on some folds and predicts on others. After the swap the resolved estimator is recursed into with the same context, so its own :outermost schedules bind to this fold loop rather than going unresolved.

Returns the schedule unchanged when all_binds is false and it is not :outermost-bound — a :nearest schedule in an optimiser position is consumed by a fold loop the host itself opens, not by the loop that reached the host.

Related

source
update_time_dependent_estimator(
    opt::AbstractVector{<:Union{var"#s936", var"#s935"} where {var"#s936"<:(Union{var"#s936", var"#s935"} where {var"#s936"<:NonFiniteAllocationOptimisationEstimator, var"#s935"<:NonFiniteAllocationOptimisationResult}), var"#s935"<:Union{TimeDependent{<:AbstractVector{<:Union{var"#s936", var"#s935"} where {var"#s936"<:NonFiniteAllocationOptimisationEstimator, var"#s935"<:NonFiniteAllocationOptimisationResult}}}, TimeDependent{<:TimeDependentOptimiserCallable}, TimeDependent{<:PreviousWeightsFunction}, TimeDependent{<:Union{Function, Type}}}}},
    ctx::TimeDependentContext
) -> Any
update_time_dependent_estimator(
    opt::AbstractVector{<:Union{var"#s936", var"#s935"} where {var"#s936"<:(Union{var"#s936", var"#s935"} where {var"#s936"<:NonFiniteAllocationOptimisationEstimator, var"#s935"<:NonFiniteAllocationOptimisationResult}), var"#s935"<:Union{TimeDependent{<:AbstractVector{<:Union{var"#s936", var"#s935"} where {var"#s936"<:NonFiniteAllocationOptimisationEstimator, var"#s935"<:NonFiniteAllocationOptimisationResult}}}, TimeDependent{<:TimeDependentOptimiserCallable}, TimeDependent{<:PreviousWeightsFunction}, TimeDependent{<:Union{Function, Type}}}}},
    ctx::TimeDependentContext,
    all_binds::Bool
) -> Any

Apply update_time_dependent_estimator element-wise to a vector of optimisation estimators or results.

Related

source
update_time_dependent_estimator(
    opt::NaiveOptimisationEstimator,
    ctx::TimeDependentContext
) -> Any
update_time_dependent_estimator(
    opt::NaiveOptimisationEstimator,
    ctx::TimeDependentContext,
    all_binds::Bool
) -> Any

Resolve the time-dependent constraints of a naive optimiser for the fold described by ctx.

Rebuilds the optimiser through its validated keyword constructor with each TimeDependent-valued field replaced by its resolved per-fold value, recursing into the fallback, so the result is an ordinary static optimiser.

Related

source
update_time_dependent_estimator(
    opt::ClusteringOptimisationEstimator,
    ctx::TimeDependentContext
) -> NestedClustered
update_time_dependent_estimator(
    opt::ClusteringOptimisationEstimator,
    ctx::TimeDependentContext,
    all_binds::Bool
) -> NestedClustered

Resolve time-dependent constraints for the fold described by ctx: the estimator's own scheduled fields (risk measures, scalarisers, fallback, …) are swapped for their per-fold values, then the inner optimiser and the (possibly just-swapped-in) fallback are recursed into with the same context.

NestedClustered overrides this with its own method resolving its own fields and inner estimators.

source
update_time_dependent_estimator(
    opt::JuMPOptimisationEstimator,
    ctx::TimeDependentContext
) -> Any
update_time_dependent_estimator(
    opt::JuMPOptimisationEstimator,
    ctx::TimeDependentContext,
    all_binds::Bool
) -> Any

Resolve time-dependent constraints for the fold described by ctx: the estimator's own scheduled fields (risk measure, objective, warm start, fallback, …) are swapped for their per-fold values, then the inner JuMP optimiser and the (possibly just-swapped-in) fallback are recursed into with the same context.

source
update_time_dependent_estimator(
    opt::NestedClustered,
    ctx::TimeDependentContext
) -> NestedClustered
update_time_dependent_estimator(
    opt::NestedClustered,
    ctx::TimeDependentContext,
    all_binds::Bool
) -> NestedClustered

Resolve time-dependent constraints for the fold described by ctx by recursing into the inner optimiser, outer optimiser, and fallback.

source
update_time_dependent_estimator(
    opt::Stacking,
    ctx::TimeDependentContext
) -> Stacking
update_time_dependent_estimator(
    opt::Stacking,
    ctx::TimeDependentContext,
    all_binds::Bool
) -> Stacking

Resolve time-dependent constraints for the fold described by ctx by recursing into the inner optimisers, outer optimiser, and fallback.

source
update_time_dependent_estimator(
    opt::SubsetResampling,
    ctx::TimeDependentContext
) -> SubsetResampling
update_time_dependent_estimator(
    opt::SubsetResampling,
    ctx::TimeDependentContext,
    all_binds::Bool
) -> SubsetResampling

Resolve time-dependent constraints for the fold described by ctx by recursing into the base optimiser and fallback.

source
update_time_dependent_estimator(
    p::Pipeline,
    ctx::TimeDependentContext
) -> Pipeline
update_time_dependent_estimator(
    p::Pipeline,
    ctx::TimeDependentContext,
    all_binds::Bool
) -> Pipeline

Resolve the time-dependent steps of a Pipeline for the fold described by ctx — the swap of ADR 0030's pipeline integration.

The swap happens in the fold loop, outside fit entirely: it maps update_time_dependent_step over the steps (names preserved), so by the time fit runs on the fold's training window every schedule step is already a plain optimiser or precomputed result and injection (inject_context / maybe_inject_step) never sees a schedule — fit and run_step never learn about folds.

Related

source
PortfolioOptimisers.update_time_dependent_fields — Function
update_time_dependent_fields(
    opt,
    ctx::TimeDependentContext
) -> Any
update_time_dependent_fields(
    opt,
    ctx::TimeDependentContext,
    all_binds::Bool
) -> Any

Rebuild a host optimiser with each TimeDependent-valued field replaced by its per-fold value for ctx.

Shared implementation behind the hosts' update_time_dependent_estimator methods. Returns opt unchanged when no field is time-dependent.

Related

source
PortfolioOptimisers.time_dependent_field_defaults — Function
time_dependent_field_defaults(opt)

Return a NamedTuple of the static defaults of the optimiser fields that may hold a TimeDependent, for those whose default is not nothing.

Used by reset_time_dependent_estimator to replace per-fold schedules with their static defaults on fold-less solves; fields absent from the tuple default to nothing. A required field — one with no static default at all, i.e. the optimiser-valued fields — is listed with NoDefault, which is not a value it can take but a declaration that a schedule there must carry its own default. The fallback method returns an empty tuple.

Related

source
time_dependent_field_defaults(
    _::HierarchicalOptimiser
) -> @NamedTuple{pe::EmpiricalPrior{PortfolioOptimisersCovariance{Covariance{SimpleExpectedReturns{Nothing}, GeneralCovariance{SimpleCovariance, Nothing}, FullMoment}, MatrixProcessing{Posdef{UnionAll, @NamedTuple{}}, Nothing, Nothing, Nothing, NTuple{4, Symbol}}}, SimpleExpectedReturns{Nothing}, Nothing}, cle::ClustersEstimator{PortfolioOptimisersCovariance{Covariance{SimpleExpectedReturns{Nothing}, GeneralCovariance{SimpleCovariance, Nothing}, FullMoment}, MatrixProcessing{Posdef{UnionAll, @NamedTuple{}}, Nothing, Nothing, Nothing, NTuple{4, Symbol}}}, Distance{Nothing, CanonicalDistance}, HClustAlgorithm{Symbol}, OptimalNumberClusters{Nothing, SecondOrderDifference{StandardisedValue{MeanValue{Nothing}, StdValue{Nothing, Bool}}}}}, wb::WeightBounds{Float64, Float64}, wf::IterativeWeightFinaliser{Int64}}

Return the static defaults of the HierarchicalOptimiser fields that may hold a TimeDependent.

Related

source
PortfolioOptimisers.reset_time_dependent_estimator — Method
reset_time_dependent_estimator(opt)

Replace every TimeDependent-valued field of opt with its static default, recursing through wrapper optimisers.

A time-dependent constraint is defined only over the folds of a cross-validation scheme, so a fold-less solve runs with the affected fields at their static defaults (see time_dependent_field_defaults). Called at the top of the _optimise methods; per-fold estimators produced by update_time_dependent_estimator contain no TimeDependent values, so they pass through unchanged. The default returns the estimator unchanged; hosts rebuild themselves, wrapper optimisers recurse.

Related

source
PortfolioOptimisers.reset_time_dependent_estimator — Method
reset_time_dependent_estimator(
    td::Union{TimeDependent{<:AbstractVector{<:Union{var"#s936", var"#s935"} where {var"#s936"<:NonFiniteAllocationOptimisationEstimator, var"#s935"<:NonFiniteAllocationOptimisationResult}}}, TimeDependent{<:TimeDependentOptimiserCallable}, TimeDependent{<:PreviousWeightsFunction}, TimeDependent{<:Union{Function, Type}}}
) -> Any

Return the optimiser a TimeDependent schedule takes outside every fold loop.

An optimiser position is required — there is no static default to fall back to — so the schedule must supply its own default, and one that does not throws a TimeDependentDefaultError. The fold-less optimiser is itself reset, so its own schedules resolve to their defaults too.

Related

source
PortfolioOptimisers.optimise — Method
optimise(
    td::Union{TimeDependent{<:AbstractVector{<:Union{var"#s936", var"#s935"} where {var"#s936"<:NonFiniteAllocationOptimisationEstimator, var"#s935"<:NonFiniteAllocationOptimisationResult}}}, TimeDependent{<:TimeDependentOptimiserCallable}, TimeDependent{<:PreviousWeightsFunction}, TimeDependent{<:Union{Function, Type}}},
    args...;
    kwargs...
) -> Any

Optimise with a TimeDependent schedule standing in for the optimiser, outside any fold loop.

There are no folds to index, so the schedule resolves to its default and that optimiser runs (see reset_time_dependent_estimator); a schedule with no default throws a TimeDependentDefaultError. Inside a fold loop this method is never reached — the loop resolves entry i first.

Related

source
PortfolioOptimisers.set_clustering_weight_finaliser_alg! — Function
set_clustering_weight_finaliser_alg!(model::JuMP.Model,
                                     alg::JuMPWeightFinaliserFormulation,
                                     wi::VecNum)

Add the deviation objective of alg to the weight finalisation model.

opt_weight_bounds has already added the decision vector w, the budget equality and the weight bounds. This method adds the epigraph variable t, the cone that bounds the deviation of w from wi, and the objective Min so * t. The cone is a NormOneCone for the two L1 formulations and a SecondOrderCone for the two L2 formulations.

Arguments

  • model: JuMP model, which must already carry w and the two scale expressions.
  • alg: The deviation formulation, one of the four JuMPWeightFinaliserFormulation subtypes.
  • wi: The weights the optimisation produced, which the model repairs.

Returns

  • nothing.

Details

  • The two relative formulations divide by wi, so they first replace each zero entry of wi in place with eps(eltype(wi)). The caller's vector carries that substitution afterwards.

Related

source
PortfolioOptimisers.opt_weight_bounds — Function
opt_weight_bounds(wf::JuMPWeightFinaliser, wb::WeightBounds, wi::VecNum) -> VecNum
opt_weight_bounds(wf::IterativeWeightFinaliser, wb::WeightBounds, w::VecNum) -> VecNum

Move a weight vector into the bounds wb, keeping the budget it already carries.

The bounds themselves are not changed. Weights that already satisfy the bounds are returned unchanged, without a solve.

The JuMPWeightFinaliser method builds the programme of its alg (see set_clustering_weight_finaliser_alg!) and solves it. A failed solve warns and falls back to a default IterativeWeightFinaliser. The IterativeWeightFinaliser method clips and redistributes instead, and may exhaust its passes with the bounds still violated.

Arguments

  • wf: Weight finaliser algorithm.
  • wb: Weight bounds.
  • wi, w: The weights the optimisation produced.

Returns

  • w::VecNum: The repaired weight vector.

Related

source
PortfolioOptimisers.finalise_weight_bounds — Function
finalise_weight_bounds(wf::WeightFinaliser, wb::WeightBounds, w::VecNum)

Apply weight finalisation to enforce bounds and determine the optimisation return code.

Runs opt_weight_bounds with the given finaliser and bounds, then returns a success or failure return code based on whether all weights are finite.

Finiteness is the whole test. A vector that still violates the bounds — which an IterativeWeightFinaliser returns when it exhausts its passes — is reported as an OptimisationSuccess.

Arguments

  • wf::WeightFinaliser: Weight finaliser algorithm.
  • wb::WeightBounds: Weight bounds configuration.
  • w::VecNum: Portfolio weights to finalise.

Returns

  • (retcode, w): Tuple of return code and adjusted weights.

Related

source
PortfolioOptimisers.port_opt_view — Method
port_opt_view(opt, i, args...)

Return a view or subset of an optimisation estimator for a given cluster index i.

Default fallback returns the estimator unchanged. Overridden for composite estimators (e.g. JuMPOptimiser, HierarchicalRiskParity) to slice all sub-estimators for the i-th cluster.

Arguments

  • opt: Optimisation estimator or result.
  • i: Cluster or asset index.
  • args...: Additional arguments (e.g. asset returns matrix).

Returns

  • Sliced or unchanged optimisation estimator.

Related

source
PortfolioOptimisers.port_opt_view — Method
port_opt_view(
    res::NonFiniteAllocationOptimisationResult,
    _::Colon,
    args...
) -> NonFiniteAllocationOptimisationResult

A precomputed optimisation result cannot be restricted to an asset subset.

Its weights were solved over the full universe and a sub-portfolio of them has no defined meaning, so an asset-subset view of a result throws. In particular, a TimeDependent schedule holding result entries is incompatible with asset-subsampling cross-validation (MultipleRandomised), whose fold loops view the optimiser to each fold's asset subset before the swap. The trivial all-assets view (Colon) passes the result through unchanged.

Related

source
PortfolioOptimisers.assert_special_nco_requirements — Function
assert_special_nco_requirements(opt)

Assert that the optimiser meets special requirements for Nested Clustered Optimisation (NCO).

The default implementation does nothing. Overridden for estimators (e.g. Stacking) that have requirements which must be validated before NCO can proceed.

Arguments

  • opt: Optimisation estimator, result, or vector thereof.

Returns

  • nothing.

Related

source
assert_special_nco_requirements(
    opt::AbstractVector{<:Union{var"#s936", var"#s935"} where {var"#s936"<:(Union{var"#s936", var"#s935"} where {var"#s936"<:NonFiniteAllocationOptimisationEstimator, var"#s935"<:NonFiniteAllocationOptimisationResult}), var"#s935"<:Union{TimeDependent{<:AbstractVector{<:Union{var"#s936", var"#s935"} where {var"#s936"<:NonFiniteAllocationOptimisationEstimator, var"#s935"<:NonFiniteAllocationOptimisationResult}}}, TimeDependent{<:TimeDependentOptimiserCallable}, TimeDependent{<:PreviousWeightsFunction}, TimeDependent{<:Union{Function, Type}}}}}
)

Assert special NCO requirements for each element of a vector of optimisation estimators or results.

Related

source
PortfolioOptimisers.factory — Method
factory(
    opt::Union{NonFiniteAllocationOptimisationEstimator, NonFiniteAllocationOptimisationResult},
    _
) -> FactorRiskContribution{JuMPOptimiser{__T_pe, __T_slv, __T_wb, __T_bgt, __T_sbgt, __T_gbgt, __T_xbgt, __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_fees, __T_sets, __T_tr, __T_ple, __T_ret, __T_sca, __T_ccnt, __T_cobj, __T_sc, __T_so, __T_ss, __T_card, __T_scard, __T_l2c, __T_lpc, __T_linfc, __T_l1, __T_l2, __T_linf, __T_lp, __T_brt, __T_x_src, __T_z_src, __T_strict}, _A, _B, _C, _D, _E, _F, Bool} where {__T_pe, __T_slv, __T_wb, __T_bgt, __T_sbgt, __T_gbgt, __T_xbgt, __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_fees, __T_sets, __T_tr, __T_ple, __T_ret, __T_sca, __T_ccnt, __T_cobj, __T_sc, __T_so, __T_ss, __T_card, __T_scard, __T_l2c, __T_lpc, __T_linfc, __T_l1, __T_l2, __T_linf, __T_lp, __T_brt, __T_x_src, __T_z_src, __T_strict, _A, _B, _C, _D, _E, _F}

Return opt unchanged.

Default pass-through factory for optimisation estimators and results. Overridden for estimators that carry parameters requiring update at each optimisation step.

Related

source
PortfolioOptimisers.assert_no_nearest_bind_optimiser_schedule — Method
assert_no_nearest_bind_optimiser_schedule(x, field::Symbol, host::Symbol)

Reject a bind = :nearest TimeDependent schedule in an optimiser-valued position no inner fold loop consumes.

bind picks which fold loop supplies the schedule's index. :nearest therefore says something different from :outermost only where the host opens a fold loop of its own and hands the field across it — NestedClustered.opti (its inner cross-validation is entered per cluster) and Stacking.opti[k] (entered per candidate), the positions declared by inner_fold_fields. Everywhere else the loop that reaches the host is the nearest one, and the two binds would name the same loop.

The positions this guards have no such inner loop:

  • A fallback (fb), on every host. The fallback walk is a retry chain within a single fold's solve — it has no fold indices of its own — so :nearest there is either redundant with :outermost or, behind a meta's inner cross-validation, silently wrong: it would resolve against the inner loop's fold numbers (tuning folds) instead of the backtest's periods, changing meaning with nesting depth. A per-fold fallback is fully expressible with :outermost, including nothing entries to switch it off on some folds (see TDO_OptE_Opt).
  • The outer optimisers (opto). They consume the combined inner output, once per solve.
  • SubsetResampling.opt. Its internal loop is over randomly drawn asset subsets, not time folds.

So a :nearest schedule in any of them has no nearest fold loop to bind to, and is rejected at construction rather than resolving against a loop the caller did not mean. No-op for anything that is not a TimeDependent.

Related

source
PortfolioOptimisers.entitled — Function
entitled(opt, f::Symbol, all_binds::Bool)

Return true when the recursion position described by all_binds may consume a bind = :nearest schedule in field f of opt.

Entitlement is per-field, not per-host: a loop scanning with all_binds = true takes :nearest schedules everywhere except in the fields the host hands across its own inner fold loop (see inner_fold_fields) — for those, the host's inner loop is the nearest one, whatever loop is doing the scanning. A field is taken by a pass iff entitled(opt, f, all_binds) || bind === :outermost.

Related

source
PortfolioOptimisers.OptE_Opt — Type
const OptE_Opt = Union{<:NonFiniteAllocationOptimisationEstimator,
                       <:NonFiniteAllocationOptimisationResult}

Alias for a non-finite allocation optimisation estimator or result.

Matches either a NonFiniteAllocationOptimisationEstimator (specifying an optimiser configuration) or a NonFiniteAllocationOptimisationResult (a pre-computed result). Used for dispatch in cross-validation and optimisation workflows that accept either form.

Related

source
PortfolioOptimisers.extract_fees — Function
extract_fees(res::OptimisationResult) -> Any
extract_fees(
    res::OptimisationResult,
    fees::Union{Nothing, Fees}
) -> Any

Obtains the fees to use for net return calculations from an optimisation result.

An explicitly provided fees wins. Otherwise the fees are read from the fees property of res, and a result exposing no such property gives nothing.

Arguments

  • res: Optimisation result, potentially containing a fees property.
  • fees: Optional fees to use, which take precedence over res.fees if provided.

Returns

  • Option{<:Fees}: The fees to use for net return calculations, or nothing if not found.

Related

source
PortfolioOptimisers.extract_pr — Function
extract_pr(res::OptimisationResult) -> Any
extract_pr(
    res::OptimisationResult,
    pr::Union{Nothing, AbstractPriorResult, ReturnsResult}
) -> Any

Extracts the prior result for risk calculation from an optimisation result.

An explicitly provided pr wins. Otherwise the one test is hasproperty(res, :pr), which property forwarding answers for a nested result: a JuMP leaf reaches its prior at res.jr.pa.pr, and res.pr resolves to it. A result that exposes no pr property throws.

Arguments

  • res: Optimisation result, which carries a prior result as its pr property or reaches one by property forwarding.
  • pr: Optional prior result to use for risk calculation, which takes precedence over the one found in res.

Returns

  • pr::Pr_RR: The prior result to use for risk calculation. Throws an ArgumentError when none is found.

Related

source
PortfolioOptimisers.synthetic_asset_weights — Function
synthetic_asset_weights(
    w::AbstractVector{<:Union{var"#s89", var"#s88"} where {var"#s89"<:Number, var"#s88"<:AbstractJuMPScalar}}
) -> Any

Normalises inner weights into the convex weights that collapse real assets onto a meta-optimiser's synthetic assets.

Quantities carried alongside the returns matrix are either extensive (returns, benchmark returns) and collapse as a plain weighted sum w'x, or intensive (rates such as rd.iv and rd.ivpa) and collapse as a weighted average. A plain weighted sum scales an intensive quantity by the gross exposure sⱼ = Σᵢ|wᵢⱼ|, so a shorting or leveraged portfolio (sⱼ ≠ 1) inflates a rate that should not depend on gross exposure at all.

Normalising the weights once here makes every subsequent product a convex combination, so callers collapsing an intensive quantity need only pass their weights through this function.

Arguments

  • w: Inner weights. A vector collapses onto a single synthetic asset; a matrix (assets × synthetic assets) collapses each column independently.

Returns

  • w: abs.(w), with each column scaled to sum to one. A column summing to zero — a degenerate synthetic asset — is left as-is rather than divided, preserving the zero row it already produced.

Related

source
PortfolioOptimisers.collapse_feature_matrix — Function
collapse_feature_matrix(Z::Nothing, sq::Bool, wi::MatNum)
collapse_feature_matrix(Z::MatNum, sq::Bool, wi::MatNum)
collapse_feature_matrix(Z::Arr3Num, sq::Bool, wi::MatNum)
collapse_feature_matrix(Z::Nothing, w::VecNum)
collapse_feature_matrix(Z::MatNum, w::VecNum)
collapse_feature_matrix(Z::Arr3Num, w::VecNum)

Aggregate a feature matrix onto the synthetic assets a meta-optimiser builds for its outer problem.

A meta-optimiser's outer problem allocates across synthetic assets — NestedClustered's clusters, Stacking's inner portfolios — each of which is a weighted combination of the real ones. Every quantity the outer ReturnsResult carries has to be re-expressed on that universe, and a feature matrix is no exception: without this collapse the outer optimiser has no feature matrix at all, so a FeatureDistance there throws rather than clustering the synthetic universe.

Features are treated as intensive, exactly as iv and ivpa are: the collapse is a convex combination, obtained by pushing the inner weights through synthetic_asset_weights first. An un-normalised weighted sum would scale each synthetic asset's feature vector by its gross exposure sⱼ = Σᵢ|wᵢⱼ|, inflating it under leverage or shorting. Under the default AngularDist the normalisation is a mathematical no-op for a rectangular feature matrix — scaling one row of the result leaves every cosine unchanged — but it is not one in the square case, where the two-sided product rescales feature columns as well, and it is what keeps the collapse bounded for any sⱼ > 0. An extensive feature (a market capitalisation, a headcount) wanting a weighted sum is not supported: the divisor depends on the inner solve, so a caller cannot pre-scale their way to one.

The two weight shapes

  • A weight matrix wi (assets × synthetic assets) collapses the whole universe at once. When sq is true the feature axis is the asset axis (features_are_assets), so it is contracted too and the result is again square on the synthetic universe.
  • A weight vector w collapses onto a single synthetic asset, which is all reconstruct_rd has in scope within a cross-validation fold. It takes no sq argument, and that absence is the statement: the second contraction of the square case needs every synthetic asset's weights simultaneously, and contracting the feature axis with the one vector available would collapse it to a single number per synthetic asset — a feature space in which every asset is trivially identical. A square feature matrix therefore keeps the real assets as its feature axis through the fold path, reading as "this synthetic asset's weighted-average neighbourhood".

Degenerate synthetic assets

A synthetic asset whose weights are entirely zero has sⱼ = 0; synthetic_asset_weights leaves the column alone rather than dividing, so the collapse gives that asset a zero feature vector instead of throwing. It then lands on the zero-feature-vector convention the distance kernel already implements, matching the zero returns column, iv and ivpa the same degenerate weights already produce.

Arguments

  • Z: Feature matrix, static (assets × features) or time-varying (observations × assets × features).
  • sq: Whether the feature axis is the asset axis, from features_are_assets.
  • wi: Inner weights, assets × synthetic assets.
  • w: Inner weights for a single synthetic asset, assets × 1.

Returns

  • nothing when Z is nothing.
  • Matrix arity: synthetic assets × features, or synthetic assets × synthetic assets when sq; observations × … with the same trailing axes for a time-varying Z.
  • Vector arity: a features-length vector for a static Z, an observations × features matrix for a time-varying one.

Related

source