Kc/ohp6 (#15)

* fix deprecs

* add benchmarks

* updates

Author: KristofferC

.gitignore

@@ -2,4 +2,6 @@
 *.jl.*.cov
 *.jl.mem
 docs/build/
-docs/site/
+docs/site/
+*.jld
+benchmark/*.md

.travis.yml

@@ -14,5 +14,4 @@ script:
 
 after_success:
   - 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"))'

REQUIRE

@@ -1 +1 @@
-julia 0.5-
+julia 0.6-

benchmark/generate_report.jl

@@ -0,0 +1,70 @@
+# The functionality to export the benchmark results to a markdown file heavily uses code from Nanosoldier.jl
+# The Nanosoldier.jl package is licensed under the MIT "Expat" License:
+#
+# Copyright (c) 2015: Jarrett Revels.
+
+const REGRESS_MARK = ":x:"
+const IMPROVE_MARK = ":white_check_mark:"
+
+function printreport(io::IO, results; iscomparisonjob::Bool = false)
+
+    if iscomparisonjob
+        print(io, """
+                  A ratio greater than `1.0` denotes a possible regression (marked with $(REGRESS_MARK)), while a ratio less
+                  than `1.0` denotes a possible improvement (marked with $(IMPROVE_MARK)). Only significant results - results
+                  that indicate possible regressions or improvements - are shown below (thus, an empty table means that all
+                  benchmark results remained invariant between builds).
+
+                  | ID | time ratio | memory ratio |
+                  |----|------------|--------------|
+                  """)
+    else
+        print(io, """
+                  | ID | time | GC time | memory | allocations |
+                  |----|------|---------|--------|-------------|
+                  """)
+    end
+
+    entries = BenchmarkTools.leaves(results)
+
+    try
+        entries = entries[sortperm(map(x -> string(first(x)), entries))]
+    end
+
+
+    for (ids, t) in entries
+        if !(iscomparisonjob) || BenchmarkTools.isregression(t) || BenchmarkTools.isimprovement(t)
+            println(io, resultrow(ids, t))
+        end
+    end
+
+    return nothing
+end
+
+idrepr(id) = (str = repr(id); str[searchindex(str, '['):end])
+intpercent(p) = string(ceil(Int, p * 100), "%")
+resultrow(ids, t::BenchmarkTools.Trial) = resultrow(ids, minimum(t))
+
+function resultrow(ids, t::BenchmarkTools.TrialEstimate)
+    t_tol = intpercent(BenchmarkTools.params(t).time_tolerance)
+    m_tol = intpercent(BenchmarkTools.params(t).memory_tolerance)
+    timestr = string(BenchmarkTools.prettytime(BenchmarkTools.time(t)), " (", t_tol, ")")
+    memstr = string(BenchmarkTools.prettymemory(BenchmarkTools.memory(t)), " (", m_tol, ")")
+    gcstr = BenchmarkTools.prettytime(BenchmarkTools.gctime(t))
+    allocstr = string(BenchmarkTools.allocs(t))
+    return "| `$(idrepr(ids))` | $(timestr) | $(gcstr) | $(memstr) | $(allocstr) |"
+end
+
+function resultrow(ids, t::BenchmarkTools.TrialJudgement)
+    t_tol = intpercent(BenchmarkTools.params(t).time_tolerance)
+    m_tol = intpercent(BenchmarkTools.params(t).memory_tolerance)
+    t_ratio = @sprintf("%.2f", BenchmarkTools.time(BenchmarkTools.ratio(t)))
+    m_ratio =  @sprintf("%.2f", BenchmarkTools.memory(BenchmarkTools.ratio(t)))
+    t_mark = resultmark(BenchmarkTools.time(t))
+    m_mark = resultmark(BenchmarkTools.memory(t))
+    timestr = "$(t_ratio) ($(t_tol)) $(t_mark)"
+    memstr = "$(m_ratio) ($(m_tol)) $(m_mark)"
+    return "| `$(idrepr(ids))` | $(timestr) | $(memstr) |"
+end
+
+resultmark(sym::Symbol) = sym == :regression ? REGRESS_MARK : (sym == :improvement ? IMPROVE_MARK : "")

benchmark/runbenchmarks.jl

@@ -0,0 +1,59 @@
+using BlockArrays
+using BenchmarkTools
+using FileIO
+
+include("generate_report.jl")
+
+const SUITE = BenchmarkGroup()
+
+g = addgroup!(SUITE, "indexing")
+# g_block = addgroup!(SUITE, "blockindexing")
+g_size = addgroup!(SUITE, "size")
+
+for n = (5,)
+    for BT in (BlockArray, PseudoBlockArray)
+        block_vec = BT(rand(n),       [1,3,1])
+        block_mat = BT(rand(n,n),     [1,3,1], [4,1])
+        block_arr = BT(rand(n,n,n),   [1,3,1], [4,1], [3, 2])
+        g["getindex", BT.name.name, "vector", n] = @benchmarkable getindex($block_vec, 3)
+        g["getindex", BT.name.name, "matrix", n] = @benchmarkable getindex($block_mat, 3, 2)
+        g["getindex", BT.name.name, "rank3", n]  = @benchmarkable getindex($block_arr, 3, 2 ,3)
+        
+        g["setindex!", BT.name.name, "vector", n] = @benchmarkable setindex!($block_vec, 3)
+        g["setindex!", BT.name.name, "matrix", n] = @benchmarkable setindex!($block_mat, 3, 2)
+        g["setindex!", BT.name.name, "rank3", n]  = @benchmarkable setindex!($block_arr, 3, 2 ,3)
+
+        g_size[BT.name.name, "vector", n] = @benchmarkable size($block_vec)
+        g_size[BT.name.name, "matrix", n] = @benchmarkable size($block_mat)
+        g_size[BT.name.name, "rank3", n]  = @benchmarkable size($block_arr)
+    end
+end
+
+
+function run_benchmarks(name, tagfilter = @tagged ALL)
+    const paramspath = joinpath(dirname(@__FILE__), "params.jld")
+    if !isfile(paramspath)
+        println("Tuning benchmarks...")
+        tune!(SUITE, verbose=true)
+        JLD.save(paramspath, "SUITE", params(SUITE))
+    end
+    loadparams!(SUITE, JLD.load(paramspath, "SUITE"), :evals, :samples)
+    results = run(SUITE[tagfilter], verbose = true, seconds = 2)
+    JLD.save(joinpath(dirname(@__FILE__), name * ".jld"), "results", results)
+end
+
+function generate_report(v1, v2)
+    v1_res = load(joinpath(dirname(@__FILE__), v1 * ".jld"), "results")
+    v2_res = load(joinpath(dirname(@__FILE__), v2 * ".jld"), "results")
+    open(joinpath(dirname(@__FILE__), "results_$(v1)_$(v2).md"), "w") do f
+        printreport(f, judge(minimum(v1_res), minimum(v2_res)); iscomparisonjob = true)
+    end
+end
+
+function generate_report(v1)
+    v1_res = load(joinpath(dirname(@__FILE__), v1 * ".jld"), "results")
+    open(joinpath(dirname(@__FILE__), "results_$(v1).md"), "w") do f
+        printreport(f, minimum(v1_res); iscomparisonjob = false)
+    end
+end
+

docs/make.jl

@@ -4,17 +4,32 @@ using Documenter, BlockArrays
 # ====================
 
 makedocs(
-    # options
     modules = [BlockArrays],
-    clean   = true,
+    format = :html,
+    sitename = "BlockArrays.jl",
     doctest = false,
-    )
+    strict = VERSION.minor == 6 && sizeof(Int) == 8, # only strict mode on 0.6 and Int64
+    pages = Any[
+        "Home" => "index.md",
+        "Manual" => [
+            "man/abstractblockarrayinterface.md",
+            "man/blockarrays.md",
+            "man/pseudoblockarrays.md",
+        ],
+        "API" => [
+            "lib/public.md",
+            "lib/internals.md"
+        ]
+    ]
+)
 
 # Deploy built documentation from Travis.
 # =======================================
 
 deploydocs(
-    # options
-    deps = Deps.pip("mkdocs", "python-markdown-math"),
-    repo = "github.com/KristofferC/BlockArrays.jl.git"
+    repo = "https://github.com/KristofferC/BlockArrays.jl",
+    target = "build",
+    julia = "nightly", # deploy from release bot
+    deps = nothing,
+    make = nothing
 )

docs/src/index.md

@@ -8,13 +8,10 @@ A block array is a partition of an array into blocks or subarrays, see [wikipedi
 
 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"]
+Pages = ["man/abstractblockarrayinterface.md", "man/blockarrays.md", "man/pseudoblockarrays.md"]
 Depth = 2
 ```
 

docs/src/lib/public.md

@@ -34,9 +34,7 @@ blocksize
 getblock
 getblock!
 setblock!
-getindex
-setindex!
-full
+Array
 blockcheckbounds
 ```
 

docs/src/man/abstractblockarrayinterface.md

@@ -10,46 +10,30 @@ In order to follow the `AbstractBlockArray` the following methods should be impl
 | `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` |
 
 For a more thorough description of the methods see the public interface documentation.
 
-
 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> A = 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
-
-* Indexing with `Enums` works as a way to access blocks and set blocks.
-
-    julia> @enum vars u=1 v=2
-
-    julia> A[u, v]
-    1×3 Array{Float64,2}:
-     0.10266  0.0670817  0.941958
-
-    julia> A[u, v] = zeros(1,3);
-
-    julia> A[u, v]
-    1×3 Array{Float64,2}:
-     0.0  0.0  0.0
-
+```
+julia> A = BlockArray(rand(4, 5), [1,3], [2,3])
+2×2-blocked 4×5 BlockArrays.BlockArray{Float64,2,Array{Float64,2}}:
+0.61179   0.965631  │  0.696476   0.392796  0.712462
+--------------------┼-------------------------------
+0.620099  0.364706  │  0.0311643  0.27895   0.73477
+0.215712  0.923602  │  0.279944   0.994497  0.383706
+0.569955  0.754047  │  0.0190392  0.548297  0.687052
+```
 
 * A bounds index checking function for indexing with blocks:
 
-    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
+```
+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]
+```
 
 * Happy users who know how to use your new block array :)
 

docs/src/man/blockarrayss.md renamed to docs/src/man/blockarrays.md

@@ -1,13 +1,17 @@
 # BlockArrays
 
-
+```@meta
+DocTestSetup = quote
+    srand(1234)
+end
+```
 
 ## Creating uninitialized `BlockArrays`.
 
 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:
 
-```jl
+```jldoctest
 julia> BlockArray(Matrix{Float32}, [1,2], [3,2])
 2×2-blocked 3×5 BlockArrays.BlockArray{Float32,2,Array{Float32,2}}:
  #undef  #undef  #undef  │  #undef  #undef
@@ -25,6 +29,7 @@ julia> BlockArray(SparseVector{Float64, Int}, [1,2])
  ------
  #undef
  #undef
+julia> BlockArray(SparseVector{Float64, Int}, [1,2])
 ```
 
 Note that accessing an undefined block will throw an "access to undefined reference"-error.
@@ -34,7 +39,7 @@ Note that accessing an undefined block will throw an "access to undefined refere
 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
+```jldoctest
 julia> block_array = BlockArray(Matrix{Float64}, [1,2], [2,2])
 2×2-blocked 3×4 BlockArrays.BlockArray{Float64,2,Array{Float64,2}}:
  #undef  #undef  │  #undef  #undef
@@ -46,24 +51,24 @@ julia> setblock!(block_array, rand(2,2), 2, 1)
 2×2-blocked 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
+   0.590845    0.566237  │  #undef  #undef
+   0.766797    0.460085  │  #undef  #undef
 
 julia> block_array[Block(1, 1)] = [1 2];
 
 julia> block_array
 2×2-blocked 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
+ 0.590845  0.566237  │  #undef  #undef
+ 0.766797  0.460085  │  #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
+```jldoctest
 julia> block_array[Block(1, 1)]
 1×2 Array{Float64,2}:
  1.0  2.0
@@ -84,26 +89,27 @@ 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])
-2×2-blocked 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
+2×2-blocked 4×5 BlockArrays.BlockArray{Float64,2,SparseMatrixCSC{Float64,Int64}}:
+ 0.0341601  0.374187  │  0.0118196  0.299058  0.0     
+ ---------------------┼-------------------------------
+ 0.0945445  0.931115  │  0.0460428  0.0       0.0     
+ 0.314926   0.438939  │  0.496169   0.0       0.0     
+ 0.12781    0.246862  │  0.732      0.449182  0.875096
 ```
 
-To get back the full array use `full`:
+To get back the underlying array use `Array`:
 
 ```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
+julia> Array(block_array_sparse))
+4×5 SparseMatrixCSC{Float64,Int64} with 15 stored entries:
+  [1, 1]  =  0.0341601
+  [2, 1]  =  0.0945445
+  [3, 1]  =  0.314926
+  [4, 1]  =  0.12781
+  ⋮
+  [3, 3]  =  0.496169
+  [4, 3]  =  0.732
+  [1, 4]  =  0.299058
+  [4, 4]  =  0.449182
+  [4, 5]  =  0.875096
 ```
-
-## Operations on `BlockArrays`.
-
-Simple unary/binary functions and reductions are available, for an overview, see the `operations.jl` file.