Add License.txt, rename ADelemtree to SparsityTracing

License.txt

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2021 Stuart Daines and collaborators
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

Project.toml

@@ -1,4 +1,4 @@
-name = "ADelemtree"
+name = "SparsityTracing"
 uuid = "06eadbd4-12ad-4cbc-ab6e-10f8370940a5"
 authors = ["Stuart Daines <stuart.daines@gmail.com>"]
 version = "0.1.0"

README.md

@@ -1,4 +1,4 @@
-# ADelemtree.jl
+# SparsityTracing.jl
 
 Automatic Jacobian sparsity detection using minimal scalar tracing and autodifferentiation.
 
@@ -7,12 +7,12 @@ Automatic Jacobian sparsity detection using minimal scalar tracing and autodiffe
 The package is not yet registered, so add it using:
 
 ```julia
-julia> ] add https://github.com/sjdaines/ADelemtree.jl
+julia> ] add https://github.com/PALEOmodel/SparsityTracing.jl
 ```
 
 ## Example
 ```julia
-julia> import ADelemtree as AD
+julia> import SparsityTracing as AD
 
 julia> function rober(du,u,p)
                    y₁,y₂,y₃ = u
@@ -47,7 +47,7 @@ julia> Jad = AD.jacobian(du_ad, length(du_ad))
 
 ## Implementation
 
-The algorithm is essentially that of SparsLinC described in Bischof etal (1996), except with a simpler but less efficient data structure. Implements a scalar type `ADelemtree.ADval{T<:Real}` that holds a value and a binary tree of scalar derivatives including the element indices used as leaf nodes. The tree is initialised to a Vector of leaf nodes by `ADelemtree.create_advec`.  It is populated with derivatives calculated by `DiffRules` when a Julia function is called (eg a function `y = f(x)` calculating the RHS of an ODE). `ADelemtree.jacobian` then walks the tree and calculates the Jacobian as a sparse matrix.  This provides a robust way of detecting Jacobian sparsity (and for test purposes only, a very slow way of calculating the actual derivative).  The sparsity pattern may then be used to generate matrix colouring for a fast AD package eg `SparseDiffTools`. 
+The algorithm is essentially that of SparsLinC described in Bischof etal (1996), except with a simpler but less efficient data structure. Implements a scalar type `SparsityTracing.ADval{T<:Real}` that holds a value and a binary tree of scalar derivatives including the element indices used as leaf nodes. The tree is initialised to a Vector of leaf nodes by `SparsityTracing.create_advec`.  It is populated with derivatives calculated by `DiffRules` when a Julia function is called (eg a function `y = f(x)` calculating the RHS of an ODE). `SparsityTracing.jacobian` then walks the tree and calculates the Jacobian as a sparse matrix.  This provides a robust way of detecting Jacobian sparsity (and for test purposes only, a very slow way of calculating the actual derivative).  The sparsity pattern may then be used to generate matrix colouring for a fast AD package eg `SparseDiffTools`. 
 
 Time taken increases approximately linearly with the number of scalar operations. Speed is approx 10 M scalar op/s (on a ~4Ghz laptop core) so 100 - 1000x slower than `y = f(x)` with primitive types (as each scalar operation generates a memory allocation to add a tree node).  This is however still ~10 - 20x faster than tracing with Symbolics.jl     
 

src/ADelemtree.jl → src/SparsityTracing.jl

@@ -18,11 +18,11 @@ where x and y are vectors.
     for examples of definitions required.
  
 # Example usage:
-    x_ad = ADelemtree.create_advec(x)           # x_ad takes values from x,  derivatives set to identity
+    x_ad = SparsityTracing.create_advec(x)           # x_ad takes values from x,  derivatives set to identity
     y_ad = f(x_ad)                              # tree of derivative information is accumulated into each element of y_ad
-    jac = ADelemtree.jacobian(y_ad, length(x))  # walk trees and generate sparse Jacobian
+    jac = SparsityTracing.jacobian(y_ad, length(x))  # walk trees and generate sparse Jacobian
  """
-module ADelemtree
+module SparsityTracing
 
 
 using SparseArrays
@@ -54,21 +54,21 @@ Usual case for an independent vector variable `x` (eg to use as input with `y =
  
 # Examples:
  ```jldoctest; setup = :(import PALEOmodel)
-julia> v_ad = PALEOmodel.ADelemtree.create_advec([1.0, 5.0])
-2-element Array{PALEOmodel.ADelemtree.ADval{Float64,2},1}:
- PALEOmodel.ADelemtree.ADval{Float64,2}(1.0, <derivnode>)
- PALEOmodel.ADelemtree.ADval{Float64,2}(5.0, <derivnode>)
+julia> v_ad = PALEOmodel.SparsityTracing.create_advec([1.0, 5.0])
+2-element Array{PALEOmodel.SparsityTracing.ADval{Float64,2},1}:
+ PALEOmodel.SparsityTracing.ADval{Float64,2}(1.0, <derivnode>)
+ PALEOmodel.SparsityTracing.ADval{Float64,2}(5.0, <derivnode>)
 
 julia> x_ad, y_ad = v_ad;
 
 julia> x_ad        # deriv is sparse vector
-PALEOmodel.ADelemtree.ADval{Float64}
+PALEOmodel.SparsityTracing.ADval{Float64}
   val=1.0
   deriv:
   [1]  =  1.0
    
 julia> y_ad       # deriv is sparse vector
-PALEOmodel.ADelemtree.ADval{Float64}
+PALEOmodel.SparsityTracing.ADval{Float64}
   val=5.0
   deriv:
   [2]  =  1.0  
@@ -79,7 +79,7 @@ julia> PALEOmodel.AD.jacobian(v_ad, 2)  # sparse 2x2 identity matrix.
   [2, 2]  =  1.0
 
 julia> z_ad = x_ad*y_ad^2    # d(x*y^2)/dx = y^2 = 5^2 = 25,  d(x*y^2)/dy = 2*x*y = 2*1*5 = 10
-PALEOmodel.ADelemtree.ADval{Float64}
+PALEOmodel.SparsityTracing.ADval{Float64}
   val=25.0
   deriv:
   [1]  =  25.0
@@ -172,7 +172,7 @@ function jacobian(advec::Vector{ADval{T}}, N) where {T}
 
     Nvar = length(advec)
 
-    @info "ADelemtree.jacobian ($Nvar, $N)"
+    @info "SparsityTracing.jacobian ($Nvar, $N)"
 
     # define arrays for sparse matrix creation
     I = Vector{Int64}()

test/runtests.jl

@@ -1,4 +1,4 @@
-import ADelemtree; const AD = ADelemtree # short name for convenience
+import SparsityTracing; const AD = SparsityTracing # short name for convenience
 
 using SparseArrays
 using LinearAlgebra  # for I
@@ -8,7 +8,7 @@ using Test
 
 
 
-@testset "ADelem" begin
+@testset "SparsityTracing" begin
 
     @testset "createviewassign" begin