GitHub

Gridap.Arrays

Gridap.Arrays — Module

This module provides:

  • An extension of the AbstractArray interface in order to properly deal with mutable caches.
  • A mechanism to generate lazy arrays resulting from operations between arrays.
  • A collection of concrete implementations of AbstractArray.

The exported names in this module are:

source
Gridap.Arrays.Broadcasting — Type
Broadcasting(f)

Returns a mapping that represents the "broadcasted" version of the function f.

Example

using Gridap.Arrays

a = [3,2]
b = [2,1]

bm = Broadcasting(+)

c = evaluate(bm,a,b)

println(c)

# output
[5, 3]
source
Gridap.Arrays.CachedArray — Type
mutable struct CachedArray{T, N, A<:AbstractArray{T, N}} <: AbstractArray{T, N}

Type providing a re-sizable array.

The size of a CachedArray is changed via the setsize! function.

A CachedArray can be build with the constructors

using Gridap.Arrays
# Create an empty CachedArray
a = CachedArray(Float64,2)
# Resize to new shape (2,3)
setsize!(a,(2,3))
size(a)
# output
(2, 3)
source
Gridap.Arrays.CompressedArray — Type
struct CompressedArray{T,N,A,P} <: AbstractArray{T,N}
  values::A
  ptrs::P
end

Type representing an array with a reduced set of values. The array is represented by a short array of values, namely the field values, and a large array of indices, namely the field ptrs. The i-th component of the resulting array is defined as values[ptrs[i]]. The type parameters A, and P are restricted to be array types by the inner constructor of this struct.

source
Gridap.Arrays.CompressedArray — Method
CompressedArray(values::AbstractArray,ptrs::AbstractArray)

Creates a CompressedArray object by the given arrays of values and ptrs.

source
Gridap.Arrays.LazyArray — Type

Subtype of AbstractArray which is the result of lazy_map. It represents the result of lazy_mapping a Map to a set of arrays that contain the mapping arguments. This struct makes use of the cache provided by the mapping in order to compute its indices (thus allowing to prevent allocation). The array is lazy, i.e., the values are only computed on demand. It extends the AbstractArray API with two methods:

array_cache(a::AbstractArray) getindex!(cache,a::AbstractArray,i...)

source
Gridap.Arrays.Map — Type

Abstract type representing a function (mapping) that provides a cache and an in-place evaluation for performance. This is the type to be used in the lazy_map function.

Derived types must implement the following method:

and optionally these ones:

The mapping interface can be tested with the test_map function.

Note that most of the functionality implemented in terms of this interface relies in duck typing. That is, it is not strictly needed to work with types that inherit from Map. This is specially useful in order to accommodate existing types into this framework without the need to implement a wrapper type that inherits from Map. For instance, a default implementation is available for Function objects. However, we recommend that new types inherit from Map.

source
Gridap.Arrays.Operation — Type
Operation(op)

Returns the map that results after applying an operation f over a set of map(s) args. That is Operation(f)(args)(x...) is formally defined as f(map(a->a(x...),args)...).

Example

using Gridap.Arrays

fa(x) = x.*x
fb(x) = sqrt.(x)

x = collect(0:5)

fab = Operation(fa)(fb)
c = evaluate(fab,x)

println(c)

# output
[0.0, 1.0, 2.0, 3.0, 4.0, 5.0]
source
Gridap.Arrays.OperationMap — Type
OperationMap(f,args)

Returns a mapping that represents the result of applying the function f to the arguments in the tuple args. That is, OperationMap(f,args)(x...) is formally defined as f(map(a->a(x...),args)...)

source
Gridap.Arrays.PosNegPartition — Type

struct representing a binary partition of a range of indices

Using this allows one to do a number of important optimizations when working with PosNegReindex

source
Gridap.Arrays.SubVector — Type
struct SubVector{T,A<:AbstractVector{T}} <: AbstractVector{T}
  vector::A
  pini::Int
  pend::Int
end

SubVector is deprecated, use view instead.

source
Gridap.Arrays.Table — Type
 struct Table{T,Vd<:AbstractVector{T},Vp<:AbstractVector} <: AbstractVector{Vector{T}}
    data::Vd
    ptrs::Vp
 end

Type representing a list of lists (i.e., a table) in compressed format.

source
Gridap.Arrays.Table — Method
Table(a::AbstractArray{<:AbstractArray})

Build a table from a vector of vectors. If the inputs are multidimensional arrays instead of vectors, they are flattened.

source
Gridap.Arrays.array_cache — Method
array_cache(a::AbstractArray)

Returns a cache object to be used in the getindex! function. It defaults to

array_cache(a::T) where T = nothing

for types T such that uses_hash(T) == Val(false), and

function array_cache(a::T) where T
  hash = Dict{UInt,Any}()
  array_cache(hash,a)
end

for types T such that uses_hash(T) == Val(true), see the uses_hash function. In the later case, the type T should implement the following signature:

array_cache(hash::Dict,a::AbstractArray)

where we pass a dictionary (i.e., a hash table) in the first argument. This hash table can be used to test if the object a has already built a cache and re-use it as follows

id = objectid(a)
if haskey(hash,id)
  cache = hash[id] # Reuse cache
else
  cache = ... # Build a new cache depending on your needs
  hash[id] = cache # Register the cache in the hash table
