Base Risk Constraints: private API

PortfolioOptimisers.AbstractRiskSeriesAlgorithm — Type
abstract type AbstractRiskSeriesAlgorithm <: AbstractAlgorithm

Abstract 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

source
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

source
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

source
PortfolioOptimisers.DrawdownRiskSeries — Type
struct DrawdownRiskSeries <: AbstractRiskSeriesAlgorithm

Selects 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

source
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

  1. Read first, the length of the :risk_frontier registry, with risk_frontier_length.
  2. Resolve the Deferred Quantities of r against the solver of the owner, giving resolved. resolve_deferred_quantities does the work, and risk_constraint_solver gives the solver.
  3. Refuse a Calibration Rule that resolved still holds, with assert_declared_calibration_resolver.
  4. Build the constraints of resolved at index i with the index method of set_risk_constraints!.
  5. Record resolved as the owner of the registry entries after first that the build left without one, with set_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, a RiskConstraintOwner.
  • pr: Prior result.
  • pl: Optional phylogeny constraints.
  • fees: Optional fees structure.
  • b1::Option{<:MatNum} = nothing: Basis of the decision vector of FactorRiskContribution, which maps it to the asset weights: the pseudoinverse of the transposed loadings, followed by the off-factor basis when flag = true. nothing for all other optimisers.

Returns

  • nothing.

Related

source
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

source
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

  1. When the model holds no :risk_frontier, return nothing.
  2. For each entry j after position first whose owner, the fourth value, is nothing, replace the owner with r.

Arguments

  • model::JuMP.Model: The JuMP optimisation model.
  • first::Integer: The registry length before r built its constraints, as risk_frontier_length reads it.
  • r::AbstractBaseRiskMeasure: The measure that values the entries.

Returns

  • nothing.

Related

source
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 nothing bound adds nothing.
  • A number adds one row. The row bounds r_expr from above when flag is true, and from below when it is false.
  • A Front_NumVec adds an entry to the :risk_frontier registry, and the frontier solve reads the entry later. The owner of the entry is written as nothing, 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$ when flag is true, and $s_c \left(u k - R(\boldsymbol{w})\right) / m \leq 0$ when it is false, 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_scale of ub. 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, a RiskConstraintOwner.
  • r_expr::JuMP.AbstractJuMPScalar: The risk expression to bound.
  • ub: The bound. It is nothing, a number, or a Front_NumVec, which is a vector of bounds or a Frontier.
  • key::Symbol: The Model State key of the risk expression. The row and the frontier entry take their keys from it.
  • flag::Bool: true for an upper bound and false for a lower bound (default: true).

Validation

  • An owner outside RiskBoundOwner, a FactorRiskContribution, ignores a number bound, and the method warns. Without the warning the bound has no effect and nothing says so. It raises ArgumentError for a Front_NumVec bound, because it solves its model once, as assert_frontier_sweep_owner refuses a frontier of every other such optimiser.
  • A programme Allocation Set raises ArgumentError for a Front_NumVec bound. 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

source
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 with rke = true appends $\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 the scale of 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: false adds nothing.

Returns

  • nothing.

Related

source
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

  1. When settings.ub is nothing and settings.rke is false, return.
  2. When the presence flag <name>_settings is registered under prefix, log a warning that names the type of r and its settings, and return.
  3. Register the presence flag with mark_state!.
  4. Bound r_expr_ub by ub with set_risk_upper_bound!, under the key of name.
  5. Add r_expr times settings.scale to risk_vec with set_risk_expression!.

JuMP formulation

Expressions

  • <name>_settings: the presence flag, true after the first measure applies its settings. The name carries the namespace prefix.

Arguments

  • model::JuMP.Model: The JuMP optimisation model.
  • opt: The owner of the constraint, a RiskConstraintOwner.
  • r_expr::JuMP.AbstractJuMPScalar: The risk expression.
  • r::RiskMeasure: The measure, read for settings and for the name of its type.
  • name::Symbol: The Model State name of the risk expression.

Keyword arguments

  • prefix::Symbol: Model State namespace for name (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, as set_variance_risk_bounds_and_expression! states.
  • ub: The bound, in the units of r_expr_ub (default: r.settings.ub).

Returns

  • nothing.

Related

source
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

  1. Read sc, the constraint scale.
  2. Read net_X, the net portfolio returns, with set_net_portfolio_returns!, and set T to its length.
  3. Create dd, $T + 1$ free variables. Entry dd[t + 1] is $dd_t$.
  4. Register the three rows below.
  5. Register dd under 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 dd lies 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

source
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_X under prefix: $-\hat{r}_t$, $t = 1, \ldots, T$, the series of the gain tail. Only loss = false builds it, the first time.

Algorithm

  1. Read net_X, the net portfolio returns, with set_net_portfolio_returns!.
  2. When loss is false, build -net_X in a registered JuMP.@expression under gain_net_X with state_build!, or read it when the model holds it.
  3. 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 matrix X.

Keyword arguments

  • loss::Bool: true gives the series of the loss tail, the net portfolio returns. false gives 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

source
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_dd under prefix: $-dd_t$, $t = 1, \ldots, T$, the negated drawdown path.

Algorithm

  1. Build dd with set_drawdown_constraints!, or read it when the model holds it.
  2. Set T = length(dd) - 1.
  3. Build -dd[2:T+1] in a registered JuMP.@expression under neg_dd with state_build!, or read it when the model holds it.
  4. 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 matrix X.

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

source
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, :L2 or :S2.

Returns

  • q: The quantity, or nothing.

Related

source
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 slot key of the measure, after resolve_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 ArgumentError when q is nothing and prior_high_order_quantity finds no key on pr. The message gives three remedies. State the quantity on the measure, or name an est or an AbstractPriorEstimator in the measure, or give the optimiser a prior estimator that computes the quantity.

Returns

  • nothing.

Related

source
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

  1. Read D2, L2 and S2 from pr with prior_high_order_quantity.
  2. When any of the three is nothing, build all three with dup_elim_sum_matrices, and replace each nothing with 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

source