# Introduction

FillArrays allows one to lazily represent arrays filled with a single entry, as well as identity matrices. This package exports the following types: Eye, Fill, Ones, Zeros, Trues and Falses. Among these, the FillArrays.AbstractFill types represent lazy versions of dense arrays where all elements have the same value. Eye, on the other hand, represents a Diagonal matrix with ones along the principal diagonal. All these types accept sizes or axes as arguments, so one may create arrays of arbitrary sizes and dimensions. A rectangular Eye matrix may be constructed analogously, by passing the size of the matrix to Eye.

## Quick Start

Create a 2x2 zero matrix

julia> z = Zeros(2,2)
2×2 Zeros{Float64}

julia> Array(z)
2×2 Matrix{Float64}:
0.0  0.0
0.0  0.0

We may specify the element type as

julia> z = Zeros{Int}(2,2)
2×2 Zeros{Int64}

julia> Array(z)
2×2 Matrix{Int64}:
0  0
0  0

We may create arrays with any number of dimensions. A Vector of ones may be created as

julia> a = Ones(4)
4-element Ones{Float64}

julia> Array(a)
4-element Vector{Float64}:
1.0
1.0
1.0
1.0

Similarly, a 2x3x2 array, where every element is equal to 10, may be created as

julia> f = Fill(10, 2,3,2)
2×3×2 Fill{Int64}, with entries equal to 10

julia> Array(f)
2×3×2 Array{Int64, 3}:
[:, :, 1] =
10  10  10
10  10  10

[:, :, 2] =
10  10  10
10  10  10

The elements of a Fill array don't need to be restricted to numbers, and these may be any Julia object. For example, we may construct an array of strings using

julia> f = Fill("hello", 2,5)
2×5 Fill{String}, with entries equal to "hello"

julia> Array(f)
2×5 Matrix{String}:
"hello"  "hello"  "hello"  "hello"  "hello"
"hello"  "hello"  "hello"  "hello"  "hello"

### Conversion to a sparse form

These Fill array types may be converted to sparse arrays as well, which might be useful in certain cases

julia> using SparseArrays

julia> z = Zeros{Int}(2,2)
2×2 Zeros{Int64}

julia> sparse(z)
2×2 SparseMatrixCSC{Int64, Int64} with 0 stored entries:
⋅  ⋅
⋅  ⋅

Note, however, that most Fill arrays are not sparse, despite being lazily evaluated.

These types have methods that perform many operations efficiently, including elementary algebra operations like multiplication and addition, as well as linear algebra methods like norm, adjoint, transpose and vec.

### Custom axes

The various Fill equivalents all support offset or custom axes, where instead of the size, one may pass a Tuple of axes. So, for example, one may use a SOneTo axis from StaticArrays.jl to construct a statically sized Fill.

julia> using StaticArrays

julia> f = Fill(2, (SOneTo(4), SOneTo(5)))
4×5 Fill{Int64, 2, Tuple{SOneTo{4}, SOneTo{5}}} with indices SOneTo(4)×SOneTo(5), with entries equal to 2

The size of such an array would be known at compile time, permitting compiler optimizations.

We may construct infinite fill arrays by passing infinite-sized axes, see InfiniteArrays.jl.

### Other lazy types

A lazy representation of an identity matrix may be constructured using Eye. For example, a 4x4 identity matrix with Float32 elements may be constructed as

julia> id = Eye{Float32}(4)
4×4 Eye{Float32}

julia> Array(id)
4×4 Matrix{Float32}:
1.0  0.0  0.0  0.0
0.0  1.0  0.0  0.0
0.0  0.0  1.0  0.0
0.0  0.0  0.0  1.0

julia> sparse(id)
4×4 SparseMatrixCSC{Float32, Int64} with 4 stored entries:
1.0   ⋅    ⋅    ⋅
⋅   1.0   ⋅    ⋅
⋅    ⋅   1.0   ⋅
⋅    ⋅    ⋅   1.0

julia> idrect = Eye(2,5) # rectangular matrix
2×5 Eye{Float64}

julia> sparse(idrect)
2×5 SparseMatrixCSC{Float64, Int64} with 2 stored entries:
1.0   ⋅    ⋅    ⋅    ⋅
⋅   1.0   ⋅    ⋅    ⋅

Note that an Eye actually returns a Diagonal matrix, where the diagonal is a Ones vector.

Broadcasting operations, and map and mapreduce, are also done efficiently, by evaluating the function being applied only once:

julia> map(sqrt, Fill(4, 2,5))  # one evaluation, not 10, to save time
2×5 Fill{Float64}, with entries equal to 2.0

julia> println.(Fill(pi, 10))
π
10-element Fill{Nothing}, with entries equal to nothing

Notice that this will only match the behaviour of a dense matrix from fill if the function is pure. And that this shortcut is taken before any other fused broadcast:

