Mean Risk: private API

PortfolioOptimisers.mean_risk_td_defaults — Function
mean_risk_td_defaults(

) -> @NamedTuple{r::Variance{RiskMeasureSettings{Float64, Nothing, Bool}, Nothing, Nothing, Nothing, SquaredSOCRiskExpr, EigenFallbackSquareRoot, SquareRootRatio, Nothing}, obj::MinimumRisk}

Return the static defaults of the MeanRisk fields that can hold a TimeDependent.

The constructor reads these defaults when it checks each schedule with assert_time_dependent_substitution, and time_dependent_field_defaults returns them. So the value of each field outside a fold loop is declared once. A field whose static default is nothing is not in the result.

Returns

  • (; r = Variance(), obj = MinimumRisk()).

Related

source
PortfolioOptimisers.solve_mean_risk! — Function
solve_mean_risk!(model, mr, pr, ::Val{false}, ::Val{false}, fees, attrs)
solve_mean_risk!(model, mr, pr, ::Val{true}, ::Val{false}, fees, attrs)
solve_mean_risk!(model, mr, pr, ::Val{false}, ::Val{true}, fees, attrs)
solve_mean_risk!(model, mr, pr, ::Val{true}, ::Val{true}, fees, attrs)

Solve the model of a MeanRisk once, or once for each point of its frontier sweep.

The first Val is true when the model holds a :ret_frontier registry, and the second is true when it holds a :risk_frontier registry. Each method reads the return terms from attrs.ret.

Algorithm

  1. With no frontier, set the objective of mr.obj with set_portfolio_objective_function!, and solve once with optimise_JuMP_model!.
  2. With a return frontier, resolve its spans with compute_ret_lbs, giving ret_frontier.
  3. With a risk frontier, resolve its spans with compute_risk_ubs, giving risk_frontier. Steps 2 and 3 both run before step 4, so every corner solve reads the model without a frontier row.
  4. Register one parameter and one ceiling row for each entry of risk_frontier with set_risk_frontier_parameters!, giving risk_axis. Register one parameter and one floor row for each entry of ret_frontier with set_ret_frontier_parameters!, giving ret_axis.
  5. Set the objective of mr.obj, and solve once at each point of the product of the axes with frontier_sweep!.

Arguments

  • model::JuMP.Model: The JuMP optimisation model.
  • mr::MeanRisk: The optimiser.
  • pr: Prior result.
  • ::Val{Bool}: true for a return frontier.
  • ::Val{Bool}: true for a risk frontier.
  • fees: Optional fees structure.
  • attrs::ResolvedJuMPOptimiser: The resolved bundle of the optimiser, which holds the return terms.

Returns

  • (retcode, sol): One return code and one solution without a frontier, and one of each for each point of the sweep with a frontier.

Related

source
PortfolioOptimisers.return_term — Function
return_term(ret, i)

Return the return term i of the ret field of an optimiser.

The field holds one term or a vector of terms. A caller that computes the value of a term at a weight vector, such as compute_ret_lbs, reads the term through this function, so it does not test the form of the field. One term answers every index, because a configuration of one term has the index 1 alone.

Returns

  • ret itself when it is one term, and ret[i] when it is a vector.

Related

source
PortfolioOptimisers.compute_ret_lbs — Function
compute_ret_lbs(model, mr, pr, fees, attrs)

Resolve the sweep points of the return frontier, one span for each swept return term.

An entry whose bound is a vector of numbers keeps it. An entry whose bound is a Frontier gets the span of a return floor that the # Mathematical definition of MeanRisk states. A frontier of k swept terms costs k + 1 corner solves: one minimum-risk solve for the low ends, and one solve for the high end of each term.

The high end of term i comes from a portfolio that maximises term i alone. The value of term i at the portfolio that maximises the sum of the terms depends on the scale of the other terms. That value can be less than its value at the minimum-risk portfolio, and then the span descends. The portfolio that maximises term i alone is at least as good for term i as every other portfolio of the same feasible set, so its span ascends.

Algorithm

  1. Read the :ret_frontier registry from the model, giving ret_frontier. Collect the positions of the entries whose bound is not a vector of numbers, giving idx.
  2. When idx is empty, return ret_frontier.
  3. Set the objective MinimumRisk and solve, giving sol_min. Unregister the objective expression.
  4. For each position j of idx, read the term index i of the entry. Set the objective MaximumElementReturn(i) and solve, giving sol_max. Unregister the objective expression.
  5. Compute the value of term i with expected_return at sol_min.w and at sol_max.w, giving rt_min and rt_max. The bound binds on the expression of the term, so a term with an uncertainty set gives its worst-case return, through ucs_expected_return. The resolved term holds the set that the model fitted. The value of the expression at the minimum-risk corner can lie below the worst case, because that solve does not raise the return.
  6. Replace the bound of entry j with range(rt_min, rt_max; length = N), with the N of its Frontier.

