Exposure constraint generation
PortfolioOptimisers.AbstractConstraintSpace — Type
abstract type AbstractConstraintSpace <: AbstractAlgorithmAbstract 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, ornothing.rd: Returns from which the space can refit, ornothing. A space that refits fromrdstates the source of the refit on its own reader, for example in thex_srcfield of a regression estimator.
Returns
basis: The change of basis, in the form thatrebase_linear_constraintsreads for this space.key::AbstractString: The key ofsets.dictagainst 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
PortfolioOptimisers.FactorSpace — Type
struct FactorSpace{__T_re} <: AbstractConstraintSpaceThe 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.
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
Mfield of aRegression. - $\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, ornothingto read therrof the prior. A precomputedRegressionstates 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 ofresolve_factor_regression. Atx_src = nothing, a precomputed result comes first, then therrof the prior, then a refit.
Constructors
FactorSpace(; re::Option{<:RegE_Reg} = nothing) -> FactorSpaceKeywords correspond to the struct's fields.
Validation
rehas the type boundOption{<:RegE_Reg}, and the constructor makes no other check. A value outside the bound, for example a raw matrix of loadings, raises aTypeErrorfrom the keyword constructor. The resolution can read the source of every space that the constructor builds.
Related
AbstractConstraintSpaceExposureConstraintEstimatorUniverseSetsRegressionfactor_space_regression: ranksreagainst the other two sources of loadings, and states the order.resolve_factor_regression: the same precedence, whichFactorRiskContributionandFactorRiskBudgetingalso use.
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.
PortfolioOptimisers.ExposureConstraintEstimator — Type
struct ExposureConstraintEstimator{__T_lce, __T_space} <: AbstractConstraintEstimatorWrapper 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 thatlcsetakes 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 bareLinearConstraintEstimatorfor it.
Constructors
ExposureConstraintEstimator(; lce::LcE_Lc_VecLcE_Lc, space::AbstractConstraintSpace) -> ExposureConstraintEstimatorKeywords 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
lceis anAbstractVector,!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.3Related
AbstractConstraintSpaceFactorSpaceLinearConstraintEstimatorLinearConstraintlinear_constraintsUniverseSetsPipelineconstraint_space_basis: makes every check that the basis needs, at generation time.constraint_step_value: the pipeline step, and the reason that a constraint from the step stays fixed to the prior of the pipeline.pipeline_asset_sets: builds the factor axis against which the names of the step resolve.
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.
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
- Resolve
rr, the loadings, withfactor_space_regressionover the three sourcesspace.re,rrandrd, under the source ofspace.re. - Raise when
rrisnothing. No source holds a basis, and no row can be assembled. - Check the declared factor axis with
factor_universe, againstsize(rr.M, 2). The call can raise, and the assembly reads no value that it returns. - Return
rrand the key of the factor axis thatfactor_axis_keyreads forrr. The names of the row resolve against that key.
Arguments
space: TheFactorSpacewhose basis the function resolves.sets: The declared universe. It must hold the factor axis thatrrnames, undersets.tfkeyorsets.cfkey.rr: The loadings of the prior, ornothing.rd: Returns from which the space can refit, ornothingon 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.strictcontrols 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 therefield ofFactorSpace, so a factor mandate works on a prior with no factor block. Raises anIsNothingError. - A missing factor axis throws.
factor_universeraises aKeyErrorthat names the key thatfactor_axis_keychose. The axis is optional onUniverseSets, but a constraint written against the axis needs it. size(rr.M, 2) == length(sets.dict[key]). Otherwisefactor_universeraises aDimensionMismatch. The check of the names againstrd.nfneeds 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 aFactorSpaceit is thefactor_axis_keyofrr.
Related
PortfolioOptimisers.port_opt_view — Method
port_opt_view(space::FactorSpace, i, args...) -> FactorSpaceReturn 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: TheFactorSpaceto view.i: The asset index the view keeps.args...: More positional arguments, which the method passes on to the view ofre.
Returns
space::FactorSpace: A space whosereholds the loadings of the selected assets, over the whole factor axis.
Related
PortfolioOptimisers.port_opt_view — Method
port_opt_view(ece::ExposureConstraintEstimator, i, args...) -> ExposureConstraintEstimatorReturn 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: TheExposureConstraintEstimatorto 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
References
- [12]
- D. Cajas. Advanced Portfolio Optimization: A Cutting-edge Quantitative Approach (Springer Nature Switzerland, 2025).