Exposure constraint generation

PortfolioOptimisers.AbstractConstraintSpace — Type
abstract type AbstractConstraintSpace <: AbstractAlgorithm

Abstract supertype for the bases that a linear constraint can be re-based into.

A re-basis applies to a constraint if and only if the constraint is a linear form in the weights. Under a change of basis $\boldsymbol{w}_b = \mathbf{P}^\intercal \boldsymbol{w}$, the row $\boldsymbol{a}$ becomes $\mathbf{P}\boldsymbol{a}$, and nothing else in the problem changes.

The limit comes from the mechanism. A re-basis rewrites a row and does not change the model. A constraint that enters the model through its own variables is outside the mechanism, even when a change of basis of the constrained quantity is well defined. These examples show the rule, and the list is not complete:

  • Cardinality, sub-group cardinality and buy-in thresholds index the binary held-indicators, not the weights.
  • The weight bounds of each asset need no counterpart in another basis. $lb \leq \mathbf{P}^\intercal\boldsymbol{w} \leq ub$ is a linear constraint, and this mechanism already takes it.
  • Turnover and tracking error are norm forms. $\lVert \mathbf{P}^\intercal(\boldsymbol{w} - \boldsymbol{w}_0) \rVert$ has a meaning, but it needs its own variables and cones. Its re-basis is possible in mathematics, but not with this mechanism.
  • A fee is a price per traded position, which the model subtracts from the return. It is not a constraint on the weights.

Each absence is a property of the constraint, not a gap in the code.

The tracking of a factor needs no re-basis. ReturnsTracking takes a benchmark return series, and the return series of a factor is a column of the factor matrix. Pass that column directly.

The family has one member now, FactorSpace. The abstract type lets the family get more members. Any linear change of basis in the weights can be a member and use the same code path, for example a currency, a sector, or an exposure table from the caller.

The family has no AssetSpace, by design. The asset frame is the absence of a re-basis, and a bare LinearConstraintEstimator states it. An AssetSpace member would make ExposureConstraintEstimator a wrapper that changes nothing and returns the rows of the constraint it wraps, bit for bit.

Interfaces

To make a new basis, subtype AbstractConstraintSpace and put the source of its change of basis in its fields. Then implement the methods below.

Basis resolution

  • PortfolioOptimisers.constraint_space_basis(space::AbstractConstraintSpace, sets::UniverseSets, rr, rd) -> (basis, key): The change of basis through which the rows project, and the key against which their names resolve.

There is no fallback. This method makes every check that the basis needs, so the assembly loop after it can assume a consistent basis. A space that checks nothing still implements the method, and its docstring states that it checks nothing.

Arguments

  • space: The basis.
  • sets: The declared universe the names resolve against.
  • rr: The loadings of the prior, or nothing.
  • rd: Returns from which the space can refit, or nothing. A space that refits from rd states the source of the refit on its own reader, for example in the x_src field of a regression estimator.

Returns

  • basis: The change of basis, in the form that rebase_linear_constraints reads for this space.
  • key::AbstractString: The key of sets.dict against which the names of the row resolve.

Asset view

  • PortfolioOptimisers.port_opt_view(space::AbstractConstraintSpace, i, args...) -> AbstractConstraintSpace: A copy of the space over the selected assets.

A basis has the assets on one axis and the names of the space on the other. The generic fallback returns an algorithm unchanged, so it is wrong for every member of this family. FactorSpace has the reference method. It slices the loadings by asset and keeps the whole factor axis.

Arguments

  • space: The basis.
  • i: The asset index the view keeps.

Returns

  • space::AbstractConstraintSpace: The basis over the selected assets.

Related

source
PortfolioOptimisers.FactorSpace — Type
struct FactorSpace{__T_re} <: AbstractConstraintSpace

The factor basis. It re-bases a constraint written in factor names through the loadings of a regression.

The field re holds the source of the basis. A precomputed Regression states the basis, an estimator refits it from the returns, and nothing reads the loadings of the prior. factor_space_regression ranks the three sources and holds the order.

Warning