Arguments

  • model::JuMP.Model: The JuMP optimisation model.
  • mr::MeanRisk: The optimiser.
  • pr: Prior result.
  • fees: Optional fees structure.
  • attrs::ResolvedJuMPOptimiser: The resolved bundle of the optimiser, which holds the return terms.

Validation

  • Each corner solve must succeed. Otherwise an ArgumentError names the solve and its return code, because a span from a failed solve is not a span.

Returns

  • A copy of the registry, with the bound of each entry of idx resolved.

Related

source
compute_ret_lbs(ret_frontier::VecPair, ::Nothing)

Return a NearOptimalCentering return frontier unchanged.

nothing means that no return term holds a Frontier. Each term states its levels as a vector of numbers, so there is no span to resolve.

Arguments

  • ret_frontier::VecPair: The :ret_frontier Model State entry.
  • ::Nothing: No per-term spans were computed.

Returns

  • ret_frontier, unchanged.

Related

source
compute_ret_lbs(ret_frontier::VecPair, rt_ends::VecPair)

Resolve the return frontier of a NearOptimalCentering from the spans of its setup.

Unlike the method of MeanRisk, this method solves no corner. near_optimal_centering_setup already solved the anchor of minimum risk and one maximum-return problem for each term that holds a Frontier, so this method only turns each span into its levels.

Algorithm

  1. Keep an entry whose levels are a vector of numbers.
  2. For an entry of term $i$ that holds a Frontier of N points, find the span i => (rt_min_i, rt_max_i) in rt_ends.
  3. Replace the Frontier with range(rt_min_i, rt_max_i; length = N).

Arguments

  • ret_frontier::VecPair: The :ret_frontier Model State entry.
  • rt_ends::VecPair: The spans of the terms, as i => (rt_min_i, rt_max_i).

Validation

  • Each term that holds a Frontier has a span in rt_ends, ArgumentError otherwise.

Returns

  • The return frontier with every span resolved into a range of sweep points.

Related

source
PortfolioOptimisers._rebuild_risk_frontier — Function
_rebuild_risk_frontier(pr::AbstractPriorResult, fees::Option{<:Fees},
                       r::AbstractBaseRiskMeasure, risk_frontier::VecPair,
                       w_min::VecNum, w_max::VecNum, i::Integer = 1)

Resolve one Frontier risk bound into the span of numbers that the sweep writes.

The span is the span of a risk ceiling that the # Mathematical definition of MeanRisk states, and r measures the risk of each corner portfolio. The two ends are sorted, so the span ascends for every measure. The risk of a measure in a vector can be larger at the minimum-risk portfolio than at the maximum-return portfolio, because the minimum-risk solve minimises the scalarised risk of all the measures.

Algorithm

  1. Read the expression, the Frontier, the polarity and the owner of entry i.
  2. Compute the risk of r at w_min and at w_max with expected_risk. The functor of r gives the value of the bounded expression.
  3. Transform each risk with variance_risk_bounds_val and the bound of the Frontier, and multiply it by factor, giving the two ends.
  4. Sort the two ends with minmax, and divide the interval into N levels with range, giving ub.

Arguments

  • pr: Prior result.
  • fees: Optional fees structure.
  • r::AbstractBaseRiskMeasure: The measure that owns entry i, already through factory.
  • risk_frontier::VecPair: The :risk_frontier registry.
  • w_min::VecNum: Weights of the minimum-risk corner portfolio.
  • w_max::VecNum: Weights of the maximum-return corner portfolio.
  • i::Integer = 1: Position of the entry in the registry.

Returns

  • The rebuilt entry. Its keys, its expression, its polarity and its owner are those of entry i, and only the bound changes. Each part comes from position i. An expression from position 1 bounds the first measure twice, and leaves the measure of entry i with no bound.

Related

source
PortfolioOptimisers.rebuild_risk_frontier — Function
rebuild_risk_frontier(model::JuMP.Model, mr::MeanRisk, pr::AbstractPriorResult,
                      fees::Option{<:Fees}, risk_frontier::VecPair, idx, attrs)

Resolve every unresolved Frontier risk bound into a span of numbers.

Two corner portfolios bound every span, and the method solves each of them once. _rebuild_risk_frontier then builds the span of each entry from the measure that owns the entry and from the Frontier of the entry.

