Variance Constraints: private API

PortfolioOptimisers.get_chol_or_sigma_pm — Function

get_chol_or_sigma_pm(
    model::Model,
    pr::AbstractPriorResult
) -> Any

Retrieve or compute and cache the upper Cholesky factor of the prior covariance matrix.

If model does not yet contain a G expression, the factor is computed from pr.chol (if available) or by Cholesky-factorising pr.sigma, then stored as the :G Model State entry.

Arguments

model::JuMP.Model: The JuMP optimisation model.
pr::AbstractPriorResult: Prior result containing sigma and optionally chol.

Returns

G::Matrix: Upper Cholesky factor of the prior covariance matrix.

Related

chol_sigma_selector

source

PortfolioOptimisers.chol_sigma_selector — Function

chol_sigma_selector(
    model::Model,
    pr::AbstractPriorResult,
    r::Union{DistributionValueatRisk, StandardDeviation, Variance}
) -> Any

Select the Cholesky factor to use for the covariance matrix.

Returns the factor from the prior (get_chol_or_sigma_pm) when r.sigma and r.chol are both nothing, the Cholesky of r.sigma when r.chol is nothing, or r.chol directly.

Arguments

model::JuMP.Model: The JuMP optimisation model.
pr: Prior result.
r::CholRM: Risk measure carrying optional sigma and chol fields.

Returns

G::Matrix: Upper Cholesky factor of the selected covariance matrix.

Related

get_chol_or_sigma_pm

source

PortfolioOptimisers.set_variance_risk_bounds_and_expression! — Function

set_variance_risk_bounds_and_expression!(
    model::Model,
    opt::RiskJuMPOptimisationEstimator,
    r_expr_ub::AbstractJuMPScalar,
    ub::Union{Nothing, Frontier, Union{var"#s137", var"#s136"} where {var"#s137"<:Number, var"#s136"<:(AbstractVector{<:Union{var"#s136", var"#s53"} where {var"#s136"<:Number, var"#s53"<:AbstractJuMPScalar}})}},
    name::Symbol,
    i,
    r_expr::AbstractJuMPScalar,
    settings::JuMPRiskMeasureSettings;
    ...
)
set_variance_risk_bounds_and_expression!(
    model::Model,
    opt::RiskJuMPOptimisationEstimator,
    r_expr_ub::AbstractJuMPScalar,
    ub::Union{Nothing, Frontier, Union{var"#s137", var"#s136"} where {var"#s137"<:Number, var"#s136"<:(AbstractVector{<:Union{var"#s136", var"#s53"} where {var"#s136"<:Number, var"#s53"<:AbstractJuMPScalar}})}},
    name::Symbol,
    i,
    r_expr::AbstractJuMPScalar,
    settings::JuMPRiskMeasureSettings,
    flag::Bool;
    prefix
)

Set the upper-bound constraint and register the variance risk expression.

Applies set_risk_upper_bound! using r_expr_ub and ub, then registers r_expr via set_risk_expression! according to settings.

Arguments

model::JuMP.Model: The JuMP optimisation model.
opt::RiskJuMPOptimisationEstimator: Risk-based optimisation estimator.
r_expr_ub::JuMP.AbstractJuMPScalar: Expression used for the upper-bound check.
ub: Upper bound value.
name::Symbol: Bare Model State entry name seeding the derived bound keys.
i: Measure index. name and i are resolved here, so the bound keys cannot drift from the key the emitter registered the risk expression under.
r_expr::JuMP.AbstractJuMPScalar: Risk expression added to the objective.
settings::RiskMeasureSettings: Settings carrying scale and rke flag.
flag::Bool: If true, sets upper bound; if false sets lower bound.

Keyword arguments

prefix::Symbol: Model State namespace for name (default: empty, i.e. the bare key).

Returns

nothing.

Related

source

PortfolioOptimisers.set_risk! — Method

set_risk!(
    model::Model,
    i,
    r::StandardDeviation,
    opt::RiskJuMPOptimisationEstimator,
    pr::AbstractPriorResult,
    args...;
    prefix,
    kwargs...
) -> Tuple{VariableRef, Symbol}

Construct the raw standard-deviation or variance risk JuMP variable and second-order cone constraint.

For StandardDeviation, adds a scalar variable sd_risk_i and the SOC constraint [sc * sd_risk; sc * G * w] in SecondOrderCone(). For Variance, dispatches to the appropriate variance formulation (SDP, SOC-squared, or quadratic) and also applies any risk-contribution constraints.

Mathematical definition

Standard deviation:

