From 2a35639c4937d8bd36f8769453ff3386804787c3 Mon Sep 17 00:00:00 2001 From: Martin Kunz Date: Thu, 10 Apr 2025 10:48:24 +0200 Subject: [PATCH 1/3] feat(docs): Imitate the standard library docs strings for AbstractArray --- src/abstractblockarray.jl | 32 +++++++++++++++++++------------- 1 file changed, 19 insertions(+), 13 deletions(-) diff --git a/src/abstractblockarray.jl b/src/abstractblockarray.jl index eceb4023..faf58cd5 100644 --- a/src/abstractblockarray.jl +++ b/src/abstractblockarray.jl @@ -3,23 +3,29 @@ #################################### """ - abstract AbstractBlockArray{T, N} <: AbstractArray{T, N} - -The abstract type that represents a blocked array. Types that implement -the `AbstractBlockArray` interface should subtype from this type. - -** Typealiases ** + AbstractBlockArray{T, N} <: AbstractArray{T, N} +Supertype for `N`-dimensional block arrays with elements of type `T`. [`BlockedArray`](@ref), [`BlockArray`](@ref) and other types are subtypes of this. See the manual section on the +the `AbstractBlockArray` interface. +""" +abstract type AbstractBlockArray{T,N} <: LayoutArray{T,N} end -* `AbstractBlockMatrix{T}` -> `AbstractBlockArray{T, 2}` +""" + AbstractBlockMatrix{T} +Supertype for two-dimensional block arrays with elements of type `T`. Alias for [`AbstractBlockArray{T,2}`](@ref). +""" +const AbstractBlockMatrix{T} = AbstractBlockArray{T,2} -* `AbstractBlockVector{T}` -> `AbstractBlockArray{T, 1}` +""" + AbstractBlockVector{T} +Supertype for one-dimensional block arrays with elements of type `T`. Alias for [`AbstractBlockArray{T,1}`](@ref). +""" +const AbstractBlockVector{T} = AbstractBlockArray{T,1} -* `AbstractBlockVecOrMat{T}` -> `Union{AbstractBlockMatrix{T}, AbstractBlockVector{T}}` """ -abstract type AbstractBlockArray{T, N} <: LayoutArray{T, N} end -const AbstractBlockMatrix{T} = AbstractBlockArray{T, 2} -const AbstractBlockVector{T} = AbstractBlockArray{T, 1} -const AbstractBlockVecOrMat{T} = Union{AbstractBlockMatrix{T}, AbstractBlockVector{T}} + AbstractVecOrMat{T} +Union type of [`AbstractBlockMatrix`](@ref) and [`AbstractBlockVector`](@ref). +""" +const AbstractBlockVecOrMat{T} = Union{AbstractBlockMatrix{T},AbstractBlockVector{T}} block2string(b, s) = string(join(map(string,b), '×'), "-blocked ", Base.dims2string(s)) _block_summary(a) = string(block2string(blocksize(a), size(a)), " ", typeof(a)) From 10b8a9f7d86e8bf867994e9e8f6a2bafae4d6640 Mon Sep 17 00:00:00 2001 From: Martin Kunz Date: Thu, 10 Apr 2025 10:49:31 +0200 Subject: [PATCH 2/3] feat(docs): Add documentation anchors in the index page --- docs/src/index.md | 4 ++-- docs/src/man/abstractblockarrayinterface.md | 2 +- 2 files changed, 3 insertions(+), 3 deletions(-) diff --git a/docs/src/index.md b/docs/src/index.md index 075b6069..7772aee8 100644 --- a/docs/src/index.md +++ b/docs/src/index.md @@ -4,9 +4,9 @@ [![Build Status](https://travis-ci.org/JuliaArrays/BlockArrays.jl.svg?branch=master)](https://travis-ci.org/JuliaArrays/BlockArrays.jl) [![codecov](https://codecov.io/gh/JuliaArrays/BlockArrays.jl/branch/master/graph/badge.svg)](https://codecov.io/gh/JuliaArrays/BlockArrays.jl) -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. +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`](@ref) 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. -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 `BlockedArray` 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 `BlockedArray` supports fast access to the full matrix to use in, for example, a linear solver. +Secondly, it also implements two concrete types of block arrays that follow [`AbstractBlockArray` interface](@ref abstract_block_array_interface). The type [`BlockArray`](@ref) 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 [`BlockedArray`](@ref) 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 `BlockedArray` supports fast access to the full matrix to use in, for example, a linear solver. ## Terminology diff --git a/docs/src/man/abstractblockarrayinterface.md b/docs/src/man/abstractblockarrayinterface.md index 33f347ad..b7079562 100644 --- a/docs/src/man/abstractblockarrayinterface.md +++ b/docs/src/man/abstractblockarrayinterface.md @@ -14,7 +14,7 @@ the block axis interface. | `findblock(A, k)` | return the block that contains the `k`th entry of `A` -# The `AbstractBlockArray` interface +# [The `AbstractBlockArray` interface](@id abstract_block_array_interface) An arrays block structure is inferred from an axes, and therefore every array is in some sense already a block array: From 79bf53052c85b6a46fcb86ef1c504e5129d25b55 Mon Sep 17 00:00:00 2001 From: Martin Kunz Date: Thu, 10 Apr 2025 10:50:49 +0200 Subject: [PATCH 3/3] chore(docs): Format tables and fix column headers --- docs/src/man/abstractblockarrayinterface.md | 20 +++++++++----------- 1 file changed, 9 insertions(+), 11 deletions(-) diff --git a/docs/src/man/abstractblockarrayinterface.md b/docs/src/man/abstractblockarrayinterface.md index b7079562..83f3f0b9 100644 --- a/docs/src/man/abstractblockarrayinterface.md +++ b/docs/src/man/abstractblockarrayinterface.md @@ -6,13 +6,12 @@ are typically `BlockedOneTo`s, but may also be standard and non-blocked `Abstrac the block axis interface. -| Methods to implement | Brief description | -| :---------------------- | :---------------- | -| `blockaxes(A)` | A one-tuple returning a range of blocks specifying the block structure | -| `getindex(A, K::Block{1})` | return a unit range of indices in the specified block | -| `blocklasts(A)` | Returns the last index of each block | -| `findblock(A, k)` | return the block that contains the `k`th entry of `A` - +| Methods to implement | Brief description | +| :------------------------- | :--------------------------------------------------------------------- | +| `blockaxes(A)` | A one-tuple returning a range of blocks specifying the block structure | +| `getindex(A, K::Block{1})` | Returns a unit range of indices in the specified block | +| `blocklasts(A)` | Returns the last index of each block | +| `findblock(A, k)` | Returns the block that contains the `k`th entry of `A` | # [The `AbstractBlockArray` interface](@id abstract_block_array_interface) @@ -37,10 +36,9 @@ julia> A[Block(1,1)] ``` It is possible to override additional functions to improve speed, however. -| Methods to implement | Brief description | -| :---------------------- | :---------------- | -| **Optional methods** | -| `BlockArrays.viewblock(A, i::Block)` | Specialised non-allocating `X[Block(i...)]`, blocked indexing | +| Optional methods | Default definition | Brief description | +| :----------------------------------- | :------------------------------------------------- | :------------------------------------------------------------ | +| `BlockArrays.viewblock(A, i::Block)` | defined in terms `Base.view` and the block indices | Specialised non-allocating `X[Block(i...)]`, blocked indexing | For a more thorough description of the methods see the public interface documentation.