ArrayIndex{N}

Subtypes of ArrayIndex represent series of transformations for a provided index to some buffer which is typically accomplished with square brackets (e.g., buffer[index[inds...]]). The only behavior that is required of a subtype of ArrayIndex is the ability to transform individual index elements (i.e. not collections). This does not guarantee bounds checking or the ability to iterate (although additional functionallity may be provided for specific types).

GetIndex(buffer) = GetIndex{true}(buffer)
GetIndex{check}(buffer) -> g

Wraps an indexable buffer in a function type that is indexed when called, so that g(inds..) is equivalent to buffer[inds...]. If check is false, then all indexing arguments are considered in-bounds. The default value for check is true, requiring bounds checking for each index.

See also SetIndex!

!!! Warning Passing false as check may result in incorrect results/crashes/corruption for out-of-bounds indices, similar to inappropriate use of @inbounds. The user is responsible for ensuring this is correctly used.

Examples

julia> ArrayInterfaceCore.GetIndex(1:10)(3)
3

julia> ArrayInterfaceCore.GetIndex{false}(1:10)(11)  # shouldn't be in-bounds
11

IndicesInfo{N}(inds::Tuple) -> IndicesInfo{N}(typeof(inds))
IndicesInfo{N}(T::Type{<:Tuple}) -> IndicesInfo{N,pdims,cdims}()
IndicesInfo(inds::Tuple) -> IndicesInfo(typeof(inds))
IndicesInfo(T::Type{<:Tuple}) -> IndicesInfo{maximum(pdims),pdims,cdims}()

Maps a tuple of indices to N dimensions. The resulting pdims is a tuple where each field in inds (or field type in T) corresponds to the parent dimensions accessed. cdims similarly maps indices to the resulting child array produced after indexing with inds. If N is not provided then it is assumed that all indices are represented by parent dimensions and there are no trailing dimensions accessed. These may be accessed by through parentdims(info::IndicesInfo) and childdims(info::IndicesInfo). If N is not provided, it is assumed that no indices are accessing trailing dimensions (which are represented as 0 in parentdims(info)[index_position]).

The the fields and types of IndicesInfo should not be accessed directly. Instead parentdims, childdims, ndims_index, and ndims_shape should be used to extract relevant information.

Examples

julia> using ArrayInterfaceCore: IndicesInfo, parentdims, childdims, ndims_index, ndims_shape

julia> info = IndicesInfo{5}(typeof((:,[CartesianIndex(1,1),CartesianIndex(1,1)], 1, ones(Int, 2, 2), :, 1)));

julia> parentdims(info)  # the last two indices access trailing dimensions
(1, (2, 3), 4, 5, 0, 0)

julia> childdims(info)
(1, 2, 0, (3, 4), 5, 0)

julia> childdims(info)[3]  # index 3 accesses a parent dimension but is dropped in the child array
0

julia> ndims_index(info)
5

julia> ndims_shape(info)
5

julia> info = IndicesInfo(typeof((:,[CartesianIndex(1,1),CartesianIndex(1,1)], 1, ones(Int, 2, 2), :, 1)));

julia> parentdims(info)  # assumed no trailing dimensions
(1, (2, 3), 4, 5, 6, 7)

julia> ndims_index(info)  # assumed no trailing dimensions
7

SetIndex!(buffer) = SetIndex!{true}(buffer)
SetIndex!{check}(buffer) -> g

Wraps an indexable buffer in a function type that sets a value at an index when called, so that g(val, inds..) is equivalent to setindex!(buffer, val, inds...). If check is false, then all indexing arguments are considered in-bounds. The default value for check is true, requiring bounds checking for each index.

See also GetIndex

!!! Warning Passing false as check may result in incorrect results/crashes/corruption for out-of-bounds indices, similar to inappropriate use of @inbounds. The user is responsible for ensuring this is correctly used.

Examples

julia> x = [1, 2, 3, 4];

julia> ArrayInterface.SetIndex!(x)(10, 2);

julia> x[2]
10

allowed_getindex(x,i...)

A scalar getindex which is always allowed.

allowed_setindex!(x,v,i...)

A scalar setindex! which is always allowed.