\[\begin{align} \hat{\sigma}(\boldsymbol{w}) &= \lVert \mathbf{G}\boldsymbol{w} \rVert_2\,. \end{align}\]

Where:

$\hat{\sigma}(\boldsymbol{w})$: Portfolio standard deviation.
$\mathbf{G}$: Upper Cholesky factor of the covariance matrix $\boldsymbol{\Sigma}$.
$\boldsymbol{w}$: Portfolio weights vector $N \times 1$.

SDP variance:

\[\begin{align} \hat{\sigma}^2(\boldsymbol{w}) &= \mathrm{tr}(\boldsymbol{\Sigma}\mathbf{W})\,. \end{align}\]

Where:

$\hat{\sigma}^2(\boldsymbol{w})$: Portfolio variance (SDP formulation).
$\mathbf{W} = \boldsymbol{w}\boldsymbol{w}^\intercal$: Outer product of portfolio weights.
$\boldsymbol{\Sigma}$: Covariance matrix.
$\mathrm{tr}(\cdot)$: Matrix trace operator.

where $\mathbf{G}$ is the upper Cholesky factor of $\boldsymbol{\Sigma}$ and $\mathbf{W}$ is the SDP matrix variable.

Arguments

model::JuMP.Model: The JuMP optimisation model.
i: Constraint index for unique variable and constraint naming.
r: Risk measure instance (StandardDeviation or Variance).
opt::JuMPOptimisationEstimator: JuMP optimisation estimator.
pr: Prior result.
pl: Optional phylogeny constraints.

Returns

A 2-tuple (risk_expr, name) of the JuMP risk expression and the bare Model State entry name it was registered under. The caller pairs the name with the same index to resolve the key, so no composed key crosses the boundary.

Related

source

PortfolioOptimisers.set_risk_constraints! — Method

set_risk_constraints!(
    model::Model,
    i,
    r::StandardDeviation,
    opt::RiskJuMPOptimisationEstimator,
    pr::AbstractPriorResult,
    args...;
    prefix,
    kwargs...
) -> VariableRef

Add standard-deviation, variance, or uncertainty-set variance risk constraints to model.

Each method builds the appropriate JuMP variables and constraints and then calls set_risk_bounds_and_expression! or set_variance_risk_bounds_and_expression!. The Variance / NonFRCJuMPOpt overload automatically chooses between SDP and SOC/quadratic formulations based on risk-contribution and phylogeny settings.

Arguments

model::JuMP.Model: The JuMP optimisation model.
i: Constraint index for unique variable and constraint naming.
r: Risk measure instance.
opt::JuMPOptimisationEstimator: JuMP optimisation estimator.
pr: Prior result.
pl: Optional phylogeny constraints.
fees: Optional fees structure.

Returns

nothing.

Related

set_risk!
set_variance_risk!
set_ucs_variance_risk!

source

PortfolioOptimisers.set_risk_constraints! — Method

set_risk_constraints!(
    model::Model,
    i,
    r::Variance,
    opt::Union{MeanRisk, NearOptimalCentering, RiskBudgeting},
    pr::AbstractPriorResult,
    pl::Union{Nothing, AbstractPhylogenyConstraintResult, AbstractVector{<:AbstractPhylogenyConstraintResult}},
    args...;
    prefix,
    kwargs...
) -> Any

Add JuMP risk constraints for Variance to model using non-factor-risk-contribution optimisers.

Computes the portfolio variance risk expression and registers the upper-bound constraint and objective contribution according to the variance risk measure settings.

Arguments

model::JuMP.Model: The JuMP optimisation model.
i: Constraint index for unique variable and constraint naming.
r::Variance: The variance risk measure.
opt::NonFRCJuMPOpt: The optimisation estimator.
pr: Prior result.
pl: Optional phylogeny constraints.

Returns

nothing.

Related

source

PortfolioOptimisers.set_risk_constraints! — Method

set_risk_constraints!(
    model::Model,
    i,
    r::Variance,
    opt::FactorRiskContribution,
    pr::AbstractPriorResult,
    ,
    ,
    b1::AbstractMatrix{<:Union{var"#s136", var"#s53"} where {var"#s136"<:Number, var"#s53"<:AbstractJuMPScalar}},
    args...;
    prefix,
    kwargs...
) -> Any

Add JuMP risk constraints for Variance to model using a FactorRiskContribution optimiser.

Computes factor-based risk contributions for the portfolio variance and registers the upper-bound constraint and objective contribution accordingly.

Arguments

