SparseMatrixExtension -> SparseMatrixLNK

Tried to document the source of the idea.

Author: j-fu

README.md

@@ -8,8 +8,16 @@
 
 Sparse matrix class with efficient successive insertion of entries.
 
-Without an intermediate data structure, efficient successive insertion/update of entries in random order into a standard compressed colume storage structure appears to be not possible. The package introduces `ExtendableSparseMatrix`, a delegating wrapper around the Julia standard `SparseMatrixCSC` struct which contains an additional linked list based (but realised in vectors) temporary extension structure.
+Without an intermediate data structure, efficient successive insertion/update of possibly duplicate entries in random order into a standard compressed colume storage structure appears to be not possible. The package introduces `ExtendableSparseMatrix`, a delegating wrapper containing a Julia standard `SparseMatrixCSC` struct for performing linear algebra operations and a `SparseMatrixLNK` struct realising a linked list based (but realised in vectors) format collecting new entries.
+
+The later is modeled after the linked list sparse matrix format described in the [whitepaper](https://www-users.cs.umn.edu/~saad/software/SPARSKIT/paper.ps) by Y. Saad.
+
+Any linear algebra method on `ExtendableSparseMatrix` starts with a `flush!` method which splices the LNK entries and the existing CSC entries into a new CSC struct and resets the LNK struct.
+
+`ExtendableSparseMatrix` is aimed to work as a drop-in replacement to `SparseMatrixCSC` in finite element and finite volume codes especally in those cases where the sparsity structure is hard to detect a priori and where working with an intermediadte COO representation appears to be not convenient.
+
+
+
 
-`ExtendableSparseMatrix` is aimed to work as a drop-in replacement to `SparseMatrixCSC` in finite element and finite volume codes.
 
 

docs/src/api.md

@@ -5,19 +5,19 @@
 
 ```@autodocs
 Modules = [ExtendableSparse]
-Pages = ["extension.jl","extendable.jl"]
+Pages = ["sparsematrixlnk.jl","extendable.jl"]
 Order = [:type]
 ```
 
 ```@autodocs
 Modules = [ExtendableSparse]
-Pages = ["extension.jl","extendable.jl"]
+Pages = ["sparsematrixlnk.jl","extendable.jl"]
 Order = [:constant]
 ```
 ## Methods
 
 ```@autodocs
 Modules = [ExtendableSparse]
-Pages = ["extension.jl","extendable.jl", "sprand.jl"]
+Pages = ["sparsematrixlnk.jl","extendable.jl", "sprand.jl"]
 Order = [:function]
 ```

docs/src/changes.md

@@ -1,10 +1,15 @@
 # Changes
 ## dev
+- Tried to track down the source from which I learned the linked list based struct in order
+  to document this. Ended up with SPARSEKIT of Y.Saad, however I believe this 
+  already was in SPARSEPAK by Chu,George,Liu.
+- Internal rename of SparseMatrixExtension to SparseMatrixLNK. 
+
+## v0.2 Dec 2019
 - more interface methods delegating to csc, in particular mul! and ldiv!
 - lazy creation of extendable part: don't create idle memory
 - nicer constructors
 
 ## V0.1, July 2019
-
 - Initial release
 

docs/src/example.md

@@ -3,28 +3,29 @@
 An `ExtendableSparseMatrix` can serve as a drop-in replacement for
 `SparseMatrixCSC`, albeit with faster assembly.
 
-The code below provides a small benchmark example. 
+The code below provides a small benchmark example.
 ```julia
 using ExtendableSparse
 using SparseArrays
 
-function ext_create(n, row_nz)
+function ext_create(n)
     A=ExtendableSparseMatrix(n,n)
-    sprand_sdd!(A,row_nz);
+    sprand_sdd!(A);
 end
 
-function csc_create(n, row_nz)
+function csc_create(n)
     A=spzeros(n,n)
-    sprand_sdd!(A,row_nz);
+    sprand_sdd!(A);
 end
 
-csc_create(10,2);
-ext_create(10,2);
-n=65536
-row_nz=5
-@time Acsc=csc_create(n,row_nz);
+# Trigger JIT compilation before timing
+csc_create(10);
+ext_create(10);
+
+n=90000
+@time Acsc=csc_create(n);
 nnz(Acsc)
-@time Aext=ext_create(n,row_nz);
+@time Aext=ext_create(n);
 nnz(Aext)
 b=rand(n);
 @time Acsc*(Acsc\b)≈b
@@ -38,6 +39,8 @@ its rows. Its  bandwidth is bounded by 2*sqrt(n), therefore it
 resembles a typical matrix of a 2D piecewise linear FEM discretization.
 For filling a matrix a, the method  conveniently albeit naively
 uses just `a[i,j]=value`. This approach is considerably faster with 
-the [`ExtendableSparseMatrix`](@ref).
+the [`ExtendableSparseMatrix`](@ref) which uses a linked list based
+structure  [`SparseMatrixLNK`](@ref) to grab new entries.
+
 
 

docs/src/index.md

@@ -1,10 +1,6 @@
-# ExtendableSparse
-
-Sparse matrix class with efficient successive insertion of entries.
-
-Without an intermediate data structure, efficient successive insertion/update of entries in random order into a standard compressed colume storage structure appears to be not possible. The package introduces `ExtendableSparseMatrix`, a delegating wrapper around the Julia standard `SparseMatrixCSC` struct which contains an additional linked list based (but realised in vectors) temporary extension structure.
-
-`ExtendableSparseMatrix` is aimed to work as a drop-in replacement to `SparseMatrixCSC` in finite element and finite volume codes.
-
-Currently it has the methods required for `AbstractSparseMatrix` (`getindex`, `setindex!`,`size`,`nnz`), as well as `lufact` and `mul!`, which is already sufficient for a number of interesting applications.
-
+````@eval
+using Markdown
+Markdown.parse("""
+$(read("../../README.md",String))
+""")
+````

src/ExtendableSparse.jl

@@ -3,11 +3,11 @@ using DocStringExtensions
 using SparseArrays
 using LinearAlgebra
 
-include("extension.jl")
+include("sparsematrixlnk.jl")
 include("extendable.jl")
 include("sprand.jl")
 
-export SparseMatrixExtension,ExtendableSparseMatrix,flush!,nnz, sprand!,sprand_sdd!
+export SparseMatrixLNK,ExtendableSparseMatrix,flush!,nnz, sprand!,sprand_sdd!
 
 export colptrs
 end # module