aos_to_soa(x)

Converts an array of structs formulation to a struct of array.

buffer(x)

Return the buffer data that x points to. Unlike parent(x::AbstractArray), buffer(x) may not return another array type.

can_avx(f) -> Bool

Returns true if the function f is guaranteed to be compatible with LoopVectorization.@avx for supported element and array types. While a return value of false does not indicate the function isn't supported, this allows a library to conservatively apply @avx only when it is known to be safe to do so.

function mymap!(f, y, args...)
    if can_avx(f)
        @avx @. y = f(args...)
    else
        @. y = f(args...)
    end
end

can_change_size(::Type{T}) -> Bool

Returns true if the Base.size of T can change, in which case operations such as pop! and popfirst! are available for collections of type T.

can_setindex(::Type{T}) -> Bool

Query whether a type can use setindex!.

childdims(::IndicesInfo) -> Tuple

Returns the child dimension mapping from IndicesInfo.

See also: IndicesInfo, parentdims

defines_strides(::Type{T}) -> Bool

Is strides(::T) defined? It is assumed that types returning true also return a valid pointer on pointer(::T).

device(::Type{T}) -> AbstractDevice

Indicates the most efficient way to access elements from the collection in low-level code. For GPUArrays, will return ArrayInterface.GPU(). For AbstractArray supporting a pointer method, returns ArrayInterface.CPUPointer(). For other AbstractArrays and Tuples, returns ArrayInterface.CPUIndex(). Otherwise, returns nothing.

fast_matrix_colors(A)

Query whether a matrix has a fast algorithm for getting the structural colors of the matrix.

fast_scalar_indexing(::Type{T}) -> Bool

Query whether an array type has fast scalar indexing.

findstructralnz(x::AbstractArray)

Return: (I,J) #indexable objects Find sparsity pattern of special matrices, the same as the first two elements of findnz(::SparseMatrixCSC).

ArrayInterfaceCore.flatten_tuples(t::Tuple) -> Tuple

Flattens any field of t that is a tuple. Only direct fields of t may be flattened.

Examples

julia> ArrayInterfaceCore.flatten_tuples((1, ()))
(1,)

julia> ArrayInterfaceCore.flatten_tuples((1, (2, 3)))
(1, 2, 3)

julia> ArrayInterfaceCore.flatten_tuples((1, (2, (3,))))
(1, 2, (3,))

has_sparsestruct(x::AbstractArray) -> Bool

Determine whether findstructralnz accepts the parameter x.

indices_do_not_alias(::Type{T<:AbstractArray}) -> Bool

Is it safe to ivdep arrays of type T? That is, would it be safe to write to an array of type T in parallel? Examples where this is not true are BitArrays or view(rand(6), [1,2,3,1,2,3]). That is, it is not safe whenever different indices may alias the same memory.

instances_do_not_alias(::Type{T}) -> Bool

Is it safe to ivdep arrays containing elements of type T? That is, would it be safe to write to an array full of T in parallel? This is not true for mutable structs in general, where editing one index could edit other indices. That is, it is not safe when different instances may alias the same memory.

is_forwarding_wrapper(::Type{T}) -> Bool

Returns true if the type T wraps another data type and does not alter any of its standard interface. For example, if T were an array then its size, indices, and elements would all be equivalent to its wrapped data.

is_splat_index(::Type{T}) -> Bool

Returns static(true) if T is a type that splats across multiple dimensions.

ismutable(::Type{T}) -> Bool

Query whether instances of type T are mutable or not, see https://github.com/JuliaDiffEq/RecursiveArrayTools.jl/issues/19.

issingular(A::AbstractMatrix) -> Bool

Determine whether a given abstract matrix is singular.

isstructured(::Type{T}) -> Bool

Query whether a type is a representation of a structured matrix.

known_first(::Type{T}) -> Union{Int,Nothing}

If first of an instance of type T is known at compile time, return it. Otherwise, return nothing.

julia> ArrayInterface.known_first(typeof(1:4))
nothing

julia> ArrayInterface.known_first(typeof(Base.OneTo(4)))
1

known_last(::Type{T}) -> Union{Int,Nothing}

