# 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.

## Warning about map and broadcasting

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.FillArrays`

— Module`FillArrays`

module to lazily represent matrices with a single value

`FillArrays.AbstractFill`

— Type`AbstractFill{T, N, Axes} <: AbstractArray{T, N}`

Supertype for lazy array types whose entries are all equal. Subtypes of `AbstractFill`

should implement `FillArrays.getindex_value`

to return the value of the entries.

`FillArrays.Falses`

— Type`FillArrays.Fill`

— Type`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
```

`FillArrays.Fill`

— Method`Fill(x, dims)`

construct lazy version of `fill(x, dims)`

`FillArrays.Fill`

— Method`Fill(x, dims...)`

construct lazy version of `fill(x, dims...)`

`FillArrays.OneElement`

— Type`OneElement(val, ind, axesorsize) <: AbstractArray`

Represents an array with the specified axes (if its a tuple of `AbstractUnitRange`

s) or size (if its a tuple of `Integer`

s), with a single entry set to `val`

and all others equal to zero, specified by `ind`

`.

`FillArrays.OneElement`

— Method`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.

`FillArrays.OneElement`

— Method`OneElement(ind::Int, n::Int)`

Creates a length `n`

vector where the `ind`

entry is equal to `1`

, and all other entries are zero.

`FillArrays.OneElement`

— Method`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.

`FillArrays.Ones`

— Type`Ones{T, N, Axes} <: AbstractFill{T, N, Axes}`

(lazy `ones`

with axes)

`FillArrays.Ones`

— Method`Ones{T}(dims...)`

construct lazy version of `ones(dims...)`

`FillArrays.Trues`

— Type`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
```

`FillArrays.Zeros`

— Type`Zeros{T, N, Axes} <: AbstractFill{T, N, Axes}`

(lazy `zeros`

with axes)

`FillArrays.Zeros`

— Method`Zeros{T}(dims...)`

construct lazy version of `zeros(dims...)`

`FillArrays.fillsimilar`

— Method`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.

`FillArrays.getindex_value`

— Function`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
```

`FillArrays.getindex_value`

— Method`getindex_value(A::OneElement)`

Return the only non-zero value stored in `A`

.

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
```

`FillArrays.nzind`

— Method`nzind(A::OneElement{T,N}) -> CartesianIndex{N}`

Return the index where `A`

contains a non-zero value.

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
```

`FillArrays.unique_value`

— Method`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.