Lot unit constraint generation
PortfolioOptimisers.LotUnitEstimator — Type
struct LotUnitEstimator{__T_val, __T_key, __T_dval} <: AbstractConstraintEstimatorResolves a lot unit written in asset or group names against a universe.
The lot unit of an asset is the number of shares in one lot. A finite allocation buys each asset in whole lots of its own lot unit. lot_unit_constraints resolves this estimator to a LotUnit. The function finds the indices of each name in the universe that key selects, and gives dval to each unnamed asset. A lot unit can also be a scalar, a vector, or an algorithmic rule such as UniformValues.
One book can mix the two cases. A broker that sells fractional shares trades an asset in lots of, for example, 0.001 shares, and an exchange that trades in board lots sells a stock only in lots of, for example, 100 shares.
A dval of nothing resolves to one(datatype), so an unnamed asset trades in whole shares. This is different from ThresholdEstimator, whose nothing gives no threshold.
The family takes the empty fallback of pipe_constraint_targets, so a lot unit is not a Pipeline step. No optimiser of a pipeline reads a lot unit. The finite allocators DiscreteAllocation and GreedyAllocation read it, and they resolve it against their own sets.
Fields
val: Lot unit of each asset, the number of shares in one lot, as a map from asset or group names to values, a scalar, a vector or an algorithmic rule.
key: Key of the universe insets.dictthat names resolve against. Ifnothing, the caller reads the key fromsets.xkey, or from the key of another declared axis when the caller is written against that axis.
dval: Lot unit of each asset thatvaldoes not name.nothinggivesone(datatype), one whole share.
Constructors
LotUnitEstimator(; val::VectorEstValType, key::Option{<:AbstractString} = nothing, dval::Option{<:Number} = nothing) -> LotUnitEstimatorKeywords correspond to the struct's fields.
Validation
assert_nonempty_gt0_finite_valchecksvalanddval, so a lot unit must be non-empty, positive and finite.- If
keyis notnothing, it must be a non-empty string.
View parameters
port_opt_view takes the view of these @vprop fields at the selected indices:
val: Sliced to the selected indices throughport_opt_view.
Examples
julia> LotUnitEstimator(; val = Dict("A" => 0.001, "B" => 100))LotUnitEstimator val ┼ Dict{String, Real}: Dict{String, Real}("B" => 100, "A" => 0.001) key ┼ nothing dval ┴ nothingjulia> LotUnitEstimator(; val = "A" => 0.001, dval = 1.0)LotUnitEstimator val ┼ Pair{String, Float64}: "A" => 0.001 key ┼ nothing dval ┴ Float64: 1.0Related
LotUnitVectorEstValTypelot_unit_constraintsAbstractConstraintEstimatorUniverseSetsDiscreteAllocationGreedyAllocationThresholdEstimator: has the same shape, and itsnothingdefault gives no threshold.
PortfolioOptimisers.LotUnit — Type
struct LotUnit{__T_val} <: AbstractConstraintResultHolds the lot unit of each asset of a finite allocation.
The lot unit is one scalar for every asset, or a vector with one value for each asset. A finite allocation buys each asset in whole lots, so the share count of an asset is a non-negative integer multiple of its lot unit. A lot unit of one buys whole shares. A lot unit below one buys fractional shares, and a lot unit above one buys board lots.
Mathematical definition
\[\begin{align} \boldsymbol{x} &= \boldsymbol{l} \odot \boldsymbol{z}\,. \end{align}\]
Where:
- $\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. - $\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. It is the
valfield. - $\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. - $\odot$: Element-wise (Hadamard) product.
- $N$: Number of assets.
Fields
val: Lot unit of each asset, as one scalar for every asset or one value for each asset. A share count of an asset is a non-negative integer multiple of its lot unit. A lot unit below one buys fractional shares, and a lot unit above one buys board lots.
Constructors
LotUnit( val::Num_VecNum) -> LotUnitLotUnit(; val::Num_VecNum = 1) -> LotUnitKeywords correspond to the struct's fields.
Validation
assert_nonempty_gt0_finite_valchecksval, so a lot unit must be non-empty, positive and finite.
Both constructors run the same check, because the positional form is the inner constructor and the keyword form calls it.
View parameters
port_opt_view takes the view of these @vprop fields at the selected indices:
val: Sliced to the selected indices throughport_opt_view.
Examples
julia> LotUnit()LotUnit val ┴ Int64: 1julia> LotUnit([0.001, 1.0, 100.0])LotUnit val ┴ Vector{Float64}: [0.001, 1.0, 100.0]Related
PortfolioOptimisers.lot_unit_constraints — Function
lot_unit_constraints(u::LotUnit, args...; kwargs...)Returns a resolved lot unit unchanged.
This method lets a caller give a LotUnit wherever lot_unit_constraints also accepts a LotUnitEstimator. The method makes no new object, so lot_unit_constraints(u) === u holds.
Algorithm
- Return
u. The method reads none of its other arguments and none of its keywords.
Arguments
u: ALotUnit.args...: More positional arguments, which the method ignores.kwargs...: More keyword arguments, which the method ignores.
Returns
lu::LotUnit: The inputu, unchanged.
Examples
julia> lot_unit_constraints(LotUnit(0.001))LotUnit val ┴ Float64: 0.001Related
lot_unit_constraints(u::LotUnitEstimator, sets::UniverseSets;
datatype::DataType = Float64, strict::Bool = false)Resolves a LotUnitEstimator against a universe.
The method resolves the names of u.val against sets, and returns a LotUnit with one value for each asset. u.val can be a dictionary, a pair, a vector of pairs, a scalar, a vector or an algorithmic rule.
Algorithm
- Take the fill value
u.dval, orone(datatype)whenu.dvalisnothing. - Resolve
u.valwithestimator_to_valagainst the universe thatu.keyselects insets. Ifu.keyisnothing, use the universe ofsets.xkey. An asset thatu.valdoes not name takes the fill value of step 1. - Wrap the resolved value in a
LotUnit, which checks that it is non-empty, positive and finite.
Arguments
u:LotUnitEstimatorthat states the lot unit of each asset.sets:UniverseSetsthat holds the asset names and the groups.datatype: Number type of the fill value whenu.dvalisnothing, and of the range thatUniformValuesresolves to.strict: Iftrue, a name inu.valthatsetsdoes not resolve raisesArgumentError. Iffalse, the method logs a warning and skips the name.
Validation
- A name in
u.valthat names neither an asset nor a group raisesArgumentErrorwhenstrictistrue. Otherwise the method logs a warning. An unnamed asset always takes the fill value of step 1. - The
LotUnitconstructor of step 3 checks the resolved value withassert_nonempty_gt0_finite_val.
Returns
lu::LotUnit: ALotUnitwith one value for each asset of the selected universe, or the scalar of a scalaru.val.
Examples
julia> sets = UniverseSets(; dict = Dict("nx" => ["A", "B", "C"]));julia> u = LotUnitEstimator(; val = Dict("A" => 0.001, "B" => 100.0));julia> lot_unit_constraints(u, sets)LotUnit val ┴ Vector{Float64}: [0.001, 100.0, 1.0]Related
lot_unit_constraints(u::LotUnitEstimator, ::Nothing; kwargs...)Refuses to resolve a LotUnitEstimator without a universe.
The estimator names assets and groups, and only a UniverseSets resolves a name to an index. The constructors of DiscreteAllocation and GreedyAllocation refuse this pair before an allocation runs, so this method is reached only by a direct call.
Algorithm
- Throw an
IsNothingErrorthat names the missingsets.
Arguments
u:LotUnitEstimatorthat states the lot unit of each asset.::Nothing: The missing universe.kwargs...: More keyword arguments, which the method ignores.
Validation
- Always throws an
IsNothingError.
Related