StructuredArrays is a small Julia package which provides multi-dimensional
arrays behaving like regular arrays but whose elements have the same given value or are
computed by applying a given function to their indices. The main advantage of such arrays
is that they are very light in terms of memory: their storage requirement is O(1)
whatever their size instead of O(n) for an ordinary array of n elements.
Note that StructuredArrays has a different purpose than
StructArrays which is designed for
arrays whose elements are struct.
All elements of a uniform array have the same value. A uniform array thus require to only
store this value and the dimensions (or the axes) of the array. In addition, some
operations (e.g., minimum, maximum, extrema, all, any, sum, prod, count,
findmin, findmax, reverse, or unique) may be implemented so as to be very fast for
uniform arrays.
To build a uniform array, call:
A = UniformArray(val, args...)which yields an array A behaving as a read-only array whose values are all val and
whose axes are defined by args.... Each of args... define an array axis and can be an
integer for a 1-based index or an integer-valued unit step range. It is thus possible to
have offset axes as in the
OffsetArrays package.
Uniform arrays implement conventional linear indexing: A[i] yields val for all linear
indices i in the range 1:length(A).
The statement A[i] = x is however not implemented because uniform arrays are considered
as read-only. You may call MutableUniformArray(val,dims) to create a mutable uniform
array. For example:
B = MutableUniformArray(val, args...)For B, the statement B[i] = x is allowed to change the value of all the elements of
B provided index i represents all possible indices in B. Typically B[:] = x or
B[1:end] = x are accepted but not B[1] = x, unless B has a single element.
Apart from all values being the same, uniform arrays behave like ordinary Julia arrays.
When calling a uniform array constructor, the element type T and the number of
dimensions N may be specified. This is most useful for T to enforce a given element
type. By default, T = typeof(val) is assumed. For example:
A = UniformArray{T}(val, args...)
B = MutableUniformArray{T,N}(val, args...)A fast uniform array is like an immutable uniform array but with the value of all elements being part of the signature so that this value is known at compile time. To build such an array, call one of:
A = FastUniformArray(val, args...)
A = FastUniformArray{T}(val, args...)
A = FastUniformArray{T,N}(val, args...)The values of the elements of a structured array are computed on the fly as a function of their indices. To build such an array, call:
A = StructuredArray(func, args...)which yields a read-only array A whose values at index i are computed as func(i) and
whose axes are defined by args.... In other words, A[i] yields func(i).
An optional leading argument S may be used to specify another index style than the
default IndexCartesian:
A = StructuredArray(S, func, args...)where S may be a sub-type of IndexStyle or an instance of such a sub-type. If S is
IndexCartesian (the default), the function func will be called with N integer
arguments, a Vararg{Int,N}, N being the number of dimensions. If S is IndexLinear,
the function func will be called with a single integer argument, an Int.
A structured array can be used to specify the location of structural non-zeros in a sparse
matrix. For instance, the structure of a lower triangular matrix of size m×n could be
given by:
StructuredArray((i,j) -> (i ≥ j), m, n)but with a constant small storage requirement whatever the size of the matrix.
Although the callable object func may not be a pure function, its return type shall be
stable and structured arrays are considered as immutable in the sense that a statement
like A[i] = x is not implemented. The type, say, T of the elements of structured array
is inferred by applying func to the unit index or may be explicitly specified:
StructuredArray{T}(S, func, dims)where, if omitted, S = IndexCartesian is assumed. The StructuredArray constructor also
supports the number of dimensions N and the indexing style S as optional type
parameters. The two following examples are equivalent:
A = StructuredArray{T,N}(S, func, args...)
A = StructuredArray{T,N,S}(func, args...)