julia> map(_ -> rand(), Fill("pi", 2,5))  # not a pure function!
2×5 Fill{Float64}, with entries equal to 0.32597672886359486

julia> map(_ -> rand(), fill("4", 2,5))  # 10 evaluations, different answer!
2×5 Matrix{Float64}:
0.549051  0.894245  0.394255  0.795547  0.748415
0.218587  0.353112  0.953125  0.49425   0.578232

julia> ones(1,5) .+ (_ -> rand()).(Fill("vec", 2))  # Fill broadcast is done first
2×5 Matrix{Float64}:
1.72794  1.72794  1.72794  1.72794  1.72794
1.72794  1.72794  1.72794  1.72794  1.72794

julia> ones(1,5) .+ (_ -> rand()).(fill("vec", 2))  # fused, 10 evaluations
2×5 Matrix{Float64}:
1.00745  1.43924  1.95674  1.99667  1.11008
1.19938  1.68253  1.64786  1.74919  1.49138

# API

FillArrays.FillType
Fill{T, N, Axes} where {T,N,Axes<:Tuple{Vararg{AbstractUnitRange,N}}}

A lazy representation of an array of dimension N whose entries are all equal to a constant of type T, with axes of type Axes. Typically created by Fill or Zeros or Ones

Examples

julia> Fill(7, (2,3))
2×3 Fill{Int64}, with entries equal to 7

julia> Fill{Float64, 1, Tuple{UnitRange{Int64}}}(7.0, (1:2,))
2-element Fill{Float64, 1, Tuple{UnitRange{Int64}}} with indices 1:2, with entries equal to 7.0
source
FillArrays.OneElementType
OneElement(val, ind, axesorsize) <: AbstractArray

Represents an array with the specified axes (if its a tuple of AbstractUnitRanges) or size (if its a tuple of Integers), with a single entry set to val and all others equal to zero, specified by ind.

source
FillArrays.OneElementMethod
OneElement(val, ind::Int, n::Int)

Creates a length n vector where the ind entry is equal to val, and all other entries are zero.

source
FillArrays.OneElementMethod
OneElement(ind::Int, n::Int)

Creates a length n vector where the ind entry is equal to 1, and all other entries are zero.

source
FillArrays.OneElementMethod
OneElement{T}(val, ind::Int, n::Int)

Creates a length n vector where the ind entry is equal to one(T), and all other entries are zero.

source
FillArrays.TruesType
Trues = Ones{Bool, N, Axes} where {N, Axes}

Lazy version of trues with axes. Typically created using Trues(dims) or Trues(dims...)

Example

julia> T = Trues(1,3)
1×3 Ones{Bool}

julia> Array(T)
1×3 Matrix{Bool}:
1  1  1
source
FillArrays.fillsimilarMethod
fillsimilar(a::AbstractFill, axes...)

creates a fill object that has the same fill value as a but with the specified axes. For example, if a isa Zeros then so is the returned object.

source
FillArrays.getindex_valueFunction
FillArrays.getindex_value(F::AbstractFill)

Return the value that F is filled with.

Examples

julia> f = Ones(3);

julia> FillArrays.getindex_value(f)
1.0

julia> g = Fill(2, 10);

julia> FillArrays.getindex_value(g)
2
source
FillArrays.getindex_valueMethod
getindex_value(A::OneElement)

Return the only non-zero value stored in A.

Note

If the index at which the value is stored doesn't lie within the valid indices of A, then this returns zero(eltype(A)).

Examples

julia> A = OneElement(2, 3)
3-element OneElement{Int64, 1, Tuple{Int64}, Tuple{Base.OneTo{Int64}}}:
⋅
1
⋅

julia> FillArrays.getindex_value(A)
1
source
FillArrays.nzindMethod
nzind(A::OneElement{T,N}) -> CartesianIndex{N}

Return the index where A contains a non-zero value.

Note

The indices are not guaranteed to lie within the valid index bounds for A, and if FillArrays.nzind(A) ∉ CartesianIndices(A) then all(iszero, A). On the other hand, if FillArrays.nzind(A) in CartesianIndices(A) then A[FillArrays.nzind(A)] == FillArrays.getindex_value(A)

Examples

julia> A = OneElement(2, (1,2), (2,2))
2×2 OneElement{Int64, 2, Tuple{Int64, Int64}, Tuple{Base.OneTo{Int64}, Base.OneTo{Int64}}}:
⋅  2
⋅  ⋅

julia> FillArrays.nzind(A)
CartesianIndex(1, 2)

julia> A[FillArrays.nzind(A)]
2
source
FillArrays.unique_valueMethod
unique_value(arr::AbstractArray)

Return only(unique(arr)) without intermediate allocations. Throws an error if arr` does not contain one and only one unique value.

source