If last of an instance of type T is known at compile time, return it. Otherwise, return nothing.

julia> ArrayInterfaceCore.known_last(typeof(1:4))
nothing

julia> ArrayInterfaceCore.known_first(typeof(static(1):static(4)))
4

known_step(::Type{T}) -> Union{Int,Nothing}

If step of an instance of type T is known at compile time, return it. Otherwise, return nothing.

julia> ArrayInterface.known_step(typeof(1:2:8))
nothing

julia> ArrayInterface.known_step(typeof(1:4))
1

lu_instance(a::Any) -> lu(a, check=false)

Returns the number.

lu_instance(a::Number) -> a

Returns the number.

luinstance(A) -> lufactorization_instance

Returns an instance of the LU factorization object with the correct type cheaply.

ArrayInterfaceCore.map_tuple_type(f, T::Type{<:Tuple})

Returns tuple where each field corresponds to the field type of T modified by the function f.

Examples

julia> ArrayInterfaceCore.map_tuple_type(sqrt, Tuple{1,4,16})
(1.0, 2.0, 4.0)

matrix_colors(A::Union{Array,UpperTriangular,LowerTriangular})

The color vector for dense matrix and triangular matrix is simply [1,2,3,..., Base.size(A,2)].

ndims_index(::Type{I}) -> Int

Returns the number of dimensions that an instance of I indexes into. If this method is not explicitly defined, then 1 is returned.

See also ndims_shape

Examples

julia> ArrayInterfaceCore.ndims_index(Int)
1

julia> ArrayInterfaceCore.ndims_index(CartesianIndex(1, 2, 3))
3

julia> ArrayInterfaceCore.ndims_index([CartesianIndex(1, 2), CartesianIndex(1, 3)])
2

ndims_shape(::Type{I}) -> Union{Int,Tuple{Vararg{Int}}}

Returns the number of dimension that are represented in the shape of the returned array when indexing with an instance of I.

See also ndims_index

Examples

```julia julia> ArrayInterfaceCore.ndims_shape([CartesianIndex(1, 1), CartesianIndex(1, 2)]) 1

julia> ndims(CartesianIndices((2,2))[[CartesianIndex(1, 1), CartesianIndex(1, 2)]]) 1

parent_type(::Type{T}) -> Type

Returns the parent array that type T wraps.

parentdims(::IndicesInfo) -> Tuple

Returns the parent dimension mapping from IndicesInfo.

See also: IndicesInfo, childdims

promote_eltype(::Type{<:AbstractArray{T,N}}, ::Type{T2})

Computes the type of the AbstractArray that results from the element type changing to promote_type(T,T2).

Note that no generic fallback is given.

restructure(x,y)

Restructures the object y into a shape of x, keeping its values intact. For simple objects like an Array, this simply amounts to a reshape. However, for more complex objects such as an ArrayPartition, not all of the structural information is adequately contained in the type for standard tools to work. In these cases, restructure gives a way to convert for example an Array into a matching ArrayPartition.

safevec(v)

It is a form of vec which is safe for all values in vector spaces, i.e., if it is already a vector, like an AbstractVector or Number, it will return said AbstractVector or Number.

undefmatrix(u::AbstractVector)

Creates the matrix version of u with possibly undefined values. Note that this is unique because similar(u,length(u),length(u)) returns a mutable type, so it is not type-matching, while fill(zero(eltype(u)),length(u),length(u)) doesn't match the array type, i.e., you'll get a CPU array from a GPU array. The generic fallback is u .* u', which works on a surprising number of types, but can be broken with weird (recursive) broadcast overloads. For higher-order tensors, this returns the matrix linear operator type which acts on the vec of the array.

zeromatrix(u::AbstractVector)

Creates the zero'd matrix version of u. Note that this is unique because similar(u,length(u),length(u)) returns a mutable type, so it is not type-matching, while fill(zero(eltype(u)),length(u),length(u)) doesn't match the array type, i.e., you'll get a CPU array from a GPU array. The generic fallback is u .* u' .* false, which works on a surprising number of types, but can be broken with weird (recursive) broadcast overloads. For higher-order tensors, this returns the matrix linear operator type which acts on the vec of the array.