Base Risk Constraints: private API
PortfolioOptimisers.AbstractRiskSeriesAlgorithm — Type
abstract type AbstractRiskSeriesAlgorithm <: AbstractAlgorithmAbstract supertype for the series that a conic risk measure reduces.
A builder of a conic tail measure reads a series of returns, one entry for each observation. The returns family reads the net portfolio returns. The drawdown family reads the negated drawdown path, which is a series of returns too. risk_series makes the series from the marker, so one builder body serves both families.
Related
PortfolioOptimisers.NonFRCJuMPOpt — Type
const NonFRCJuMPOpt = Union{MeanRisk, NearOptimalCentering, RiskBudgeting}Groups the JuMP optimisers that do not use factor risk contribution.
FactorRiskContribution is the one JuMP optimiser outside the group. Two methods dispatch on this alias. The frontier method of set_risk_upper_bound! records a Frontier bound, and risk_contribution_constraints writes the risk contribution rows of a Variance. A factor risk contribution optimiser reaches neither method.
Related
PortfolioOptimisers.RiskConstraintOwner — Type
const RiskConstraintOwner = Union{RiskJuMPOptimisationEstimator, AbstractProgrammeAllocationSet}Groups the owners of the risk constraints that a builder writes. An owner is a JuMP optimiser, whose programme the constraint joins, or a programme Allocation Set, whose projection the constraint joins.
Every set_risk_constraints! and set_risk! method takes the owner in its opt slot. A builder reads the owner through three methods and no others. risk_constraint_solver gives the solver that resolves a Deferred Quantity. risk_contribution_constraints gives the risk contribution rows of a Variance. set_risk_upper_bound! writes the bound on the risk expression. A RiskBoundOwner honours the bound. A FactorRiskContribution ignores a number bound with a warning, and refuses a frontier or a per-asset vector.
Related
PortfolioOptimisers.RiskBoundOwner — Type
const RiskBoundOwner = Union{NonFRCJuMPOpt, AbstractProgrammeAllocationSet}Groups the owners that honour the settings.ub of a risk measure.
The group holds every JuMP optimiser except FactorRiskContribution, and the programme Allocation Set. On a programme Allocation Set, ub is the ceiling of its projection.
Related
PortfolioOptimisers.NetReturnsRiskSeries — Type
struct NetReturnsRiskSeries <: AbstractRiskSeriesAlgorithmSelects the net portfolio returns as the series that a risk measure reduces.
Every tail measure of returns reads this series. A range measure can read it alone, because its gain tail reads the same series negated, which loss = false gives in risk_series.
Related
PortfolioOptimisers.DrawdownRiskSeries — Type
struct DrawdownRiskSeries <: AbstractRiskSeriesAlgorithmSelects the negated drawdown path as the series that a risk measure reduces.
-dd[2:T+1] carries the sign of a return, so a builder of a measure of returns builds the drawdown measure with no change of sign.
The drawdown series has no gain tail. A run-up follows a different recurrence and is not the negation of the drawdown. So risk_series takes no loss keyword for this marker, and no range measure reads a drawdown series.
Related
PortfolioOptimisers.set_resolved_risk_constraints! — Function
set_resolved_risk_constraints!(
model::Model,
i::Integer,
r::RiskMeasure,
opt::Union{AbstractProgrammeAllocationSet, JuMPOptimisationEstimator},
pr::AbstractPriorResult,
pl::Union{Nothing, AbstractPhylogenyConstraintResult, AbstractVector{<:AbstractPhylogenyConstraintResult}},
fees::Union{Nothing, Fees},
b1::Union{Nothing, AbstractMatrix{<:Union{Number, AbstractJuMPScalar}}};
kwargs...
)
Resolves one risk measure and builds its constraints at index i.
The two methods of set_risk_constraints! both call this function, so a measure resolves the same way alone and in a vector.
Algorithm
- Read
first, the length of the:risk_frontierregistry, withrisk_frontier_length. - Resolve the Deferred Quantities of
ragainst the solver of the owner, givingresolved.resolve_deferred_quantitiesdoes the work, andrisk_constraint_solvergives the solver. - Refuse a Calibration Rule that
resolvedstill holds, withassert_declared_calibration_resolver. - Build the constraints of
resolvedat indexiwith the index method ofset_risk_constraints!. - Record
resolvedas the owner of the registry entries afterfirstthat the build left without one, withset_risk_frontier_owner!.
Arguments
model::JuMP.Model: The JuMP optimisation model.i::Integer: The position of the measure in the risk measure vector.r::RiskMeasure: The risk measure.opt: The owner of the constraint, aRiskConstraintOwner.pr: Prior result.pl: Optional phylogeny constraints.fees: Optional fees structure.b1::Option{<:MatNum} = nothing: Basis of the decision vector ofFactorRiskContribution, which maps it to the asset weights: the pseudoinverse of the transposed loadings, followed by the off-factor basis whenflag = true.nothingfor all other optimisers.
Returns
nothing.
Related
PortfolioOptimisers.risk_frontier_length — Function
risk_frontier_length(model::Model) -> Int64
Returns the number of entries in the :risk_frontier Model State registry, or 0 when the model holds no registry.
set_resolved_risk_constraints! reads the length before a risk measure builds its constraints. The entries after that position are the entries that the measure adds.
Arguments
model::JuMP.Model: The JuMP optimisation model.
Returns
n::Int: The number of registry entries.
Related
PortfolioOptimisers.set_risk_frontier_owner! — Function
set_risk_frontier_owner!(
model::Model,
first::Integer,
r::AbstractBaseRiskMeasure
)
Records r as the owner of every :risk_frontier entry after position first that has no owner yet.
rebuild_risk_frontier resolves a Frontier bound into a span of numbers, and it values the corner portfolios with the measure that owns the entry. The owner is the measure that the bounded expression measures, and expected_risk values it. The functor of each owner gives the value of its bounded expression, in the units that the bound of the Frontier converts. For a plain measure, that is the measure itself. A composite measure bounds the expression of a term, so its builder records the measure of that term first. The vr, sk and kt terms of VarianceSkewKurtosis are the example. The position of an entry does not give its measure: a measure registers an entry only when its settings.ub is a Front_NumVec, and one measure can register several entries.
Algorithm
- When the model holds no
:risk_frontier, returnnothing. - For each entry
jafter positionfirstwhose owner, the fourth value, isnothing, replace the owner withr.
Arguments
model::JuMP.Model: The JuMP optimisation model.first::Integer: The registry length beforerbuilt its constraints, asrisk_frontier_lengthreads it.r::AbstractBaseRiskMeasure: The measure that values the entries.
Returns
nothing.
Related
PortfolioOptimisers.set_risk_upper_bound! — Function
set_risk_upper_bound!(
::Model,
::Union{AbstractProgrammeAllocationSet, RiskJuMPOptimisationEstimator},
r_expr,
::Nothing,
key
)
set_risk_upper_bound!(
::Model,
::Union{AbstractProgrammeAllocationSet, RiskJuMPOptimisationEstimator},
r_expr,
::Nothing,
key,
flag::Bool
)
Bounds the risk expression r_expr by ub, or records ub for a frontier solve.
The type of ub and the owner opt select the method.
- A
nothingbound adds nothing. - A number adds one row. The row bounds
r_exprfrom above whenflagistrue, and from below when it isfalse. - A
Front_NumVecadds an entry to the:risk_frontierregistry, and the frontier solve reads the entry later. The owner of the entry is written asnothing, because the measure is not known here.set_risk_frontier_owner!writes the owner afterwards.
Under a ratio objective the head divides the weights by $k$ after the solve, so the row bounds the risk of the weights that the head returns. That is exact for a risk expression of degree one in the weights. A builder whose risk expression has a higher degree passes a separate expression of degree one, as set_variance_risk_bounds_and_expression! does.
JuMP formulation
Expressions
risk_frontier: registered by the frontier method on its first call. It is a vector of entries(<key>_ub_var, <key>_ub) => (R, ub, flag, nothing), and each later call appends one entry.
Constraints
<key>_ub: $s_c \left(R(\boldsymbol{w}) - u k\right) / m \leq 0$ whenflagistrue, and $s_c \left(u k - R(\boldsymbol{w})\right) / m \leq 0$ when it isfalse, registered by the number method.
Where:
- $s_c$: Constraint scale. It multiplies both sides of a row, so a positive value leaves the feasible set unchanged.
- $k$: Variable that scales the budget in the homogenised problem.
- $R(\boldsymbol{w})$: Portfolio risk.
- $u$: The bound,
ub. - $m$: The
bound_scaleofub. The division keeps the coefficients of the row of order one, so a bound of the size of a fourth moment holds.
Arguments
model::JuMP.Model: The JuMP optimisation model.opt: The owner of the constraint, aRiskConstraintOwner.r_expr::JuMP.AbstractJuMPScalar: The risk expression to bound.ub: The bound. It isnothing, a number, or aFront_NumVec, which is a vector of bounds or aFrontier.key::Symbol: The Model State key of the risk expression. The row and the frontier entry take their keys from it.flag::Bool:truefor an upper bound andfalsefor a lower bound (default:true).
Validation
- An owner outside
RiskBoundOwner, aFactorRiskContribution, ignores a number bound, and the method warns. Without the warning the bound has no effect and nothing says so. It raisesArgumentErrorfor aFront_NumVecbound, because it solves its model once, asassert_frontier_sweep_ownerrefuses a frontier of every other such optimiser. - A programme Allocation Set raises
ArgumentErrorfor aFront_NumVecbound. Its ceiling is one number. The constructor of the set refuses such a bound first, and this method refuses a set that reaches the builder without that check.
Returns
nothing.
Related
PortfolioOptimisers.set_risk_expression! — Function
set_risk_expression!(
model::Model,
r_expr::AbstractJuMPScalar,
scale::Number,
rke::Bool
)
Appends the risk expression r_expr, times scale, to model[:risk_vec].
scalarise_risk_expression! reduces the entries of risk_vec to the risk that the objective reads. When rke is false, the function adds nothing, and the measure reaches the model through its bound alone.
JuMP formulation
Expressions
risk_vec: registered on the first call as an empty vector of affine and quadratic expressions. Each call withrke = trueappends $\mathcal{R}_i = \omega R(\boldsymbol{w})$.
Where:
- $\mathcal{R}_i$: Entry $i$ of
risk_vec, the risk expression of the $i$-th risk measure times thescaleof the measure. - $R(\boldsymbol{w})$: Portfolio risk.
- $\omega$: The weight of the measure,
scale.
Arguments
model::JuMP.Model: The JuMP optimisation model.r_expr::JuMP.AbstractJuMPScalar: The risk expression to add.scale::Number: The weight of the measure.rke::Bool:falseadds nothing.
Returns
nothing.
Related
PortfolioOptimisers.set_unindexed_risk_bounds_and_expression! — Function
set_unindexed_risk_bounds_and_expression!(
model::Model,
opt::Union{AbstractProgrammeAllocationSet, RiskJuMPOptimisationEstimator},
r_expr::AbstractJuMPScalar,
r::RiskMeasure,
name::Symbol;
prefix,
r_expr_ub,
ub
)
Bounds the risk expression of a measure that has no index, and adds it to the risk that the objective reads. Only the first measure of the type under prefix takes effect.
The builders of MaximumDrawdown, WorstRealisation, NoRisk, Range and BrownianDistanceVariance do not read the index of the measure. A measure of these types has no parameter that sets two instances apart, so its builder registers the risk expression once, under name. The bound row takes the name <name>_ub, and a second bound cannot have the same name. So the settings of the first measure take effect. The settings of a later measure have no effect, and the function logs a warning that says so.
A measure whose settings hold no bound and set rke to false changes nothing, and the function returns at once. A tail of a range measure is such a measure when it has no bound, so it does not take the place of a later measure.
Algorithm
- When
settings.ubisnothingandsettings.rkeisfalse, return. - When the presence flag
<name>_settingsis registered underprefix, log a warning that names the type ofrand its settings, and return. - Register the presence flag with
mark_state!. - Bound
r_expr_ubbyubwithset_risk_upper_bound!, under the key ofname. - Add
r_exprtimessettings.scaletorisk_vecwithset_risk_expression!.
JuMP formulation
Expressions
<name>_settings: the presence flag,trueafter the first measure applies its settings. The name carries the namespaceprefix.
Arguments
model::JuMP.Model: The JuMP optimisation model.opt: The owner of the constraint, aRiskConstraintOwner.r_expr::JuMP.AbstractJuMPScalar: The risk expression.r::RiskMeasure: The measure, read forsettingsand for the name of its type.name::Symbol: The Model State name of the risk expression.
Keyword arguments
prefix::Symbol: Model State namespace forname(default: empty, i.e. the bare key).r_expr_ub::JuMP.AbstractJuMPScalar: The expression that the bound row acts on (default:r_expr). A builder whose risk has degree two passes its square root, of degree one, asset_variance_risk_bounds_and_expression!states.ub: The bound, in the units ofr_expr_ub(default:r.settings.ub).
Returns
nothing.
Related
PortfolioOptimisers.set_drawdown_constraints! — Function
set_drawdown_constraints!(
model::Model,
X::AbstractMatrix{<:Union{Number, AbstractJuMPScalar}};
prefix
) -> Any
Adds the drawdown variables of the portfolio to model, and returns them.
The function builds the variables once for each prefix. A second call returns the variables that the first call registered.
Mathematical definition
The absolute drawdown of the net portfolio returns is
\[\begin{align} c_t &= \sum_{s=1}^{t} \hat{r}_s\,, \quad c_0 = 0\,, \\ d_t &= c_t - \max_{0 \leq s \leq t} c_s \leq 0\,. \end{align}\]
It satisfies the recurrence $-d_0 = 0$ and $-d_t = \max(0,\, -d_{t-1} - \hat{r}_t)$.
Where:
- $\hat{r}_t$: Net portfolio return at observation $t$, $\boldsymbol{x}_t^\intercal \boldsymbol{w}$ less the fees charged at $t$.
- $c_t$: Cumulative simple portfolio return at period $t$.
- $d_t \leq 0$: Absolute drawdown at period $t$.
Algorithm
- Read
sc, the constraint scale. - Read
net_X, the net portfolio returns, withset_net_portfolio_returns!, and setTto its length. - Create
dd, $T + 1$ free variables. Entrydd[t + 1]is $dd_t$. - Register the three rows below.
- Register
ddunder the Model State key<prefix>dd, and return it.
JuMP formulation
Variables
dd: created, $(T + 1) \times 1$, and registered under the Model State key<prefix>dd.
Constraints
cdd_start: $s_c\, dd_0 = 0$.cdd_geq_0: $s_c\, dd_t \geq 0$, $\forall\, t = 1,\ldots,T$.cdd: $s_c \left(\hat{r}_t + dd_t - dd_{t-1}\right) \geq 0$, $\forall\, t = 1,\ldots,T$.
Each name is a Model State key, and a caller reads the row back under prefix followed by the name.
Where:
- $s_c$: Constraint scale. It multiplies both sides of a row, so a positive value leaves the feasible set unchanged.
- $dd_t$: Drawdown variable of observation $t$, with $dd_0 = 0$. The rows hold it at or above the drawdown $-d_t$.
- $\hat{r}_t$: Net portfolio return at observation $t$, $\boldsymbol{x}_t^\intercal \boldsymbol{w}$ less the fees charged at $t$.
- $T$: Number of observations.
Relaxation
The encoding is not exact: the entries below bound the quantity instead of reproducing it, and the bound is tight only under the condition stated here.
- The rows give $dd_t \geq \max(0,\, dd_{t-1} - \hat{r}_t)$, so by induction $dd_t \geq -d_t$ for every $t$. Each entry of
ddlies at or above the drawdown. - The bound on an entry is tight when the objective pulls that entry down. A sum over the entries, as in the average drawdown, pulls on every entry. A maximum over the entries, as in the maximum drawdown, pulls on the largest entry alone, and the other entries can lie above their drawdowns.
Arguments
model::JuMP.Model: The JuMP optimisation model.X::MatNum: The asset returns matrix, $T \times N$.
Keyword arguments
prefix::Symbol: Model State namespace (default: empty, i.e. the bare key).
Returns
dd: The drawdown variables, $(T + 1) \times 1$.
Related
PortfolioOptimisers.risk_series — Function
risk_series(
model::Model,
::NetReturnsRiskSeries,
pr::AbstractPriorResult;
loss,
prefix
) -> Tuple{Any, Any}
Returns the series of net portfolio returns that a conic risk measure reduces, and its length.
The measure of returns and the measure of drawdowns are one programme under the substitution of -dd[2:T+1] for net_X. The two methods of this function make that substitution, so each builder takes (series, T) and builds both measures. On both markers the series carries the sign of a return, and a loss is a negative entry.
Mathematical definition
\[\begin{align} s_t &= \begin{cases} \hat{r}_t & \text{for the loss tail}\,, \\ -\hat{r}_t & \text{for the gain tail}\,. \end{cases} \end{align}\]
Where:
- $s_t$: Entry $t$ of the series that a conic risk measure reduces. It carries the sign of a return, so a loss is a negative entry.
- $\hat{r}_t$: Net portfolio return at observation $t$, $\boldsymbol{x}_t^\intercal \boldsymbol{w}$ less the fees charged at $t$.
The gain tail reads one registered copy of the negated series for each prefix. Every gain tail of the model reads that entry, so the negation is built once and a user can read it. A negation made before a macro and held by no entry cost each gain tail a copy of the $T \times N$ terms.
JuMP formulation
Expressions
gain_net_Xunderprefix: $-\hat{r}_t$, $t = 1, \ldots, T$, the series of the gain tail. Onlyloss = falsebuilds it, the first time.
Algorithm
- Read
net_X, the net portfolio returns, withset_net_portfolio_returns!. - When
lossisfalse, build-net_Xin a registeredJuMP.@expressionundergain_net_Xwithstate_build!, or read it when the model holds it. - Return the series and its length.
Arguments
model::JuMP.Model: The JuMP optimisation model.alg::NetReturnsRiskSeries: The marker that selects the net portfolio returns.pr::AbstractPriorResult: Prior result containing the returns matrixX.
Keyword arguments
loss::Bool:truegives the series of the loss tail, the net portfolio returns.falsegives the series of the gain tail, their negation (default:true).prefix::Symbol: Model State namespace (default: empty, i.e. the bare key).
Returns
series: The series $s_t$, $T \times 1$.T::Int: The number of observations.
Related
risk_series(
model::Model,
::DrawdownRiskSeries,
pr::AbstractPriorResult;
prefix
) -> Tuple{Any, Any}
Returns the negated drawdown path that a drawdown risk measure reduces, and its length.
The negation gives the drawdown path the sign of a return, so a builder of a measure of returns builds the drawdown measure with no change.
The method takes no loss keyword, because a drawdown has no gain tail. A call that asks for the gain tail raises a MethodError, and does not build the loss tail a second time.
Mathematical definition
\[\begin{align} s_t &= -dd_t\,, \quad t = 1,\ldots,T\,. \end{align}\]
Where:
- $s_t$: Entry $t$ of the series that a conic risk measure reduces. It carries the sign of a return, so a loss is a negative entry.
- $dd_t$: Drawdown variable of observation $t$, with $dd_0 = 0$. The rows hold it at or above the drawdown $-d_t$.
- $T$: Number of observations.
Every drawdown measure under one prefix reads one registered copy of the negated path, so the negation is built once and a user can read it.
JuMP formulation
Expressions
neg_ddunderprefix: $-dd_t$, $t = 1, \ldots, T$, the negated drawdown path.
Algorithm
- Build
ddwithset_drawdown_constraints!, or read it when the model holds it. - Set
T = length(dd) - 1. - Build
-dd[2:T+1]in a registeredJuMP.@expressionunderneg_ddwithstate_build!, or read it when the model holds it. - Return the series and
T.
Arguments
model::JuMP.Model: The JuMP optimisation model.alg::DrawdownRiskSeries: The marker that selects the negated drawdown path.pr::AbstractPriorResult: Prior result containing the returns matrixX.
Keyword arguments
prefix::Symbol: Model State namespace (default: empty, i.e. the bare key).
Returns
series: The negated drawdown path-dd[2:T+1], $T \times 1$.T::Int: The number of observations.
Related
PortfolioOptimisers.prior_high_order_quantity — Function
prior_high_order_quantity(pr::AbstractPriorResult, key::Symbol)Returns the high-order quantity that key names on the prior result pr, or nothing when pr carries none.
A HighOrderPrior has the fields kt, sk, V and the three vectorisation matrices. A LowOrderPrior has none of them. A HighOrderPrior fitted with one of the two tensors holds nothing in the field of the other. The function returns nothing in both cases, and never raises.
Arguments
pr: Prior result.key::Symbol: The name of the quantity, for example:kt,:sk,:V,:D2,:L2or:S2.
Returns
q: The quantity, ornothing.
Related
PortfolioOptimisers.assert_high_order_quantity — Function
assert_high_order_quantity(q, pr::AbstractPriorResult, rm::Symbol, key::Symbol,
est::Symbol)Refuses a high-order risk measure when neither the measure nor the prior carries its tensor.
The builder can build the measure when either side gives the quantity, so the check reads the pair and not the type of pr. A measure that states how to build its own cokurtosis passes with a LowOrderPrior. A HighOrderPrior that computed neither tensor fails.
Arguments
q: The value in the slotkeyof the measure, afterresolve_deferred_quantities.pr: Prior result.rm::Symbol: The name of the risk measure type, for the message.key::Symbol: The name of the quantity, for example:kt.est::Symbol: The name of the estimator slot of the measure, for the message.
Validation
- Raises
ArgumentErrorwhenqisnothingandprior_high_order_quantityfinds nokeyonpr. The message gives three remedies. State the quantity on the measure, or name anestor anAbstractPriorEstimatorin the measure, or give the optimiser a prior estimator that computes the quantity.
Returns
nothing.
Related
PortfolioOptimisers.dup_elim_sum_selector — Function
dup_elim_sum_selector(pr::AbstractPriorResult, N::Integer)Returns the duplication, elimination and summation matrices for N assets, from the prior result pr when it carries them.
dup_elim_sum_matrices depends on the asset count alone, so a rebuilt matrix equals the matrix that a HighOrderPrior carries. A measure that holds its own tensor can therefore build against a LowOrderPrior, because the builder reads nothing else from the prior.
Algorithm
- Read
D2,L2andS2fromprwithprior_high_order_quantity. - When any of the three is
nothing, build all three withdup_elim_sum_matrices, and replace eachnothingwith its rebuilt matrix. One call builds all three, so the cost does not depend on how many are missing.
Arguments
pr: Prior result.N::Integer: The number of assets.
Returns
(D2, L2, S2): The duplication, elimination and summation matrices.
Related