From 257855649365e2b89495009c8057788f9ef9ae0d Mon Sep 17 00:00:00 2001 From: "Documenter.jl" Date: Thu, 10 Nov 2022 14:14:38 +0000 Subject: [PATCH] build based on 55b150a --- dev/index.html | 2 +- dev/install/index.html | 2 +- dev/introduction/index.html | 2 +- dev/mappings/index.html | 2 +- dev/refs/index.html | 4 ++-- dev/search/index.html | 2 +- dev/simplifications/index.html | 2 +- dev/sparse/index.html | 2 +- dev/vectors/index.html | 2 +- 9 files changed, 10 insertions(+), 10 deletions(-) diff --git a/dev/index.html b/dev/index.html index c6615d6..17834f2 100644 --- a/dev/index.html +++ b/dev/index.html @@ -1,2 +1,2 @@ -Home · LazyAlgebra for Julia
Edit on GitHub

Home

This is the documentation of the LazyAlgebra package for Julia. The sources are here.

Contents

Index

+Home · LazyAlgebra for Julia
Edit on GitHub

Home

This is the documentation of the LazyAlgebra package for Julia. The sources are here.

Contents

Index

diff --git a/dev/install/index.html b/dev/install/index.html index aea2e57..c1a1496 100644 --- a/dev/install/index.html +++ b/dev/install/index.html @@ -8,4 +8,4 @@ pkg> test LazyAlgebra

If something goes wrong, it may be because you already have an old version of LazyAlgebra. Uninstall LazyAlgebra as follows:

pkg> rm LazyAlgebra
 pkg> gc
 pkg> add https://github.com/emmt/LazyAlgebra.jl

before re-installing.

To revert to Julia's REPL, hit the Backspace key at the ... pkg> prompt.

Installation in scripts

To install LazyAlgebra in a Julia script, write:

if VERSION >= v"0.7.0-"; using Pkg; end
-Pkg.add(PackageSpec(url="https://github.com/emmt/LazyAlgebra.jl", rev="master"));

or with url="git@github.com:emmt/LazyAlgebra.jl" if you want to use ssh.

This also works from the Julia REPL.

+Pkg.add(PackageSpec(url="https://github.com/emmt/LazyAlgebra.jl", rev="master"));

or with url="git@github.com:emmt/LazyAlgebra.jl" if you want to use ssh.

This also works from the Julia REPL.

diff --git a/dev/introduction/index.html b/dev/introduction/index.html index f7b1f7e..d0fddd2 100644 --- a/dev/introduction/index.html +++ b/dev/introduction/index.html @@ -4,4 +4,4 @@ E = inv(D)

yields E which is another reference to A. In other words, inv(inv(A)) -> A holds assuming by default that A is invertible. This follows the principles of laziness. It is however, possible to prevent this by extending the Base.inv method so as to throw an exception when applied to the specific type of A:

Base.inv(::SomeNonInvertibleMapping) = error("non-invertible mapping")

where SomeNonInvertibleMapping <: Mapping is the type of A.

Other example of simplifications:

B = 3A
 C = 7B'

where mappings B and C are such that B*x -> 3*(A*x) and C*x -> 21*(A*x) for any vector x. That is C*x is evaluated as 21*(A*x) not as 7*(3*(A*x)) thanks to simplifications occurring while the mapping C is constructed.

Using the -> to denote in the right-hand side the actual construction made by LazyAlgebra for the expression in the left-hand side and assuming A, B and C are linear mappings, the following simplications will occur:

(A + C + B + 3C)' -> A' + B' + 4C'
 (A*B*3C)'         -> 3C'*B'*A'
-inv(A*B*3C)       -> 3\inv(C)*inv(B)*inv(A)

However, if M is a non-linear mapping, then:

inv(A*B*3M) -> inv(M)*(3\inv(B))*inv(A)

which can be compared to inv(A*B*3C) when all operands are linear mappings.

Note

Due to the associative rules applied by Julia, parentheses are needed around constructions like 3*C if it has to be interpreted as 3C in all contexes. Otherwise, A*B*(3*C) is equivalent to A*B*3C while A*B*3*C is interpreted as ((A*B)*3)*C; that is, compose A and B, apply A*B to 3 and right multiply the result by C.

Creating new mappings

LazyAlgebra provides a number of simple mappings. Creating new primitive mapping types (not by combining existing mappings as explained above) which benefit from the LazyAlgebra framework is as simple as declaring a new mapping subtype of Mapping (or one of its abstract subtypes) and extending two methods vcreate and apply! specialized for the new mapping type. For mode details, see here.

+inv(A*B*3C) -> 3\inv(C)*inv(B)*inv(A)

However, if M is a non-linear mapping, then:

inv(A*B*3M) -> inv(M)*(3\inv(B))*inv(A)

which can be compared to inv(A*B*3C) when all operands are linear mappings.

Note

Due to the associative rules applied by Julia, parentheses are needed around constructions like 3*C if it has to be interpreted as 3C in all contexes. Otherwise, A*B*(3*C) is equivalent to A*B*3C while A*B*3*C is interpreted as ((A*B)*3)*C; that is, compose A and B, apply A*B to 3 and right multiply the result by C.

Creating new mappings

LazyAlgebra provides a number of simple mappings. Creating new primitive mapping types (not by combining existing mappings as explained above) which benefit from the LazyAlgebra framework is as simple as declaring a new mapping subtype of Mapping (or one of its abstract subtypes) and extending two methods vcreate and apply! specialized for the new mapping type. For mode details, see here.

diff --git a/dev/mappings/index.html b/dev/mappings/index.html index 6418eb9..9abb8f9 100644 --- a/dev/mappings/index.html +++ b/dev/mappings/index.html @@ -78,4 +78,4 @@ (A.outdims == B.outdims && A.inpdims == B.inpdims && A.A === B.A && A.I === B.I && A.J === B.J)

Remarks:

+end

which may be simplified to just calling vscale! unconditionally:

vscale!(y, β)

