Near optimal centering (a): private API

PortfolioOptimisers.NearOptimalSetup — Type
struct NearOptimalSetup{__T_w_opt, __T_rk_opt, __T_rt_opt, __T_rk_delta, __T_rt_delta, __T_rt_min, __T_rt_max, __T_rt_ends, __T_w_min, __T_w_max, __T_r, __T_opt, __T_attrs, __T_w_min_retcode, __T_w_opt_retcode, __T_w_max_retcode} <: AbstractResult

The data that near_optimal_centering_setup computes before the centring model of NearOptimalCentering is built.

It holds the three anchors, the bounds $\epsilon_{1}$ and $\epsilon_{2}$ of the near optimal region, the returns of the anchors, the risk measures and the optimiser that the centring model reads, and the return codes of the anchor sub-problems.

Fields

  • w_opt: Anchor portfolio of the objective, or a vector of them.
  • rk_opt: Risk ceiling $\epsilon_{2}$ of the near optimal region, or one for each point of a frontier sweep.
  • rt_opt: Return floor $\epsilon_{1}$ of the near optimal region, or one for each point of a frontier sweep.
  • rk_delta: Width of the near optimal region in risk, the slack of the risk ceiling rk_opt at the anchor of the objective.
  • rt_delta: Width of the near optimal region in return, the slack of the return floor rt_opt at the anchor of the objective.
  • rt_min: Return of the anchor of minimum risk.
  • rt_max: Return of the anchor of maximum return.
  • rt_ends: The span of each return term that holds a Frontier, as i => (rt_min_i, rt_max_i) pairs, or nothing when no return term holds one. The low end is the return of the term at the anchor of minimum risk. The high end is its return at the portfolio that maximises that term alone.
  • w_min: Anchor portfolio of minimum risk.
  • w_max: Anchor portfolio of maximum return.
  • r: Risk measure or vector of risk measures.
  • opt: JuMP optimiser configuration.
  • attrs: The resolved bundle of the inner JuMP optimiser, a ResolvedJuMPOptimiser, which the Model Assembly reads.
  • w_min_retcode: Return code of the sub-problem of minimum risk.
  • w_opt_retcode: Return code of the sub-problem of the objective, or one for each point of a frontier sweep.
  • w_max_retcode: Return code of the sub-problem of maximum return.

Related