model::JuMP.Model: The JuMP optimisation model.
i: Constraint index for unique variable and constraint naming.
r::Variance: The variance risk measure.
opt::FactorRiskContribution: The factor risk contribution optimisation estimator.
pr: Prior result.
b1::MatNum: Factor budget matrix used for risk contribution computations.

Returns

nothing.

Related

source

PortfolioOptimisers.set_risk_constraints! — Method

set_risk_constraints!(
    model::Model,
    i,
    r::UncertaintySetVariance,
    opt::RiskJuMPOptimisationEstimator,
    pr::AbstractPriorResult,
    args...;
    prefix,
    rd,
    kwargs...
) -> Any

Add JuMP risk constraints for UncertaintySetVariance to model.

Computes portfolio variance using an uncertainty set covariance matrix derived from the prior or the risk measure's own ucs field, and registers the upper-bound constraint and objective contribution.

Arguments

model::JuMP.Model: The JuMP optimisation model.
i: Constraint index for unique variable and constraint naming.
r::UncertaintySetVariance: The uncertainty set variance risk measure.
opt::RiskJuMPOptimisationEstimator: Risk-based optimisation estimator.
pr: Prior result.

Returns

nothing.

Related

source

PortfolioOptimisers.sdp_rc_variance_flag! — Function

sdp_rc_variance_flag!(
    _::Model,
    _::Union{MeanRisk, NearOptimalCentering, RiskBudgeting},
    _::Nothing
) -> Bool

Return whether risk-contribution constraints require the SDP variance formulation.

Returns false for Nothing (no risk-contribution constraints) and true for LinearConstraint (risk-contribution constraints are present).

Arguments

model::JuMP.Model: The JuMP optimisation model.
opt::NonFRCJuMPOpt: Optimisation estimator.
rc: Risk-contribution constraint (nothing or LinearConstraint).

Returns

flag::Bool: Whether risk-contribution constraints require the SDP formulation.

Related

sdp_variance_flag!

source

PortfolioOptimisers.sdp_variance_flag! — Function

sdp_variance_flag!(
    model::Model,
    rc_flag::Bool,
    pl::Union{Nothing, AbstractPhylogenyConstraintResult, AbstractVector{<:AbstractPhylogenyConstraintResult}};
    prefix
) -> Union{LinearBound, SquareRootBound}

Return the FrontierBoundEstimator that selects the appropriate variance formulation.

Returns LinearBound (SDP formulation) when any of the following hold: rc_flag is true, model already contains a rc_variance expression, or pl contains a SemiDefinitePhylogeny constraint. Returns SquareRootBound (SOC formulation) otherwise.

Arguments

model::JuMP.Model: The JuMP optimisation model.
rc_flag::Bool: Whether risk-contribution constraints require the SDP formulation.
pl: Optional phylogeny constraint(s).

Returns

bound::FrontierBoundEstimator: LinearBound for SDP; SquareRootBound for SOC.

Related

source

PortfolioOptimisers.set_variance_risk! — Function

set_variance_risk!(
    model::Model,
    i,
    r::Variance,
    pr::AbstractPriorResult,
    ::LinearBound;
    prefix
) -> Any

Build the variance risk JuMP expression according to the selected formulation.

The flag-dispatching overload routes to either set_sdp_variance_risk! (SDP) or the appropriate SOC/quadratic overload. The SquaredSOCRiskExpr overload encodes variance as the square of an SOC variable. The QuadRiskExpr overload encodes variance directly as $\boldsymbol{w}^\intercal \Sigma \boldsymbol{w}$.

Arguments

model::JuMP.Model: The JuMP optimisation model.
i: Constraint index for unique variable and constraint naming.
r::Variance: Variance risk measure.
pr::AbstractPriorResult: Prior result containing the covariance matrix sigma.
flag:
- ::LinearBound: Use the SDP formulation.
- ::SquareRootBound: Use the SOC formulation.
i: Constraint index for unique variable and constraint naming.

Returns

The variance risk JuMP expression.

Related

source

PortfolioOptimisers.set_sdp_variance_risk! — Function

set_sdp_variance_risk!(
    model::Model,
    i,
    r::Variance,
    pr::AbstractPriorResult;
    prefix
) -> Any

Build the SDP variance risk expression using the semidefinite matrix W.

Computes sigma_W = sigma * W and registers tr(sigma_W) as the :variance_risk_ entry at index i.

Arguments

model::JuMP.Model: The JuMP optimisation model.
i: Constraint index for unique variable and constraint naming.
r::Variance: Variance risk measure.
pr::AbstractPriorResult: Prior result containing the covariance matrix sigma.

