Entropy pooling Prior (b): private API
Types
PortfolioOptimisers.TailViewTerms — Type
struct TailViewTerms{__T_idx, __T_coef, __T_op, __T_rhs}The assets that one tail view names, their coefficients, its operator and its target.
This type is an implementation detail and is not intended for direct use. ep_view_terms makes it. ep_normalise_tail_view and ep_add_tail_view! read it.
Fields
idx:idx: The indices of the assets that the view names.
coef:coef: The coefficient of each named asset.
op:op: The operator of the view (:eq,:geqor:leq).
rhs:rhs: The target of the view.
Related
Functions
PortfolioOptimisers.ep_view_terms — Function
ep_view_terms(res::ParsingResult, sets::UniverseSets, X::MatNum; strict::Bool = false,
ledger::Option{<:AbstractVector} = nothing) -> Option{<:TailViewTerms}Resolve one parsed tail view into the assets that it names, their coefficients, its operator and its target.
ep_view_terms gives a ParsingResult to get_linear_constraints. That function resolves the variable names against the universe, and reports the names that it cannot place. It also negates a >= equation, so ep_view_terms undoes the negation to keep the operator. A linear view does not need the operator, because a row of A x <= b holds it. A tail view needs it, because each operator selects a different formulation.
Algorithm
- Resolve the view against the universe with
get_linear_constraints. The result islc. Returnnothingwhen it places no name of the view. - Read the sign
sgnand the inequality flag of the operator of the view withcomparison_sign_ineq_flag. From them, select the operatoropof the view and the blockblkoflcthat holds the row. - Multiply the row
Aand the targetrhsbysgn. This undoes the negation thatget_linear_constraintsapplies to a>=equation. - Return the indices of the non-zero entries of
A, the coefficients at those indices,opandrhs.
Arguments
res: The parsed view constraint.sets: The universe sets that map the asset names to indices.X: The asset returns matrix. The function reads only its element type.strict: Iftrue, raise an error for an asset that the universe does not hold. Iffalse, warn.ledger: The Departure Ledger of the entry of the fit, ornothingwhen no caller collects the drops.get_linear_constraintsfills it.
Returns
nothing: When the universe holds no name of the view.terms::TailViewTerms: The assets that the view names, their coefficients, the operator of the view (:eq,:geqor:leq) and its target.
Related
PortfolioOptimisers.ep_normalise_view_term — Function
ep_normalise_view_term(coef::Number, op::Symbol, rhs::Number)Divide a tail view of one asset by its coefficient.
The function returns the operator and the target of the same view with a coefficient of one. When the coefficient is negative, it reverses the operator.
Algorithm
- Divide the target by the coefficient. The result is
rhs. - When the coefficient is negative, exchange
:geqand:leq. The result isop. A division by a negative number keeps an equality, so:eqdoes not change.
Arguments
coef: The coefficient that the view gives the risk measure of the asset.op: The comparison operator of the view.rhs: The target value of the view.
Returns
op::Symbol: The operator of the normalised view.rhs::Number: The target of the normalised view.
Related
PortfolioOptimisers.ep_view_formulations — Function
ep_view_formulations(alg, N::Integer, key::Symbol)Expand the formulation setting of a tail view group to one formulation for each view.
One formulation applies to every view. A vector gives one formulation for each view. nothing lets each view select its formulation.
Arguments
alg: The formulation setting.N: The number of views.key: The name of the field, for the error message.
Validation
- If
algis a vector,length(alg) == N.
Returns
algs::AbstractVector: One entry for each view.
Related
PortfolioOptimisers.ep_sbar — Function
ep_sbar(sbar, T::Integer, alpha::Number, w::VecNum, ord::VecInt)Find the number of largest losses that the integer conditional value-at-risk formulation reads.
Algorithm
- A
CountOfis a number of losses. Returnsbar.val, at mostT. - A
FractionOfis a fraction ofT. Returnceil(Int, sbar.val * T), at least one and at mostT. nothinguses the rule of thumb of [1]. Go through the losses from the largest down, and add their prior probabilities. Stop at the positionsat which the sum first reachesalpha.- Return two times
s, at leastceil(Int, 2 * alpha * T), at least one and at mostT.
Cajas [1] uses a count of at most s for a view at or above the prior CVaR. For a view below the prior CVaR, it uses a count above s and far below T. Its examples use int(alpha * T) for the first case and int(2 * alpha * T) for the second case. The library uses the larger count for every view, and the factor of two is its own.
Arguments
sbar: The setting thatIntegerConditionalValueatRiskViewholds. ACountOfis a number of losses, aFractionOfis a fraction ofT, andnothinguses the rule of thumb of [1].T: The number of observations.alpha: The significance level of the view.w: The prior probability weights.ord: The indices of the losses in ascending order, so the largest loss is last.
Returns
sbar::Int: The number of largest losses, in1:T.
Related
References
- [1] D. Cajas. Entropy Pooling with CVaR and EVaR Views. Available at SSRN 7120258 (2026). Section 2.2, Equation 4, and Section 4.
PortfolioOptimisers.ep_assert_reachable_view — Function
ep_assert_reachable_view(op::Symbol, rhs::Number, x::AbstractVector{<:VecNum},
coef::VecNum, w::VecNum, eqn::AbstractString,
name::AbstractString; worst::Bool = false)Refuse a tail view that no reweighting of the sample can reach, and tell whether the view binds the posterior.
A tail risk measure of a reweighted sample is between the smallest and the largest loss of the sample at a positive prior probability. So a coefficient-weighted sum of measures is between the sums of those bounds, and no change of the probabilities meets a view outside that band. For one asset the band is exact. For several assets it is an outer bound, because a reweighting that puts every asset at its worst loss together does not always exist. The posterior of entropy pooling puts no mass where the prior puts none, so an observation of zero prior probability does not widen the band.
An edge of the band needs the mass of the posterior on the scenarios at that edge. The posterior of entropy pooling is positive wherever the prior is positive, so it meets an edge only when the measure reaches the edge at such a posterior. The measures differ at the worst loss:
- The CVaR of one asset equals its worst loss when the posterior puts at least
alphaon the scenarios of that loss. A posterior that is positive on every scenario does this, so the caller of a CVaR view passesworst = true, and the method acceptsrhs == hifor a view of one asset. - The EVaR and the RLVaR reach the worst loss only in the limit of a posterior on the worst scenario, so the method refuses
rhs == hifor them. - A sum of CVaRs over several assets reaches
hionly when one posterior puts at leastalphaon the worst scenarios of each asset together. The method does not check that joint condition, so it refusesrhs == hifor a view of several assets. - Every measure equals the smallest loss only when all the mass is on the scenarios of that loss, so the method refuses
rhs == lo.
A left-hand side that is constant on the support has no edge. Each measure of a constant series is that constant, so every posterior meets the view when the prior meets it, and none meets it otherwise. The method refuses such a view when the prior does not meet it. Otherwise it returns false, so the caller drops the view, which binds no posterior. The formulations of a view below the prior value fail on a constant series, because the prior value of an EVaR or an RLVaR is a little above the constant.
Algorithm
- Calculate
hiover the observations withw > 0. It is the sum over the assets of the coefficient times the largest loss when the coefficient is positive, and times the smallest loss when the coefficient is negative. Calculatelowith the opposite choice. - When
lo == hi, raise an error unless the prior meets the view:rhs <= hiwhenopasks the statistic to be at leastrhs, andrhs >= lowhenopasks it to be at mostrhs. Returnfalse. - When
opasks the statistic to be at leastrhs, raise an error unlessrhsis belowhi. Withworst = trueand one asset,rhs == hipasses too. - When
opasks the statistic to be at mostrhs, raise an error unlessrhsis abovelo. - Return
true.
Arguments
op: The comparison operator of the view.rhs: The target value of the view.x: The loss series of each asset that the view names.coef: The coefficient that the view gives the risk measure of each asset.w: The prior probability weights.eqn: The equation of the view, for the error message.name: The name of the view family, for the error message.worst: Iftrue, the measure of one asset equals its worst loss at a posterior that is positive on every scenario of the support. Only a CVaR view passestrue.
Validation
- If
lo == hi,rhs <= hiwhenopis:geqor:eq, andrhs >= lowhenopis:leqor:eq. - Else, if
opis:geqor:eq,rhs < hi. Withworst = trueand one asset,rhs <= hi. - Else, if
opis:leqor:eq,rhs > lo.
Returns
binds::Bool:falsewhen the left-hand side is constant on the support, so every posterior meets the view.trueotherwise.
Related
PortfolioOptimisers.ep_cvar_formulation — Function
ep_cvar_formulation(alg::Option{<:CVaRVF}, mixed::Bool, op::Symbol, rhs::Number,
pv::Number)Select the formulation of one conditional value-at-risk view.
The function returns a stated formulation with no change. For nothing, it selects LinearConditionalValueatRiskView when that formulation writes the view exactly, which it does for every view whose upper level set is convex. For the other views it selects IntegerConditionalValueatRiskView. These are a view whose coefficients have both signs, an upper bound, and an equality below the prior value of the left hand side.
The table gives the branch for each input:
alg | mixed | op | rhs against pv | Branch |
|---|---|---|---|---|
| stated | any | any | any | alg, unchanged |
nothing | false | :geq | any | LinearConditionalValueatRiskView |
nothing | false | :eq | rhs >= pv | LinearConditionalValueatRiskView |
nothing | false | :eq | rhs < pv | IntegerConditionalValueatRiskView |
nothing | false | :leq | any | IntegerConditionalValueatRiskView |
nothing | true | any | any | IntegerConditionalValueatRiskView |
SequentialTailView is never the default. It writes every view that the integer formulation writes, with no integer variable. But its posterior is a local minimiser of the divergence, and nothing selects an exact formulation.
Arguments
alg: The stated formulation, ornothing.mixed: Whether the coefficients of the view have both signs.op: The comparison operator of the view.rhs: The target value of the view.pv: The prior value of the left hand side of the view.
Returns
alg::CVaRVF: The formulation to use.
Related
PortfolioOptimisers.ep_evar_formulation — Function
ep_evar_formulation(alg::Option{<:EVaRVF}, mixed::Bool, single::Bool, op::Symbol,
rhs::Number, pv::Number)Select the formulation of one entropic value-at-risk view.
The function returns a stated formulation with no change. For nothing, it selects ConicEntropicValueatRiskView when that formulation writes the view exactly, which it does for every view whose upper level set is convex. An upper bound and an equality below the prior value use GridTailView when the view names one asset. The grid holds one asset only, so the same views over several assets use SequentialTailView, the one formulation that can write them. A view whose coefficients have both signs also uses SequentialTailView.
The table gives the branch for each input:
alg | mixed | single | op | rhs against pv | Branch |
|---|---|---|---|---|---|
| stated | any | any | any | any | alg, unchanged |
nothing | false | any | :geq | any | ConicEntropicValueatRiskView |
nothing | false | any | :eq | rhs >= pv | ConicEntropicValueatRiskView |
nothing | false | true | :eq | rhs < pv | GridTailView |
nothing | false | true | :leq | any | GridTailView |
nothing | false | false | :eq | rhs < pv | SequentialTailView |
nothing | false | false | :leq | any | SequentialTailView |
nothing | true | false | any | any | SequentialTailView |
Arguments
alg: The stated formulation, ornothing.mixed: Whether the coefficients of the view have both signs.single: Whether the view names one asset.op: The comparison operator of the view.rhs: The target value of the view.pv: The prior value of the left hand side of the view.
Returns
alg::EVaRVF: The formulation to use.
Related
PortfolioOptimisers.ep_rlvar_formulation — Function
ep_rlvar_formulation(alg::Option{<:RLVaRVF}, mixed::Bool, single::Bool, op::Symbol,
rhs::Number, pv::Number)Select the formulation of one relativistic value-at-risk view.
The function returns a stated formulation with no change. For nothing, it selects ConicRelativisticValueatRiskView when that formulation writes the view exactly, which it does for every view whose upper level set is convex. An upper bound and an equality below the prior value use GridTailView when the view names one asset. The grid holds one asset only, so the same views over several assets use SequentialTailView, the one formulation that can write them. A view whose coefficients have both signs also uses SequentialTailView.
The table gives the branch for each input:
alg | mixed | single | op | rhs against pv | Branch |
|---|---|---|---|---|---|
| stated | any | any | any | any | alg, unchanged |
nothing | false | any | :geq | any | ConicRelativisticValueatRiskView |
nothing | false | any | :eq | rhs >= pv | ConicRelativisticValueatRiskView |
nothing | false | true | :eq | rhs < pv | GridTailView |
nothing | false | true | :leq | any | GridTailView |
nothing | false | false | :eq | rhs < pv | SequentialTailView |
nothing | false | false | :leq | any | SequentialTailView |
nothing | true | false | any | any | SequentialTailView |
Arguments
alg: The stated formulation, ornothing.mixed: Whether the coefficients of the view have both signs.single: Whether the view names one asset.op: The comparison operator of the view.rhs: The target value of the view.pv: The prior value of the left hand side of the view.
Returns
alg::RLVaRVF: The formulation to use.
Related
PortfolioOptimisers.ep_sequential_sides — Function
ep_sequential_sides(x::AbstractVector{<:VecNum}, coef::VecNum, op::Symbol, rhs::Number,
pv::Number)Orient a tail view as a lower bound, and split its assets into the dual side and the primal side of a sequential formulation.
Algorithm
- Orient the view. For an upper bound, and for an equality whose target is at or below the prior value of the left hand side, multiply both sides by minus one, so that the view reads
>=. Keep a lower bound, and an equality whose target is above the prior value. So the function writes an equality as the bound that the prior does not meet, and the minimiser of the entropy makes that bound tight. - Put every asset with a positive oriented coefficient on the dual side. Its measure is concave in the probabilities and takes its exact dual block. Put every asset with a negative oriented coefficient on the primal side. Its measure takes a linear upper bound.
Arguments
x: The loss series of each asset that the view names.coef: The coefficient that the view gives the risk measure of each asset.op: The comparison operator of the view.rhs: The target value of the view.pv: The prior value of the left hand side of the view.
Returns
xd::AbstractVector{<:VecNum}: The loss series of the assets on the dual side.cd::VecNum: Their oriented coefficients, which are positive.xp::AbstractVector{<:VecNum}: The loss series of the assets on the primal side.cp::VecNum: Their oriented coefficients, which are negative.rhs::Number: The target of the oriented view.
Related
PortfolioOptimisers.ep_add_grid_tail_view! — Function
ep_add_grid_tail_view!(epc::AbstractDict, grid::AbstractVector, op::Symbol, row, msg)Keep the usable points of a tail view grid, and add the rows of its lower-bound half.
The entropic and the relativistic methods of GridTailView share ep_add_grid_tail_view!. Both build a grid of points, drop the points whose row is not usable, and add one linear row for each kept point. They differ in what a point is and in how they build its row. Each gives its row builder to this function as row.
The function drops a point whose row is not finite, because a coefficient that is not finite goes to the solver as NaN * x[j]. The message msg of the caller names the setting that put the whole grid at such points.
The upper-bound half also drops a point whose bound is at or below zero. Its coefficients are positive and the posterior sums to one, so no posterior meets its row. The lower-bound half keeps such a point. Every posterior meets its row, so the row changes no posterior.
The rows of the lower-bound half keep the norm scale of add_ep_constraint!. A row with a small bound is at the small end of the grid. A posterior that meets a lower bound moves mass toward the largest loss, where every row has its largest coefficient. So at such a posterior, a row with a small bound has a slack of many orders of magnitude. A division by the bound puts coefficients of the order of its reciprocal into the dual that OptimEntropyPooling solves.
Algorithm
- Build the row of every point with
row. Keep the points whose coefficients and right-hand side are all finite. - Raise an error with
msgwhen the function keeps no point. - When the view has a lower-bound half, multiply the row of each kept point by minus one, so that the row has the
<=sense of the key:ineq. Add the row toepcunder that key withadd_ep_constraint!. - When the view has an upper-bound half, keep only the points whose right-hand side is positive. Raise an error with
msgwhen no point remains. - Return the kept points. The caller puts them into the tail view constraint of the upper-bound half.
Arguments
epc: The dictionary of entropy pooling constraints, from keys to(lhs, rhs)pairs.grid: The points of the grid.op: The comparison operator of the view.row: A function that takes one point and returns the coefficients and the right-hand side of its row.msg: A function of no arguments that returns the message of the error. The function calls it only when the grid keeps no point.
Validation
- At least one point of the grid has a finite row. If the view has an upper-bound half, at least one such row also has a positive bound. A grid that keeps no point raises an
ArgumentErrorwith the messagemsg().
Returns
grid::AbstractVector: The points of the grid whose row is finite and, if the view has an upper-bound half, whose bound is positive.
Related
PortfolioOptimisers.ep_tail_view_prior_args — Function
ep_tail_view_prior_args(tail_views::ConditionalValueatRiskView, w::VecNum)
ep_tail_view_prior_args(tail_views::EntropicValueatRiskView, w::VecNum)
ep_tail_view_prior_args(tail_views::RelativisticValueatRiskView, w::VecNum)Return the trailing arguments under which a prior(...) reference of this tail view group resolves.
ep_tail_view_prior_args is one of the two functions that hold the differences between the measures for ep_tail_views!. Its tuple names the statistic that get_pr_value reads, and holds the level, the prior probabilities and the settings of the search for that statistic. replace_prior_views passes the tuple on with no change. So a new measure needs a new method here, and no copy of the lowering.
Arguments
tail_views: The tail view group whose settings the tuple holds.w: The prior probability weights.
Returns
args::Tuple: The trailing arguments ofreplace_prior_views, which start with the tag of the statistic.
Related
PortfolioOptimisers.ep_normalise_tail_view — Function
ep_normalise_tail_view(terms::TailViewTerms, X::MatNum, w::VecNum, eqn::AbstractString,
name::AbstractString; worst::Bool = false)Normalise the coefficients of a tail view, read the loss series of its assets, and tell whether its coefficients have both signs.
Every tail view goes through these steps. The function divides a view of one asset by its coefficient, so the target is a value of the measure. It multiplies a view of several assets whose coefficients have one sign by that sign. Then every coefficient is positive, and the view is a positive combination of measures, whose upper level set is convex. A view whose coefficients have both signs is a relative view, and the function keeps it as stated.
Algorithm
- Read
mixed, which istrueif the coefficients have both signs. - When the view names one asset, divide the view by the coefficient of that asset with
ep_normalise_view_term, which reverses the operator when the coefficient is negative. Set the coefficient to one. - When the view names several assets and
mixedisfalse, multiply both sides by the sign of the first coefficient with the same function. Then every coefficient is positive, and the operator reverses when the sign is negative. - Read the loss series
xof each asset as the negated column of its returns. - Refuse a target that no reweighting of the sample on the support of
wreaches, withep_assert_reachable_view. Returnnothingwhen the left-hand side is constant on the support, because every posterior then meets the view.
Arguments
terms: The resolved terms of the view, asep_view_termsreturns them.X: The matrix of asset returns.w: The prior probability weights.eqn: The equation of the view, for the error messages.name: The name of the risk measure, for the error messages.worst: Iftrue, the measure of one asset equals its worst loss at a posterior that is positive on every scenario. It goes toep_assert_reachable_view.
Returns
nothing: The view binds no posterior, so the caller drops it.
Otherwise, a tuple of:
x::AbstractVector{<:VecNum}: The loss series of each asset that the view names.coef::VecNum: The normalised coefficient of each asset.op::Symbol: The operator of the normalised view.rhs::Number: The target of the normalised view.mixed::Bool:trueif the coefficients have both signs.
Related
PortfolioOptimisers.ep_add_tail_view! — Function
ep_add_tail_view!(epc::AbstractDict, tvs::AbstractVector,
tail_views::ConditionalValueatRiskView, alg, X::MatNum,
terms::TailViewTerms, eqn::AbstractString, w::VecNum)
ep_add_tail_view!(epc::AbstractDict, tvs::AbstractVector,
tail_views::EntropicValueatRiskView, alg, X::MatNum,
terms::TailViewTerms, eqn::AbstractString, w::VecNum)
ep_add_tail_view!(epc::AbstractDict, tvs::AbstractVector,
tail_views::RelativisticValueatRiskView, alg, X::MatNum,
terms::TailViewTerms, eqn::AbstractString, w::VecNum)Lower one resolved tail view into the constraints that its measure and its formulation need.
ep_add_tail_view! is the second of the two functions that hold the differences between the measures for ep_tail_views!. ep_tail_views! parses the group, expands its asset groups, and resolves its prior references and its terms. This function does every step after that point, and these are the steps that the measures do not share. A new measure needs a new method here and in ep_tail_view_prior_args.
Every measure accepts a view over several assets. Each method normalises the view with ep_normalise_tail_view, which also tells whether the coefficients have both signs. A view whose left-hand side is constant on the support binds no posterior, so the method adds no constraint for it. Only the CVaR method passes worst = true, because only the CVaR of one asset equals its worst loss at a posterior that is positive on every scenario. It reads pv, the prior value of the left hand side, as the coefficient-weighted sum of the measures of the assets under w. Then it selects the formulation and lowers the view:
- A
ConditionalValueatRiskViewreads the prior CVaR of each asset withConditionalValueatRisk. It selects the formulation withep_cvar_formulation, and appends the constraint withep_add_cvar_view!. - An
EntropicValueatRiskViewreads the prior EVaR of each asset, and the dual variable that attains it, withep_evar. It selects the formulation withep_evar_formulation, and appends the constraints withep_add_evar_view!. - A
RelativisticValueatRiskViewreads the prior RLVaR of each asset, and the primal pair that attains it, withep_rlvar. It selects the formulation withep_rlvar_formulation, and appends the constraints withep_add_rlvar_view!.
Arguments
epc: The dictionary of entropy pooling constraints, from keys to(lhs, rhs)pairs.tvs: The vector of tail view constraints, to which the function appends.tail_views: The tail view group of the view. It holds the level, the formulation setting and the settings of the searches.alg: The formulation of this view, asep_view_formulationsexpands it.X: The matrix of asset returns.terms: The resolved terms of the view, asep_view_termsreturns them.eqn: The equation of the view, for the error messages.w: The prior probability weights.
Returns
nothing: The function mutatesepcandtvsin-place.
Related
ep_tail_views!ep_tail_view_prior_argsep_normalise_tail_viewep_add_cvar_view!ep_add_evar_view!ep_add_rlvar_view!EntropyPoolingPrior
References
- [1] D. Cajas. Entropy Pooling with CVaR and EVaR Views. Available at SSRN 7120258 (2026). Section 2.2, Equations 2 to 6, and Section 2.3, Equations 7 to 11.
- [2] D. Cajas. Entropy Pooling with Relativistic Value at Risk Views. Available at SSRN 7329718 (2026). Section 2, Equations 1 to 5, and Section 3.2, Equation 7.
PortfolioOptimisers.ep_check_tail_window — Method
ep_check_tail_window(tv::IntegerConditionalValueatRiskViewConstraint, w::VecNum)Warn when the window of an integer conditional value-at-risk view can restrict the posterior.
The model of IntegerConditionalValueatRiskView accepts only the posteriors that put at least alpha of their mass on the sbar largest losses of each asset. When this restriction is active, the window holds exactly alpha, and the function warns. A window that holds more is not active at the posterior, so a small change of the posterior does not reach the restriction.
Algorithm
- For each asset of the view, skip a window that holds every observation, because it restricts nothing.
- Sum
wover the window. Warn when the sum minusalphais at mostalphatimes the cube root of the machine epsilon ofw. This margin is far above the feasibility tolerance of a solver and far below the mass of one observation.
Arguments
tv: The integer conditional value-at-risk view constraint.w: The posterior probabilities of the last solve.
Returns
nothing.
Related
References
- [1]
- D. Cajas. Entropy Pooling with CVaR and EVaR Views. Available at SSRN 7120258 (2026).
- [2]
- D. Cajas. Entropy Pooling with Relativistic Value at Risk Views. Available at SSRN 7329718 (2026).