A precomputed re does not refit. The rows use exactly the loadings that the caller gave, whatever data the problem is solved on later. Constraint generation cannot see that it runs inside a cross-validation fold. The loadings have the correct shape for the full universe, so the projection is stale with no error and no warning. Two forms already give a basis that changes. The first is re = <an estimator>, which refits per fold and per subproblem. The second is a time-dependent schedule on lcse, which is already TD_Option and can hold a different basis per period. A NestedClustered outer solve refuses a stated result. That solve replaces the universe with cluster names and does not slice it, so no view of the loadings can follow it.

Mathematical definition

\[\begin{align} \boldsymbol{w}_f &= \mathbf{M}^\intercal \boldsymbol{w} \\ \boldsymbol{a}^\intercal \boldsymbol{w}_f &= (\mathbf{M}\boldsymbol{a})^\intercal \boldsymbol{w} \\ \mathbf{A}\boldsymbol{w}_f \leq \boldsymbol{b} &\iff \left(\mathbf{A}\mathbf{M}^\intercal\right)\boldsymbol{w} \leq \boldsymbol{b}\,. \end{align}\]

Where:

  • $\mathbf{M}$: $Na \times Nf$ matrix of loadings, the M field of a Regression.
  • $\boldsymbol{w}$: Portfolio weights vector $N \times 1$.
  • $\boldsymbol{w}_f$: $Nf \times 1$ vector of factor exposures.
  • $\boldsymbol{a}$: $Nf \times 1$ row that the user wrote in factor names.
  • $\mathbf{A}$: $Nc \times Nf$ coefficient matrix, with one row per constraint.
  • $\boldsymbol{b}$: $Nc \times 1$ right-hand side of those constraints.

The third line is the complete re-basis, and it states two facts. The first fact is that the product of the coefficient matrix and $\mathbf{M}^\intercal$ turns a constraint over the factors into a constraint over the assets. The second fact is that $\boldsymbol{b}$ is the same on both sides, because a change of basis acts on the row and never on the bound. An equality has the same form, with $=$ in place of $\leq$.

A factor exposure is $\mathbf{M}^\intercal\boldsymbol{w}$ and nothing more. Its definition does not use the intercept that a Regression also holds, and no line above contains that intercept. The $\boldsymbol{b}$ above is the right-hand side of the constraints, a different quantity from the intercept.

The names resolve against the factor axis that the loadings name. factor_axis_key reads sets.tfkey for a Regression and sets.cfkey for a CrossSectionalFactorModel. Thus a mandate written for one family never resolves against the names of the other.

The loadings are rr.M, not rr.L. The columns of M are the named original factors, and a user must write a constraint in names that can go in an equation. Under DimensionReductionRegression, the columns of L are principal components. Risk decomposition reads L, and that is correct. M and L are the two sides of one projection, not two conventions that differ.

Fields

  • re: Source of the loadings through which the rows are re-based, or nothing to read the rr of the prior. A precomputed Regression states the basis. An estimator fits the basis to the returns, so a factor mandate also works on a prior with no factor block. The precedence is the one of resolve_factor_regression. At x_src = nothing, a precomputed result comes first, then the rr of the prior, then a refit.

Constructors

FactorSpace(; re::Option{<:RegE_Reg} = nothing) -> FactorSpace

Keywords correspond to the struct's fields.

Validation

  • re has the type bound Option{<:RegE_Reg}, and the constructor makes no other check. A value outside the bound, for example a raw matrix of loadings, raises a TypeError from the keyword constructor. The resolution can read the source of every space that the constructor builds.

Related

References

  • [12] D. Cajas. Advanced Portfolio Optimization: A Cutting-edge Quantitative Approach (Springer Nature Switzerland, 2025). Section 9.1, Equation 9.6. The original source of this formulation was not found. The formulation follows this work and is not checked against the original.
source
PortfolioOptimisers.ExposureConstraintEstimator — Type
struct ExposureConstraintEstimator{__T_lce, __T_space} <: AbstractConstraintEstimator

Wrapper that re-bases a linear constraint into another basis.

