Lot unit constraint generation

PortfolioOptimisers.LotUnitEstimator — Type
struct LotUnitEstimator{__T_val, __T_key, __T_dval} <: AbstractConstraintEstimator

Resolves 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 in sets.dict that names resolve against. If nothing, the caller reads the key from sets.xkey, or from the key of another declared axis when the caller is written against that axis.
  • dval: Lot unit of each asset that val does not name. nothing gives one(datatype), one whole share.

Constructors

LotUnitEstimator(;    val::VectorEstValType,    key::Option{<:AbstractString} = nothing,    dval::Option{<:Number} = nothing) -> LotUnitEstimator

Keywords correspond to the struct's fields.

Validation

  • assert_nonempty_gt0_finite_val checks val and dval, so a lot unit must be non-empty, positive and finite.
  • If key is not nothing, it must be a non-empty string.

View parameters

port_opt_view takes the view of these @vprop fields at the selected indices:

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.0

Related

source
PortfolioOptimisers.LotUnit — Type
struct LotUnit{__T_val} <: AbstractConstraintResult

Holds 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 val field.
  • $\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) -> LotUnit

Keywords correspond to the struct's fields.

Validation

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:

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

source
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

  1. Return u. The method reads none of its other arguments and none of its keywords.

Arguments

  • u: A LotUnit.
  • args...: More positional arguments, which the method ignores.
  • kwargs...: More keyword arguments, which the method ignores.

Returns

  • lu::LotUnit: The input u, unchanged.

Examples

julia> lot_unit_constraints(LotUnit(0.001))LotUnit  val ┴ Float64: 0.001

Related

source
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

  1. Take the fill value u.dval, or one(datatype) when u.dval is nothing.
  2. Resolve u.val with estimator_to_val against the universe that u.key selects in sets. If u.key is nothing, use the universe of sets.xkey. An asset that u.val does not name takes the fill value of step 1.
  3. Wrap the resolved value in a LotUnit, which checks that it is non-empty, positive and finite.

Arguments

  • u: LotUnitEstimator that states the lot unit of each asset.
  • sets: UniverseSets that holds the asset names and the groups.
  • datatype: Number type of the fill value when u.dval is nothing, and of the range that UniformValues resolves to.
  • strict: If true, a name in u.val that sets does not resolve raises ArgumentError. If false, the method logs a warning and skips the name.

Validation

  • A name in u.val that names neither an asset nor a group raises ArgumentError when strict is true. Otherwise the method logs a warning. An unnamed asset always takes the fill value of step 1.
  • The LotUnit constructor of step 3 checks the resolved value with assert_nonempty_gt0_finite_val.

Returns

  • lu::LotUnit: A LotUnit with one value for each asset of the selected universe, or the scalar of a scalar u.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

source
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

  1. Throw an IsNothingError that names the missing sets.

Arguments

  • u: LotUnitEstimator that states the lot unit of each asset.
  • ::Nothing: The missing universe.
  • kwargs...: More keyword arguments, which the method ignores.

Validation

Related

source