Operators: private API
Mathematical functions
⊙, ⊘, ⊕ and ⊖ multiply, divide, add and subtract element by element, and each accepts a scalar or an array on either side. ⊗ gives the outer product of two arrays as a matrix. dot_scalar takes the dot product of two vectors. When one side is a scalar, it treats that scalar as a vector of equal entries, and the scalar can be a JuMP expression. support_product multiplies matrices and reads the right operand only where a row of the left operand has a coefficient that is not zero, so a NaN reaches only the rows that read it.
PortfolioOptimisers.:⊗ — Function
⊗(A::ArrNum, B::ArrNum) -> Matrix{promote_type(eltype(A), eltype(B))}Tensor product of two arrays. The result is a matrix of size (length(A), length(B)), and its entry (i, j) is A[i] * B[j].
Mathematical definition
\[\begin{align} (\boldsymbol{a} \otimes \boldsymbol{b})_{ij} &= a_{i} b_{j}\,. \end{align}\]
Where:
- $\boldsymbol{a}$: Vectorised first array
A, of length $n$. - $\boldsymbol{b}$: Vectorised second array
B, of length $m$. - $a_{i}$, $b_{j}$: Entries of $\boldsymbol{a}$ and $\boldsymbol{b}$ in linear index order.
The result is the outer product $\boldsymbol{a} \boldsymbol{b}^\intercal$, an $n \times m$ matrix. A and B can have any shape, because the operator reads both in linear index order.
Arguments
A::ArrNum: First array.B::ArrNum: Second array.
Examples
julia> PortfolioOptimisers.:⊗([1, 2], [3, 4])2×2 Matrix{Int64}: 3 4 6 8Related
PortfolioOptimisers.:⊙ — Function
⊙(A::ArrNum, B::ArrNum) -> AbstractArray
⊙(A::ArrNum, B) -> AbstractArray
⊙(A, B::ArrNum) -> AbstractArray
⊙(A, B) -> promote_type(eltype(A), eltype(B))Elementwise (Hadamard) multiplication.
Mathematical definition
\[\begin{align} (\boldsymbol{a} \odot \boldsymbol{b})_{i} &= a_{i} b_{i}\,, \\ (\boldsymbol{a} \odot \beta)_{i} &= a_{i} \beta\,, \\ (\alpha \odot \boldsymbol{b})_{i} &= \alpha b_{i}\,, \\ \alpha \odot \beta &= \alpha \beta\,. \end{align}\]
Where:
- $\boldsymbol{a}$, $\boldsymbol{b}$: Array operands, read in linear index order.
- $\alpha$, $\beta$: Scalar operands.
- $i$: Linear index, $i = 1,\ldots,n$.
Both array operands must have the same length. A scalar operand multiplies every entry of the array operand. An array result has the shape of the array operand.
Arguments
A: First operand (array or scalar).B: Second operand (array or scalar).
Examples
julia> PortfolioOptimisers.:⊙([1, 2], [3, 4])2-element Vector{Int64}: 3 8julia> PortfolioOptimisers.:⊙([1, 2], 2)2-element Vector{Int64}: 2 4julia> PortfolioOptimisers.:⊙(2, [3, 4])2-element Vector{Int64}: 6 8julia> PortfolioOptimisers.:⊙(2, 3)6Related
PortfolioOptimisers.:⊘ — Function
⊘(A::ArrNum, B::ArrNum) -> AbstractArray
⊘(A::ArrNum, B) -> AbstractArray
⊘(A, B::ArrNum) -> AbstractArray
⊘(A, B) -> promote_type(eltype(A), eltype(B))Elementwise (Hadamard) division.
Mathematical definition
\[\begin{align} (\boldsymbol{a} \oslash \boldsymbol{b})_{i} &= \frac{a_{i}}{b_{i}}\,, \\ (\boldsymbol{a} \oslash \beta)_{i} &= \frac{a_{i}}{\beta}\,, \\ (\alpha \oslash \boldsymbol{b})_{i} &= \frac{\alpha}{b_{i}}\,, \\ \alpha \oslash \beta &= \frac{\alpha}{\beta}\,. \end{align}\]
Where:
- $\boldsymbol{a}$, $\boldsymbol{b}$: Array operands, read in linear index order.
- $\alpha$, $\beta$: Scalar operands.
- $i$: Linear index, $i = 1,\ldots,n$.
Both array operands must have the same length. An array result has the shape of the array operand. The operator does not check the divisor, so a zero divisor gives an infinity or a NaN.
Arguments
A: Dividend (array or scalar).B: Divisor (array or scalar).
Examples
julia> PortfolioOptimisers.:⊘([4, 9], [2, 3])2-element Vector{Float64}: 2.0 3.0julia> PortfolioOptimisers.:⊘([4, 6], 2)2-element Vector{Float64}: 2.0 3.0julia> PortfolioOptimisers.:⊘(8, [2, 4])2-element Vector{Float64}: 4.0 2.0julia> PortfolioOptimisers.:⊘(8, 2)4.0Related
PortfolioOptimisers.:⊕ — Function
⊕(A::ArrNum, B::ArrNum) -> AbstractArray
⊕(A::ArrNum, B) -> AbstractArray
⊕(A, B::ArrNum) -> AbstractArray
⊕(A, B) -> promote_type(eltype(A), eltype(B))Elementwise (Hadamard) addition.
Mathematical definition
\[\begin{align} (\boldsymbol{a} \oplus \boldsymbol{b})_{i} &= a_{i} + b_{i}\,, \\ (\boldsymbol{a} \oplus \beta)_{i} &= a_{i} + \beta\,, \\ (\alpha \oplus \boldsymbol{b})_{i} &= \alpha + b_{i}\,, \\ \alpha \oplus \beta &= \alpha + \beta\,. \end{align}\]
Where:
- $\boldsymbol{a}$, $\boldsymbol{b}$: Array operands, read in linear index order.
- $\alpha$, $\beta$: Scalar operands.
- $i$: Linear index, $i = 1,\ldots,n$.
Both array operands must have the same length. The operator adds a scalar operand to every entry of the array operand. The built-in + refuses an array and a scalar. An array result has the shape of the array operand.
Arguments
A: First summand (array or scalar).B: Second summand (array or scalar).
Examples
julia> PortfolioOptimisers.:⊕([1, 2], [3, 4])2-element Vector{Int64}: 4 6julia> PortfolioOptimisers.:⊕([1, 2], 2)2-element Vector{Int64}: 3 4julia> PortfolioOptimisers.:⊕(2, [3, 4])2-element Vector{Int64}: 5 6julia> PortfolioOptimisers.:⊕(2, 3)5Related
PortfolioOptimisers.:⊖ — Function
⊖(A::ArrNum, B::ArrNum) -> AbstractArray
⊖(A::ArrNum, B) -> AbstractArray
⊖(A, B::ArrNum) -> AbstractArray
⊖(A, B) -> promote_type(eltype(A), eltype(B))Elementwise (Hadamard) subtraction.
Mathematical definition
\[\begin{align} (\boldsymbol{a} \ominus \boldsymbol{b})_{i} &= a_{i} - b_{i}\,, \\ (\boldsymbol{a} \ominus \beta)_{i} &= a_{i} - \beta\,, \\ (\alpha \ominus \boldsymbol{b})_{i} &= \alpha - b_{i}\,, \\ \alpha \ominus \beta &= \alpha - \beta\,. \end{align}\]
Where:
- $\boldsymbol{a}$, $\boldsymbol{b}$: Array operands, read in linear index order.
- $\alpha$, $\beta$: Scalar operands.
- $i$: Linear index, $i = 1,\ldots,n$.
Both array operands must have the same length. The operator subtracts a scalar B from every entry of A, and it subtracts every entry of B from a scalar A. The built-in - refuses an array and a scalar. An array result has the shape of the array operand.
Arguments
A: Minuend (array or scalar).B: Subtrahend (array or scalar).
Examples
julia> PortfolioOptimisers.:⊖([4, 6], [1, 2])2-element Vector{Int64}: 3 4julia> PortfolioOptimisers.:⊖([4, 6], 2)2-element Vector{Int64}: 2 4julia> PortfolioOptimisers.:⊖(8, [2, 4])2-element Vector{Int64}: 6 4julia> PortfolioOptimisers.:⊖(8, 2)6Related
PortfolioOptimisers.dot_scalar — Function
dot_scalar(a::Union{Number, JuMP.AbstractJuMPScalar}, b::VecNum) -> Union{Number, JuMP.AbstractJuMPScalar}
dot_scalar(a::VecNum, b::Union{Number, JuMP.AbstractJuMPScalar}) -> Union{Number, JuMP.AbstractJuMPScalar}
dot_scalar(a::VecNum, b::VecNum) -> NumberDot product of two operands, where one operand can be a scalar.
- If one argument is a
Union{Number, JuMP.AbstractJuMPScalar}and the other is aVecNum, the function returns the product of the scalar and the sum of the vector. - If both arguments are
VecNums, the function returns theirdotproduct.
Mathematical definition
\[\begin{align} \mathrm{dot\_scalar}(\alpha, \boldsymbol{b}) &= \alpha \sum_{i=1}^{n} b_{i}\,, \\ \mathrm{dot\_scalar}(\boldsymbol{a}, \beta) &= \beta \sum_{i=1}^{n} a_{i}\,, \\ \mathrm{dot\_scalar}(\boldsymbol{a}, \boldsymbol{b}) &= \boldsymbol{a}^\intercal \boldsymbol{b}\,. \end{align}\]
Where:
- $\alpha$, $\beta$: Scalar operand, a number or a
JuMPscalar. - $\boldsymbol{a}$, $\boldsymbol{b}$: Vector operand of length $n$.
The first two forms equal the dot product of the vector with a constant vector whose entries all equal the scalar. The function takes the sum of the vector, so it builds no constant vector of length $n$.
Arguments
a: First operand, a scalar or a vector.b: Second operand, a scalar or a vector.
Returns
res: The scalar result. It is aJuMPexpression when the scalar operand is aJuMPscalar.
Examples
julia> PortfolioOptimisers.dot_scalar(2.0, [1.0, 2.0, 3.0])12.0julia> PortfolioOptimisers.dot_scalar([1.0, 2.0, 3.0], 2.0)12.0julia> PortfolioOptimisers.dot_scalar([1.0, 2.0, 3.0], [4.0, 5.0, 6.0])32.0Related
PortfolioOptimisers.support_product — Function
support_product(A::MatNum, B::VecNum_MatNum) -> VecNum_MatNum
support_product(A::MatNum, S::MatNum, C::MatNum) -> MatNumProduct of matrices that reads the right operand only where a row of A has a coefficient that is not zero.
The plain product A * B multiplies each coefficient of a row of A by each entry of a column of B. Because 0 * NaN is NaN, one non-finite entry of B makes every entry in its column of A * B a NaN, also in a row of A that has a zero coefficient at that position. This product gives NaN only where the support of a row meets a non-finite entry of the column. At all other entries, it gives the plain product. When every entry of B is finite, the result is A * B. The method with three matrices does the same for the quadratic form A * S * transpose(C).
Mathematical definition
\[\begin{align} \mathcal{S}_{i}(\mathbf{A}) &= \left\{k : a_{ik} \neq 0\right\}\,, \\ \left(\mathbf{A} \odot \mathbf{B}\right)_{ij} &= \begin{cases} \sum_{k \in \mathcal{S}_{i}(\mathbf{A})} a_{ik} b_{kj} & b_{kj} \in \mathbb{R} \ \forall k \in \mathcal{S}_{i}(\mathbf{A})\,, \\ \mathrm{NaN} & \text{otherwise}\,, \end{cases} \\ \left(\mathbf{A} \odot \mathbf{S} \odot \mathbf{C}^{\intercal}\right)_{ij} &= \begin{cases} \sum_{k \in \mathcal{S}_{i}(\mathbf{A})} \sum_{l \in \mathcal{S}_{j}(\mathbf{C})} a_{ik} s_{kl} c_{jl} & s_{kl} \in \mathbb{R} \ \forall (k, l) \in \mathcal{S}_{i}(\mathbf{A}) \times \mathcal{S}_{j}(\mathbf{C})\,, \\ \mathrm{NaN} & \text{otherwise}\,. \end{cases} \end{align}\]
Where:
- $\mathcal{S}_{i}(\mathbf{A})$: Support of row $i$ of $\mathbf{A}$, the columns where its coefficient is not zero. A non-finite coefficient is in the support.
- $a_{ik}$, $c_{jl}$: Entries of the left operand
Aand of the outer right operandC. - $b_{kj}$, $s_{kl}$: Entries of the right operand
Band of the middle operandS. - $\odot$: The product over the support.
A term outside the support is zero, so the sum over the support equals the plain sum wherever the plain sum is finite. A non-finite coefficient of A is in the support of its row, so it makes that row of the result non-finite, as in the plain product. A non-finite coefficient of C does the same to a column of the result.
Algorithm
- Return the plain product when every entry of
B, or ofS, is finite. - Replace each non-finite entry of
B, or ofS, by zero, and take the plain product. - For each entry of the result, count the non-finite entries of
B, or ofS, that its supports meet. The count is the product of the indicator matrices of the supports and the indicator matrix of the non-finite entries. - Write
NaNat each entry whose count is positive.
Arguments
A: The left operand,m × n.B: The right operand, withnrows.S: The middle operand,n × p.C: The outer right operand,q × p, which enters transposed.
Returns
P::VecNum_MatNum: The product, with the shape ofA * Bor ofA * S * transpose(C).
Examples
julia> A = [1.0 0.0; 1.0 1.0];julia> A * [2.0, NaN]2-element Vector{Float64}: NaN NaNjulia> PortfolioOptimisers.support_product(A, [2.0, NaN])2-element Vector{Float64}: 2.0 NaNjulia> PortfolioOptimisers.support_product(A, [1.0 0.0; 0.0 NaN], A)2×2 Matrix{Float64}: 1.0 1.0 1.0 NaNRelated