as vscale!(y, β) does nothing if β = 1.

  • @inbounds could be used for the loops but this would require checking that all indices are whithin the bounds. In this example, only k is guaranteed to be valid, i and j have to be checked.

    • diff --git a/dev/refs/index.html b/dev/refs/index.html index b3ba9de..a06e0f0 100644 --- a/dev/refs/index.html +++ b/dev/refs/index.html @@ -1,5 +1,5 @@ -Reference · LazyAlgebra for Julia
    Edit on GitHub

    Reference

    The following provides detailled documentation about types and methods provided by the LazyAlgebra package. This information is also available from the REPL by typing ? followed by the name of a method or a type.

    Methods for linear mappings

    LazyAlgebra.nrows — Function
    nrows(A)

    yields the equivalent number of rows of the linear operator A. Not all operators extend this method.

    In the implemented generalization of linear operators, the equivalent number of rows is the number of element of the result of applying the operator be it single- or multi-dimensional.

    source
    LazyAlgebra.ncols — Function
    ncols(A)

    yields the equivalent number of columns of the linear operator A. Not all operators extend this method.

    In the implemented generalization of linear operators, the equivalent number of columns is the number of element of an argument of the operator be it single- or multi-dimensional.

    source
    LazyAlgebra.row_size — Function
    row_size(A)

    yields the dimensions of the result of applying the linear operator A, this is equivalent to output_size(A). Not all operators extend this method.

    source
    LazyAlgebra.col_size — Function
    col_size(A)

    yields the dimensions of the argument of the linear operator A, this is equivalent to input_size(A). Not all operators extend this method.

    source

    Sparse operators

    Types and compressed storage formats

    LazyAlgebra.SparseOperators.SparseOperator — Type
    SparseOperator{T,M,N}

    is the abstract type inherited by sparse operator types. Parameter T is the type of the elements. Parameters M and N are the number of dimensions of the rows and of the columns respectively. Sparse operators are a generalization of sparse matrices in the sense that they implement linear mappings which can be applied to N-dimensonal arguments to produce M-dimensional results (as explained below). See GeneralMatrix for a similar generalization but for dense matrices.

    See CompressedSparseOperator for usage of sparse operators implementing compressed storage formats.

    source
    LazyAlgebra.SparseOperators.CompressedSparseOperator — Type
    CompressedSparseOperator{F,T,M,N}

    is an abstract sub-type of SparseOperator{T,M,N} and is inherited by the concrete types implementing sparse operators with compressed storage in format F.

    Format F is specificed as a symbol and can be:

    • :COO for Compressed Sparse Coordinate storage format. This format is not the most efficient, it is mostly used as an intermediate for building a sparse operator in one of the following formats.

    • :CSC for Compressed Sparse Column storage format. This format is very efficient for applying the adjoint of the sparse operator.

    • :CSR for Compressed Sparse Row storage format. This format is very efficient for directly applying the sparse operator.

    To construct (or convert to) a sparse operator with compressed storage format F, you can call:

    CompressedSparseOperator{F}(args...; kwds...)
+Reference · LazyAlgebra for Julia
    Edit on GitHub
    Reference
    The following provides detailled documentation about types and methods provided by the LazyAlgebra package.  This information is also available from the REPL by typing ? followed by the name of a method or a type.
    Methods for linear mappings
    LazyAlgebra.nrows — Function
    nrows(A)
    yields the equivalent number of rows of the linear operator A. Not all operators extend this method.
    In the implemented generalization of linear operators, the equivalent number of rows is the number of element of the result of applying the operator be it single- or multi-dimensional.
    source
    LazyAlgebra.ncols — Function
    ncols(A)
    yields the equivalent number of columns of the linear operator A. Not all operators extend this method.
    In the implemented generalization of linear operators, the equivalent number of columns is the number of element of an argument of the operator be it single- or multi-dimensional.
    source
    LazyAlgebra.row_size — Function
    row_size(A)
    yields the dimensions of the result of applying the linear operator A, this is equivalent to output_size(A). Not all operators extend this method.
    source
    LazyAlgebra.col_size — Function
    col_size(A)
    yields the dimensions of the argument of the linear operator A, this is equivalent to input_size(A). Not all operators extend this method.
    source
    Sparse operators
    Types and compressed storage formats
    LazyAlgebra.SparseOperators.SparseOperator — Type
    SparseOperator{T,M,N}
    is the abstract type inherited by sparse operator types.  Parameter T is the type of the elements.  Parameters M and N are the number of dimensions of the rows and of the columns respectively.  Sparse operators are a generalization of sparse matrices in the sense that they implement linear mappings which can be applied to N-dimensonal arguments to produce M-dimensional results (as explained below).  See GeneralMatrix for a similar generalization but for dense matrices.
    See CompressedSparseOperator for usage of sparse operators implementing compressed storage formats.
    source
    LazyAlgebra.SparseOperators.CompressedSparseOperator — Type
    CompressedSparseOperator{F,T,M,N}
    is an abstract sub-type of SparseOperator{T,M,N} and is inherited by the concrete types implementing sparse operators with compressed storage in format F.
    Format F is specificed as a symbol and can be:
    • :COO for Compressed Sparse Coordinate storage format.  This format is not the most efficient, it is mostly used as an intermediate for building a sparse operator in one of the following formats.
    • :CSC for Compressed Sparse Column storage format.  This format is very efficient for applying the adjoint of the sparse operator.
    • :CSR for Compressed Sparse Row storage format.  This format is very efficient for directly applying the sparse operator.
    To construct (or convert to) a sparse operator with compressed storage format F, you can call:
    CompressedSparseOperator{F}(args...; kwds...)
 CompressedSparseOperator{F,T}(args...; kwds...)
 CompressedSparseOperator{F,T,M}(args...; kwds...)
 CompressedSparseOperator{F,T,M,N}(args...; kwds...)
    where given parameters T, M and N, arguments args... and optional keywords kwds... will be passed to the concrete constructor SparseOperatorCOO, SparseOperatorCSC or SparseOperatorCSR corresponding to the format F.
    It is possible to use a compressed sparse operator A as an iterator:
    for (Aij,i,j) in A # simple but slow for CSR and CSC
@@ -21,4 +21,4 @@
      i   = get_row(A, k) # get row index of entry
      j   = get_col(A, k) # get column index of entry
      Aij = get_val(A, k) # get value of entry