Algorithm

  1. Copy the registry, giving risk_frontier.
  2. Set the objective MinimumRisk and solve, giving sol_min. Unregister the objective expression.
  3. Set the objective MaximumReturn and solve, giving sol_max. Unregister the objective expression.
  4. For each position i of idx, resolve the owner of entry i against the prior and the solver with factory, giving r. set_risk_frontier_owner! wrote the owner during Model Assembly.
  5. Replace entry i with _rebuild_risk_frontier of r at sol_min.w and sol_max.w.

Arguments

  • model::JuMP.Model: The JuMP optimisation model.
  • mr::MeanRisk: The optimiser.
  • pr: Prior result.
  • fees: Optional fees structure.
  • risk_frontier::VecPair: The :risk_frontier registry.
  • idx::VecInt: Registry positions that need a rebuild, as unresolved_risk_frontier returns them.
  • attrs::ResolvedJuMPOptimiser: The resolved bundle of the optimiser.

Validation

  • Each corner solve must succeed. Otherwise an ArgumentError names the solve and its return code, because a span from a failed solve is not a span.

Returns

  • A copy of the registry, with every entry of idx resolved and every other entry unchanged.

Related

source
PortfolioOptimisers.unresolved_risk_frontier — Function
unresolved_risk_frontier(model::JuMP.Model)

Read the risk frontier out of model and find the entries that still need a rebuild.

An entry is resolved when its bound is a vector of numbers. Every other entry holds a Frontier, which rebuild_risk_frontier turns into numbers. Every method of compute_risk_ubs calls this function first, and the methods differ only in the call to rebuild_risk_frontier that follows.

Arguments

  • model::JuMP.Model: The model, which holds the :risk_frontier registry.

Returns

  • (risk_frontier, idx): The frontier vector of pairs, and the indices of its unresolved entries. An empty idx means that no rebuild is needed.

Related

source
PortfolioOptimisers.compute_risk_ubs — Function
compute_risk_ubs(model::JuMP.Model, mr::MeanRisk, pr::AbstractPriorResult,
                 fees::Option{<:Fees}, attrs::ResolvedJuMPOptimiser)

Resolve the sweep points of the risk frontier of the model.

NearOptimalCentering has a method of its own, which takes the two corner portfolios that its setup already solved.

Algorithm

  1. Read the registry and the positions of its unresolved entries with unresolved_risk_frontier, giving risk_frontier and idx.
  2. When idx is empty, return risk_frontier.
  3. Otherwise resolve the entries of idx with rebuild_risk_frontier.

Arguments

  • model::JuMP.Model: The JuMP optimisation model.
  • mr::MeanRisk: The optimiser.
  • pr: Prior result.
  • fees: Optional fees structure.
  • attrs::ResolvedJuMPOptimiser: The resolved bundle of the optimiser.

Returns

  • The registry, with the bound of every entry resolved into a vector of numbers.

Related

source
compute_risk_ubs(model::JuMP.Model, noc::NearOptimalCentering{<:Any, <:Any, <:Any, <:Any, <:Any, <:Any, <:Any, <:Any, <:Any, <:Any, <:ConstrainedNearOptimalCentering}, pr::AbstractPriorResult, fees::Option{<:Fees}, w_min::VecNum, w_max::VecNum, args...)

Compute risk upper bounds for a constrained NearOptimalCentering frontier sweep.

Identifies risk frontier entries that are not yet resolved (i.e. not concrete weight vectors) and rebuilds them using the minimum and maximum portfolio weights.

Arguments

  • model::JuMP.Model: JuMP optimisation model containing risk_frontier.
  • noc::NearOptimalCentering{..., <:ConstrainedNearOptimalCentering}: Constrained Near Optimal Centering optimiser.
  • pr::AbstractPriorResult: Prior result with asset moments.
  • fees::Option{<:Fees}: Optional fees configuration.
  • w_min::VecNum: Minimum-risk portfolio weights.
  • w_max::VecNum: Maximum-risk (maximum-return) portfolio weights.

Returns

  • Updated risk frontier vector of (keys, vals) pairs.

Related

source
PortfolioOptimisers.build_mean_risk_model — Function
build_mean_risk_model(mr::MeanRisk, attrs::ResolvedJuMPOptimiser,
                      rd::ReturnsResult, str_names::Bool; blocks::Tuple = ())

Build the model of a MeanRisk, with every constraint, return term and risk measure, and with no objective.

mr.obj shapes the model. Under MaximumRatio the model holds the homogenised weights, and under every other objective $k$ is the number 1. _optimise builds the model of the optimisation with this function. resolve_ratio_frontier! builds a second model with it, with MinimumRisk in place of the ratio.

Algorithm

  1. Make a new model. With str_names, give each variable and each row its string name.
  2. Register the scales with set_model_scales!, the number of observations with set_model_observations!, the homogenisation variables of a ratio with set_maximum_ratio_factor_variables!, the corner of a lifted variance with set_sdp_lift_corner!, and the weights with set_w!.
  3. Add the weight bounds, the budgets, the constraints, the return terms and the risk measures of every block with assemble_jump_model!.

