Near optimal centering (a): private API
PortfolioOptimisers.NearOptimalCenteringAlgorithm — Type
abstract type NearOptimalCenteringAlgorithm <: OptimisationAlgorithmAbstract supertype for Near Optimal Centering algorithm variants.
Related
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} <: AbstractResultThe 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 ceilingrk_optat the anchor of the objective.
rt_delta: Width of the near optimal region in return, the slack of the return floorrt_optat 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 aFrontier, asi => (rt_min_i, rt_max_i)pairs, ornothingwhen 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:JuMPoptimiser configuration.
attrs: The resolved bundle of the inner JuMP optimiser, aResolvedJuMPOptimiser, 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
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
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
- Fit the measures to the prior and the solvers with
factory. - For one measure, return the risk of
w_min, ofw_optand ofw_maxfromexpected_risk. - For a vector of measures, compute the three risks of each measure times its
settings.scale, and combine the measures withscalariser.
Arguments
scalariser: Scalariser of a vector of measures, such asSumScalariser. The method for one measure does not read it.r: Risk measure or vector of risk measures.pr: Prior result.fees: Fees, ornothing.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_optis a vector whenw_optholds one anchor for each point of a frontier sweep.
Related
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
- Process the optimiser into its attributes with
resolve_jump_optimiser, with the blocks ofblocks, reducenocandrdto 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, withconstraint_block_steps. - If an anchor of minimum risk or of maximum return is missing, if the variant is
UnconstrainedNearOptimalCentering, or if a return term holds aFrontier, 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. - Solve each missing anchor as a
MeanRiskproblem. The anchors of minimum risk and of maximum return solve with the copies without bounds, and the anchor ofobjsolves withrandoptas they are. - For the unconstrained variant, replace
randoptwith the copies without bounds, which the centring model reads. - Compute the risks of the anchors with
near_optimal_centering_risksonr, and their returns withexpected_returnon the return terms ofopt. 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, throughucs_expected_return. - For each return term that holds a
Frontier, compute its span withreturn_term_ends. - 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
binsisnothing.
Arguments
noc::NearOptimalCentering: The estimator.rd: The returns result to use.blocks: The blocks after the block ofnoc.opt, the keywordblocksofresolve_jump_optimiser.kwargs...: Keyword arguments passed toresolve_jump_optimiser.
Returns
setup::NearOptimalSetup: The anchors, the bounds of the region and the return codes of the anchor sub-problems.
Related
PortfolioOptimisers.frontier_return_terms — Function
frontier_return_terms(ret)Return the indices of the return terms whose settings.lb is a Frontier.
A term whose settings.lb is a vector of numbers states its levels, so it needs no corner solve and is not in the answer. An empty answer means that no corner solve runs.
Related
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
- For each index $i$ in
swept, solve aMeanRiskproblem with the objectiveMaximumElementReturn(i), the risk measuresnb_r, the optimisernb_opt, the initial weightsw_iniand the blocksblocks. - Make the pair
i => (rt_min_i, rt_max_i)of the returns of term $i$ atw_minand at that solution.
Arguments
swept::VecInt: Indices of the return terms that hold aFrontier.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, ornothing.w_min::VecNum: Anchor of minimum risk.w_ini: Initial weights of each solve, ornothing.blocks: The blocks after the block ofnb_opt, on the reduced universe, fromconstraint_block_steps.
Validation
- Each solve must succeed,
ArgumentErrorotherwise.
Returns
- A vector of
i => (rt_min_i, rt_max_i)pairs, one per swept term.
Related
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
- Make
il, the indices $i$ with a finite $w_{l,i}$ and $w_{l,i} \neq w_{u,i}$. - 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
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.
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 whoserteistrue. - $\epsilon_{1}$, $\epsilon_{2}$: The return floor
noc_rtand the risk ceilingnoc_rkof 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_boundsreturns. - $m_{R}$, $m_{\mathrm{ret}}$: The scales of the anchor cones,
m_rkandm_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, theanchor_cone_scaleofrk_delta.m_rt::Number: The scale of the return cone, theanchor_cone_scaleofrt_delta.
Returns
obj_expr: The barrier, registered under that name.
Related
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
- Add the barrier with
set_near_optimal_centering_constraints!. - For
ConstrainedNearOptimalCentering, add the Objective Penalty withadd_penalty_to_objective!. - Set the objective to minimise $s_{o}$ times that expression, where $s_{o}$ is the objective scale
so.
JuMP formulation
Objective
- $\min\; s_{o}\, b$, where $b$ is
obj_exprofset_near_optimal_centering_constraints!. ForConstrainedNearOptimalCentering, $b$ also holds the Custom Objective Terms and the Objective Penalty.
Arguments
alg:UnconstrainedNearOptimalCenteringorConstrainedNearOptimalCentering.model::JuMP.Model: The JuMP optimisation model.noc::NearOptimalCentering: The estimator. The method reads no field of it.attrs::ResolvedJuMPOptimiser: The resolved bundle of the optimiser.m_rk::Number,m_rt::Number: The scales of the anchor cones ofset_near_optimal_centering_constraints!.
Returns
nothing.
Related
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.
- With one risk ceiling and one return floor, register them as the constant expressions
noc_rkandnoc_rt, set the objective withset_near_optimal_objective_function!, and solve once. - With a vector of bounds, one for each point of a sweep, register
noc_rkandnoc_rtas parameters withset_noc_anchor_parameters!. - For
UnconstrainedNearOptimalCentering, solve once for each point, with the bounds of that point. - For
ConstrainedNearOptimalCentering, resolve the return frontier withcompute_ret_lbsand the risk frontier withcompute_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: Theanchor_cone_scaleofrk_deltaofNearOptimalSetup, which divides the risk cone of the barrier.s_rt::Number: Theanchor_cone_scaleofrt_deltaofNearOptimalSetup, 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 ofreturn_term_ends, the anchors of minimum risk and of maximum return, and oneValflag for each frontier registry.
Returns
(retcode, sol)for one solve, or(retcodes, sols)for a sweep.
Related
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
- Compute the constants $m_{R}$ and $m_{\mathrm{ret}}$ with
bound_scale. - Register the parameters
noc_rk_unitandnoc_rt_unit, and the expressionsnoc_rk$= m_{R}$noc_rk_unitandnoc_rt$= m_{\mathrm{ret}}$noc_rt_unit. - Set the objective with
set_near_optimal_objective_function!. - 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, whichset_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, whichset_noc_anchor!writes.
Related
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 ofp_rk, in the flat order of the sweep.rt_units::VecNum: The return floors in the units ofp_rt, in the flat order of the sweep.i::Integer: The flat index of the sweep point.
Returns
nothing.
Related
PortfolioOptimisers.compute_ret_lbs — Method
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_frontierModel State entry.::Nothing: No per-term spans were computed.
Returns
ret_frontier, unchanged.
Related
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
- Keep an entry whose levels are a vector of numbers.
- For an entry of term $i$ that holds a
FrontierofNpoints, find the spani => (rt_min_i, rt_max_i)inrt_ends. - Replace the
Frontierwithrange(rt_min_i, rt_max_i; length = N).
Arguments
ret_frontier::VecPair: The:ret_frontierModel State entry.rt_ends::VecPair: The spans of the terms, asi => (rt_min_i, rt_max_i).
Validation
- Each term that holds a
Frontierhas a span inrt_ends,ArgumentErrorotherwise.
Returns
- The return frontier with every span resolved into a range of sweep points.
Related