Discrete finite allocation
PortfolioOptimisers.DiscreteAllocationResult — Type
struct DiscreteAllocationResult{__T_retcode, __T_s_retcode, __T_l_retcode, __T_shares, __T_cost, __T_w, __T_cash, __T_fees, __T_s_model, __T_l_model, __T_fb} <: FiniteAllocationOptimisationResultResult type for DiscreteAllocation.
shares, cost and w are signed, so a short position carries a negative share count, a negative cost and a negative weight. fees is the charge the two sub-problems paid over the whole horizon, and it is never signed. cash is the cash that the account holds after both sides trade, as the collateral algorithm of the input states it. It includes the cash that no side received, and it is negative when the book borrows. Under the default ProceedsCollateral, sum(cost) + cash + fees is the cash of the input. retcode is a failure when either sub-problem failed. s_retcode and l_retcode carry the return code of the short and of the long side, and s_model and l_model carry the two JuMP models when save is true.
Fields
retcode: Optimisation return code.
s_retcode: Return code for the short allocation sub-problem.
l_retcode: Return code for the long allocation sub-problem.
shares: Number of shares allocated per asset.
cost: Cost of the allocation.
w: Realised portfolio weights.
cash: Remaining uninvested cash after allocation, from the third method of the collateral algorithm of the input. It includes the cash that no side received, and it is negative when the book borrows.
fees: Fee the allocation paid over the whole horizon. It is the sum of the two sides' charges, and it is never signed.
s_model:JuMPmodel for the short allocation.
l_model:JuMPmodel for the long allocation.
fb: The fallback chain that answered this result: the(estimator, result)pair of every attemptoptimisemade before this one, in the order they ran, ornothingwhen the estimator it was asked of answered (seeFbChain).
Constructors
DiscreteAllocationResult(; retcode::OptimisationReturnCode, s_retcode::Option{<:OptimisationReturnCode}, l_retcode::Option{<:OptimisationReturnCode}, shares::VecNum, cost::VecNum, w::VecNum, cash::Number, fees::Number, s_model::Option{<:JuMP.Model}, l_model::Option{<:JuMP.Model}, fb::Option{<:FOptE_FOpt_FbChain}) -> DiscreteAllocationResultKeywords correspond to the struct's fields.
Related
References
- [247] R. A. Martin. PyPortfolioOpt: portfolio optimization in Python. Journal of Open Source Software 6, 3066 (2021). Methods, page 3. The original source of this formulation was not found. The formulation follows this work and is not checked against the original.
PortfolioOptimisers.DiscreteAllocation — Type
struct DiscreteAllocation{__T_slv, __T_sc, __T_so, __T_wf, __T_unit, __T_sets, __T_strict, __T_fb} <: FiniteAllocationOptimisationEstimatorDiscrete Allocation portfolio optimiser.
DiscreteAllocation turns target weights into share counts in whole lots by solving a Mixed-Integer Programming (MIP) problem. [247] states only that the package it describes converts optimal weights into a discrete allocation, in its Methods on page 3. It does not state the programme. The book tracks the target as closely as the error of wf measures it, and leaves as little cash idle as it can.
The integer variable of the model counts lots. unit states the lot unit of each asset, so the share count of an asset is its lot count times its lot unit. The default LotUnit(1) buys whole shares. A lot unit below one buys fractional shares, and a lot unit above one buys board lots. A LotUnitEstimator resolves the lot unit against sets.
The long and the short side of a book are two separate sub-problems, each with its own cash and its own budget. Each sub-problem holds a non-negative share vector, and optimise negates the short side when it recombines the two. s_retcode and l_retcode of the result carry the two return codes.
Mathematical definition
One sub-problem, under the default ErrorWeightFinaliser(; dev = AbsoluteWeightDeviation()):
\[\begin{align} \underset{\boldsymbol{z} \in \mathbb{Z}_{\geq 0}^{N}}{\min} \quad & u + r\,, \\ \text{s.t.} \quad & \boldsymbol{x} = \boldsymbol{l} \odot \boldsymbol{z}\,, \\ & u \geq \lVert C \boldsymbol{w} - \boldsymbol{x} \odot \boldsymbol{p} \rVert_1\,, \\ & r = C - \boldsymbol{x}^\intercal \boldsymbol{p}\,, \\ & r - F(\boldsymbol{x}) \geq 0\,. \end{align}\]
Where:
- $\boldsymbol{z} \in \mathbb{Z}_{\geq 0}^{N}$: Lot count vector of one side of a finite allocation, the number of whole lots of each asset, the model variable
z. - $\boldsymbol{l}$: Lot unit of each asset of one side of a finite allocation, the number of shares in one lot. A scalar applies to every asset.
- $\boldsymbol{x}$: Share count vector of one side of a finite allocation, the model expression
x. Each entry is a non-negative integer multiple of the lot unit of its asset. - $u$: Allocation error bound, the model variable
uthat bounds the deviation of the book from its target. - $r = C - \boldsymbol{x}^{\intercal} \boldsymbol{p}$: Leftover cash of one side, before the fee.
- $F(\boldsymbol{x})$: Side fee, the fee that one side pays over the whole horizon. It is zero when the input states no fee.
- $\boldsymbol{w}$: Side target weights, the weights of one side of a finite allocation normalised to sum to one. The short side is negated first, so every entry is non-negative.
- $C$: Side cash, the cash that one side of a finite allocation can spend.
- $\boldsymbol{p}$: Asset price vector of one side of a finite allocation.
- $\odot$: Element-wise (Hadamard) product.
- $N$: Number of assets.
$C \boldsymbol{w}$ is the target money of each position. $C$ is already the side's share of the cash, so the side's weights are normalised before they are multiplied by it, and the targets of a side sum to its cash.
The fee of set_allocation_fees! enters the budget and never the objective. The objective reads track well, and leave no capital idle, so a fee added to $r$ and minimised would reward the model for paying more fees, because a larger fee shrinks the leftover. The budget instead states that the fee must be affordable. The objective still pushes $\boldsymbol{x}^\intercal \boldsymbol{p}$ up, so every unit of fee competes with a unit of position, and the model drops a position whose fixed fee buys too little tracking.
wf selects the row that bounds $u$, and the error term $e$ that takes the place of $u$ in the objective $e + r$. The norm wf.alg selects the norm of the row, and the deviation wf.dev selects the residual and $e$. The integrality and the budget do not change with it.
wf.dev | Row on $u$ | $e$ |
|---|---|---|
AbsoluteWeightDeviation | $u \geq \lVert \boldsymbol{x} \odot \boldsymbol{p} - C \boldsymbol{w} \rVert$ | $u$ |
RelativeWeightDeviation | $u \geq \lVert (\boldsymbol{x} \odot \boldsymbol{p}) \oslash (C \boldsymbol{w}) - \boldsymbol{1} \rVert$ | $C u$ |
Where:
- $\lVert \cdot \rVert$: The norm of
wf.alg. - $\oslash$: Element-wise division.
- $\boldsymbol{1}$: Vector of ones.
The absolute error is money, and so is $r$. The relative error is the realised weight of each position over its target weight, less one, and it has no unit. The relative deviation prices it in money as $C u$, so a relative error of one over the whole side is worth the whole side's cash. Without that factor the model gives up any amount of tracking to leave one unit less of cash idle.
The row bounds the norm itself. It does not divide the norm by norm_factor, and an L2Norm and a SquaredL2Norm build the same JuMP.SecondOrderCone over $[u;\, \cdot]$. The square is monotonic on a non-negative norm, so the minimiser is the one a squared objective would give, but the objective value is the norm. The relative deviation replaces a zero target weight with eps so that the division is defined.
Fields
slv: Solver or vector of solvers.
sc: Constraint scale factor.
so: Objective scale factor.
wf: Weight finaliser.
unit: Lot unit of each asset, the number of shares that one purchase buys. ALotUnitstates it, and aLotUnitEstimatorresolves it againstsets. A share count is a non-negative integer multiple of the lot unit of its asset. The defaultLotUnit(1)buys whole shares.
sets: Universe sets that aLotUnitEstimatorinunitresolves against, ornothing. The universe must name the assets of the input in the order ofw.
strict: Whether a constraint that names an asset or a group thatsetsdoes not hold raises an error. When it isfalse, the constraint generator warns and skips the entry.
fb: Fallback result or estimator.
Constructors
DiscreteAllocation(; slv::Slv_VecSlv, sc::Number = 1, so::Number = 1, wf::JuMPWeightFinaliserFormulation = ErrorWeightFinaliser(; dev = AbsoluteWeightDeviation()), unit::LuE_Lu = LotUnit(), sets::Option{<:UniverseSets} = nothing, strict::Bool = false, fb::Option{<:FOptE_FOpt} = GreedyAllocation(; unit = unit, sets = sets, strict = strict)) -> DiscreteAllocationKeywords correspond to the struct's fields. The default fallback reads the same unit, sets and strict, so a failed solve falls back to the same lots.
Validation
- If
slvis a vector:!isempty(slv). sc > 0,so > 0.- If
unitis aLotUnitEstimator,setsis notnothing, else anIsNothingError.LotUnitchecks that a stated lot unit is positive and finite.
Examples
julia> DiscreteAllocation(; slv = Solver(; solver = nothing))DiscreteAllocation slv ┼ Solver │ name ┼ String: "" │ solver ┼ nothing │ settings ┼ nothing │ check_sol ┼ @NamedTuple{}: NamedTuple() │ add_bridges ┴ Bool: true sc ┼ Int64: 1 so ┼ Int64: 1 wf ┼ ErrorWeightFinaliser │ alg ┼ L1Norm │ │ ddof ┴ Int64: 0 │ dev ┴ AbsoluteWeightDeviation() unit ┼ LotUnit │ val ┴ Int64: 1 sets ┼ nothing strict ┼ Bool: false fb ┼ GreedyAllocation │ unit ┼ LotUnit │ │ val ┴ Int64: 1 │ sets ┼ nothing │ strict ┼ Bool: false │ fb ┴ nothingRelated
optimiseDiscreteAllocationResultFiniteAllocationOptimisationEstimatorGreedyAllocationset_discrete_error!
References
- [247] R. A. Martin. PyPortfolioOpt: portfolio optimization in Python. Journal of Open Source Software 6, 3066 (2021). Methods, page 3. 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(a, args...; kwargs...) -> a
factory(a::AbstractArray{<:Union{Nothing, AbstractEstimator, AbstractAlgorithm,
AbstractResult, StatsBase.CovarianceEstimator}},
args...; kwargs...) -> AbstractArrayRebuild an estimator, an algorithm or a result with runtime values. These two methods are the leaf and the array step of the traversal.
factory and port_opt_view are the two propagation mechanisms of this library. factory passes runtime values, such as prior moments, observation weights and previous portfolio weights, down a tree of composed structs. port_opt_view passes an index selection, a subset of the assets, down the same tree.
factory is a traversal, so it owns the identity on every leaf, as fmap in Functors.jl and adapt_structure in Adapt.jl do. A value that has no method of its own comes back with no change: a data field, a scalar, nothing, a set of observation weights and a covariance estimator of StatsBase. So a @propagatable struct sends each @fprop field to factory directly, whatever the field holds.
The array method is the one forwarding contract for every propagation field that holds an array of estimators, algorithms, results or covariance estimators. It applies factory to each element, and it forwards args... and kwargs... with no change. A family that accepts an array of them needs no method of its own. A family that needs more than the forward defines its own, more specific method. A concrete element type, through concrete_typed_array_if_abstract, is an example. An array of data, such as a vector of numbers, is a leaf, and it comes back with no change and with no copy.
Algorithm
The leaf method:
- Return
awith no change, and dropargs...andkwargs.... This method is the leaf of the recursion. Because of it, a call of the verb on a type with no tags returns the value and raises no error.
The array method:
- For each element
aiofa, callfactoryonai, and forwardargs...andkwargs...with no change. - Collect the results into a new array of the shape of
a, in the order ofa, and return it.
A @propagatable struct always has a generated method that is more specific than the leaf method. If the struct has at least one @fprop or @wprop field, that method builds the struct again with its keyword constructor. It sends each @fprop field through factory and each @wprop field through _wprop. If the struct has no such field, that method returns x.
The leaf method does not fill a nothing field. A weights field that must take the incoming weights when it holds nothing carries @wprop, and it goes to _wprop.
Arguments
a: Any value, which the leaf method returns with no change. For the array method, an array of estimators, algorithms, results, covariance estimators ornothing, which it rebuilds one element at a time.args...: Positional arguments. The leaf method ignores them, and the array method forwards them.kwargs...: Keyword arguments. The leaf method ignores them, and the array method forwards them.
Returns
a: The input with no change, for the leaf method.v::AbstractArray: The rebuilt elements, in an array of the shape ofa, for the array method.
Examples
julia> factory(nothing, 1, 2; x = 3)julia> factory([1.0, 2.0], 1, 2; x = 3)2-element Vector{Float64}: 1.0 2.0julia> factory(MeanValue())MeanValue w ┴ nothingRelated
factory(res::FiniteAllocationOptimisationResult, fb::Option{<:FOptE_FOpt_FbChain})Rebuild a finite allocation result with a new fallback record fb.
Every finite allocation result has fb as its last field, as the continuous results do. optimise calls this method with the FbChain of the failed attempts when a fallback answered. A concrete result type can define its own method when a rebuild needs more than a new fb.
Algorithm
- Read every field of
res, in order, into the tupleflds. - Call the constructor of the type of
res, without its type parameters, with every entry offldsexcept the last, and thenfb.
Related
PortfolioOptimisers._optimise — Method
_optimise(da::DiscreteAllocation, fai::FiniteAllocationInput; str_names::Bool = false,
save::Bool = true, kwargs...) -> DiscreteAllocationResultAllocate a book into whole lots with a DiscreteAllocation.
optimise calls this method, once for an allocator with no fallback, and once for each step of the fallback chain otherwise.
Algorithm
- Read the target weights, the long and the short side, and the charge of each side with
prepare_finite_allocation. It removes each Unpriced Asset from its side, and gives its target weight to the rulefai.upw. - Resolve the lot unit of each asset with
allocation_lot_unit. Each side views a vector lot unit with its own mask. - Start every share count, cost and weight at zero, so an Unpriced Asset holds zero in each.
- Solve the short side with
finite_sub_allocation, on its negated weights, with the short cash thatfai.cagives. - Compute the long side's cash with
fai.ca, from the money of the shares that the short side sold and the fee that it paid. SeeAbstractCollateralAlgorithm. - Solve the long side with
finite_sub_allocation. - Recombine the two sides over the whole universe, and negate the short side's shares, cost and weights.
- Compute
cash, the cash that the account holds after the trade, with the third method offai.ca. It includes the cash that no side received, such as the weight of an Unpriced Asset underupw = nothing. - Set
retcodeto anOptimisationFailurewhen either side failed, with one warning per failed side, and to anOptimisationSuccessotherwise.
Arguments
da: The discrete allocation optimiser.fai: TheFiniteAllocationInputcarrying the target weights, the prices, the cash, the collateral algorithm, and the optional horizon and fees.str_names: Whether the JuMP variables get string names.save: Whether the result keeps the two JuMP models.kwargs: Accepted, so that every optimiser takes one call, and ignored.
Returns
res::DiscreteAllocationResult: The realised allocation.cashis the cash that the account holds after the trade, andfeesis the sum of the two sides' fees.
Related
References
- [247]
- R. A. Martin. PyPortfolioOpt: portfolio optimization in Python. Journal of Open Source Software 6, 3066 (2021).