-end
    The low-level methods each_row, each_col, each_off, get_row, get_col and get_val are not automatically exported by LazyAlgebra, this is the purpose of the statement using LazyAlgebra.SparseMethods.
    source
    LazyAlgebra.SparseOperators.SparseOperatorCOO — Type
    Sparse operators in Compressed Sparse Coordinate (COO) format store the significant entries in no particular order, as a vector of values, a vector of linear row indices and a vector of linear column indices.  It is even possible to have repeated entries.  This format is very useful to build a sparse linear operator.  It can be converted to a more efficient format like Compressed Sparse Column (CSC) or Compressed Sparse Row (CSR) for fast application of the sparse linear mapping or of its adjoint.
    A sparse operator in COO storage format can be constructed by providing all necessary information:
    SparseOperatorCOO(vals, rows, cols, rowsiz, colsiz)
    where vals is the vector of values of the sparse entries, rows and cols are integer valued vectors with the linear row and column indices of the sparse entries, rowsiz and colsiz are the sizes of the row and column dimensions. The entries values and respective linear row and column indices of the k-th sparse entry are given by vals[k], rows[k] and cols[k].  For efficiency reasons, sparse operators are currently limited to fast arrays because they can be indexed linearly with no loss of performances.  If vals, rows and/or cols are not fast arrays, they will be automatically converted to linearly indexed arrays.
    A sparse operator in COO storage format can be directly constructed from a 2-dimensional Julia array A:
    SparseOperatorCOO(A, sel = (v,i,j) -> (v != zero(v)))
    where optional argument sel is a selector function which is called as sel(v,i,j) with v, i and j the value, the row and the column linear indices for each entries of A and which is assumed to yield true for the entries of A to be selected in the sparse structure and false for the entries of A to discard.  The default selector is such that all non-zeros of A are selected.
    The element type, say T, for the sparse coefficients can be imposed by rewriting the above examples as:
    SparseOperatorCOO{T}(args...)
    A sparse operator in COO storage format implementing generalized matrix-vector multiplication can also be directly constructed from a L-dimensional Julia array (with L ≥ 2) A by:
    SparseOperatorCOO{T,M}(A[, sel])
    with M the number of leading dimensions of A corresponding to the rows of the operator, the trailing N = L - M dimensions being assumed to correspond to the columns of the operator.  These dimensions are the size of, respectively, the output and the input arrays when applying the operator.  The parameter N may be specified (although it can be automatically determined):
    SparseOperatorCOO{T,M,N}(A[, sel])
    provided the equality M + N = ndims(A) holds.
    A last parameter V can be specified for the type of the vector to store the coefficients of the sparse operator:
    SparseOperatorCOO{T,M,N,V}(args...)
    provided V implements standard linear indexing.  The default is to take V = Vector{T}.  As a special case, you can choose a uniform boolean vector from the StructuredArrays package to store the sparse coefficients:
    SparseOperatorCOO{T,M,N,UniformVector{Bool}}(args...)
    to get a compressed sparse operator in COO format whose values are an immutable uniform vector of true values requiring no storage.  This is useful to only store the sparse structure of the operator, that is the indices in COO format of the sparse coefficients not their values.
    The SparseOperatorCOO constructor can also be used to convert a sparse operator in another storage format into the COO format.  In that case, parameter T may also be specified to convert the type of the sparse coefficients.
    source
    LazyAlgebra.SparseOperators.SparseOperatorCSC — Type
    Sparse operators in Compressed Sparse Column (CSC) format store the significant entries in a column-wise order, as a vector of values, a vector of corresponding linear row indices and a vector of offsets indicating, for each column, the range of indices in the vectors of values and of row indices.  This storage format is very suitable for fast application of the operator, notably its adjoint.
    A sparse operator in CSC storage format can be constructed by providing all necessary information:
    SparseOperatorCSC(vals, rows, offs, rowsiz, colsiz)
    where vals is the vector of values of the sparse entries, rows is an integer valued vector of the linear row indices of the sparse entries, offs is a column-wise table of offsets in these arrays, rowsiz and colsiz are the sizes of the row and column dimensions.  The entries values and respective linear row indices of the j-th column are given by vals[k] and rows[k] with k ∈ offs[j]+1:offs[j+1].  The linear column index j is in the range 1:n where n = prod(colsiz) is the equivalent number of columns.  For efficiency reasons, sparse operators are currently limited to fast arrays because they can be indexed linearly with no loss of performances.  If vals, rows and/or offs are not fast arrays, they will be automatically converted to linearly indexed arrays.
    A sparse operator in CSC storage format can be directly constructed from a 2-dimensional Julia array A:
    SparseOperatorCSC(A, sel = (v,i,j) -> (v != zero(v)))
    where optional argument sel is a selector function which is called as sel(v,i,j) with v, i and j the value, the row and the column linear indices for each entries of A and which is assumed to yield true for the entries of A to be selected in the sparse structure and false for the entries of A to discard.  The default selector is such that all non-zeros of A are selected.
    The element type, say T, for the sparse coefficients can be imposed by rewriting the above examples as:
    SparseOperatorCSC{T}(args...)
    A sparse operator in CSC storage format implementing generalized matrix-vector multiplication can also be directly constructed from a L-dimensional Julia array (with L ≥ 2) A by:
    SparseOperatorCSC{T,M}(A[, sel])
    with M the number of leading dimensions of A corresponding to the rows of the operator, the trailing N = L - M dimensions being assumed to correspond to the columns of the operator.  These dimensions are the size of, respectively, the output and the input arrays when applying the operator.  The parameter N may be specified (although it can be automatically determined):
    SparseOperatorCSC{T,M,N}(A[, sel])
    provided the equality M + N = ndims(A) holds.
    A last parameter V can be specified for the type of the vector to store the coefficients of the sparse operator:
    SparseOperatorCSC{T,M,N,V}(args...)
    provided V implements standard linear indexing.  The default is to take V = Vector{T}.  As a special case, you can choose a uniform boolean vector from the StructuredArrays package to store the sparse coefficients:
    SparseOperatorCSC{T,M,N,UniformVector{Bool}}(args...)
    to get a compressed sparse operator in CSC format whose values are an immutable uniform vector of true values requiring no storage.  This is useful to only store the sparse structure of the operator, that is the indices in CSC format of the sparse coefficients not their values.
    The SparseOperatorCSC constructor can also be used to convert a sparse operator in another storage format into the CSC format.  In that case, parameter T may also be specified to convert the type of the sparse coefficients.
    source
    LazyAlgebra.SparseOperators.SparseOperatorCSR — Type
    Sparse operators in Compressed Sparse Row (CSR) format store the significant entries in a row-wise order, as a vector of values, a vector of corresponding linear column indices and a vector of offsets indicating, for each row, the range of indices in the vectors of values and of column indices.  This storage format is very suitable for fast application of the operator.
    A sparse operator in CSR storage format can be constructed by providing all necessary information:
    SparseOperatorCSR(vals, cols, offs, rowsiz, colsiz)
    where vals is the vector of values of the sparse entries, cols is an integer valued vector of the linear column indices of the sparse entries, offs is a column-wise table of offsets in these arrays, rowsiz and colsiz are the sizes of the row and column dimensions.  The entries values and respective linear column indices of the i-th row are given by vals[k] and cols[k] with k ∈ offs[i]+1:offs[i+1].  The linear row index i is in the range 1:m where m = prod(rowsiz) is the equivalent number of rows.  For efficiency reasons, sparse operators are currently limited to fast arrays because they can be indexed linearly with no loss of performances.  If vals, cols and/or offs are not fast arrays, they will be automatically converted to linearly indexed arrays.
    A sparse operator in CSR storage format can be directly constructed from a 2-dimensional Julia array A:
    SparseOperatorCSR(A, sel = (v,i,j) -> (v != zero(v)))
    where optional argument sel is a selector function which is called as sel(v,i,j) with v, i and j the value, the row and the column linear indices for each entries of A and which is assumed to yield true for the entries of A to be selected in the sparse structure and false for the entries of A to discard.  The default selector is such that all non-zeros of A are selected.
    The element type, say T, for the sparse coefficients can be imposed by rewriting the above examples as:
    SparseOperatorCSR{T}(args...)
    A sparse operator in CSR storage format implementing generalized matrix-vector multiplication can also be directly constructed from a L-dimensional Julia array (with L ≥ 2) A by:
    SparseOperatorCSR{T,M}(A[, sel])
    with M the number of leading dimensions of A corresponding to the rows of the operator, the trailing N = L - M dimensions being assumed to correspond to the columns of the operator.  These dimensions are the size of, respectively, the output and the input arrays when applying the operator.  The parameter N may be specified (although it can be automatically determined):
    SparseOperatorCSR{T,M,N}(A[, sel])
    provided the equality M + N = ndims(A) holds.
    A last parameter V can be specified for the type of the vector to store the coefficients of the sparse operator:
    SparseOperatorCSR{T,M,N,V}(args...)
    provided V implements standard linear indexing.  The default is to take V = Vector{T}.  As a special case, you can choose a uniform boolean vector from the StructuredArrays package to store the sparse coefficients:
    SparseOperatorCSR{T,M,N,UniformVector{Bool}}(args...)
    to get a compressed sparse operator in CSR format whose values are an immutable uniform vector of true values requiring no storage.  This is useful to only store the sparse structure of the operator, that is the indices in CSR format of the sparse coefficients not their values.
    The SparseOperatorCSR constructor can also be used to convert a sparse operator in another storage format into the CSR format.  In that case, parameter T may also be specified to convert the type of the sparse coefficients.
    source
    Methods
    LazyAlgebra.SparseOperators.unpack! — Function
    unpack!(A, S; flatten=false) -> A
    unpacks the non-zero coefficients of the sparse operator S into the array A and returns A.  Keyword flatten specifies whether to only consider the length of A instead of its dimensions.  In any cases, A must have as many elements as length(S) and standard linear indexing.
    Just call Array(S) to unpack the coefficients of a sparse operator S without providing the destination array.
    source
    Low-level interface
    These methods are provided by using LazyAlgebra.SparseMethods.
    LazyAlgebra.SparseOperators.each_row — Function
    each_row(A)
    yields an iterator over the linear row indices of the sparse operator A stored in a Compressed Sparse Row (CSR) format, this includes the adjoint of a sparse operator in Compressed Sparse Column (CSC) format.
    source
    LazyAlgebra.SparseOperators.each_col — Function
    each_col(A)
    yields an iterator over the linear column indices of the sparse operator A stored in a Compressed Sparse Column (CSC) format, this includes the adjoint of a sparse operator in Compressed Sparse Row (CSR) format.
    source
    LazyAlgebra.SparseOperators.each_off — Function
    For a sparse operator A stored in a Compressed Sparse Coordinate (COO) format, the call:
    each_off(A)
    yields an iterator over the indices in the arrays of values and of linear row and column indices for the k-th entry of A.
    For a sparse operator A stored in a Compressed Sparse Column (CSC) format, the call:
    each_off(A, j)
    yields an iterator over the indices in the arrays of values and linear row indices for the j-th column of A.
    For a sparse operator A stored in a Compressed Sparse Row (CSR) format, the call:
    each_off(A, i)
    yields an iterator over the indices in the arrays of values and linear column indices for the i-th row of A.
    source
    LazyAlgebra.SparseOperators.get_row — Function
    get_row(A, k) -> i
    yields the linear row index of the k-th entry of the sparse operator A stored in a Compressed Sparse Column (CSC) or Coordinate (COO) formats (this includes adjoint of sparse operators in CSR format).
    source
    LazyAlgebra.SparseOperators.get_rows — Function
    get_rows(A)
    yields the row indices of the entries of the sparse operator A.  The returned array may be shared with A, call copy_rows(A) instead if you want to modify the contents of the returned array with no side effects on A.
    source
    LazyAlgebra.SparseOperators.get_col — Function
    get_col(A, k) -> j
    yields the linear column index of the k-th entry of the sparse operator A stored in a Compressed Sparse Row (CSR) or Coordinate (COO) formats (this includes adjoint of sparse operators in CSC format).
    source
    LazyAlgebra.SparseOperators.get_cols — Function
    get_cols(A)
    yields the column indices of the entries of the sparse operator A.  The returned array may be shared with A, call copy_cols(A) instead if you want to modify the contents of the returned array with no side effects on A.
    source
    LazyAlgebra.SparseOperators.get_val — Function
    get_val(A, k) -> v
    yields the value of the k-th entry of the sparse operator A stored in a Compressed Sparse Row (CSR), Compressed Sparse Column (CSC) or Coordinate (COO) format.
    Argument may also be the adjoint of a sparse operator:
    get_val(A', k) -> conj(get_val(A, k))
    source
    LazyAlgebra.SparseOperators.get_vals — Function
    get_vals(A)
    yields the array storing the values of the sparse operator A.  The returned array is shared with A, call copy_vals(A) instead if you want to modify the contents of the returned array with no side effects on A.
    As a convenience, argument may also be the adjoint of a sparse operator:
    get_vals(A') -> get_vals(A)
    which yields the unmodified values of A, hence the caller has to take the conjugate of these values.  The method get_val(A',k) however takes care of conjugating the values.
    source
    LazyAlgebra.SparseOperators.set_val! — Function
    set_val!(A, k, v) -> A
    assigns v to the value of the k-th entry of the sparse operator A stored in a Compressed Sparse Row (CSR), Compressed Sparse Column (CSC) or Coordinate (COO) format.
    source
    LazyAlgebra.SparseOperators.get_offs — Function
    get_offs(A)
    yields the table of offsets of the sparse operator A.  Not all operators extend this method.
    Warning
    The interpretation of offsets depend on the type of A.  For instance, assuming offs = get_offs(A), then the index range of the j-th column of a SparseMatrixCSC is offs[j]:(offs[j+1]-1) while the index range is (offs[j]+1):offs[j+1] for a SparseOperatorCSC.  For this reason, it is recommended to call each_off instead or to call get_offs with 2 arguments as shown below.
    For a transparent usage of the offsets, the method should be called with 2 arguments:
    get_offs(A, i) -> k1, k2
    which yields the offsets of the first and last elements in the arrays of values and linear column indices for the i-th row of the sparse operator A stored in a Compressed Sparse Row (CSR) format.  If k2 < k1, it means that the i-th row is empty.  Calling each_off(A,i) directly yields k1:k2.
    get_offs(A, j) -> k1, k2
    yields the offsets of the first and last elements in the arrays of values and linear row indices for the j-th column of the sparse operator A stored in a Compressed Sparse Column (CSC) format.  If k2 < k1, it means that the j-th column is empty.  Calling each_off(A,j) directly yields k1:k2.
    source
    LazyAlgebra.SparseOperators.copy_rows — Function
    copy_rows(A) -> rows
    yields a copy of the linear row indices of entries in sparse operator A.  The result is a vector that is not shared by A, the caller may thus modify its contents with no side effects on A.
    source
    LazyAlgebra.SparseOperators.copy_cols — Function
    copy_cols(A) -> cols
    yields a copy of the linear column indices of entries in sparse operator A. The result is a vector that is not shared by A, the caller may thus modify its contents with no side effects on A.
    source
    LazyAlgebra.SparseOperators.copy_vals — Function
    copy_vals([T = eltype(A),] A) -> vals
    yields a copy of the values of the entries in sparse operator A converted to type T.  The result is a vector that is not shared by A, the caller may thus modify its contents with no side effects on A.
    source
    
+end

    The low-level methods each_row, each_col, each_off, get_row, get_col and get_val are not automatically exported by LazyAlgebra, this is the purpose of the statement using LazyAlgebra.SparseMethods.

    source
    LazyAlgebra.SparseOperators.SparseOperatorCOO — Type

    Sparse operators in Compressed Sparse Coordinate (COO) format store the significant entries in no particular order, as a vector of values, a vector of linear row indices and a vector of linear column indices. It is even possible to have repeated entries. This format is very useful to build a sparse linear operator. It can be converted to a more efficient format like Compressed Sparse Column (CSC) or Compressed Sparse Row (CSR) for fast application of the sparse linear mapping or of its adjoint.

    A sparse operator in COO storage format can be constructed by providing all necessary information:

    SparseOperatorCOO(vals, rows, cols, rowsiz, colsiz)

    where vals is the vector of values of the sparse entries, rows and cols are integer valued vectors with the linear row and column indices of the sparse entries, rowsiz and colsiz are the sizes of the row and column dimensions. The entries values and respective linear row and column indices of the k-th sparse entry are given by vals[k], rows[k] and cols[k]. For efficiency reasons, sparse operators are currently limited to fast arrays because they can be indexed linearly with no loss of performances. If vals, rows and/or cols are not fast arrays, they will be automatically converted to linearly indexed arrays.

    A sparse operator in COO storage format can be directly constructed from a 2-dimensional Julia array A:

    SparseOperatorCOO(A, sel = (v,i,j) -> (v != zero(v)))

    where optional argument sel is a selector function which is called as sel(v,i,j) with v, i and j the value, the row and the column linear indices for each entries of A and which is assumed to yield true for the entries of A to be selected in the sparse structure and false for the entries of A to discard. The default selector is such that all non-zeros of A are selected.

    The element type, say T, for the sparse coefficients can be imposed by rewriting the above examples as:

    SparseOperatorCOO{T}(args...)

    A sparse operator in COO storage format implementing generalized matrix-vector multiplication can also be directly constructed from a L-dimensional Julia array (with L ≥ 2) A by:

    SparseOperatorCOO{T,M}(A[, sel])

    with M the number of leading dimensions of A corresponding to the rows of the operator, the trailing N = L - M dimensions being assumed to correspond to the columns of the operator. These dimensions are the size of, respectively, the output and the input arrays when applying the operator. The parameter N may be specified (although it can be automatically determined):

    SparseOperatorCOO{T,M,N}(A[, sel])

    provided the equality M + N = ndims(A) holds.

    A last parameter V can be specified for the type of the vector to store the coefficients of the sparse operator:

    SparseOperatorCOO{T,M,N,V}(args...)

    provided V implements standard linear indexing. The default is to take V = Vector{T}. As a special case, you can choose a uniform boolean vector from the StructuredArrays package to store the sparse coefficients:

    SparseOperatorCOO{T,M,N,UniformVector{Bool}}(args...)

    to get a compressed sparse operator in COO format whose values are an immutable uniform vector of true values requiring no storage. This is useful to only store the sparse structure of the operator, that is the indices in COO format of the sparse coefficients not their values.

    The SparseOperatorCOO constructor can also be used to convert a sparse operator in another storage format into the COO format. In that case, parameter T may also be specified to convert the type of the sparse coefficients.

    source
    LazyAlgebra.SparseOperators.SparseOperatorCSC — Type

    Sparse operators in Compressed Sparse Column (CSC) format store the significant entries in a column-wise order, as a vector of values, a vector of corresponding linear row indices and a vector of offsets indicating, for each column, the range of indices in the vectors of values and of row indices. This storage format is very suitable for fast application of the operator, notably its adjoint.

    A sparse operator in CSC storage format can be constructed by providing all necessary information:

    SparseOperatorCSC(vals, rows, offs, rowsiz, colsiz)

    where vals is the vector of values of the sparse entries, rows is an integer valued vector of the linear row indices of the sparse entries, offs is a column-wise table of offsets in these arrays, rowsiz and colsiz are the sizes of the row and column dimensions. The entries values and respective linear row indices of the j-th column are given by vals[k] and rows[k] with k ∈ offs[j]+1:offs[j+1]. The linear column index j is in the range 1:n where n = prod(colsiz) is the equivalent number of columns. For efficiency reasons, sparse operators are currently limited to fast arrays because they can be indexed linearly with no loss of performances. If vals, rows and/or offs are not fast arrays, they will be automatically converted to linearly indexed arrays.

    A sparse operator in CSC storage format can be directly constructed from a 2-dimensional Julia array A:

    SparseOperatorCSC(A, sel = (v,i,j) -> (v != zero(v)))

    where optional argument sel is a selector function which is called as sel(v,i,j) with v, i and j the value, the row and the column linear indices for each entries of A and which is assumed to yield true for the entries of A to be selected in the sparse structure and false for the entries of A to discard. The default selector is such that all non-zeros of A are selected.

    The element type, say T, for the sparse coefficients can be imposed by rewriting the above examples as:

    SparseOperatorCSC{T}(args...)

    A sparse operator in CSC storage format implementing generalized matrix-vector multiplication can also be directly constructed from a L-dimensional Julia array (with L ≥ 2) A by:

    SparseOperatorCSC{T,M}(A[, sel])

    with M the number of leading dimensions of A corresponding to the rows of the operator, the trailing N = L - M dimensions being assumed to correspond to the columns of the operator. These dimensions are the size of, respectively, the output and the input arrays when applying the operator. The parameter N may be specified (although it can be automatically determined):

    SparseOperatorCSC{T,M,N}(A[, sel])

    provided the equality M + N = ndims(A) holds.

    A last parameter V can be specified for the type of the vector to store the coefficients of the sparse operator:

    SparseOperatorCSC{T,M,N,V}(args...)

    provided V implements standard linear indexing. The default is to take V = Vector{T}. As a special case, you can choose a uniform boolean vector from the StructuredArrays package to store the sparse coefficients:

    SparseOperatorCSC{T,M,N,UniformVector{Bool}}(args...)

    to get a compressed sparse operator in CSC format whose values are an immutable uniform vector of true values requiring no storage. This is useful to only store the sparse structure of the operator, that is the indices in CSC format of the sparse coefficients not their values.

    The SparseOperatorCSC constructor can also be used to convert a sparse operator in another storage format into the CSC format. In that case, parameter T may also be specified to convert the type of the sparse coefficients.

    source
    LazyAlgebra.SparseOperators.SparseOperatorCSR — Type

    Sparse operators in Compressed Sparse Row (CSR) format store the significant entries in a row-wise order, as a vector of values, a vector of corresponding linear column indices and a vector of offsets indicating, for each row, the range of indices in the vectors of values and of column indices. This storage format is very suitable for fast application of the operator.

    A sparse operator in CSR storage format can be constructed by providing all necessary information:

    SparseOperatorCSR(vals, cols, offs, rowsiz, colsiz)

    where vals is the vector of values of the sparse entries, cols is an integer valued vector of the linear column indices of the sparse entries, offs is a column-wise table of offsets in these arrays, rowsiz and colsiz are the sizes of the row and column dimensions. The entries values and respective linear column indices of the i-th row are given by vals[k] and cols[k] with k ∈ offs[i]+1:offs[i+1]. The linear row index i is in the range 1:m where m = prod(rowsiz) is the equivalent number of rows. For efficiency reasons, sparse operators are currently limited to fast arrays because they can be indexed linearly with no loss of performances. If vals, cols and/or offs are not fast arrays, they will be automatically converted to linearly indexed arrays.

    A sparse operator in CSR storage format can be directly constructed from a 2-dimensional Julia array A:

    SparseOperatorCSR(A, sel = (v,i,j) -> (v != zero(v)))

    where optional argument sel is a selector function which is called as sel(v,i,j) with v, i and j the value, the row and the column linear indices for each entries of A and which is assumed to yield true for the entries of A to be selected in the sparse structure and false for the entries of A to discard. The default selector is such that all non-zeros of A are selected.

    The element type, say T, for the sparse coefficients can be imposed by rewriting the above examples as:

    SparseOperatorCSR{T}(args...)

    A sparse operator in CSR storage format implementing generalized matrix-vector multiplication can also be directly constructed from a L-dimensional Julia array (with L ≥ 2) A by:

    SparseOperatorCSR{T,M}(A[, sel])

    with M the number of leading dimensions of A corresponding to the rows of the operator, the trailing N = L - M dimensions being assumed to correspond to the columns of the operator. These dimensions are the size of, respectively, the output and the input arrays when applying the operator. The parameter N may be specified (although it can be automatically determined):

    SparseOperatorCSR{T,M,N}(A[, sel])

    provided the equality M + N = ndims(A) holds.

    A last parameter V can be specified for the type of the vector to store the coefficients of the sparse operator:

    SparseOperatorCSR{T,M,N,V}(args...)

    provided V implements standard linear indexing. The default is to take V = Vector{T}. As a special case, you can choose a uniform boolean vector from the StructuredArrays package to store the sparse coefficients:

    SparseOperatorCSR{T,M,N,UniformVector{Bool}}(args...)

    to get a compressed sparse operator in CSR format whose values are an immutable uniform vector of true values requiring no storage. This is useful to only store the sparse structure of the operator, that is the indices in CSR format of the sparse coefficients not their values.

    The SparseOperatorCSR constructor can also be used to convert a sparse operator in another storage format into the CSR format. In that case, parameter T may also be specified to convert the type of the sparse coefficients.

    source

    Methods

    LazyAlgebra.SparseOperators.unpack! — Function
    unpack!(A, S; flatten=false) -> A

    unpacks the non-zero coefficients of the sparse operator S into the array A and returns A. Keyword flatten specifies whether to only consider the length of A instead of its dimensions. In any cases, A must have as many elements as length(S) and standard linear indexing.

    Just call Array(S) to unpack the coefficients of a sparse operator S without providing the destination array.

    source

    Low-level interface

    These methods are provided by using LazyAlgebra.SparseMethods.

    LazyAlgebra.SparseOperators.each_row — Function
    each_row(A)

    yields an iterator over the linear row indices of the sparse operator A stored in a Compressed Sparse Row (CSR) format, this includes the adjoint of a sparse operator in Compressed Sparse Column (CSC) format.

    source
    LazyAlgebra.SparseOperators.each_col — Function
    each_col(A)

    yields an iterator over the linear column indices of the sparse operator A stored in a Compressed Sparse Column (CSC) format, this includes the adjoint of a sparse operator in Compressed Sparse Row (CSR) format.

    source
    LazyAlgebra.SparseOperators.each_off — Function

    For a sparse operator A stored in a Compressed Sparse Coordinate (COO) format, the call:

    each_off(A)

    yields an iterator over the indices in the arrays of values and of linear row and column indices for the k-th entry of A.

    For a sparse operator A stored in a Compressed Sparse Column (CSC) format, the call:

    each_off(A, j)

    yields an iterator over the indices in the arrays of values and linear row indices for the j-th column of A.

    For a sparse operator A stored in a Compressed Sparse Row (CSR) format, the call:

    each_off(A, i)

    yields an iterator over the indices in the arrays of values and linear column indices for the i-th row of A.

    source
    LazyAlgebra.SparseOperators.get_row — Function
    get_row(A, k) -> i

    yields the linear row index of the k-th entry of the sparse operator A stored in a Compressed Sparse Column (CSC) or Coordinate (COO) formats (this includes adjoint of sparse operators in CSR format).

    source
    LazyAlgebra.SparseOperators.get_rows — Function
    get_rows(A)

    yields the row indices of the entries of the sparse operator A. The returned array may be shared with A, call copy_rows(A) instead if you want to modify the contents of the returned array with no side effects on A.

    source
    LazyAlgebra.SparseOperators.get_col — Function
    get_col(A, k) -> j

    yields the linear column index of the k-th entry of the sparse operator A stored in a Compressed Sparse Row (CSR) or Coordinate (COO) formats (this includes adjoint of sparse operators in CSC format).

    source
    LazyAlgebra.SparseOperators.get_cols — Function
    get_cols(A)

    yields the column indices of the entries of the sparse operator A. The returned array may be shared with A, call copy_cols(A) instead if you want to modify the contents of the returned array with no side effects on A.

    source
    LazyAlgebra.SparseOperators.get_val — Function
    get_val(A, k) -> v

    yields the value of the k-th entry of the sparse operator A stored in a Compressed Sparse Row (CSR), Compressed Sparse Column (CSC) or Coordinate (COO) format.

    Argument may also be the adjoint of a sparse operator:

    get_val(A', k) -> conj(get_val(A, k))
    source
    LazyAlgebra.SparseOperators.get_vals — Function
    get_vals(A)

    yields the array storing the values of the sparse operator A. The returned array is shared with A, call copy_vals(A) instead if you want to modify the contents of the returned array with no side effects on A.

    As a convenience, argument may also be the adjoint of a sparse operator:

    get_vals(A') -> get_vals(A)

    which yields the unmodified values of A, hence the caller has to take the conjugate of these values. The method get_val(A',k) however takes care of conjugating the values.

    source
    LazyAlgebra.SparseOperators.set_val! — Function
    set_val!(A, k, v) -> A

    assigns v to the value of the k-th entry of the sparse operator A stored in a Compressed Sparse Row (CSR), Compressed Sparse Column (CSC) or Coordinate (COO) format.

    source
    LazyAlgebra.SparseOperators.get_offs — Function
    get_offs(A)

    yields the table of offsets of the sparse operator A. Not all operators extend this method.

    Warning

    The interpretation of offsets depend on the type of A. For instance, assuming offs = get_offs(A), then the index range of the j-th column of a SparseMatrixCSC is offs[j]:(offs[j+1]-1) while the index range is (offs[j]+1):offs[j+1] for a SparseOperatorCSC. For this reason, it is recommended to call each_off instead or to call get_offs with 2 arguments as shown below.

    For a transparent usage of the offsets, the method should be called with 2 arguments:

    get_offs(A, i) -> k1, k2

    which yields the offsets of the first and last elements in the arrays of values and linear column indices for the i-th row of the sparse operator A stored in a Compressed Sparse Row (CSR) format. If k2 < k1, it means that the i-th row is empty. Calling each_off(A,i) directly yields k1:k2.

    get_offs(A, j) -> k1, k2

    yields the offsets of the first and last elements in the arrays of values and linear row indices for the j-th column of the sparse operator A stored in a Compressed Sparse Column (CSC) format. If k2 < k1, it means that the j-th column is empty. Calling each_off(A,j) directly yields k1:k2.

    source
    LazyAlgebra.SparseOperators.copy_rows — Function
    copy_rows(A) -> rows

    yields a copy of the linear row indices of entries in sparse operator A. The result is a vector that is not shared by A, the caller may thus modify its contents with no side effects on A.

    source
    LazyAlgebra.SparseOperators.copy_cols — Function
    copy_cols(A) -> cols

    yields a copy of the linear column indices of entries in sparse operator A. The result is a vector that is not shared by A, the caller may thus modify its contents with no side effects on A.

    source
    LazyAlgebra.SparseOperators.copy_vals — Function
    copy_vals([T = eltype(A),] A) -> vals

    yields a copy of the values of the entries in sparse operator A converted to type T. The result is a vector that is not shared by A, the caller may thus modify its contents with no side effects on A.

    source
    diff --git a/dev/search/index.html b/dev/search/index.html index 8b6380a..5c8ad57 100644 --- a/dev/search/index.html +++ b/dev/search/index.html @@ -1,2 +1,2 @@ -Search · LazyAlgebra for Julia

    Loading search...

      +Search · LazyAlgebra for Julia

      Loading search...

        diff --git a/dev/simplifications/index.html b/dev/simplifications/index.html index 3e2a1c2..3718ec1 100644 --- a/dev/simplifications/index.html +++ b/dev/simplifications/index.html @@ -14,4 +14,4 @@ inv(A::Inverse) = unveil(A) inv(A::Adjoint) = AdjointInverse(A) inv(A::AdjointInverse) = A'

        Coding recommendations

        To make the code easier to maintain and avoid incosistencies, there are a few recommendations to follow. This is especially true for coding the simplification rules that are automatically performed.

        +/(A::Mapping, α::Number) = A*inv(α)

        Only the right-multiplication is in charge of deciding whether the operation is commutative and these two methods returns their result as an expression to delegate the construction of the result to the methods implementing the left-multiplication of a mapping by a scalar, the composition of two mappings, etc.

        diff --git a/dev/sparse/index.html b/dev/sparse/index.html index 03bdf08..4e1cb2c 100644 --- a/dev/sparse/index.html +++ b/dev/sparse/index.html @@ -50,4 +50,4 @@ convert(CompressedSparseOperator{:CSC,T}, A)

        If you just want to convert the type of the values stored by the sparse operator A to type T while keeping its storage format, any of the following will do the job:

        SparseOperator{T}(A)
 CompressedSparseOperator{Any,T}(A)
 convert(SparseOperator{T}, A)
-convert(CompressedSparseOperator{Any,T}, A)

        As can be seen, specifying Any for the format parameter in CompressedSparseOperator is a mean to keep the same storage format.

        Other methods

        A sparse operator S can be reshaped:

        reshape(S, rowdims, coldims)

        where rowdims and coldims are the new list of dimensions for the rows and the columns, their product must be equal to the product of the former lists of dimensions (which means that you cannot change the number of elements of the input and output of a sparse operator). The reshaped sparse operator and S share the arrays of non-zero coefficients and corresponding row and column indices, hence reshaping is a fast operation.

        The non-zero coefficients of a sparse operator S can be unpacked into a provided array A:

        unpack!(A, S; flatten=false) -> A

        Keyword flatten specifies whether to only consider the length of A instead of its dimensions. In any cases, A must have as many elements as length(S) and standard linear indexing. Just call Array(S) to unpack the coefficients of the sparse operator S without providing the destination array or Array{T}(S) if you want to a specific element type T.

        [LinearInterpolators]: https://github.com/emmt/LinearInterpolators.jl [SparseArrays]: https://docs.julialang.org/en/latest/stdlib/SparseArrays/#Sparse-Arrays-1 [sparse]: https://docs.julialang.org/en/latest/stdlib/SparseArrays/#SparseArrays.sparse [SparseMatrixCSC]: https://docs.julialang.org/en/latest/stdlib/SparseArrays/#SparseArrays.SparseMatrixCSC

        +convert(CompressedSparseOperator{Any,T}, A)

        As can be seen, specifying Any for the format parameter in CompressedSparseOperator is a mean to keep the same storage format.

        Other methods

        A sparse operator S can be reshaped:

        reshape(S, rowdims, coldims)

        where rowdims and coldims are the new list of dimensions for the rows and the columns, their product must be equal to the product of the former lists of dimensions (which means that you cannot change the number of elements of the input and output of a sparse operator). The reshaped sparse operator and S share the arrays of non-zero coefficients and corresponding row and column indices, hence reshaping is a fast operation.

        The non-zero coefficients of a sparse operator S can be unpacked into a provided array A:

        unpack!(A, S; flatten=false) -> A

        Keyword flatten specifies whether to only consider the length of A instead of its dimensions. In any cases, A must have as many elements as length(S) and standard linear indexing. Just call Array(S) to unpack the coefficients of the sparse operator S without providing the destination array or Array{T}(S) if you want to a specific element type T.

        [LinearInterpolators]: https://github.com/emmt/LinearInterpolators.jl [SparseArrays]: https://docs.julialang.org/en/latest/stdlib/SparseArrays/#Sparse-Arrays-1 [sparse]: https://docs.julialang.org/en/latest/stdlib/SparseArrays/#SparseArrays.sparse [SparseMatrixCSC]: https://docs.julialang.org/en/latest/stdlib/SparseArrays/#SparseArrays.SparseMatrixCSC

        diff --git a/dev/vectors/index.html b/dev/vectors/index.html index 225f6ba..032a21a 100644 --- a/dev/vectors/index.html +++ b/dev/vectors/index.html @@ -1,2 +1,2 @@ -Methods for vectors · LazyAlgebra for Julia
        Edit on GitHub

        Methods for vectors

        A vector is that which has the algebra of a vector space (Peano 1888, van der Waerden 1931). See talk by Jiahao Chen: Taking Vector Transposes Seriously at JuliaCon 2017.

        Vectorized methods

        Most necessary operations on the variables of interest are linear operations. Hence variables (whatever their specific type and size) are just called vectors in LazyAlgebra. Numerical methods based on LazyAlgebra manipulate the variables via a small number of vectorized methods:

        • vdot([T,][w,]x,y) yields the inner product of x and y; that is, the sum of conj(x[i])*y[i] or, if w is specified, the sum of w[i]*conj(x[i])*y[i], for all indices i. Optional argument T is the type of the result; for real valued vectors, T is a floating-point type; for complex valued vectors, T can be a complex type (with floating-point parts) or a floating-point type to compute only the real part of the inner product. vdot([T,]sel,x,y) yields the sum of x[i]*y[i] for all i ∈ sel where sel is a selection of indices.

        • vnorm1([T,]x) yields the L-1 norm of x, that is the sum of the absolute values of the components of x. Optional argument T is the floating-point type of the result.

        • vnorm2([T,]x) yields the Euclidean (or L-2) norm of x, that is the square root of sum of the squared values of the components of x. Optional argument T is the floating-point type of the result.

        • vnorminf([T,]x) L-∞ norm of x, that is the maximal absolute values of the components of x. Optional argument T is the floating-point type of the result

        • vcreate(x) yields a new variable instance similar to x. If x is an array, the element type of the result is a floating-point type.

        • vcopy!(dst,src) copies the contents of src into dst and returns dst.

        • vcopy(x) yields a fresh copy of the vector x.

        • vswap!(x,y) exchanges the contents of x and y (which must have the same type and size if they are arrays).

        • vfill!(x,α) sets all elements of x with the scalar value α and return x.

        • vzero!(x)fills x with zeros and returns it.

        • vscale!(dst,α,src) overwrites dst with α*src and returns dst. The convention is that, if α = 0, then dst is filled with zeros whatever the contents of src.

        • vscale!(x,α) and vscale!(α,x) overwrite x with α*x and returns x. The convention is that, if α = 0, then x is filled with zeros whatever its prior contents.

        • vscale(α,x) and vscale(x,α) yield a new vector whose elements are those of x multiplied by the scalar α.

        • vproduct!(dst,[sel,]x,y) overwrites dst with the elementwise multiplication of x by y. Optional argument sel is a selection of indices to consider.

        • vproduct(x,y) yields the elementwise multiplication of x by y.

        • vupdate!(y,[sel,]α,x) overwrites y with α*x + y and returns y. Optional argument sel is a selection of indices to which apply the operation (if an index is repeated, the operation will be performed several times at this location).

        • vcombine(α,x,β,y) yields the linear combination α*x or α*x + β*y.

        • vcombine!(dst,α,x,β,y) overwrites dst with the linear combination dst = α*x or dst = α*x + β*y and returns dst.

        Note that the names of these methods all start with a v (for vector) as the conventions used by these methods may be particular. For instance, compared to copy! and when applied to arrays, vcopy! imposes that the two arguments have exactly the same dimensions. Another example is the vdot method which has a slightly different semantics than Julia dot method.

        LazyAlgebra already provides implementations of these methods for Julia arrays with floating-point type elements. This implementation assumes that an array is a valid vector providing it has suitable type and dimensions.

        Implementing a new vector type

        To have a numerical method based on LazyAlgebra be applicable to a new given type of variables, it is sufficient to implement a subset of these basic methods specialized for this kind of variables.

        The various operations that should be implemented for a vector are:

        • compute the inner product of two vectors of the same kind (vdot(x,y) method);
        • create a vector of a given kind (vcreate(x) method);
        • copy a vector (vcopy!(dst,src));
        • fill a vector with a given value (vfill!(x,α) method);
        • exchange the contents of two vectors (vswap!(x,y) method);
        • linearly combine several vectors (vcombine!(dst,α,x,β,y) method).

        Derived methods are:

        • compute the Euclidean norm of a vector (vnorm2 method, based on vdot by default);
        • multiply a vector by a scalar: vscale!(dst,α,src) and/or vscale!(x,α) methods (based on vcombine! by default);
        • update a vector by a scaled step: vupdate!(y,α,x) method (based on vcombine! by default) and, for some constrained optimization methods, vupdate!(y,sel,α,x) method;
        • erase a vector: vzero!(x) method (based on vfill! by default);
        • vscale and vcopy methods are implemented with vcreate and respectivelyvscale! and vcopy!.

        Other methods which may be required by some packages:

        • compute the L-1 norm of a vector: vnorm1(x) method;
        • compute the L-∞ norm of a vector: vnorminf(x) method;

        Methods that must be implemented (V represent the vector type):

        vdot(x::V, y::V)
        vscale!(dst::V, alpha::Real, src::V) -> dst

        methods that may be implemented:

        vscale!(alpha::Real, x::V) -> x

        For mappings and linear operators (see Implementation of new mappings for details), implement:

        apply!(α::Scalar, P::Type{<:Operations}, A::Ta, x::Tx, β::Scalar, y::Ty) -> y

        and

        vcreate(P::Type{P}, A::Ta, x::Tx) -> y

        for Ta<:Mapping and the supported operations P<:Operations.

        +Methods for vectors · LazyAlgebra for Julia
        Edit on GitHub

        Methods for vectors

        A vector is that which has the algebra of a vector space (Peano 1888, van der Waerden 1931). See talk by Jiahao Chen: Taking Vector Transposes Seriously at JuliaCon 2017.

        Vectorized methods

        Most necessary operations on the variables of interest are linear operations. Hence variables (whatever their specific type and size) are just called vectors in LazyAlgebra. Numerical methods based on LazyAlgebra manipulate the variables via a small number of vectorized methods:

        • vdot([T,][w,]x,y) yields the inner product of x and y; that is, the sum of conj(x[i])*y[i] or, if w is specified, the sum of w[i]*conj(x[i])*y[i], for all indices i. Optional argument T is the type of the result; for real valued vectors, T is a floating-point type; for complex valued vectors, T can be a complex type (with floating-point parts) or a floating-point type to compute only the real part of the inner product. vdot([T,]sel,x,y) yields the sum of x[i]*y[i] for all i ∈ sel where sel is a selection of indices.

        • vnorm1([T,]x) yields the L-1 norm of x, that is the sum of the absolute values of the components of x. Optional argument T is the floating-point type of the result.

        • vnorm2([T,]x) yields the Euclidean (or L-2) norm of x, that is the square root of sum of the squared values of the components of x. Optional argument T is the floating-point type of the result.

        • vnorminf([T,]x) L-∞ norm of x, that is the maximal absolute values of the components of x. Optional argument T is the floating-point type of the result

        • vcreate(x) yields a new variable instance similar to x. If x is an array, the element type of the result is a floating-point type.

        • vcopy!(dst,src) copies the contents of src into dst and returns dst.

        • vcopy(x) yields a fresh copy of the vector x.

        • vswap!(x,y) exchanges the contents of x and y (which must have the same type and size if they are arrays).

        • vfill!(x,α) sets all elements of x with the scalar value α and return x.

        • vzero!(x)fills x with zeros and returns it.

        • vscale!(dst,α,src) overwrites dst with α*src and returns dst. The convention is that, if α = 0, then dst is filled with zeros whatever the contents of src.

        • vscale!(x,α) and vscale!(α,x) overwrite x with α*x and returns x. The convention is that, if α = 0, then x is filled with zeros whatever its prior contents.

        • vscale(α,x) and vscale(x,α) yield a new vector whose elements are those of x multiplied by the scalar α.

        • vproduct!(dst,[sel,]x,y) overwrites dst with the elementwise multiplication of x by y. Optional argument sel is a selection of indices to consider.

        • vproduct(x,y) yields the elementwise multiplication of x by y.

        • vupdate!(y,[sel,]α,x) overwrites y with α*x + y and returns y. Optional argument sel is a selection of indices to which apply the operation (if an index is repeated, the operation will be performed several times at this location).

        • vcombine(α,x,β,y) yields the linear combination α*x or α*x + β*y.

        • vcombine!(dst,α,x,β,y) overwrites dst with the linear combination dst = α*x or dst = α*x + β*y and returns dst.

        Note that the names of these methods all start with a v (for vector) as the conventions used by these methods may be particular. For instance, compared to copy! and when applied to arrays, vcopy! imposes that the two arguments have exactly the same dimensions. Another example is the vdot method which has a slightly different semantics than Julia dot method.

        LazyAlgebra already provides implementations of these methods for Julia arrays with floating-point type elements. This implementation assumes that an array is a valid vector providing it has suitable type and dimensions.

        Implementing a new vector type

        To have a numerical method based on LazyAlgebra be applicable to a new given type of variables, it is sufficient to implement a subset of these basic methods specialized for this kind of variables.

        The various operations that should be implemented for a vector are:

        • compute the inner product of two vectors of the same kind (vdot(x,y) method);
        • create a vector of a given kind (vcreate(x) method);
        • copy a vector (vcopy!(dst,src));
        • fill a vector with a given value (vfill!(x,α) method);
        • exchange the contents of two vectors (vswap!(x,y) method);
        • linearly combine several vectors (vcombine!(dst,α,x,β,y) method).

        Derived methods are:

        • compute the Euclidean norm of a vector (vnorm2 method, based on vdot by default);
        • multiply a vector by a scalar: vscale!(dst,α,src) and/or vscale!(x,α) methods (based on vcombine! by default);
        • update a vector by a scaled step: vupdate!(y,α,x) method (based on vcombine! by default) and, for some constrained optimization methods, vupdate!(y,sel,α,x) method;
        • erase a vector: vzero!(x) method (based on vfill! by default);
        • vscale and vcopy methods are implemented with vcreate and respectivelyvscale! and vcopy!.

        Other methods which may be required by some packages:

        • compute the L-1 norm of a vector: vnorm1(x) method;
        • compute the L-∞ norm of a vector: vnorminf(x) method;

        Methods that must be implemented (V represent the vector type):

        vdot(x::V, y::V)
        vscale!(dst::V, alpha::Real, src::V) -> dst

        methods that may be implemented:

        vscale!(alpha::Real, x::V) -> x

        For mappings and linear operators (see Implementation of new mappings for details), implement:

        apply!(α::Scalar, P::Type{<:Operations}, A::Ta, x::Tx, β::Scalar, y::Ty) -> y

        and

        vcreate(P::Type{P}, A::Ta, x::Tx) -> y

        for Ta<:Mapping and the supported operations P<:Operations.