source
PortfolioOptimisers.near_optimal_centering_td_defaults — Function
near_optimal_centering_td_defaults(

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

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

The check of the constructor, assert_time_dependent_substitution, and time_dependent_field_defaults both read it, so the value of a field outside a fold loop is stated once. A field whose static default is nothing is not in the tuple.

Related

source
PortfolioOptimisers.near_optimal_centering_risks — Function
near_optimal_centering_risks(scalariser, r, pr, fees, slv, w_min, w_opt, w_max)

Return the risk of the three anchor portfolios of NearOptimalCentering.

The barrier compares these values with the model's :risk expression, so each value has the units of that expression. The model drops the combination weight scale of a single measure, so the method for one measure does not apply it. The model combines a vector of measures with their weights, so the method for a vector applies each scale and then the scalariser.

Algorithm

  1. Fit the measures to the prior and the solvers with factory.
  2. For one measure, return the risk of w_min, of w_opt and of w_max from expected_risk.
  3. For a vector of measures, compute the three risks of each measure times its settings.scale, and combine the measures with scalariser.

Arguments

  • scalariser: Scalariser of a vector of measures, such as SumScalariser. The method for one measure does not read it.
  • r: Risk measure or vector of risk measures.
  • pr: Prior result.
  • fees: Fees, or nothing.
  • slv: Solver or vector of solvers.
  • w_min: Anchor portfolio of minimum risk.
  • w_opt: Anchor portfolio of the objective, or a vector of them.
  • w_max: Anchor portfolio of maximum return.

Returns

  • (risk_min, risk_opt, risk_max): The risks of the three anchors. risk_opt is a vector when w_opt holds one anchor for each point of a frontier sweep.

Related

source
PortfolioOptimisers.near_optimal_centering_setup — Function
near_optimal_centering_setup(noc::NearOptimalCentering, rd::ReturnsResult;
                             blocks::Tuple = (), kwargs...)

Solve the anchors of NearOptimalCentering, and compute the bounds of its near optimal region.

Algorithm

  1. Process the optimiser into its attributes with resolve_jump_optimiser, with the blocks of blocks, reduce noc and rd to the investable universe, and bind a data benchmark to the rows of the view. Give the blocks after the first of the bundle to every anchor sub-problem below, viewed at the investable universe, with constraint_block_steps.
  2. If an anchor of minimum risk or of maximum return is missing, if the variant is UnconstrainedNearOptimalCentering, or if a return term holds a Frontier, make the copies of the risk measures and of the optimiser without bounds. The copies keep their uncertainty sets, so every anchor and the centring model read the same worst case.
  3. Solve each missing anchor as a MeanRisk problem. The anchors of minimum risk and of maximum return solve with the copies without bounds, and the anchor of obj solves with r and opt as they are.
  4. For the unconstrained variant, replace r and opt with the copies without bounds, which the centring model reads.
  5. Compute the risks of the anchors with near_optimal_centering_risks on r, and their returns with expected_return on the return terms of opt. Thus each anchor is a value of the expression that the centring model bounds. A term with a fitted uncertainty set gives its worst-case return, through ucs_expected_return.
  6. For each return term that holds a Frontier, compute its span with return_term_ends.
  7. Compute $\epsilon_{2} = R(\boldsymbol{w}_{\mathrm{opt}}) + (R(\boldsymbol{w}_{\max}) - R(\boldsymbol{w}_{\min})) / m$ and $\epsilon_{1} = \mathrm{ret}(\boldsymbol{w}_{\mathrm{opt}}) - (\mathrm{ret}(\boldsymbol{w}_{\max}) - \mathrm{ret}(\boldsymbol{w}_{\min})) / m$, with $m = T / N$ when bins is nothing.

Arguments

  • noc::NearOptimalCentering: The estimator.
  • rd: The returns result to use.
  • blocks: The blocks after the block of noc.opt, the keyword blocks of resolve_jump_optimiser.
  • kwargs...: Keyword arguments passed to resolve_jump_optimiser.

Returns

  • setup::NearOptimalSetup: The anchors, the bounds of the region and the return codes of the anchor sub-problems.

Related

source
PortfolioOptimisers.return_term_ends — Function
return_term_ends(swept, ret, nb_r, nb_opt, rd, pr, fees, w_min, w_ini; blocks = ())

Return the span of each return term that holds a Frontier.

The low end of the span of term $i$ is its return at the anchor of minimum risk w_min. The high end is its return at the portfolio that maximises term $i$ alone, so each term costs one solve. The anchor of maximum return maximises the combined return, so its value of term $i$ depends on the scale of the other terms, and it can be below the low end.

Algorithm

  1. For each index $i$ in swept, solve a MeanRisk problem with the objective MaximumElementReturn(i), the risk measures nb_r, the optimiser nb_opt, the initial weights w_ini and the blocks blocks.
  2. Make the pair i => (rt_min_i, rt_max_i) of the returns of term $i$ at w_min and at that solution.

Arguments

  • swept::VecInt: Indices of the return terms that hold a Frontier.
  • ret: The return terms of the processed optimiser.
  • nb_r: The risk measures without bounds.
  • nb_opt::JuMPOptimiser: The optimiser without return bounds.
  • rd: The returns result to use.
  • pr::AbstractPriorResult: Prior result.
  • fees: Fees, or nothing.
  • w_min::VecNum: Anchor of minimum risk.
  • w_ini: Initial weights of each solve, or nothing.
  • blocks: The blocks after the block of nb_opt, on the reduced universe, from constraint_block_steps.

Validation

  • Each solve must succeed, ArgumentError otherwise.

Returns

  • A vector of i => (rt_min_i, rt_max_i) pairs, one per swept term.

Related

source
PortfolioOptimisers.barrier_weight_bounds — Function
barrier_weight_bounds(w_lb::VecNum, w_ub::VecNum)

Return the assets whose lower bound and whose upper bound enter the barrier of NearOptimalCentering.

A weight bound is an inequality of the near optimal region, so its margin is a term of the barrier. An infinite bound states no inequality, and it has no term. An asset with $w_{l,i} = w_{u,i}$ has a fixed weight. That pair is an equality, and an equality has no term in the barrier: the two margins are zero at every feasible point, so their logarithms have no finite value.

Algorithm

  1. Make il, the indices $i$ with a finite $w_{l,i}$ and $w_{l,i} \neq w_{u,i}$.
  2. Make iu, the indices $i$ with a finite $w_{u,i}$ and $w_{l,i} \neq w_{u,i}$.

Arguments

  • w_lb::VecNum: Lower weight bounds, one per asset.
  • w_ub::VecNum: Upper weight bounds, one per asset.

Returns

  • (il, iu)::Tuple{Vector{Int}, Vector{Int}}: The assets of the lower terms and of the upper terms.

Related

source
PortfolioOptimisers.set_near_optimal_centering_constraints! — Function
set_near_optimal_centering_constraints!(model::JuMP.Model, wb::WeightBounds, m_rk::Number,
                                        m_rt::Number)

Add the logarithmic barrier of NearOptimalCentering to the model, and return it.

Each logarithm is a variable bounded above by an exponential cone, so the barrier is a conic objective. The objective maximises each of these variables, so at the optimum each one equals its logarithm. The barrier reads the risk ceiling noc_rk and the return floor noc_rt that the caller registers, and barrier_weight_bounds selects the weight bounds that have a term.

The two anchor cones divide their slack by a scale, $m_{R}$ and $m_{\mathrm{ret}}$. This subtracts the constant $\ln m$ from each logarithm, so the optimum does not move. The scales are the widths rk_delta and rt_delta of NearOptimalSetup, which are the slacks of the anchor cones at the anchor of the objective, so each slack is of order one near the centre. anchor_cone_scale computes them, and it takes one when the region is degenerate. A slack in the units of the risk is small against the other entries of the cone. With the EntropicValueatRisk ceiling of a ConstrainedNearOptimalCentering on 5 assets, with Clarabel at its default settings, the undivided cones stopped at ALMOST_SOLVED and broke the ceiling by 1.3 %, or failed. The cones divided by the size of the anchor broke it by 1.4e-5, or failed. The cones divided by the widths reached OPTIMAL at 25, 50 and 75 % of the span of the ceiling, and held it.

Note

The scales give the solver a well-conditioned model, and nothing more. A solver can still stop at an approximate solution. The check_sol field of Solver decides whether that solution is a success. The default refuses it and tries the next solver.

JuMP formulation

Variables

  • log_risk, log_ret: $t_{R}$, $t_{\mathrm{ret}}$.
  • log_w: $\boldsymbol{t}_{l}$, one entry for each asset in $\mathcal{L}$.
  • log_delta_w: $\boldsymbol{t}_{u}$, one entry for each asset in $\mathcal{U}$.

Constraints

  • clog_risk: $s\,(t_{R}, 1, (\epsilon_{2} - R(\boldsymbol{w})) / m_{R}) \in \mathcal{K}_{\exp}$, which is $t_{R} \leq \ln((\epsilon_{2} - R(\boldsymbol{w})) / m_{R})$.
  • clog_ret: $s\,(t_{\mathrm{ret}}, 1, (\mathrm{ret} - \epsilon_{1}) / m_{\mathrm{ret}}) \in \mathcal{K}_{\exp}$, which is $t_{\mathrm{ret}} \leq \ln((\mathrm{ret} - \epsilon_{1}) / m_{\mathrm{ret}})$.
  • clog_w[i]: $s\,(t_{l,i}, 1, w_{i} - w_{l,i}) \in \mathcal{K}_{\exp}$ for $i \in \mathcal{L}$.
  • clog_delta_w[i]: $s\,(t_{u,i}, 1, w_{u,i} - w_{i}) \in \mathcal{K}_{\exp}$ for $i \in \mathcal{U}$.

Expressions

  • obj_expr: $-\left(t_{\mathrm{ret}} + t_{R} + \sum_{i \in \mathcal{L}} t_{l,i} + \sum_{i \in \mathcal{U}} t_{u,i}\right)$, the barrier.

Where:

  • $\boldsymbol{w}$: Portfolio weights vector $N \times 1$.
  • $R(\boldsymbol{w})$: Portfolio risk.
  • $\mathrm{ret}$: Return expression of the model, the model's :ret. It is the sum of the scaled expressions of the return terms whose rte is true.
  • $\epsilon_{1}$, $\epsilon_{2}$: The return floor noc_rt and the risk ceiling noc_rk of the near optimal region.
  • $w_{l,i}$, $w_{u,i}$: Lower and upper weight bounds of asset $i$, from wb.
  • $\mathcal{L}$, $\mathcal{U}$: The assets that barrier_weight_bounds returns.
  • $m_{R}$, $m_{\mathrm{ret}}$: The scales of the anchor cones, m_rk and m_rt.
  • $s$: The constraint scale, sc.
  • $\mathcal{K}_{\exp} = \mathrm{cl}\,\{(a,b,c) : b\, e^{a/b} \leq c,\, b > 0\}$: Exponential cone.

Arguments

  • model::JuMP.Model: The JuMP optimisation model.
  • wb::WeightBounds: Weight bounds of the model, one entry for each asset.
  • m_rk::Number: The scale of the risk cone, the anchor_cone_scale of rk_delta.
  • m_rt::Number: The scale of the return cone, the anchor_cone_scale of rt_delta.

Returns

  • obj_expr: The barrier, registered under that name.

Related

source
PortfolioOptimisers.set_near_optimal_objective_function! — Function
set_near_optimal_objective_function!(alg, model, noc, attrs, m_rk, m_rt)

Set the Near Optimal Centering objective function in the JuMP model.

The objective minimises $s_{o}$ times the barrier of set_near_optimal_centering_constraints!. For ConstrainedNearOptimalCentering, it also holds the Objective Penalty, which holds the Custom Objective Terms of opt.cobj.

The middle of the constrained variant, assemble_jump_model!, adds the Custom Objective Terms to the Objective Penalty, with the objective MinimumRisk of the assembly, and not noc.obj. The centring solve minimises the barrier, and noc.obj is the objective of the anchor sub-problem.

The middle of UnconstrainedNearOptimalCentering calls no add_custom_objective_term!, and its objective calls no add_penalty_to_objective!, so opt.cobj prices the anchor sub-problems and not the centring solve. No builder of that variant adds to the Objective Penalty, so the penalty is empty, and its omission changes no number.

Algorithm

  1. Add the barrier with set_near_optimal_centering_constraints!.
  2. For ConstrainedNearOptimalCentering, add the Objective Penalty with add_penalty_to_objective!.
  3. Set the objective to minimise $s_{o}$ times that expression, where $s_{o}$ is the objective scale so.

JuMP formulation

Objective

Arguments

Returns

  • nothing.

Related

source
PortfolioOptimisers.solve_noc! — Function
solve_noc!(noc, model, rk_opt, rt_opt, s_rk, s_rt, opt, attrs, args...)

Register the bounds of the near optimal region, set the barrier objective, and solve the centring model.

s_rk and s_rt divide the anchor cones of the barrier, see set_near_optimal_centering_constraints!.

Algorithm

The method dispatches on the type of the bounds, on the variant, and on the frontiers that the model registers.

  1. With one risk ceiling and one return floor, register them as the constant expressions noc_rk and noc_rt, set the objective with set_near_optimal_objective_function!, and solve once.
  2. With a vector of bounds, one for each point of a sweep, register noc_rk and noc_rt as parameters with set_noc_anchor_parameters!.
  3. For UnconstrainedNearOptimalCentering, solve once for each point, with the bounds of that point.
  4. For ConstrainedNearOptimalCentering, resolve the return frontier with compute_ret_lbs and the risk frontier with compute_risk_ubs, make their parameters, and solve once for each point of the product of the two axes, with the bounds of that point.

JuMP formulation

Expressions

  • noc_rk: $\epsilon_{2}$, the risk ceiling, a constant in step 1.
  • noc_rt: $\epsilon_{1}$, the return floor, a constant in step 1.

set_noc_anchor_parameters! registers the two expressions of a sweep.

Arguments

  • noc::NearOptimalCentering: The estimator.
  • model::JuMP.Model: The JuMP optimisation model.
  • rk_opt: Risk ceiling $\epsilon_{2}$, or one for each point of a sweep.
  • rt_opt: Return floor $\epsilon_{1}$, or one for each point of a sweep.
  • s_rk::Number: The anchor_cone_scale of rk_delta of NearOptimalSetup, which divides the risk cone of the barrier.
  • s_rt::Number: The anchor_cone_scale of rt_delta of NearOptimalSetup, which divides the return cone of the barrier.
  • opt::BaseJuMPOptimisationEstimator: The optimiser of the centring model.
  • attrs::ResolvedJuMPOptimiser: The resolved bundle of the optimiser.
  • args...: For the constrained variant, the returns of the anchors, the spans of return_term_ends, the anchors of minimum risk and of maximum return, and one Val flag for each frontier registry.

Returns

  • (retcode, sol) for one solve, or (retcodes, sols) for a sweep.

Related

source
PortfolioOptimisers.set_noc_anchor_parameters! — Function
set_noc_anchor_parameters!(model, noc, attrs, rk_opts, rt_opts, s_rk, s_rt)

Register the risk ceiling and the return floor of a swept centring model as parameters, and set the objective.

noc_rk and noc_rt are the risk ceiling $\epsilon_{2}$ and the return floor $\epsilon_{1}$ of the near optimal region. A sweep moves them from point to point. So each one is a parameter times a constant, the model is built once, and only the values of the parameters change between solves.

The constant is the bound_scale of the bounds, so each parameter takes values in $[-1, 1]$. A parameter with the size of a risk leaves the exponential cones of the barrier badly scaled.

Algorithm

  1. Compute the constants $m_{R}$ and $m_{\mathrm{ret}}$ with bound_scale.
  2. Register the parameters noc_rk_unit and noc_rt_unit, and the expressions noc_rk $= m_{R}$ noc_rk_unit and noc_rt $= m_{\mathrm{ret}}$ noc_rt_unit.
  3. Set the objective with set_near_optimal_objective_function!.
  4. Divide the bounds by the constants.

JuMP formulation

Variables

  • noc_rk_unit, noc_rt_unit: $p_{R}$, $p_{\mathrm{ret}}$, parameters with the start value zero. set_noc_anchor! sets their values.

Expressions

  • noc_rk: $\epsilon_{2} = m_{R}\, p_{R}$.
  • noc_rt: $\epsilon_{1} = m_{\mathrm{ret}}\, p_{\mathrm{ret}}$.

Arguments

  • model::JuMP.Model: The JuMP optimisation model.
  • noc::NearOptimalCentering: The estimator, which selects the objective.
  • attrs::ResolvedJuMPOptimiser: The resolved bundle of the optimiser.
  • rk_opts::VecNum: The risk ceilings, one for each point of the sweep.
  • rt_opts::VecNum: The return floors, one for each point of the sweep.
  • s_rk::Number, s_rt::Number: The scales of the anchor cones, which set_near_optimal_objective_function! receives.

Returns

  • (p_rk, p_rt, rk_units, rt_units): The two parameters, and the bounds in the units of the parameters, which set_noc_anchor! writes.

Related

source
PortfolioOptimisers.set_noc_anchor! — Function
set_noc_anchor!(p_rk, p_rt, rk_units, rt_units, i)

Set the risk ceiling and the return floor of the centring model to those of sweep point i.

It is the hook that frontier_sweep! calls before each solve of a swept NearOptimalCentering. near_optimal_centering_setup computes the bounds of point i from the anchor of obj at point i of the same sweep, and i is the flat index that frontier_sweep_axes counts. So each point is centred on the near optimal region of its own anchor.

Arguments

  • p_rk: The parameter of the risk ceiling.
  • p_rt: The parameter of the return floor.
  • rk_units::VecNum: The risk ceilings in the units of p_rk, in the flat order of the sweep.
  • rt_units::VecNum: The return floors in the units of p_rt, in the flat order of the sweep.
  • i::Integer: The flat index of the sweep point.

Returns

  • nothing.

Related

source
PortfolioOptimisers.compute_ret_lbs — Method
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