You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
Add more examples with different block structures + some minor improvements (#81)
* Add more examples with different block structures, and improve some minor things. Fixes#80 and #79.
* Try to fix reference warning
* Apply feedback, add clarification about block sizes
A block array is a partition of an array into blocks or subarrays, see [wikipedia](https://en.wikipedia.org/wiki/Block_matrix) for a more extensive description. This package has two purposes. Firstly, it defines an interface for an `AbstractBlockArray` block arrays that can be shared among types representing different types of block arrays. The advantage to this is that it provides a consistent API for block arrays.
7
+
A block array is a partition of an array into multiple blocks or subarrays, see [wikipedia](https://en.wikipedia.org/wiki/Block_matrix) for a more extensive description. This package has two purposes. Firstly, it defines an interface for an `AbstractBlockArray` block arrays that can be shared among types representing different types of block arrays. The advantage to this is that it provides a consistent API for block arrays.
8
+
9
+
Secondly, it also implements two concrete types of block arrays that follow the `AbstractBlockArray` interface. The type `BlockArray` stores each single block contiguously, by wrapping an `AbstractArray{<:AbstractArray{T,N},N}` to concatenate all blocks – the complete array is thus not stored contiguously. Conversely, a `PseudoBlockArray` stores the full matrix contiguously (by wrapping only one `AbstractArray{T, N}`) and only superimposes a block structure. This means that `BlockArray` supports fast non copying extraction and insertion of blocks, while `PseudoBlockArray` supports fast access to the full matrix to use in, for example, a linear solver.
10
+
11
+
12
+
## Terminology
13
+
14
+
We talk about an “a×b-blocked m×n block array”, if we have ``m \times n`` values arranged in ``a \times b`` blocks, like in the following example:
15
+
16
+
```julia
17
+
2×3-blocked 4×4 BlockArray{Float64,2}:
18
+
0.56609 │ 0.95429 │ 0.06884030.980771
19
+
0.203829 │ 0.138667 │ 0.02004180.0515364
20
+
──────────┼────────────┼──────────────────────
21
+
0.963832 │ 0.391176 │ 0.9257990.148993
22
+
0.18693 │ 0.838529 │ 0.8012360.793251
23
+
```
24
+
25
+
The dimension of arrays works the same as with standard Julia arrays; for example the following is a ``2 \times 2`` block vector:
26
+
27
+
```julia
28
+
2-blocked 4-element BlockArray{Float64,1}:
29
+
0.35609231970760424
30
+
0.7732179994849591
31
+
───────────────────
32
+
0.8455294223894625
33
+
0.04250653797187476
34
+
```
35
+
36
+
A block array layout is specified its _block sizes_ – a tuple of `AbstractArray{Int}`. The length of the tuple is equal to the dimension, the length of each block size array is the number of blocks in the corresponding dimension, and the sum of each block size is the scalar size in that dimension. For example, `BlockArray{Int}(undef, [2,2,2], [2,2,2], [2,2,2])` will produce a blocked cube (an `AbstractArray{Int, 3}`, i.e., 3 dimensions), consisting of 27 2×2×2 blocks (3 in each dimension) and 216 values (6 in each dimension).
8
37
9
-
Secondly, it also implements two different type of block arrays that follow the `AbstractBlockArray` interface. The type `BlockArray` stores each block contiguously while the type `PseudoBlockArray` stores the full matrix contiguously. This means that `BlockArray` supports fast non copying extraction and insertion of blocks while `PseudoBlockArray` supports fast access to the full matrix to use in in for example a linear solver.
Copy file name to clipboardExpand all lines: docs/src/man/blockarrays.md
+51-17Lines changed: 51 additions & 17 deletions
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -8,25 +8,51 @@ DocTestSetup = quote
8
8
end
9
9
```
10
10
11
+
## Creating `BlockArray`s from an array
11
12
12
-
## Creating uninitialized `BlockArrays`
13
+
An `AbstractArray` can be repacked into a `BlockArray` with `BlockArray(array, block_sizes...)`. The block sizes are each an `AbstractVector{Int}` which determines the size of the blocks in that dimension (so the sum of `block_sizes` in every dimension must match the size of `array` in that dimension).
13
14
14
-
A block array can be created with initialized blocks using the `BlockArray{T}(block_sizes)`
15
-
function. The block_sizes are each an `AbstractVector{Int}` which determines the size of the blocks in that dimension. We here create a `[1,2]×[3,2]` block matrix of `Float32`s:
A block array can be created with uninitialized values (but initialized blocks) using the
37
+
`BlockArray{T}(undef, block_sizes)` function. The `block_sizes` are each an `AbstractVector{Int}` which determines the size of the blocks in that dimension. We here create a block matrix of `Float32`s:
We can also any other user defined array type that supports `similar`.
25
51
52
+
26
53
## Creating `BlockArrays` with uninitialized blocks.
27
54
28
-
A `BlockArray` can be created with the blocks left uninitialized using the `BlockArray(undef, block_type, block_sizes...)` function.
29
-
The `block_type` should be an array type, it could for example be `Matrix{Float64}`. The block sizes are each an `AbstractVector{Int}` which determines the size of the blocks in that dimension. We here create a `[1,2]×[3,2]` block matrix of `Float32`s:
55
+
A `BlockArray` can be created with the blocks left uninitialized using the `BlockArray(undef_blocks[, block_type], block_sizes...)` function. We here create a `[1,2]×[3,2]` block matrix of `Float32`s:
We can also use a `SparseVector` or any other user defined array type by
41
-
specifying it as the second argument:
66
+
The `block_type` should be an array type. It specifies the internal block type, which defaults to an `Array` of the according dimension. We can also use a `SparseVector` or any other user defined array type:
Note that accessing an undefined block will throw an "access to undefined reference"-error.
53
-
54
-
## Setting and getting blocks and values
77
+
!!! warning
78
+
79
+
Note that accessing an undefined block will throw an "access to undefined reference"-error! If you create an array with undefined blocks, you _have_ to [initialize it block-wise](@ref setting_and_getting)); whole-array functions like `fill!` will not work:
0 commit comments