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, :geq or :leq).
  • rhs: rhs: The target of the view.

Related

source

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

  1. Resolve the view against the universe with get_linear_constraints. The result is lc. Return nothing when it places no name of the view.
  2. Read the sign sgn and the inequality flag of the operator of the view with comparison_sign_ineq_flag. From them, select the operator op of the view and the block blk of lc that holds the row.
  3. Multiply the row A and the target rhs by sgn. This undoes the negation that get_linear_constraints applies to a >= equation.
  4. Return the indices of the non-zero entries of A, the coefficients at those indices, op and rhs.

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: If true, raise an error for an asset that the universe does not hold. If false, warn.
  • ledger: The Departure Ledger of the entry of the fit, or nothing when no caller collects the drops. get_linear_constraints fills 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, :geq or :leq) and its target.

Related

source
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

  1. Divide the target by the coefficient. The result is rhs.
  2. When the coefficient is negative, exchange :geq and :leq. The result is op. A division by a negative number keeps an equality, so :eq does 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

source
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 alg is a vector, length(alg) == N.

Returns

  • algs::AbstractVector: One entry for each view.

Related

source
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

  1. A CountOf is a number of losses. Return sbar.val, at most T.
  2. A FractionOf is a fraction of T. Return ceil(Int, sbar.val * T), at least one and at most T.
  3. nothing uses the rule of thumb of [1]. Go through the losses from the largest down, and add their prior probabilities. Stop at the position s at which the sum first reaches alpha.
  4. Return two times s, at least ceil(Int, 2 * alpha * T), at least one and at most T.

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 that IntegerConditionalValueatRiskView holds. A CountOf is a number of losses, a FractionOf is a fraction of T, and nothing uses 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, in 1: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.
source
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 alpha on the scenarios of that loss. A posterior that is positive on every scenario does this, so the caller of a CVaR view passes worst = true, and the method accepts rhs == hi for 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 == hi for them.
  • A sum of CVaRs over several assets reaches hi only when one posterior puts at least alpha on the worst scenarios of each asset together. The method does not check that joint condition, so it refuses rhs == hi for 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

  1. Calculate hi over the observations with w > 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. Calculate lo with the opposite choice.
  2. When lo == hi, raise an error unless the prior meets the view: rhs <= hi when op asks the statistic to be at least rhs, and rhs >= lo when op asks it to be at most rhs. Return false.
  3. When op asks the statistic to be at least rhs, raise an error unless rhs is below hi. With worst = true and one asset, rhs == hi passes too.
  4. When op asks the statistic to be at most rhs, raise an error unless rhs is above lo.
  5. 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: If true, 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 passes true.

Validation

  • If lo == hi, rhs <= hi when op is :geq or :eq, and rhs >= lo when op is :leq or :eq.
  • Else, if op is :geq or :eq, rhs < hi. With worst = true and one asset, rhs <= hi.
  • Else, if op is :leq or :eq, rhs > lo.

Returns

  • binds::Bool: false when the left-hand side is constant on the support, so every posterior meets the view. true otherwise.

Related

source
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:

algmixedoprhs against pvBranch
statedanyanyanyalg, unchanged
nothingfalse:geqanyLinearConditionalValueatRiskView
nothingfalse:eqrhs >= pvLinearConditionalValueatRiskView
nothingfalse:eqrhs < pvIntegerConditionalValueatRiskView
nothingfalse:leqanyIntegerConditionalValueatRiskView
nothingtrueanyanyIntegerConditionalValueatRiskView

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, or nothing.
  • 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

source
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:

algmixedsingleoprhs against pvBranch
statedanyanyanyanyalg, unchanged
nothingfalseany:geqanyConicEntropicValueatRiskView
nothingfalseany:eqrhs >= pvConicEntropicValueatRiskView
nothingfalsetrue:eqrhs < pvGridTailView
nothingfalsetrue:leqanyGridTailView
nothingfalsefalse:eqrhs < pvSequentialTailView
nothingfalsefalse:leqanySequentialTailView
nothingtruefalseanyanySequentialTailView

Arguments

  • alg: The stated formulation, or nothing.
  • 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

source
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:

algmixedsingleoprhs against pvBranch
statedanyanyanyanyalg, unchanged
nothingfalseany:geqanyConicRelativisticValueatRiskView
nothingfalseany:eqrhs >= pvConicRelativisticValueatRiskView
nothingfalsetrue:eqrhs < pvGridTailView
nothingfalsetrue:leqanyGridTailView
nothingfalsefalse:eqrhs < pvSequentialTailView
nothingfalsefalse:leqanySequentialTailView
nothingtruefalseanyanySequentialTailView

Arguments

  • alg: The stated formulation, or nothing.
  • 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

source
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

  1. 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.
  2. 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

source
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

  1. Build the row of every point with row. Keep the points whose coefficients and right-hand side are all finite.
  2. Raise an error with msg when the function keeps no point.
  3. 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 to epc under that key with add_ep_constraint!.
  4. When the view has an upper-bound half, keep only the points whose right-hand side is positive. Raise an error with msg when no point remains.
  5. 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 ArgumentError with the message msg().

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

source
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 of replace_prior_views, which start with the tag of the statistic.

Related

source
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

  1. Read mixed, which is true if the coefficients have both signs.
  2. 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.
  3. When the view names several assets and mixed is false, 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.
  4. Read the loss series x of each asset as the negated column of its returns.
  5. Refuse a target that no reweighting of the sample on the support of w reaches, with ep_assert_reachable_view. Return nothing when the left-hand side is constant on the support, because every posterior then meets the view.

Arguments

  • terms: The resolved terms of the view, as ep_view_terms returns 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: If true, the measure of one asset equals its worst loss at a posterior that is positive on every scenario. It goes to ep_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: true if the coefficients have both signs.

Related

source
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:

  1. A ConditionalValueatRiskView reads the prior CVaR of each asset with ConditionalValueatRisk. It selects the formulation with ep_cvar_formulation, and appends the constraint with ep_add_cvar_view!.
  2. An EntropicValueatRiskView reads the prior EVaR of each asset, and the dual variable that attains it, with ep_evar. It selects the formulation with ep_evar_formulation, and appends the constraints with ep_add_evar_view!.
  3. A RelativisticValueatRiskView reads the prior RLVaR of each asset, and the primal pair that attains it, with ep_rlvar. It selects the formulation with ep_rlvar_formulation, and appends the constraints with ep_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, as ep_view_formulations expands it.
  • X: The matrix of asset returns.
  • terms: The resolved terms of the view, as ep_view_terms returns them.
  • eqn: The equation of the view, for the error messages.
  • w: The prior probability weights.

Returns

  • nothing: The function mutates epc and tvs in-place.

Related

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.
source
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

  1. For each asset of the view, skip a window that holds every observation, because it restricts nothing.
  2. Sum w over the window. Warn when the sum minus alpha is at most alpha times the cube root of the machine epsilon of w. 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

source

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).