docs + interface (#6)

Author: KristofferC

.gitignore

@@ -1,3 +1,5 @@
 *.jl.cov
 *.jl.*.cov
 *.jl.mem
+docs/build/
+docs/site/

.travis.yml

@@ -9,8 +9,10 @@ notifications:
   email: false
 # uncomment the following lines to override the default test script
 script:
-    - if [[ -a .git/shallow ]]; then git fetch --unshallow; fi
-    - julia -e 'Pkg.clone(pwd()); Pkg.test("BlockArrays"; coverage=true)'
+  - if [[ -a .git/shallow ]]; then git fetch --unshallow; fi
+  - julia -e 'Pkg.clone(pwd()); Pkg.test("BlockArrays"; coverage=true)'
 
 after_success:
-- julia -e 'cd(Pkg.dir("BlockArrays")); Pkg.add("Coverage"); using Coverage; Codecov.submit(process_folder())'
+  - julia -e 'cd(Pkg.dir("BlockArrays")); Pkg.add("Coverage"); using Coverage; Codecov.submit(process_folder())'
+  - julia -e 'Pkg.clone("https://github.com/MichaelHatherly/Documenter.jl")'
+  - julia -e 'cd(Pkg.dir("BlockArrays")); include(joinpath("docs", "make.jl"))'

README.md

@@ -2,155 +2,17 @@
 
 [![Build Status](https://travis-ci.org/KristofferC/BlockArrays.jl.svg?branch=master)](https://travis-ci.org/KristofferC/BlockArrays.jl) [![codecov](https://codecov.io/gh/KristofferC/BlockArrays.jl/branch/master/graph/badge.svg)](https://codecov.io/gh/KristofferC/BlockArrays.jl)
 
-A block array is a partition of an array into blocks or subarrays, see [wikipedia](https://en.wikipedia.org/wiki/Block_matrix) for a good description. This package introduces the abstract type `AbstractBlockArray` for arrays that exhibit this block structure. Currently, two concrete types are implemented that have very similar API but differs in how the blocks are stored in memory. The type `BlockArray` stores each block contiguously while the type `PseudoBlockArray` stores the full matrix contiguously. Which one to use depends on your use case, `BlockArray` supports fast non copying extraction and insertion of blocks while `PseudoBlockArray` supports directly using the underlying full matrix in for example a linear solver. Both these types follow the `AbstractArray` interface and should work in arbitrary dimensions for arbitrary block types as long as the block type itself satisfies the `AbstractArray` interface.
+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.
 
-This README will first provide an overview over the `BlockArray` type and then later discuss the few differences between `BlockArrays` and `PseudoBlockArrays`.
+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.
 
 **Note:** Currently, a quite new build of julia master is needed to use this package.
 
-### Creating uninitialized `BlockArrays`
+## Documentation
 
-A `BlockArray` can be created with the blocks left uninitialized using the `BlockArray(block_type, block_sizes...)` function.
-The `block_type` should be an array type, it could for example be `Matrix{Float64}`. The block sizes are each a `Vector{Int}` which determines the size of the blocks in that dimension. We here create a `[1,2]×[3,2]` block matrix of `Float32`s:
+Documentation is built automatically with help from MkDocs on Travis CI and hosted by GitHub Pages.
 
-```jl
-julia> BlockArray(Matrix{Float32}, [1,2], [3,2])
-3×5 BlockArrays.BlockArray{Float32,2,Array{Float32,2}}:
- #undef  #undef  #undef  │  #undef  #undef
- ------------------------┼----------------
- #undef  #undef  #undef  │  #undef  #undef
- #undef  #undef  #undef  │  #undef  #undef
-```
-
-We can also use a `SparseVector` or any other user defined array type:
-
-```jl
-julia> BlockArray(SparseVector{Float64, Int}, [1,2])
-3-element BlockArrays.BlockArray{Float64,1,SparseVector{Float64,Int64}}:
- #undef
- ------
- #undef
- #undef
-```
-
-Note that accessing an undefined block will throw an "access to undefined reference"-error.
-
-### Setting and getting blocks and values
-
-A block can be set by `setblock!(block_array, v, i...)` where `v` is the array to set and `i` is the block index.
-An alternative syntax for this is `block_array[Block(i...)] = v`.
-
-```jl
-julia> block_array = BlockArray(Matrix{Float64}, [1,2], [2,2])
-3×4 BlockArrays.BlockArray{Float64,2,Array{Float64,2}}:
- #undef  #undef  │  #undef  #undef
- ----------------┼----------------
- #undef  #undef  │  #undef  #undef
- #undef  #undef  │  #undef  #undef
-
-julia> setblock!(block_array, rand(2,2), 2, 1)
-3×4 BlockArrays.BlockArray{Float64,2,Array{Float64,2}}:
- #undef      #undef      │  #undef  #undef
- ------------------------┼----------------
-   0.314407    0.298761  │  #undef  #undef
-   0.91585     0.644499  │  #undef  #undef
-
-julia> block_array[Block(1, 1)] = [1 2];
-
-julia> block_array
-3×4 BlockArrays.BlockArray{Float64,2,Array{Float64,2}}:
- 1.0       2.0       │  #undef  #undef
- --------------------┼----------------
- 0.314407  0.298761  │  #undef  #undef
- 0.91585   0.644499  │  #undef  #undef
-```
-
-Note that this will "take ownership" of the passed in array, that is, no copy is made.
-
-A block can be retrieved with `getblock(block_array, i...)` or `block_array[Block(i...)]`:
-
-```jl
-julia> block_array[Block(1, 1)]
-1×2 Array{Float64,2}:
- 1.0  2.0
-```
-
-Similarly to `setblock!` this does not copy the returned array.
-
-For setting and getting a single scalar element, the usual `setindex!` and `getindex` are available.
-
-```jl
-julia> block_array[1, 2]
-2.0
-```
-
-### Converting between `BlockArray` and normal arrays
-
-An array can be repacked into a `BlockArray` with`BlockArray(array, block_sizes...)`:
-
-```jl
-julia> block_array_sparse = BlockArray(sprand(4, 5, 0.7), [1,3], [2,3])
-4×5 BlockArrays.BlockArray{Float64,2,SparseMatrixCSC{Float64,Int64}}:
- 0.0       0.284338  │  0.0         0.52346   0.403969
- --------------------┼--------------------------------
- 0.909193  0.0       │  0.0         0.3401    0.922003
- 0.0       0.736793  │  0.00840872  0.804832  0.441806
- 0.0       0.0       │  0.553519    0.757454  0.575238
-```
-
-To get back the full array use `full`:
-
-```jl
-julia> full(block_array_sparse)
-4×5 sparse matrix with 13 Float64 nonzero entries:
-    [2, 1]  =  0.909193
-    [1, 2]  =  0.284338
-      ⋮
-    [3, 5]  =  0.441806
-    [4, 5]  =  0.575238
-```
-
-### Operations on `BlockArrays`.
-
-Simple unary/binary functions and reductions are available, for an overview, see the `operations.jl` file.
-
-## `PseudoBlockArrays`
-
-`PseudoBlockArrays` are similar to `BlockArrays` except the full matrix is stored contiguously. This means that it is no longer possible to set and get blocks by simply changing a reference. However, the wrapped array can be directly used in for example linear solvers.
-
-Creating a `PseudoBlockArray` works in the same way as a `BlockArray`.
-
-```julia
-julia> pseudo = PseudoBlockArray(rand(3,3), [1,2], [2,1])
-3×3 BlockArrays.PseudoBlockArray{Float64,2,Array{Float64,2}}:
- 0.282059  0.560107  │  0.540811
- --------------------┼----------
- 0.46358   0.11423   │  0.520826
- 0.250737  0.809022  │  0.905993
-```
-
-This "takes ownership" of the passed in array so no copy of the array is made.
-
-Setting and getting blocks uses the same API as `BlockArrays`. The difference here is that setting a block will update the block in place and getting a block
-will extract a copy of the block and return it. For `PseudoBlockArrays` there is a mutating block getter called `getblock!` which updates a passed in array to avoid a copy:
-
-```julia
-julia> A = zeros(2,2)
-
-julia> getblock!(A, pseudo, 2, 1);
-
-julia> A
-2×2 Array{Float64,2}:
- 0.46358   0.11423
- 0.250737  0.809022
-```
-
-The underlying array is accessed with `full` just like for `BlockArray`.
-
-## TODO
-
-- Linear algebra stuff
-- Investigate performance (for example that bounds check removal work properly)
+[![](https://img.shields.io/badge/docs-stable-blue.svg)](https://KristofferC.github.io/BlockArrays.jl/stable) [![](https://img.shields.io/badge/docs-latest-blue.svg)](https://KristofferC.github.io/BlockArrays.jl/latest)
 
 ## Author
 

docs/make.jl

@@ -0,0 +1,23 @@
+using Documenter, BlockArrays
+
+# Build documentation.
+# ====================
+
+makedocs(
+    # options
+    modules = [BlockArrays],
+    clean   = true,
+    doctest = false,
+    )
+
+# Deploy built documentation from Travis.
+# =======================================
+
+# Needs to install an additional dep, mkdocs-material, so provide a custom `deps`.
+custom_deps() = run(`pip install --user pygments mkdocs mkdocs-material`)
+
+deploydocs(
+    # options
+    deps = custom_deps,
+    repo = "github.com/KristofferC/BlockArrays.jl.git"
+)

docs/mkdocs.yml

@@ -0,0 +1,31 @@
+site_name:        BlockArrays.jl
+repo_url:         https://github.com/KristofferC/BlockArrays.jl
+site_description: Description...
+site_author:      Kristoffer Carlsson
+
+theme: readthedocs
+
+extra_css:
+  - assets/Documenter.css
+
+extra_javascript:
+  - https://cdn.mathjax.org/mathjax/latest/MathJax.js?config=TeX-AMS-MML_HTMLorMML
+  - assets/mathjaxhelper.js
+
+markdown_extensions:
+  - extra
+  - tables
+  - fenced_code
+  - mdx_math
+
+docs_dir: 'build'
+
+pages:
+- Home: index.md
+- Manual:
+  - AbstractBlockArray interface: man/abstractblockarrayinterface.md
+  - BlockArrays: man/blockarrayss.md
+  - PseudoBlockArrays: man/pseudoblockarrays.md
+- Library:
+  - Public: lib/public.md
+  - Internals: lib/internals.md

docs/src/index.md

@@ -0,0 +1,29 @@
+# BlockArrays.jl
+
+*Block arrays in Julia*
+
+[![Build Status](https://travis-ci.org/KristofferC/BlockArrays.jl.svg?branch=master)](https://travis-ci.org/KristofferC/BlockArrays.jl) [![codecov](https://codecov.io/gh/KristofferC/BlockArrays.jl/branch/master/graph/badge.svg)](https://codecov.io/gh/KristofferC/BlockArrays.jl)
+
+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.
+
+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.
+
+**Note:** Currently, a quite new build of julia master is needed to use this package.
+
+
+## Manual Outline
+
+    {contents}
+    Pages = ["man/abstractblockarrayinterface.md", "man/blockarrayss.md", "man/pseudoblockarrays.md"]
+    Depth = 2
+
+## Library Outline
+
+    {contents}
+    Pages = ["lib/public.md", "lib/internals.md"]
+    Depth = 2
+
+## [Index]({ref#main-index})
+
+    {index}
+    Pages = ["lib/public.md", "lib/internals.md"]

docs/src/lib/internals.md

@@ -0,0 +1,21 @@
+    {meta}
+    CurrentModule = BlockArrays
+
+# Internal Documentation
+
+## Contents
+
+    {contents}
+    Pages = ["internals.md"]
+
+## Index
+
+    {index}
+    Pages = ["internals.md"]
+
+## Internals
+
+    {docs}
+    BlockIndex
+    blockindex2global
+    global2blockindex

docs/src/lib/public.md

@@ -0,0 +1,47 @@
+    {meta}
+    CurrentModule = BlockArrays
+
+# Public Documentation
+
+Documentation for `BlockArrays.jl`'s public interface.
+
+See [Internal Documentation]({ref}) for internal package docs covering all submodules.
+
+
+## Contents
+
+    {contents}
+    Pages = ["public.md"]
+
+## Index
+
+    {index}
+    Pages = ["public.md"]
+
+## AbstractBlockArray interface
+
+This sections defines the functions a subtype of `AbstractBlockArray` should define to be a part of the `AbstractBlockArray` interface. An `AbstractBlockArray{T, N}` is a subtype of `AbstractArray{T,N}` and should therefore also fulfill the [`AbstractArray` interface](http://docs.julialang.org/en/latest/manual/interfaces/#abstract-arrays).
+
+    {docs}
+    AbstractBlockArray
+    BlockBoundsError
+    Block
+    nblocks
+    blocksize
+    getblock
+    getblock!
+    setblock!
+    full
+    blockcheckbounds
+
+## BlockArray
+
+    {docs}
+    BlockArray
+
+
+
+## PseudoBlockArray
+
+    {docs}
+    PseudoBlockArray

docs/src/man/abstractblockarrayinterface.md

@@ -0,0 +1,38 @@
+# The AbstractBlockArray interface
+
+
+| Methods to implement    | Brief description |
+| :---------------------- | :---------------- |
+| `nblocks(A)`            | Tuple of number of blocks in each dimension |
+| `nblocks(A, i)`         | Number of blocks in dimension `i` |
+| `blocksize(A, i...)`    | Size of the block at block index `i...` |
+| `getblock(A, i...)`     | `X[Block(i...)]`, blocked indexing  |
+| `setblock!(A, v, i...)` | `X[Block(i...)] = v`, blocked index assignment |
+| `full(A)`               | The non blocked array |
+| **Optional methods**    |                        |
+| `getblock!(x, A, i)`    | `X[i]`, blocked index assignment with in place storage in `x` |
+
+
+With the methods above implemented the following are automatically provided:
+
+* A pretty printing `show` function that uses unicode lines to split up the blocks:
+
+    julia> BlockArray(rand(4, 5), [1,3], [2,3])
+    2×2-blocked 4×5 BlockArrays.BlockArray{Float64,2,Array{Float64,2}}:
+     0.28346   0.234328  │  0.10266   0.0670817  0.941958
+     --------------------┼-------------------------------
+     0.881618  0.152164  │  0.938311  0.819992   0.860623
+     0.74367   0.16049   │  0.704886  0.950269   0.601036
+     0.502035  0.259069  │  0.857453  0.197673   0.962873
+
+
+* A bounds index checking function for indexing with blocks:
+    julia> A = BlockArray(rand(4, 5), [1,3], [2,3]);
+
+    julia> blockcheckbounds(A, 5, 3)
+    ERROR: BlockBoundsError: attempt to access 2×2-blocked 4×5 BlockArrays.BlockArray{Float64,2,Array{Float64,2}} at block index [5,3]
+     in blockcheckbounds(::BlockArrays.BlockArray{Float64,2,Array{Float64,2}}, ::Int64, ::Int64) at .julia/v0.5/BlockArrays/src/abstractblockarray.jl:190
+     in eval(::Module, ::Any) at ./boot.jl:226
+
+* Happy users who know how to use your new block array :)
+