Returns

The variance risk JuMP expression.

Related

set_variance_risk!

source

PortfolioOptimisers.variance_risk_bounds_expr — Function

variance_risk_bounds_expr(
    model::Model,
    i,
    ::LinearBound;
    prefix
) -> Tuple{Any, Symbol}

Return the JuMP expression and the bare Model State entry name used for the variance upper-bound check.

When flag is true (SDP formulation) the variance expression and the :variance_risk_ name are returned; otherwise the standard-deviation variable and the :dev_ name.

Arguments

model::JuMP.Model: The JuMP optimisation model.
i: Constraint index.
flag:
- ::LinearBound: Use the SDP formulation.
- ::SquareRootBound: Use the SOC formulation.

Returns

A 2-tuple (expr, name) of the bound expression and its bare Model State entry name.

Related

variance_risk_bounds_val

source

PortfolioOptimisers.rc_variance_constraints! — Function

rc_variance_constraints!(args...; kwargs...)

Add linear risk-contribution constraints on the variance decomposition to model.

The fall-through method does nothing. The concrete method extracts the diagonal of the sigma_W_i expression and adds inequality and/or equality constraints of the form A_ineq * diag(sigma_W) <= B_ineq * variance_risk and A_eq * diag(sigma_W) == B_eq * variance_risk.

Arguments

model::JuMP.Model: The JuMP optimisation model.
i: Constraint index for unique variable and constraint naming.
rc::LinearConstraint: Linear risk-contribution constraint.
variance_risk::JuMP.AbstractJuMPScalar: Total variance risk expression.

Returns

nothing.

Related

source

PortfolioOptimisers.set_ucs_variance_risk! — Function

set_ucs_variance_risk!(
    model::Model,
    i,
    ucs::BoxUncertaintySet,
    args...;
    prefix
) -> Tuple{Any, Symbol}

Build an uncertainty-set variance risk expression for box, ellipsoidal, compact or norm-ball uncertainty.

The BoxUncertaintySet overload introduces symmetric auxiliary matrices Au and Al and encodes the worst-case variance as tr(Au * ub) - tr(Al * lb). The EllipsoidalUncertaintySet overload introduces a PSD matrix E, the compound matrix W + E, and adds an SOC constraint to bound the ellipsoidal perturbation term. The NormBallUncertaintySet overload, defined on the covariance tag alone, is the ellipsoid's lifted form with the set's own map $\mathbf{L}^{\intercal}$ in place of the Cholesky factor and the cone of the dual norm order in place of the second-order cone, raised by norm_ball_dual_norm_epigraph!; it factorises nothing, and a map with no column raises no cone and leaves tr(sigma * (W + E)). These three lift the weights into the semidefinite matrix W, so each calls set_sdp_constraints! itself. The CompactCovarianceUncertaintySet overload lifts nothing: it bounds the nominal deviation and the residual C .* w - Q * z with one SOC constraint each, and returns the sum of their squares. It is the one overload that leaves the programme a second-order cone programme.

Arguments

model::JuMP.Model: The JuMP optimisation model.
i: Constraint index for unique variable and constraint naming.
ucs: Uncertainty set instance (BoxUncertaintySet, EllipsoidalUncertaintySet, CompactCovarianceUncertaintySet or a covariance NormBallUncertaintySet).
sigma::MatNum: Fallback covariance matrix (used by every overload but the box). The set's own val field wins over it. The box overload names no centre at all, so it ignores both.

Returns

A 2-tuple (ucs_variance_risk, name) of the uncertainty-set variance expression and its bare Model State entry name.

Related

References

[97] R. H. Tütüncü and M. Koenig. Robust asset allocation. Annals of Operations Research 132, 157–187 (2004).
[26] Y. Feng and D. P. Palomar. A signal processing perspective of financial engineering. Foundations and Trends in Signal Processing 9, 1–231 (2016).
[5] D. Cajas. Advanced Portfolio Optimization: A Cutting-edge Quantitative Approach (Springer Nature Switzerland, 2025). Section 11.3.

source

References

[5]: D. Cajas. Advanced Portfolio Optimization: A Cutting-edge Quantitative Approach (Springer Nature Switzerland, 2025).
[26]: Y. Feng and D. P. Palomar. A signal processing perspective of financial engineering. Foundations and Trends in Signal Processing 9, 1–231 (2016).
[97]: R. H. Tütüncü and M. Koenig. Robust asset allocation. Annals of Operations Research 132, 157–187 (2004).