README updates for 0.7

Author: schmrlng

README.md

@@ -5,12 +5,12 @@
 [![Build Status](https://travis-ci.org/JuliaArrays/StaticArrays.jl.svg?branch=master)](https://travis-ci.org/JuliaArrays/StaticArrays.jl)
 [![Build status](https://ci.appveyor.com/api/projects/status/xabgh1yhsjxlp30d?svg=true)](https://ci.appveyor.com/project/JuliaArrays/staticarrays-jl)
 [![Coverage Status](https://coveralls.io/repos/github/JuliaArrays/StaticArrays.jl/badge.svg?branch=master)](https://coveralls.io/github/JuliaArrays/StaticArrays.jl?branch=master)
-[![codecov.io](http://codecov.io/github/JuliaArrays/StaticArrays.jl/coverage.svg?branch=master)](http://codecov.io/github/JuliaArrays/StaticArrays.jl?branch=master)
+[![codecov.io](https://codecov.io/github/JuliaArrays/StaticArrays.jl/branch/master/graph/badge.svg)](http://codecov.io/github/JuliaArrays/StaticArrays.jl/branch/master)
 [![](https://img.shields.io/badge/docs-latest-blue.svg)](https://JuliaArrays.github.io/StaticArrays.jl/latest)
 [![](https://img.shields.io/badge/docs-stable-blue.svg)](https://JuliaArrays.github.io/StaticArrays.jl/stable)
 
 **StaticArrays** provides a framework for implementing statically sized arrays
-in Julia (≥ 0.5), using the abstract type `StaticArray{Size,T,N} <: AbstractArray{T,N}`.
+in Julia, using the abstract type `StaticArray{Size,T,N} <: AbstractArray{T,N}`.
 Subtypes of `StaticArray` will provide fast implementations of common array and
 linear algebra operations. Note that here "statically sized" means that the
 size can be determined from the *type*, and "static" does **not** necessarily
@@ -27,40 +27,34 @@ Full documentation can be found [here](https://JuliaArrays.github.io/StaticArray
 ## Speed
 
 The speed of *small* `SVector`s, `SMatrix`s and `SArray`s is often > 10 × faster
-than `Base.Array`. See this simplified benchmark (or see the full results [here](https://github.com/andyferris/StaticArrays.jl/blob/master/perf/bench10.txt)):
+than `Base.Array`. See this simplified benchmark:
 
 ```
 ============================================
     Benchmarks for 3×3 Float64 matrices
 ============================================
-
-Matrix multiplication               -> 8.2x speedup
-Matrix multiplication (mutating)    -> 3.1x speedup
-Matrix addition                     -> 45x speedup
-Matrix addition (mutating)          -> 5.1x speedup
-Matrix determinant                  -> 170x speedup
-Matrix inverse                      -> 125x speedup
-Matrix symmetric eigendecomposition -> 82x speedup
-Matrix Cholesky decomposition       -> 23.6x speedup
+Matrix multiplication               -> 5.1x speedup
+Matrix multiplication (mutating)    -> 1.6x speedup
+Matrix addition                     -> 14.0x speedup
+Matrix addition (mutating)          -> 2.1x speedup
+Matrix determinant                  -> 119.3x speedup
+Matrix inverse                      -> 65.6x speedup
+Matrix symmetric eigendecomposition -> 24.8x speedup
+Matrix Cholesky decomposition       -> 12.1x speedup
 ```
 
-These results improve significantly when using `julia -O3` with immutable static
-arrays, as the extra optimization results in surprisingly good SIMD code.
-
 Note that in the current implementation, working with large `StaticArray`s puts a
 lot of stress on the compiler, and becomes slower than `Base.Array` as the size
 increases.  A very rough rule of thumb is that you should consider using a
-normal `Array` for arrays larger than 100 elements. For example, the performance
-crossover point for a matrix multiply microbenchmark seems to be about 11x11 in
-julia 0.5 with default optimizations.
+normal `Array` for arrays larger than 100 elements.
 
 
 ## Quick start
 
+Add *StaticArrays* from the [Pkg REPL](https://docs.julialang.org/en/latest/stdlib/Pkg/#Getting-Started-1), i.e., `pkg> add StaticArrays`. Then:
 ```julia
-Pkg.add("StaticArrays")  # or Pkg.clone("https://github.com/JuliaArrays/StaticArrays.jl")
-using StaticArrays
 using LinearAlgebra
+using StaticArrays
 
 # Create an SVector using various forms, using constructors, functions or macros
 v1 = SVector(1, 2, 3)
@@ -104,7 +98,8 @@ rand(MMatrix{20,20}) * rand(MMatrix{20,20}) # large matrices can use BLAS
 eigen(m3) # eigen(), etc uses specialized algorithms up to 3×3, or else LAPACK
 
 # Static arrays stay statically sized, even when used by Base functions, etc:
-typeof(eigen(m3)) == Eigen{Float64,Float64,SArray{Tuple{3,3},Float64,2,9},SArray{Tuple{3},Float64,1,3}}
+typeof(eigen(m3).vectors) == SMatrix{3,3,Float64,9}
+typeof(eigen(m3).values) == SVector{3,Float64}
 
 # similar() returns a mutable container, while similar_type() returns a constructor:
 typeof(similar(m3)) == MArray{Tuple{3,3},Int64,2,9} # (final parameter is length = 9)
@@ -138,27 +133,7 @@ performance optimizations may be made when the size of the array is known to the
 compiler. One example of this is by loop unrolling, which has a substantial
 effect on small arrays and tends to automatically trigger LLVM's SIMD
 optimizations. Another way performance is boosted is by providing specialized
-methods for `det`, `inv`, `eig` and `chol` where the algorithm depends on the
+methods for `det`, `inv`, `eigen` and `cholesky` where the algorithm depends on the
 precise dimensions of the input. In combination with intelligent fallbacks to
 the methods in Base, we seek to provide a comprehensive support for statically
 sized arrays, large or small, that hopefully "just works".
-
-## Relationship to *FixedSizeArrays* and *ImmutableArrays*
-
-Several existing packages for statically sized arrays have been developed for
-Julia, noteably *FixedSizeArrays* and *ImmutableArrays* which provided signficant
-inspiration for this package. Upon consultation, it has been decided to move
-forward with *StaticArrays* which has found a new home in the *JuliaArrays*
-github organization. It is recommended that new users use this package, and
-that existing dependent packages consider switching to *StaticArrays* sometime
-during the life-cycle of Julia v0.5.
-
-You can try `using StaticArrays.FixedSizeArrays` to add some compatibility
-wrappers for the most commonly used features of the *FixedSizeArrays* package,
-such as `Vec`, `Mat`, `Point` and `@fsa`. These wrappers do not provide a
-perfect interface, but may help in trying out *StaticArrays* with pre-existing
-code.
-
-Furthermore, `using StaticArrays.ImmutableArrays` will let you use the typenames
-from the *ImmutableArrays* package, which does not include the array size as a
-type parameter (e.g. `Vector3{T}` and `Matrix3x3{T}`).

perf/README_benchmarks.jl

@@ -0,0 +1,42 @@
+using BenchmarkTools
+using LinearAlgebra
+using StaticArrays
+
+add!(C, A, B) = (C .= A .+ B)
+
+function simple_bench(N, T=Float64)
+    A = rand(T,N,N)
+    A = A'*A
+    B = copy(A)
+    SA = SMatrix{N,N}(A)
+    MA = MMatrix{N,N}(A)
+    MB = copy(MA)
+
+    print("""
+============================================
+    Benchmarks for $N×$N $T matrices
+============================================
+""")
+    ops = [
+        ("Matrix multiplication              ", *, (A, A), (SA, SA)),
+        ("Matrix multiplication (mutating)   ", mul!, (B, A, A), (MB, MA, MA)),
+        ("Matrix addition                    ", +, (A, A), (SA, SA)),
+        ("Matrix addition (mutating)         ", add!, (B, A, A), (MB, MA, MA)),
+        ("Matrix determinant                 ", det, A, SA),
+        ("Matrix inverse                     ", inv, A, SA),
+        ("Matrix symmetric eigendecomposition", eigen, A, SA),
+        ("Matrix Cholesky decomposition      ", cholesky, A, SA)
+    ]
+    for (name, op, Aargs, SAargs) in ops
+        if Aargs isa Tuple && length(Aargs) == 2
+            speedup = @belapsed($op($Aargs[1], $Aargs[2])) / @belapsed($op($SAargs[1], $SAargs[2]))
+        elseif Aargs isa Tuple && length(Aargs) == 3
+            speedup = @belapsed($op($Aargs[1], $Aargs[2], $Aargs[3])) / @belapsed($op($SAargs[1], $SAargs[2], $SAargs[3]))
+        else
+            speedup = @belapsed($op($Aargs)) / @belapsed($op($SAargs))
+        end
+        println(name*" -> $(round(speedup, digits=1))x speedup")
+    end
+end
+
+simple_bench(3)