end

This mechanism is needed, e.g., to re-use intermediate results in complex lazy operation trees. In multi-threading computations, a different hash table per thread has to be used in order to avoid race conditions.

source
Gridap.Arrays.evaluate! — Method
evaluate!(cache,f,x...)

Applies the mapping f at the arguments x... using the scratch data provided in the given cache object. The cache object is built with the return_cache function using arguments of the same type as in x. In general, the returned value y can share some part of its state with the cache object. If the result of two or more calls to this function need to be accessed simultaneously (e.g., in multi-threading), create and use several cache objects (e.g., one cache per thread).

source
Gridap.Arrays.evaluate — Method
evaluate(f,x...)

evaluates the mapping f at the arguments in x by creating a temporary cache internally. This functions is equivalent to

cache = return_cache(f,x...)
evaluate!(cache,f,x...)
source
Gridap.Arrays.getindex! — Method
getindex!(cache,a::AbstractArray,i...)

Returns the item of the array a associated with index i by (possibly) using the scratch data passed in the cache object.

It defaults to

getindex!(cache,a::AbstractArray,i...) = a[i...]

As for standard Julia arrays, the user needs to implement only one of the following signatures depending on the IndexStyle of the array.

getindex!(cache,a::AbstractArray,i::Integer)
getindex!(cache,a::AbstractArray{T,N},i::Vararg{Integer,N}) where {T,N}

Examples

Iterating over an array using the getindex! function

using Gridap.Arrays

a = collect(10:15)

cache = array_cache(a)
for i in eachindex(a)
  ai = getindex!(cache,a,i)
  println("$i -> $ai")
end

# output
1 -> 10
2 -> 11
3 -> 12
4 -> 13
5 -> 14
6 -> 15
source
Gridap.Arrays.lazy_map — Method
lazy_map(f,a::AbstractArray...) -> AbstractArray

Applies the Map (or Function) f to the entries of the arrays in a (see the definition of Map).

The resulting array r is such that r[i] equals to evaluate(f,ai...) where ai is the tuple containing the i-th entry of the arrays in a (see function evaluate for more details). In other words, the resulting array is numerically equivalent to:

map( (x...)->evaluate(f,x...), a...)

Examples

Using a function as mapping

using Gridap.Arrays

a = collect(0:5)
b = collect(10:15)

c = lazy_map(+,a,b)

println(c)

# output
[10, 12, 14, 16, 18, 20]

Using a user-defined mapping

using Gridap.Arrays
import Gridap.Arrays: evaluate!

a = collect(0:5)
b = collect(10:15)

struct MySum <: Map end

evaluate!(cache,::MySum,x,y) = x + y

k = MySum()

c = lazy_map(k,a,b)

println(c)

# output
[10, 12, 14, 16, 18, 20]
source
Gridap.Arrays.return_cache — Method
return_cache(f,x...)

Returns the cache needed to lazy_map mapping f with arguments of the same type as the objects in x. This function returns nothing by default, i.e., no cache.

source
Gridap.Arrays.return_type — Method
return_type(f,x...)

Returns the type of the result of calling mapping f with arguments of the types of the objects x.

source
Gridap.Arrays.setsize! — Method
setsize!(a, s)

Changes the size of the CachedArray a to the size described the the tuple s. After calling setsize!, the array can store uninitialized values.

source
Gridap.Arrays.test_array — Method
test_array(
  a::AbstractArray{T,N}, b::AbstractArray{S,N},cmp=(==)) where {T,S,N}

Checks if the entries in a and b are equal using the comparison function cmp. It also stresses the new methods added to the AbstractArray interface.

source
Gridap.Arrays.test_map — Method
test_map(y,f,x...;cmp=(==))

Function used to test if the mapping f has been implemented correctly. f is a Map sub-type, x is a tuple in the domain of the mapping and y is the expected result. Function cmp is used to compare the computed result with the expected one. The checks are done with the @test macro.

source
Gridap.Arrays.testargs — Method
testargs(f,x...)

The default implementation of this function is testargs(f,x...) = x. One can overload it in order to use lazy_map with 0-length array and maps with non-trivial domains.

source
Gridap.Arrays.testitem — Method
testitem(a::AbstractArray{T}) -> Any

Returns an arbitrary instance of eltype(a). The default returned value is the first entry in the array if length(a)>0 and testvalue(eltype(a)) if length(a)==0 See the testvalue function.

Examples

using Gridap.Arrays

a = collect(3:10)
ai = testitem(a)

b = Int[]
bi = testitem(b)

(ai, bi)

# output
(3, 0)
source
Gridap.Arrays.testvalue — Function
testvalue(::Type{T}) where T

Returns an arbitrary instance of type T. It defaults to zero(T) for non-array types and to an empty array for array types. It can be overloaded for new types T if zero(T) does not makes sense. This function is used to compute testitem for 0-length arrays.

source
Gridap.Arrays.uses_hash — Method
uses_hash(::Type{<:AbstractArray})

This function is used to specify if the type T uses the hash-based mechanism to reuse caches. It should return either Val(true) or Val(false). It defaults to

uses_hash(::Type{<:AbstractArray}) = Val(false)

Once this function is defined for the type T it can also be called on instances of T.

source