Risk budget constraint generation
PortfolioOptimisers.RiskBudget — Type
struct RiskBudget{__T_val} <: AbstractConstraintResultHolds the non-negative risk budgets that a risk-budgeting optimiser targets.
The budget sets the target share of the total risk for each entry of an axis. AssetRiskBudgeting reads it over the assets, and FactorRiskBudgeting reads it over the factors. A budget built by hand keeps its own sum. It gives the same weights as the normalised budget, because the barrier row is homogeneous in the budget.
Mathematical definition
A risk-budgeting model minimises the risk of an unnormalised weight vector under a logarithmic barrier. It divides that vector by the budget variable to get the portfolio weights.
\[\begin{align} \underset{\boldsymbol{y},\, k}{\min}\quad & \phi(\boldsymbol{y})\\ \textrm{s.t.}\quad & \boldsymbol{b}^\intercal \ln(\boldsymbol{y}) \geq 0\,,\\ & \boldsymbol{1}^\intercal \boldsymbol{y} = k\,,\\ & \boldsymbol{y},\, k \geq 0\,,\\ & \boldsymbol{w} = \boldsymbol{y} / k\,. \end{align}\]
The barrier row states the budget. At the optimum, the Karush-Kuhn-Tucker conditions give the risk-contribution identity:
\[\begin{align} y_i \frac{\partial \phi(\boldsymbol{y})}{\partial y_i} &= \lambda\, b_i\,. \end{align}\]
Where:
- $\boldsymbol{b}$: Risk budget vector, the
valfield. - $\boldsymbol{y}$: Unnormalised weight vector.
- $k$: Variable that scales the budget in the homogenised problem.
- $\boldsymbol{w}$: Portfolio weights vector $N \times 1$.
- $\phi$: Risk measure of the optimiser.
- $\lambda$: Multiplier of the barrier constraint.
The original source writes the barrier as $\boldsymbol{b}^\intercal \ln(\boldsymbol{y}) \geq c$ with an arbitrary constant $c$. It scales $\boldsymbol{y}$ to sum to one after the solve. This library writes $c = 0$.
Only the relative entries of $\boldsymbol{b}$ change the solution. With $c = 0$, the barrier row is positively homogeneous of degree one in $\boldsymbol{b}$. Thus $s\, \boldsymbol{b}^\intercal \ln(\boldsymbol{y}) \geq 0$ and $\boldsymbol{b}^\intercal \ln(\boldsymbol{y}) \geq 0$ define the same set for every $s > 0$. The multiplier $\lambda$ of the risk-contribution identity takes the scale.
Fields
val: Vector of non-negative risk budgets, one for each entry of the axis that the budget is written against. The estimator method ofrisk_budget_constraintsnormalises the budget to sum to one. A budget built by hand keeps its own sum. The model reads the budget inside a logarithmic barrier, so only the relative entries change the solution.
Constructors
RiskBudget( val::Num_VecNum) -> RiskBudgetRiskBudget(; val::Num_VecNum) -> RiskBudgetKeywords correspond to the struct's fields. The keyword form calls the positional form, so both forms run the same checks.
Validation
!isempty(val),IsEmptyErrorotherwise.all(x -> zero(x) <= x, val),DomainErrorotherwise. The check accepts a zero entry and refuses a negative entry.
The inner constructor takes Num_VecNum and not VecNum, because @concrete makes a generic method RiskBudget(val::__T_val) where __T_val. Every argument matches that generic method. An inner method on VecNum does not apply to a scalar, so a scalar goes to the generic method and skips both checks. Num_VecNum applies to a scalar, and it is more specific than the generic method, so both forms run both checks.
A scalar val is a valid input. A scalar RiskBudgetEstimator resolves to the scalar 1.0, because risk_budget_constraints divides the scalar by itself. Such a budget states one allocation over a one-entry axis. An optimiser accepts it only for a one-asset universe, because the risk-budgeting builder compares the length of the budget with the number of weights.
View parameters
port_opt_view takes the view of these @vprop fields at the selected indices:
val: Sliced to the selected indices throughport_opt_view.
Examples
julia> RiskBudget(; val = [0.2, 0.3, 0.5])RiskBudget val ┴ Vector{Float64}: [0.2, 0.3, 0.5]Related
RiskBudgetEstimatorrisk_budget_constraints: only its estimator method normalises the budget to sum to one. Its method for aRiskBudgetreturns the object unchanged, so a budget built by hand keeps its own sum.AbstractConstraintResultAssetRiskBudgetingFactorRiskBudgetingport_opt_view
References
- [146] B. Bruder and T. Roncalli. Managing risk exposures using the risk budgeting approach. Available at SSRN 2009778 (2012). Section 2.3.3, Equation 9, Section 2.4, and Appendix A.2.
- [147] S. Maillard, T. Roncalli and J. Teiletche. On the properties of equally-weighted risk contributions portfolios. Available at SSRN 1271972 (2008). Section 3.3, Equation 7, and Appendix A.2. It states the barrier first, for equal budgets.
- [12] D. Cajas. Advanced Portfolio Optimization: A Cutting-edge Quantitative Approach (Springer Nature Switzerland, 2025). Section 10.1.3, Equation 10.8. It adds the budget variable $k$.
PortfolioOptimisers.RiskBudgetEstimator — Type
struct RiskBudgetEstimator{__T_val, __T_dval} <: AbstractConstraintEstimatorResolves a risk budget written in asset or group names against a universe.
risk_budget_constraints resolves it to a RiskBudget. The function finds the indices of each name of val in the selected universe, and gives dval to each unnamed entry. Then it normalises the budget to sum to one. A group name gives its value to every asset in the group.
This estimator has no key field. risk_budget_constraints takes the key as a positional argument, and uses sets.xkey when the key is nothing. ThresholdEstimator has the same shape, but it holds the key in a field.
A dval of nothing becomes the reciprocal of the length of the axis that the key selects. An unnamed entry starts at the uniform share of that axis, not at zero. On a universe of four assets and two factors, a factor budget that names only F1 gives F2 the value 0.5.
A scalar val resolves to a scalar, not to a uniform vector. The normalisation divides the scalar by itself, so every scalar resolves to RiskBudget(1.0), and the value of the scalar has no effect. Only a one-entry axis can use such a budget, because RiskBudgeting compares the budget with a vector of N weights. Write the uniform budget as nothing, which risk_budget_constraints turns into 1/N over N entries. UniformValues gives the same range through this estimator.
Fields
val: Map from names to risk budget values. A name can be an asset or a group, and a group gives its value to every asset in the group. A scalar resolves toRiskBudget(1.0)for every value of the scalar, so only a one-entry axis can use it. Write the uniform budget asnothing.
dval: Default value of each entry thatvaldoes not name.
Constructors
RiskBudgetEstimator(; val::VectorEstValType, dval::Option{<:Number} = nothing) -> RiskBudgetEstimatorKeywords correspond to the struct's fields.
Validation
assert_nonempty_nonneg_finite_valchecksval, and it checksdvalwhendvalis notnothing.
Examples
julia> RiskBudgetEstimator(; val = Dict("A" => 0.2, "B" => 0.3, "C" => 0.5))RiskBudgetEstimator val ┼ Dict{String, Float64}: Dict("B" => 0.3, "A" => 0.2, "C" => 0.5) dval ┴ nothingjulia> RiskBudgetEstimator(; val = ["A" => 0.2, "B" => 0.3, "C" => 0.5])RiskBudgetEstimator val ┼ Vector{Pair{String, Float64}}: ["A" => 0.2, "B" => 0.3, "C" => 0.5] dval ┴ nothingTwo different scalars resolve to the same budget. The uniform budget over the universe is nothing:
julia> sets = UniverseSets(; dict = Dict("nx" => ["A", "B", "C"]));julia> risk_budget_constraints(RiskBudgetEstimator(; val = 0.2), sets)RiskBudget val ┴ Float64: 1.0julia> risk_budget_constraints(RiskBudgetEstimator(; val = 0.9), sets)RiskBudget val ┴ Float64: 1.0julia> risk_budget_constraints(nothing; N = 3)RiskBudget val ┴ StepRangeLen{Float64, Base.TwicePrecision{Float64}, Base.TwicePrecision{Float64}, Int64}: StepRangeLen(0.3333333333333333, 0.0, 3)Related
RiskBudgetrisk_budget_constraintsUniverseSetsThresholdEstimator: has the same shape, and holds the universe key in a field.
References
- [146] B. Bruder and T. Roncalli. Managing risk exposures using the risk budgeting approach. Available at SSRN 2009778 (2012). Section 2.3.3, Equation 9, and Section 2.4.
- [12] D. Cajas. Advanced Portfolio Optimization: A Cutting-edge Quantitative Approach (Springer Nature Switzerland, 2025). Section 10.1.3, Equation 10.8. It adds the budget variable $k$.
PortfolioOptimisers.risk_budget_constraints — Function
risk_budget_constraints(::Nothing, args...; N::Integer, kwargs...)Makes the uniform risk budget when the caller gives no risk budget.
This method returns a RiskBudget with N equal entries of 1/N.
The vector is a constant range, not an Array. inv(N) sets its element type, which is Float64 for an Int N and BigFloat for a BigInt N. This method takes no datatype keyword, and it ignores a datatype in kwargs....
sum of a range uses the formula of the arithmetic series, and does not add the entries. For each N from 1 to 20000, the sum of the budget is within 1.1e-16 of one, and the sum of the collected entries is within 2.0e-15 of one. The sum of the budget is exactly 1.0 for N = 3, 7 and 10, but it is 0.9999999999999999 for N = 49. The estimator method divides by a computed sum, and its sum is also within round-off of one.
Algorithm
- Compute
iN, the reciprocal ofN. - Make the constant range of length
Nwhose start and stop are bothiN. - Wrap it in a
RiskBudget, which checks that it is non-empty and non-negative.
Arguments
::Nothing: Shows that the caller gives no risk budget.args...: More positional arguments, which the method ignores.N::Integer: Number of entries of the budgeted axis. This keyword has no default.kwargs...: More keyword arguments, which the method ignores.
Returns
rb::RiskBudget: ARiskBudgetwhosevalis a range ofNentries, each equal to1/N.
Examples
julia> risk_budget_constraints(nothing; N = 3)RiskBudget val ┴ StepRangeLen{Float64, Base.TwicePrecision{Float64}, Base.TwicePrecision{Float64}, Int64}: StepRangeLen(0.3333333333333333, 0.0, 3)Related
risk_budget_constraints(rb::RiskBudget, args...; kwargs...)Returns a resolved risk budget unchanged.
This method lets a caller give a RiskBudget wherever risk_budget_constraints also accepts a RiskBudgetEstimator.
This method does not normalise the budget, unlike the estimator method. A budget built by hand, such as RiskBudget(; val = [1, 2, 3]), reaches the optimiser with a sum of 6. The solution does not change, because the barrier row is homogeneous in the budget. On a three-asset variance model, the weights for [1, 2, 3] and for [1/6, 2/6, 3/6] differ by at most 3.5e-5, which is the solver tolerance.
Algorithm
- Return
rb. The method reads none of its other arguments and none of its keywords.
Arguments
rb: ARiskBudget.args...: More positional arguments, which the method ignores.kwargs...: More keyword arguments, which the method ignores.
Returns
rb::RiskBudget: The inputRiskBudget, unchanged.
Examples
julia> risk_budget_constraints(RiskBudget(; val = [0.2, 0.3, 0.5]))RiskBudget val ┴ Vector{Float64}: [0.2, 0.3, 0.5]julia> risk_budget_constraints(RiskBudget(; val = [1, 2, 3]))RiskBudget val ┴ Vector{Int64}: [1, 2, 3]Related
risk_budget_constraints(rb::VectorEstValType,
sets::UniverseSets, dval::Option{<:Number} = nothing,
key::Option{<:AbstractString} = nothing; strict::Bool = false,
kwargs...)Resolves a map from asset or group names to risk budget values against a universe.
The map can be a dictionary, a pair or a vector of pairs. rb can also be a scalar, a vector or an algorithmic rule such as UniformValues. The method resolves each name against the universe that key selects in sets, and normalises the result to sum to one.
A scalar rb resolves to a scalar, not to a uniform vector, so the normalisation returns 1.0 for every value of the scalar. An optimiser accepts this budget only for a one-asset universe. Write the uniform budget as nothing, which the method for Nothing turns into 1/N over N entries.
The normalisation divides by a computed sum, so the sum of the result is within round-off of one, and not always exactly one.
Algorithm
- Take
dvalas the fill value. Ifdvalisnothing, use the reciprocal of the length of the universe thatkeyselects. Ifkeyis alsonothing, use the universe ofsets.xkey. - Resolve
rbagainstsetswithestimator_to_val, and call the resultval. An asset name writes one entry. A group name writes one entry for each member of the group. Each unnamed entry keeps the fill value of step 1. - Divide
valbysum(val). - Wrap the result in a
RiskBudget, which checks that it is non-empty and non-negative.
Arguments
rb: Map from asset or group names to risk budget values, or a scalar, a vector or an algorithmic rule.sets:UniverseSetsthat holds the universe and the groups.dval: Fill value of each entry thatrbdoes not name. Ifnothing, the method uses1/length(sets.dict[key]), withsets.xkeyin place of anothingkey.key: Key of the universe insets.dictthat names resolve against. Ifnothing, the caller reads the key fromsets.xkey, or from the key of another declared axis when the caller is written against that axis.FactorRiskBudgetingpasses the factor axis key of its ownre, because its budget is written in factor names.strict: Iftrue, a name inrbthatsetsdoes not resolve raisesArgumentError. Iffalse, the name logs a warning.
Validation
- A name in
rbthat names neither an asset nor a group ofsetsraisesArgumentErrorwhenstrictistrue. Otherwise the method logs a warning, and the name writes nothing. - A budget whose entries are all zero divides by zero in step 3. The result is a
NaNvector, which fails the non-negativity check ofRiskBudget. The call raisesDomainError, and does not return aNaNbudget. A zero entry is valid, and only an all-zero budget raises this error.
Returns
rb::RiskBudget: ARiskBudgetthat holds the normalised budget.
Examples
julia> sets = UniverseSets(; xkey = "nx", dict = Dict("nx" => ["A", "B", "C"], "group1" => ["A", "B"]));julia> risk_budget_constraints(["A" => 0.2, "group1" => 0.8], sets)RiskBudget val ┴ Vector{Float64}: [0.41379310344827586, 0.41379310344827586, 0.17241379310344826]A budget written in factor names resolves against the factor axis, which is the key that FactorRiskBudgeting passes. Each factor that the budget does not name takes the default 1/length(sets.dict[key]) before the normalisation:
julia> sets = UniverseSets(; dict = Dict("nx" => ["A", "B", "C"], "nf" => ["F1", "F2"]));julia> risk_budget_constraints(Dict("F1" => 0.25), sets, nothing, sets.tfkey)RiskBudget val ┴ Vector{Float64}: [0.3333333333333333, 0.6666666666666666]Related
risk_budget_constraints(rb::RiskBudgetEstimator, sets::UniverseSets,
key::Option{<:AbstractString} = nothing; strict::Bool = false,
kwargs...)Resolves a RiskBudgetEstimator against a universe.
This method calls the mapping method with the two fields of the estimator.
The key is a positional argument of this method, not a field of the estimator. ThresholdEstimator holds its key in a field, so threshold_constraints takes no key argument. Both functions call estimator_to_val, and both resolve a key of the factor axis. On a universe of four assets and two factors, a budget that names only F1 returns a vector of two entries.
This function has no vector method. A vector of estimators raises MethodError, because no broader method accepts it. RkbE_Rkb gives the reason.
Algorithm
- Call
risk_budget_constraints(rb.val, sets, rb.dval, key; strict = strict, kwargs...). This call resolves the map, normalises it and makes theRiskBudget.
Arguments
rb: ARiskBudgetEstimatorthat holds the map and the fill value.sets:UniverseSetsthat holds the universe and the groups.key: Key of the universe insets.dictthat names resolve against. Ifnothing, the caller reads the key fromsets.xkey, or from the key of another declared axis when the caller is written against that axis.FactorRiskBudgetingpasses the factor axis key of its ownre, because its budget is written in factor names.strict: Iftrue, a name inrb.valthatsetsdoes not resolve raisesArgumentError. Iffalse, the name logs a warning.kwargs...: More keyword arguments, which the method gives to the mapping method.
Returns
rb::RiskBudget: ARiskBudgetthat holds the normalised budget.
Examples
julia> sets = UniverseSets(; dict = Dict("nx" => ["A", "B", "C", "D"], "nf" => ["F1", "F2"]));julia> risk_budget_constraints(RiskBudgetEstimator(; val = Dict("F1" => 0.4)), sets, sets.tfkey)RiskBudget val ┴ Vector{Float64}: [0.4444444444444445, 0.5555555555555556]Related
References
- [12]
- D. Cajas. Advanced Portfolio Optimization: A Cutting-edge Quantitative Approach (Springer Nature Switzerland, 2025).
- [146]
- B. Bruder and T. Roncalli. Managing Risk Exposures Using the Risk Budgeting Approach. Available at SSRN 2009778 (2012).
- [147]
- S. Maillard, T. Roncalli and J. Teiletche. On the Properties of Equally-Weighted Risk Contributions Portfolios. Available at SSRN 1271972 (2008).