update docs, readme and version

Project.toml

@@ -1,7 +1,7 @@
 name = "KrylovKit"
 uuid = "0b1a1467-8014-51b9-945f-bf0ae24f4b77"
 authors = ["Jutho Haegeman"]
-version = "0.4.2"
+version = "0.5.0"
 
 [deps]
 LinearAlgebra = "37e2e46d-f89d-539d-b4ee-838fcccc9c8e"

README.md

@@ -4,30 +4,36 @@ A Julia package collecting a number of Krylov-based algorithms for linear proble
 value and eigenvalue problems and the application of functions of linear maps or operators
 to vectors.
 
+| **Documentation**                                                               | **Build Status**                                                                                |
+|:-------------------------------------------------------------------------------:|:-----------------------------------------------------------------------------------------------:|
+| [![][docs-stable-img]][docs-stable-url] [![][docs-dev-img]][docs-dev-url] | [![CI][github-img]][github-url] [![][codecov-img]][codecov-url] |
 
-| **Documentation** | **Build Status** |
-|:-----------------:|:----------------:|
-| [![][docs-stable-img]][docs-stable-url] [![][docs-dev-img]][docs-dev-url] | [![][travis-img]][travis-url] [![][appveyor-img]][appveyor-url] [![][codecov-img]][codecov-url] [![][coveralls-img]][coveralls-url] |
-
-## Release notes for the latest version
+[docs-dev-img]: https://img.shields.io/badge/docs-dev-blue.svg
+[docs-dev-url]: https://jutho.github.io/KrylovKit.jl/latest
 
-### v0.3
-*   a new method `expintegrator` that generalizes `exponentiate` (and the latter is now a
-    special case of the former), i.e. it computes a linear combination of the so-called
-    ``ϕⱼ`` functions that corresponds to the solution of a linear inhomogeneous ODE.
+[docs-stable-img]: https://img.shields.io/badge/docs-stable-blue.svg
+[docs-stable-url]: https://jutho.github.io/KrylovKit.jl/stable
 
-*   stricter handling of keyword arguments; unknown keyword arguments are no longer ignored
-    but give an error.
+[github-img]: https://github.com/Jutho/KrylovKit.jl/workflows/CI/badge.svg
+[github-url]: https://github.com/Jutho/KrylovKit.jl/actions?query=workflow%3ACI
 
-### v0.2
-*   a new method `geneigsolve` for generalized eigenvalue problems ``A x = λ B x``, with a
-    single implementation for symmetric/hermitian problems with positive definite `B`, based
-    on the Golub-Ye inverse free algorithm.
+[codecov-img]: https://codecov.io/gh/Jutho/KrylovKit.jl/branch/master/graph/badge.svg
+[codecov-url]: https://codecov.io/gh/Jutho/KrylovKit.jl
 
-*   a `verbosity` keyword that takes integer values to control the amount of information
-    that is printed while the algorithm is running.
+## Release notes for the latest version
 
-### v0.1: first official release
+### v0.5
+This version introduces (minimal) breaking changes, if you use KrylovKit.jl with custom
+vector types: KrylovKit.jl no longer depends on `eltype(::YourCustomVector)` and
+`similar(::YourCustumVector, ::Type{<:Number})`. Instead, KrylovKit.jl does now rely on
+`Base.:*(::Number, ::YourCustomVector)` to be defined as a means of creating new vectors,
+possibly with a different scalar type, so as to be able to represent this computation. Note
+that `Base.similar(::YourCustomVector)` (without the second argument) should still be
+defined to create uninitialized vectors of the same type as the one of the argument.
+
+The motivation for this is that using `eltype(::YourCustomVector)` to represent its scalar
+type, was often not the compatible with the requirements for `Base.eltype` if your type also
+supports iteration or indexing.
 
 ## Overview
 KrylovKit.jl accepts general functions or callable objects as linear maps, and general Julia

docs/src/index.md

@@ -63,28 +63,30 @@ However, KrylovKit.jl distinguishes itself from the previous packages in the fol
     particular higher-dimensional arrays or any custom user type that supports the
     following functions (with `v` and `w` two instances of this type and `α, β` scalars
     (i.e. `Number`)):
-    *   `Base.similar(v, [T::Type<:Number])`: a way to construct additional similar vectors,
-        possibly with a different scalar type `T`.
-    *   `Base.copyto!(w, v)`: copy the contents of `v` to a preallocated vector `w`
+    *   `Base.:*(α, v)`: multiply `v` with a scalar `α`, which can be of a different scalar
+        type; in particular this method is used to create vectors similar to `v` but with a
+        different type of underlying scalars.
+    *   `Base.similar(v)`: a way to construct vectors which are exactly similar to `v`
     *   `LinearAlgebra.mul!(w, v, α)`: out of place scalar multiplication; multiply
         vector `v` with scalar `α` and store the result in `w`
     *   `LinearAlgebra.rmul!(v, α)`: in-place scalar multiplication of `v` with `α`; in
-        particular with `α = false`, `v` is initialized with all zeros
+        particular with `α = false`, `v` is the corresponding zero vector
     *   `LinearAlgebra.axpy!(α, v, w)`: store in `w` the result of `α*v + w`
     *   `LinearAlgebra.axpby!(α, v, β, w)`: store in `w` the result of `α*v + β*w`
     *   `LinearAlgebra.dot(v,w)`: compute the inner product of two vectors
     *   `LinearAlgebra.norm(v)`: compute the 2-norm of a vector
 
-    Furthermore, KrylovKit provides two types satisfying the above requirements that might
-    facilitate certain applications:
+    Algorithms in KrylovKit.jl are tested against such a minimal implementation (named
+    `MinimalVec`) in the test suite. This type is only defined in the tests. However,
+    KrylovKit provides two types implementing this interface and slightly more, to make
+    them behave more like `AbstractArrays` (e.g. also `Base.:+` etc), which can facilitate
+    certain applications:
     *   [`RecursiveVec`](@ref) can be used for grouping a set of vectors into a single
-        vector like structure (can be used recursively). The reason that e.g.
-        `Vector{<:Vector}` cannot be used for this is that it returns the wrong `eltype`
-        and methods like `similar(v, T)` and `fill!(v, α)`
-        don't work correctly.
+        vector like structure (can be used recursively). This is more robust than trying to
+        use nested `Vector{<:Vector}` types.
     *   [`InnerProductVec`](@ref) can be used to redefine the inner product (i.e. `dot`)
         and corresponding norm (`norm`) of an already existing vector like object. The
-        latter should help with implementing certain type of preconditioners
+        latter should help with implementing certain type of preconditioners.
 
 ## Current functionality