ExposureConstraintEstimator wraps a LinearConstraintEstimator, a precomputed LinearConstraint, or a vector of either. It also declares the basis in which the rows are written. It wraps and does not reimplement, so it reuses the equation parser, the checks of val and key, and the expansion of groups. The bound of lce holds every shape that lcse takes except this wrapper, so every such shape can take a re-basis.

The projection happens at generation time, and constraint generation gives an ordinary LinearConstraint over the assets. That constraint goes into the existing lcsr slot and the existing model assembly, and there is no second path for constraints. Near Optimal Centering, time-dependent schedules and every optimiser that uses JuMPOptimiser take factor exposure constraints with no change.

The re-basis is on this type, and not on LinearConstraintEstimator, by design. That type also goes to gcarde and sgcarde, which build rows over the binary held-indicators. A projected row is not integral, and it is not an index into those indicators. The bounds of those two slots do not admit this wrapper. Thus the type system makes the category error impossible, and no check at run time is necessary.

An ExposureConstraintEstimator is also a Pipeline step without a wrapper. The step reads the prior slot for its basis, and writes an ordinary LinearConstraint over the assets into constraints. The factor names resolve against the nf axis that pipeline_asset_sets builds from rd.nf, so the axis and the loadings agree by construction. For a factor mandate, use the lcse field of a JuMPOptimiser, not the step. The step projects once, against the prior that it read. The field projects again against the prior of the optimiser, in each fold. constraint_step_value states the trade-off in full.

Fields

  • lce: Wrapped linear constraint estimator, precomputed linear constraint, or vector of either, written in the names of the basis of the space. It takes every shape that lcse takes except this wrapper, so every such shape can take a re-basis.
  • space: Basis in which the wrapped constraint is written. It has no default. A constraint over the assets needs no space, so use a bare LinearConstraintEstimator for it.

Constructors

ExposureConstraintEstimator(;    lce::LcE_Lc_VecLcE_Lc,    space::AbstractConstraintSpace) -> ExposureConstraintEstimator

Keywords correspond to the struct's fields. space has no default, and the caller must give it. A re-basis is a choice of the user, and the library never infers it.

Validation

  • If lce is an AbstractVector, !isempty(lce).

The constructor checks only that condition. Constraint generation makes every check that the basis needs. The names are on the factor axis and the basis comes from the prior, and one object cannot see both. constraint_space_basis makes those three checks and states them.

Examples

julia> sets = UniverseSets(; dict = Dict("nx" => ["A", "B", "C"], "nf" => ["MTUM", "VLUE"]));julia> rr = Regression(; M = [1.0 0.0; 0.5 0.5; 0.0 1.0]);julia> ece = ExposureConstraintEstimator(; lce = LinearConstraintEstimator(; val = "MTUM <= 0.3"),                                         space = FactorSpace());julia> lcr = linear_constraints(ece, sets; rr = rr);julia> lcr.ineq.A1×3 transpose(::Matrix{Float64}) with eltype Float64: 1.0  0.5  0.0julia> lcr.ineq.B1-element Vector{Float64}: 0.3

Related

References

  • [12] D. Cajas. Advanced Portfolio Optimization: A Cutting-edge Quantitative Approach (Springer Nature Switzerland, 2025). Section 9.1, Equation 9.6. The original source of this formulation was not found. The formulation follows this work and is not checked against the original.
source
PortfolioOptimisers.constraint_space_basis — Function
constraint_space_basis(space::AbstractConstraintSpace, sets::UniverseSets, rr, rd)
    -> (basis, key)

Resolve the basis through which a re-based constraint projects, and the key against which its names resolve. Throw if either is not usable.

This function makes every check that a space needs before the assembly of the first row, so the assembly loop can assume a consistent basis. A FactorSpace needs two checks. The loadings must come from one of the three sources that factor_space_regression ranks. The factor axis must be declared, and it must agree with the loadings on the number of factors. factor_universe makes the second check, and every other reader of the declared axis also uses it.

