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} <: FiniteAllocationOptimisationResult

Result 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: JuMP model for the short allocation.
  • l_model: JuMP model for the long allocation.
  • fb: The fallback chain that answered this result: the (estimator, result) pair of every attempt optimise made before this one, in the order they ran, or nothing when the estimator it was asked of answered (see FbChain).

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}) -> DiscreteAllocationResult

Keywords 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.
source
PortfolioOptimisers.DiscreteAllocation — Type
struct DiscreteAllocation{__T_slv, __T_sc, __T_so, __T_wf, __T_unit, __T_sets, __T_strict, __T_fb} <: FiniteAllocationOptimisationEstimator

Discrete 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 u that 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.devRow 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.

Note

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. A LotUnit states it, and a LotUnitEstimator resolves it against sets. A share count is a non-negative integer multiple of the lot unit of its asset. The default LotUnit(1) buys whole shares.
  • sets: Universe sets that a LotUnitEstimator in unit resolves against, or nothing. The universe must name the assets of the input in the order of w.
  • strict: Whether a constraint that names an asset or a group that sets does not hold raises an error. When it is false, 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)) -> DiscreteAllocation

Keywords 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 slv is a vector: !isempty(slv).
  • sc > 0, so > 0.
  • If unit is a LotUnitEstimator, sets is not nothing, else an IsNothingError. LotUnit checks 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 ┴ nothing

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.
source
PortfolioOptimisers.factory — Method
factory(a, args...; kwargs...) -> a
factory(a::AbstractArray{<:Union{Nothing, AbstractEstimator, AbstractAlgorithm,
                                 AbstractResult, StatsBase.CovarianceEstimator}},
        args...; kwargs...) -> AbstractArray

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

  1. Return a with no change, and drop args... and kwargs.... 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:

  1. For each element ai of a, call factory on ai, and forward args... and kwargs... with no change.
  2. Collect the results into a new array of the shape of a, in the order of a, 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 or nothing, 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 of a, 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 ┴ nothing

Related

source
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

  1. Read every field of res, in order, into the tuple flds.
  2. Call the constructor of the type of res, without its type parameters, with every entry of flds except the last, and then fb.

Related

source
PortfolioOptimisers._optimise — Method
_optimise(da::DiscreteAllocation, fai::FiniteAllocationInput; str_names::Bool = false,
          save::Bool = true, kwargs...) -> DiscreteAllocationResult

Allocate 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

  1. 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 rule fai.upw.
  2. Resolve the lot unit of each asset with allocation_lot_unit. Each side views a vector lot unit with its own mask.
  3. Start every share count, cost and weight at zero, so an Unpriced Asset holds zero in each.
  4. Solve the short side with finite_sub_allocation, on its negated weights, with the short cash that fai.ca gives.
  5. 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. See AbstractCollateralAlgorithm.
  6. Solve the long side with finite_sub_allocation.
  7. Recombine the two sides over the whole universe, and negate the short side's shares, cost and weights.
  8. Compute cash, the cash that the account holds after the trade, with the third method of fai.ca. It includes the cash that no side received, such as the weight of an Unpriced Asset under upw = nothing.
  9. Set retcode to an OptimisationFailure when either side failed, with one warning per failed side, and to an OptimisationSuccess otherwise.

Arguments

  • da: The discrete allocation optimiser.
  • fai: The FiniteAllocationInput carrying 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. cash is the cash that the account holds after the trade, and fees is the sum of the two sides' fees.

Related

source

References

[247]
R. A. Martin. PyPortfolioOpt: portfolio optimization in Python. Journal of Open Source Software 6, 3066 (2021).