Turnover
The turnover measures the absolute change of each weight from a set of reference weights, such as the weights before a rebalance. You can use it to compute fees or as a constraint. It is also a risk measure, which the turnover risk measure page describes.
PortfolioOptimisers.TurnoverEstimator — Type
struct TurnoverEstimator{__T_w, __T_val, __T_dval, __T_fixed} <: AbstractEstimatorTurnover bounds before turnover_constraints aligns them to a universe. The bounds can name assets or groups.
val can be a number, a vector, a pair, a dictionary, a vector of pairs, or a VectorAbstractEstimatorValueAlgorithm. A pair, a dictionary and a vector of pairs use asset or group names as keys, and dval is the bound of every asset that the keys do not name. turnover_constraints resolves the names against a UniverseSets and returns a Turnover whose val holds one bound per asset.
The w field holds the reference weights, not the candidate weights, as on Turnover.
Fields
w: Reference portfolio weight vector. The deviation of each asset is the difference between the candidate weight and this weight. It is never the candidate weight vector that an optimiser solves for.
val: Turnover bound. A number is one bound for every asset, and a vector holds one bound per asset. ATurnoverEstimatorcan also name the bounds by asset or by group, andturnover_constraintsresolves the names to one bound per asset. AFeesreads thevalof itsTurnoveras a fee rate per asset, not as a bound.
dval: Default value of each entry thatvaldoes not name.
fixed: Iftrue,factorykeeps the reference weightswand ignores the new weights. Iffalse,factoryreplaceswwith the new weights.
Constructors
TurnoverEstimator(; w::VecNum, val::VectorEstValType, dval::Option{<:Number} = nothing, fixed::Bool = false) -> TurnoverEstimatorKeywords correspond to the struct's fields.
Validation
w, throughassert_nonempty_finite_val:!isempty(w)andall(isfinite, w).val, throughassert_nonempty_nonneg_finite_val:AbstractDict:!isempty(val),all(isfinite, values(val))andall(x -> x >= 0, values(val)).- Vector of pairs:
!isempty(val),all(isfinite, getindex.(val, 2))andall(x -> x[2] >= 0, val). Pair:isfinite(val[2])andval[2] >= 0.AbstractVectorof numbers:!isempty(val),all(isfinite, val)andall(x -> x >= 0, val).Number:isfinite(val)andval >= 0.VectorAbstractEstimatorValueAlgorithm: no rule.
dval, throughassert_nonneg: if notnothing,dval >= 0. This rule admits+Inf, which the rules ofvalrefuse.dvalis the bound of every asset thatvaldoes not name, anddval = +Infleaves these assets with no bound.dval = nothinggives them a bound of zero, which freezes their weights.
View parameters
port_opt_view takes the view of these @vprop fields at the selected indices:
w: Sliced to the selected indices throughport_opt_view.val: Sliced to the selected indices throughport_opt_view.
Examples
julia> TurnoverEstimator(; w = [0.2, 0.3, 0.5], val = Dict("A" => 0.1, "B" => 0.2), dval = 0.0)TurnoverEstimator w ┼ Vector{Float64}: [0.2, 0.3, 0.5] val ┼ Dict{String, Float64}: Dict("B" => 0.2, "A" => 0.1) dval ┼ Float64: 0.0 fixed ┴ Bool: falseRelated
PortfolioOptimisers.Turnover — Type
struct Turnover{__T_w, __T_val, __T_fixed} <: AbstractResultBound on the weight change of each asset from a reference portfolio.
The w field holds the reference weights, not the candidate weights. The candidate weights are the weight variable of the optimiser, and no field holds them. factory(tn, w) replaces the reference weights with w. Give it the weights of the last rebalance, and they become the reference of the next rebalance.
val is the bound. A Fees holds the same type and reads val as a fee rate per asset. The type that holds the Turnover thus gives the meaning of val.
Mathematical definition
\[\begin{align} \boldsymbol{Tn}(\boldsymbol{w}) &\coloneqq \lvert \boldsymbol{w} - \boldsymbol{w}_{0} \rvert\,, \\ \boldsymbol{Tn}(\boldsymbol{w}) &\leq \boldsymbol{\delta}\,. \end{align}\]
Where:
- $\boldsymbol{Tn}(\boldsymbol{w})$:
N × 1turnover vector. - $\boldsymbol{w}$:
N × 1vector of candidate portfolio weights. - $\boldsymbol{w}_{0}$: Reference portfolio weights vector $N \times 1$, the weights from which the turnover is measured.
- $\boldsymbol{\delta}$:
N × 1vector of maximum turnover, thevalfield. A scalarvalbroadcasts to every asset. - $\lvert \cdot \rvert$: Element-wise absolute value.
Fields
w: Reference portfolio weight vector. The deviation of each asset is the difference between the candidate weight and this weight. It is never the candidate weight vector that an optimiser solves for.
val: Turnover bound. A number is one bound for every asset, and a vector holds one bound per asset. ATurnoverEstimatorcan also name the bounds by asset or by group, andturnover_constraintsresolves the names to one bound per asset. AFeesreads thevalof itsTurnoveras a fee rate per asset, not as a bound.
fixed: Iftrue,factorykeeps the reference weightswand ignores the new weights. Iffalse,factoryreplaceswwith the new weights.
Constructors
Turnover(; w::VecNum, val::Num_VecNum = 0.0, fixed::Bool = false) -> TurnoverKeywords correspond to the struct's fields.
Validation
The constructor checks the rules in the order of this list, so its error names the first rule that a value breaks.
w, throughassert_nonempty_finite_val:!isempty(w)andall(isfinite, w).val, throughassert_nonemptyandassert_nonneg:AbstractVector:!isempty(val)andall(x -> x >= 0, val).Number:val >= 0.
A bound of
+Infleaves an asset with no bound, so the constructor does not check thatvalis finite. It refusesNaNand-Inf, because neither is>= 0.length(w) == length(val)ifvalis anAbstractVector. The constructor raises aDimensionMismatchif this rule breaks.
View parameters
port_opt_view takes the view of these @vprop fields at the selected indices:
w: Sliced to the selected indices throughport_opt_view.val: Sliced to the selected indices throughport_opt_view.
Examples
julia> Turnover(; w = [0.2, 0.3, 0.5], val = [0.1, 0.2, 0.0])Turnover w ┼ Vector{Float64}: [0.2, 0.3, 0.5] val ┼ Vector{Float64}: [0.1, 0.2, 0.0] fixed ┴ Bool: falsejulia> Turnover(; w = [0.2, 0.3, 0.5], val = 0.02, fixed = true)Turnover w ┼ Vector{Float64}: [0.2, 0.3, 0.5] val ┼ Float64: 0.02 fixed ┴ Bool: trueRelated
set_turnover_constraints!: writes the absolute value of each asset as oneNormOneConerow on an auxiliary variable, and bounds that variable byval._set_turnover_constraints!set_turnover_fees!: readsvalas a fee rate per asset, not as a bound.TurnoverEstimatorAbstractResultVecNumNum_VecNumturnover_constraintsfactory(tn::Turnover, w::VecNum)Feesport_opt_view
References
- [12] D. Cajas. Advanced Portfolio Optimization: A Cutting-edge Quantitative Approach (Springer Nature Switzerland, 2025). Section 9.1, Equations 9.10 and 9.11. The original source of this formulation was not found. The formulation follows this work and is not checked against the original.
PortfolioOptimisers.factory — Method
factory(tn::Turnover, w::VecNum)Replace the reference weights of a Turnover, unless its fixed field is true.
The fixed field selects the weight vector that the result holds. A fixed constraint keeps the reference weights that it was built with, so the function ignores w and returns tn.
Algorithm
- If
tn.fixedistrue, returntnunchanged. The result holds the reference weightstn.w, and the argumentwhas no effect. - If
tn.fixedisfalse, build a newTurnoverwhosewis the argumentw, and whosevalandfixedare those oftn. The result holds the argumentw.
Arguments
tn: The constraint to update. It gives the turnover bounds and thefixedflag.w: New reference weight vector.
Validation
- Step 2 builds a
Turnover, so its constructor checksw. Step 1 checks nothing.
Returns
tn::Turnover:tniftn.fixedistrue. Otherwise, a new constraint withwas its reference weights.
Examples
julia> tn = Turnover(; w = [0.2, 0.3, 0.5], val = [0.1, 0.2, 0.0])Turnover w ┼ Vector{Float64}: [0.2, 0.3, 0.5] val ┼ Vector{Float64}: [0.1, 0.2, 0.0] fixed ┴ Bool: falsejulia> factory(tn, [0.0, 0.2, 0.8])Turnover w ┼ Vector{Float64}: [0.0, 0.2, 0.8] val ┼ Vector{Float64}: [0.1, 0.2, 0.0] fixed ┴ Bool: falsejulia> tn = Turnover(; w = [0.2, 0.3, 0.5], val = [0.1, 0.2, 0.0], fixed = true)Turnover w ┼ Vector{Float64}: [0.2, 0.3, 0.5] val ┼ Vector{Float64}: [0.1, 0.2, 0.0] fixed ┴ Bool: truejulia> factory(tn, [0.0, 0.2, 0.8])Turnover w ┼ Vector{Float64}: [0.2, 0.3, 0.5] val ┼ Vector{Float64}: [0.1, 0.2, 0.0] fixed ┴ Bool: trueRelated
PortfolioOptimisers.factory — Method
factory(tn::TurnoverEstimator, w::VecNum)Replace the reference weights of a TurnoverEstimator, unless its fixed field is true.
The fixed field selects the weight vector that the result holds. A fixed estimator keeps the reference weights that it was built with, so the function ignores w and returns tn.
Algorithm
- If
tn.fixedistrue, returntnunchanged. The result holds the reference weightstn.w, and the argumentwhas no effect. - If
tn.fixedisfalse, build a newTurnoverEstimatorwhosewis the argumentw, and whoseval,dvalandfixedare those oftn. The result holds the argumentw.
Arguments
tn: The estimator to update. It gives the turnover bounds, the default bound and thefixedflag.w: New reference weight vector.
Validation
- Step 2 builds a
TurnoverEstimator, so its constructor checksw. Step 1 checks nothing.
Returns
tn::TurnoverEstimator:tniftn.fixedistrue. Otherwise, a new estimator withwas its reference weights.
Examples
julia> tn = TurnoverEstimator(; w = [0.2, 0.3, 0.5], val = Dict("A" => 0.1, "B" => 0.2), dval = 0.0)TurnoverEstimator w ┼ Vector{Float64}: [0.2, 0.3, 0.5] val ┼ Dict{String, Float64}: Dict("B" => 0.2, "A" => 0.1) dval ┼ Float64: 0.0 fixed ┴ Bool: falsejulia> factory(tn, [0.1, 0.4, 0.5])TurnoverEstimator w ┼ Vector{Float64}: [0.1, 0.4, 0.5] val ┼ Dict{String, Float64}: Dict("B" => 0.2, "A" => 0.1) dval ┼ Float64: 0.0 fixed ┴ Bool: falsejulia> tn = TurnoverEstimator(; w = [0.2, 0.3, 0.5], val = Dict("A" => 0.1, "B" => 0.2), dval = 0.0, fixed = true)TurnoverEstimator w ┼ Vector{Float64}: [0.2, 0.3, 0.5] val ┼ Dict{String, Float64}: Dict("B" => 0.2, "A" => 0.1) dval ┼ Float64: 0.0 fixed ┴ Bool: truejulia> factory(tn, [0.1, 0.4, 0.5])TurnoverEstimator w ┼ Vector{Float64}: [0.2, 0.3, 0.5] val ┼ Dict{String, Float64}: Dict("B" => 0.2, "A" => 0.1) dval ┼ Float64: 0.0 fixed ┴ Bool: trueRelated
PortfolioOptimisers.factory — Method
factory(tn::VecTnE_Tn, w::VecNum)Replace the reference weights of each entry of a vector of turnover constraints or estimators.
The method does what the generic vector method of factory does, and then calls concrete_typed_array_if_abstract. The element type of a vector that holds a Turnover and a TurnoverEstimator is then a Union of the two types, not an abstract type.
Algorithm
- For each entry
tnioftn, in the order oftn, callfactoryontniwithw. Afixedentry returns itself with its own reference weights, so the result can hold entries of both kinds. - Pass the vector of step 1 through
concrete_typed_array_if_abstract. The two turnover types have no common concrete type, so step 1 can give the vector an abstract element type. This step narrows it to aUnionof the element types.
Arguments
tn: Vector of turnover constraints or estimators.w: New reference weight vector.
Returns
res::VecTnE_Tn: One updated entry per entry oftn, in the order oftn.
Examples
julia> tn1 = Turnover(; w = [0.2, 0.3, 0.5], val = [0.1, 0.2, 0.0]);julia> tn2 = Turnover(; w = [0.2, 0.3, 0.5], val = [0.05, 0.1, 0.0]);julia> factory([tn1, tn2], [0.1, 0.4, 0.5])2-element Vector{Turnover{Vector{Float64}, Vector{Float64}, Bool}}: Turnover w ┼ Vector{Float64}: [0.1, 0.4, 0.5] val ┼ Vector{Float64}: [0.1, 0.2, 0.0] fixed ┴ Bool: false Turnover w ┼ Vector{Float64}: [0.1, 0.4, 0.5] val ┼ Vector{Float64}: [0.05, 0.1, 0.0] fixed ┴ Bool: falseRelated
PortfolioOptimisers.turnover_constraints — Function
turnover_constraints(tn::TurnoverEstimator, sets::UniverseSets; datatype::DataType = Float64,
strict::Bool = false)Resolve the names of a TurnoverEstimator against a universe, and return a Turnover.
The result holds the reference weights of tn and one turnover bound per asset of sets. TurnoverEstimator lists the shapes that tn.val can take.
Algorithm
- Resolve
tn.valagainst the universe ofsetswithestimator_to_val. The result is one turnover bound per asset, in the order of the universe and not in the order of the keys oftn.val. Every asset that the keys do not name takestn.dval, orzero(datatype)iftn.dvalisnothing. A key that names neither an asset nor a group raises an error ifstrictistrue, and logs a warning ifstrictisfalse. - Build a
Turnoverfromtn.w, the bounds of step 1 andtn.fixed.
Arguments
tn: The estimator to resolve. It gives the reference weights, the turnover bounds and the default bound.sets:UniverseSetsthat holds the asset names of the universe and the groups.datatype: Element type of the bounds iftn.dvalisnothing. It has no effect iftn.dvalis a number.strict: Iftrue, a key that names no asset and no group raises an error. Iffalse, it logs a warning.
Returns
tn::Turnover: The reference weights oftn, with one turnover bound per asset ofsets.
Examples
julia> sets = UniverseSets(; dict = Dict("nx" => ["A", "B", "C"]));julia> tn = TurnoverEstimator(; w = [0.2, 0.3, 0.5], val = Dict("A" => 0.1, "B" => 0.2));julia> turnover_constraints(tn, sets)Turnover w ┼ Vector{Float64}: [0.2, 0.3, 0.5] val ┼ Vector{Float64}: [0.1, 0.2, 0.0] fixed ┴ Bool: falseRelated
TurnoverEstimatorTurnoverUniverseSetsestimator_to_val: resolves the names oftn.valagainst the universe ofsets.
turnover_constraints(tn::Option{<:Turnover}, args...; kwargs...)
turnover_constraints(tns::AbstractVector{<:Turnover}, ::Nothing, args...; kwargs...)Return a resolved turnover constraint, a vector of them, or nothing, unchanged.
A Turnover holds one bound per asset, so it needs no universe. A vector of them with no universe also returns unchanged, as a vector of LinearConstraint does. The constructors of JuMPOptimiser and of ProgrammeAllocationSet refuse a vector that holds a TurnoverEstimator when they have no universe, so such a vector never reaches this method.
Algorithm
- Return the first argument unchanged. The method reads no other argument and no keyword.
Arguments
tn: ATurnover, ornothing.tns: A vector ofTurnover.args...: More positional arguments. The method ignores them.kwargs...: Keyword arguments. The method ignores them.
Returns
tn::Option{<:Turnover}: The input constraint, unchanged.tns::AbstractVector{<:Turnover}: The input vector, unchanged.
Examples
julia> tn = Turnover(; w = [0.2, 0.3, 0.5], val = [0.1, 0.2, 0.0]);julia> turnover_constraints(tn)Turnover w ┼ Vector{Float64}: [0.2, 0.3, 0.5] val ┼ Vector{Float64}: [0.1, 0.2, 0.0] fixed ┴ Bool: falseRelated
turnover_constraints(tn::VecTnE_Tn, sets::UniverseSets; datatype::DataType = Float64,
strict::Bool = false)Apply turnover_constraints to each entry of a vector of turnover constraints or estimators.
Algorithm
- For each entry
tnioftn, in the order oftn, callturnover_constraintsontniwithsets,datatypeandstrict. An entry that is already aTurnoverpasses through. - Collect the results into a vector that preserves the order of
tn.
Arguments
tn: Vector of turnover constraints or estimators.sets:UniverseSetsthat holds the asset names of the universe and the groups.datatype: Element type of the bounds of an estimator whosedvalisnothing.strict: Iftrue, a key that names no asset and no group raises an error. Iffalse, it logs a warning.
Returns
res::VecTn: One resolved turnover constraint per entry oftn, in the order oftn.
Examples
julia> sets = UniverseSets(; dict = Dict("nx" => ["A", "B", "C"]));julia> tn1 = TurnoverEstimator(; w = [0.2, 0.3, 0.5], val = Dict("A" => 0.1, "B" => 0.2));julia> tn2 = TurnoverEstimator(; w = [0.1, 0.4, 0.5], val = Dict("B" => 0.15, "C" => 0.3));julia> turnover_constraints([tn1, tn2], sets)2-element Vector{Turnover{Vector{Float64}, Vector{Float64}, Bool}}: Turnover w ┼ Vector{Float64}: [0.2, 0.3, 0.5] val ┼ Vector{Float64}: [0.1, 0.2, 0.0] fixed ┴ Bool: false Turnover w ┼ Vector{Float64}: [0.1, 0.4, 0.5] val ┼ Vector{Float64}: [0.0, 0.15, 0.3] fixed ┴ Bool: falseRelated
PortfolioOptimisers.port_opt_view — Method
port_opt_view(tn::VecTnE_Tn, i, args...)View each entry of a vector of turnover constraints or estimators at a subset of the assets.
The method does what the generic vector method of port_opt_view does, and then calls concrete_typed_array_if_abstract, for the reason that factory(tn::VecTnE_Tn, w::VecNum) gives.
Algorithm
- For each entry
tnioftn, in the order oftn, callport_opt_viewontniwithiandargs.... The@vproptags of each type select the fields to slice.wand a vectorvalbecome views ati, and a number or a dictionaryvalstays unchanged. - Pass the vector of step 1 through
concrete_typed_array_if_abstract.
Arguments
tn: Vector of turnover constraints or estimators.i: Index or indices of the subset of assets.args...: More arguments, which the method gives unchanged to theport_opt_viewof each entry.
Returns
res::VecTnE_Tn: One view per entry oftn, in the order oftn.
Examples
julia> tn1 = Turnover(; w = [0.2, 0.3, 0.5], val = [0.1, 0.2, 0.0], fixed = true);julia> tn2 = TurnoverEstimator(; w = [0.2, 0.3, 0.5], val = Dict("A" => 0.1, "B" => 0.2), dval = 0.0, fixed = true);julia> PortfolioOptimisers.port_opt_view(concrete_typed_array([tn1, tn2]), 1:2)2-element Vector{Union{Turnover{SubArray{Float64, 1, Vector{Float64}, Tuple{UnitRange{Int64}}, true}, SubArray{Float64, 1, Vector{Float64}, Tuple{UnitRange{Int64}}, true}, Bool}, TurnoverEstimator{SubArray{Float64, 1, Vector{Float64}, Tuple{UnitRange{Int64}}, true}, Dict{String, Float64}, Float64, Bool}}}: Turnover w ┼ SubArray{Float64, 1, Vector{Float64}, Tuple{UnitRange{Int64}}, true}: [0.2, 0.3] val ┼ SubArray{Float64, 1, Vector{Float64}, Tuple{UnitRange{Int64}}, true}: [0.1, 0.2] fixed ┴ Bool: true TurnoverEstimator w ┼ SubArray{Float64, 1, Vector{Float64}, Tuple{UnitRange{Int64}}, true}: [0.2, 0.3] val ┼ Dict{String, Float64}: Dict("B" => 0.2, "A" => 0.1) dval ┼ Float64: 0.0 fixed ┴ Bool: trueRelated
PortfolioOptimisers.needs_previous_weights — Method
needs_previous_weights(tn::TnE_Tn) -> Bool
needs_previous_weights(tn::VecTnE_Tn) -> BoolTell whether a turnover constraint or estimator needs the previous portfolio weights.
A fixed entry keeps its own reference weights, so it needs no previous weights, and the method for one entry returns !tn.fixed. The vector method reduces with any, not with all. So one entry that is not fixed makes the whole vector need the previous weights.
Algorithm
- On a single
TnE_Tn, return!tn.fixed. - On a
VecTnE_Tn, apply step 1 to every entry and reduce withany.
Arguments
tn: One turnover constraint or estimator, or a vector of them.
Returns
Bool:trueiftnneeds the previous weights, elsefalse.
Related
TurnoverEstimatorTurnoverTnE_TnVecTnE_Tnfactory(tn::Turnover, w::VecNum): reads the samefixedflag.
References
- [12]
- D. Cajas. Advanced Portfolio Optimization: A Cutting-edge Quantitative Approach (Springer Nature Switzerland, 2025).