Arguments

  • mr::MeanRisk: The optimiser, already reduced to the investable assets.
  • attrs::ResolvedJuMPOptimiser: The resolved bundle of the optimiser.
  • rd: The returns result to use.
  • str_names::Bool: true gives each variable and each row of the model its string name.
  • blocks: The blocks after the block of the head, as assemble_jump_model! takes them.

Returns

  • model::JuMP.Model: The model, with no objective.

Related

source
PortfolioOptimisers.set_frontier_spans! — Function
set_frontier_spans!(model::JuMP.Model, name::Symbol, resolved::VecPair)

Write the bound of each entry of resolved into the entry of the registry name of model that has the same key.

The entries of resolved belong to another model, built from the same optimiser, so their expressions are expressions of that model. Only the bound moves. The key of an entry, (bound_var_key, bound_key), names the bound in each model, so the function matches the entries by key and not by position.

Arguments

  • model::JuMP.Model: The JuMP optimisation model.
  • name::Symbol: The registry, :ret_frontier or :risk_frontier.
  • resolved::VecPair: The resolved registry of the other model.

Validation

  • Each entry of the registry of model has an entry with the same key in resolved. Otherwise an ArgumentError names the key.

Returns

  • nothing. The registry name of model is replaced with a copy that holds the bounds of resolved.

Related

source
PortfolioOptimisers.resolve_ratio_frontier! — Function
resolve_ratio_frontier!(model::JuMP.Model, mr::MeanRisk,
                        attrs::ResolvedJuMPOptimiser, rd::ReturnsResult;
                        blocks::Tuple = ())

Resolve each Frontier of the model of a MaximumRatio on a model that is not homogenised, and write the spans into the registries of model.

The span of a Frontier reads the two corner portfolios $\boldsymbol{w}^{-}$ and $\boldsymbol{w}^{+}$, which the # Mathematical definition of MeanRisk states over the weights $\boldsymbol{w}$. Under every other objective $k$ is the number 1, so the model of the optimisation states these programmes, and compute_ret_lbs and compute_risk_ubs solve the corners on it. The model of a MaximumRatio holds the weights $\boldsymbol{y} = k \boldsymbol{w}$, the normalisation row and the floor of $k$. On that model, a minimum-risk solve gives the maximum-ratio portfolio. A maximum-return solve is unbounded in $k$ when $r_f > 0$, and gives any feasible point when $r_f = 0$.

A fix of $k = 1$ on that model does not give the programmes back. The objective also sets the corner of a lifted variance, set_sdp_lift_corner!, and the mark of mark_risk_minimised! that a semidefinite phylogeny reads. So the method builds a second model with build_mean_risk_model, with MinimumRisk in place of the ratio, and resolves the registries on it. The span is then the span that the same Frontier has under MinimumRisk.

The objective of the second model changes the model only through the mark of mark_risk_minimised!. With the mark, a semidefinite phylogeny on the weights of a variance in the objective omits its penalty $p\,\mathrm{tr}(\mathbf{W})$. Neither corner programme holds that penalty. Under MaximumReturn the penalty enters both corner solves, and a penalty that is large next to the returns moves the maximum-return corner far from the maximum return. Without a semidefinite phylogeny, the two objectives build the same model.

The cost is one more model build. Only a MaximumRatio pays it, and only when a registry holds a Frontier. A vector of bounds needs no corner solve, and it costs nothing.

Algorithm

  1. Under an objective that is not a MaximumRatio, return.
  2. Collect the registries, :ret_frontier and :risk_frontier, that hold an entry whose bound is not a vector of numbers. When there is none, return.
  3. Rebuild mr with the objective MinimumRisk(), giving cmr. Build its model with build_mean_risk_model and the blocks of blocks, giving cmodel. So the corners solve on the feasible set of every block.
  4. Resolve the return registry of cmodel with compute_ret_lbs, and its risk registry with compute_risk_ubs. The order is the order of solve_mean_risk!.
  5. Write each resolved bound into the entry of model that has the same key, with set_frontier_spans!. solve_mean_risk! then finds no entry to resolve, and solves no corner on the homogenised model.

Arguments

  • model::JuMP.Model: The JuMP optimisation model.
  • mr::MeanRisk: The optimiser, already reduced to the investable assets.
  • attrs::ResolvedJuMPOptimiser: The resolved bundle of the optimiser.
  • rd: The returns result to use.
  • blocks: The blocks after the block of the head, as assemble_jump_model! takes them.

Validation

Returns

  • nothing.

Related

source