rd holds the returns from which the space can refit. The JuMPOptimiser and the Pipeline step pass it, and the standalone route passes nothing.

Algorithm

  1. Resolve rr, the loadings, with factor_space_regression over the three sources space.re, rr and rd, under the source of space.re.
  2. Raise when rr is nothing. No source holds a basis, and no row can be assembled.
  3. Check the declared factor axis with factor_universe, against size(rr.M, 2). The call can raise, and the assembly reads no value that it returns.
  4. Return rr and the key of the factor axis that factor_axis_key reads for rr. The names of the row resolve against that key.

Arguments

  • space: The FactorSpace whose basis the function resolves.
  • sets: The declared universe. It must hold the factor axis that rr names, under sets.tfkey or sets.cfkey.
  • rr: The loadings of the prior, or nothing.
  • rd: Returns from which the space can refit, or nothing on the standalone route.

Validation

The names come from the factor axis, but the basis comes from the prior. The two can disagree in ways that no single object can check. Thus this function makes the three checks below, and the constructor makes none of them.

  • A missing basis throws, whatever the value of strict. strict controls unknown names, and an unknown name affects one row. The generator drops that row, and the rest is still the problem that the caller described. A missing regression is different, because no row can be built. A silent drop of all rows gives a feasible portfolio that looks plausible and has none of the requested exposure. "Missing" means that no source holds loadings. The space can give its own through the re field of FactorSpace, so a factor mandate works on a prior with no factor block. Raises an IsNothingError.
  • A missing factor axis throws. factor_universe raises a KeyError that names the key that factor_axis_key chose. The axis is optional on UniverseSets, but a constraint written against the axis needs it.
  • size(rr.M, 2) == length(sets.dict[key]). Otherwise factor_universe raises a DimensionMismatch. The check of the names against rd.nf needs the returns, so the optimiser makes it.

Returns

  • basis::AbstractLoadingsRegressionResult: The loadings through which the rows project.
  • key::AbstractString: The key against which the names of the row resolve. For a FactorSpace it is the factor_axis_key of rr.

Related

source
PortfolioOptimisers.port_opt_view — Method
port_opt_view(space::FactorSpace, i, args...) -> FactorSpace

Return a copy of a FactorSpace over the selected assets.

Only the basis is data. The Regression method of port_opt_view slices re and keeps the rows of M at i. The loadings have one row per asset, so a subset of assets is a subset of rows, and the projection over the subset is exact. A space with re === nothing comes back unchanged. An estimator in re goes through its own view method, and a default estimator comes back as the same object.

A slice of the universe thus gives a slice of the space. A NestedClustered outer solve does not slice the universe. It writes cluster names over the asset universe, and no slice of the rows of the loadings can follow that. For that reason, assert_external_optimiser refuses a space whose re is a precomputed result.

Arguments

  • space: The FactorSpace to view.
  • i: The asset index the view keeps.
  • args...: More positional arguments, which the method passes on to the view of re.

Returns

  • space::FactorSpace: A space whose re holds the loadings of the selected assets, over the whole factor axis.

Related

source
PortfolioOptimisers.port_opt_view — Method
port_opt_view(ece::ExposureConstraintEstimator, i, args...) -> ExposureConstraintEstimator

Return a copy of an ExposureConstraintEstimator over the selected assets.

The method passes the wrapped constraint through and views the space, and it does nothing more. The wrapped shape is written in the names of the space, so an asset index has no meaning for it. The basis of the space is the only part of the estimator that has an asset index.

The generic vector method of port_opt_view covers a VecEcE_LcE_Lc slot, mixed or not. It views each element in turn, and does not slice the list of constraints by asset index.

Arguments

  • ece: The ExposureConstraintEstimator to view.
  • i: The asset index the view keeps.
  • args...: More positional arguments, which the method passes on to the view of the space.

Returns

  • ece::ExposureConstraintEstimator: The same wrapped shape, over a viewed space.

Related

source

References

[12]
D. Cajas. Advanced Portfolio Optimization: A Cutting-edge Quantitative Approach (Springer Nature Switzerland, 2025).