Implement rand_tangent and difference (#91)

* Implement rand_tangent and differnece

* Bump docs build version

* Extra tests

* Test on latest version

* Remove old Manifest

* Add tests / remove untested feature

* Moves Foo to runtests

* Modify testsets

* Regenerate Manifest

* Fix typo

* Add TODO

Co-authored-by: Nick Robinson <npr251@gmail.com>

* Fix docs hopefully

* Don't export difference or rand_tangent

* Bump patch

* Fix tests

Co-authored-by: Nick Robinson <npr251@gmail.com>

Author: willtebbutt

src/rand_tangent.jl

@@ -0,0 +1,40 @@
+"""
+    rand_tangent([rng::AbstractRNG,] x)
+
+Returns a randomly generated tangent vector appropriate for the primal value `x`.
+"""
+rand_tangent(x) = rand_tangent(Random.GLOBAL_RNG, x)
+
+rand_tangent(rng::AbstractRNG, x::Symbol) = DoesNotExist()
+rand_tangent(rng::AbstractRNG, x::AbstractChar) = DoesNotExist()
+rand_tangent(rng::AbstractRNG, x::AbstractString) = DoesNotExist()
+
+rand_tangent(rng::AbstractRNG, x::Integer) = DoesNotExist()
+
+rand_tangent(rng::AbstractRNG, x::T) where {T<:Number} = randn(rng, T)
+
+rand_tangent(rng::AbstractRNG, x::StridedArray) = rand_tangent.(Ref(rng), x)
+
+function rand_tangent(rng::AbstractRNG, x::T) where {T<:Tuple}
+    return Composite{T}(rand_tangent.(Ref(rng), x)...)
+end
+
+function rand_tangent(rng::AbstractRNG, xs::T) where {T<:NamedTuple}
+    return Composite{T}(; map(x -> rand_tangent(rng, x), xs)...)
+end
+
+function rand_tangent(rng::AbstractRNG, x::T) where {T}
+    if !isstructtype(T)
+        throw(ArgumentError("Non-struct types are not supported by this fallback."))
+    end
+
+    field_names = fieldnames(T)
+    if length(field_names) > 0
+        tangents = map(field_names) do field_name
+            rand_tangent(rng, getfield(x, field_name))
+        end
+        return Composite{T}(; NamedTuple{field_names}(tangents)...)
+    else
+        return NO_FIELDS
+    end
+end

test/rand_tangent.jl

@@ -0,0 +1,80 @@
+using FiniteDifferences: rand_tangent
+
+@testset "generate_tangent" begin
+    rng = MersenneTwister(123456)
+
+    @testset "Primal: $(typeof(x)), Tangent: $T_tangent" for (x, T_tangent) in [
+
+        # Things without sensible tangents.
+        ("hi", DoesNotExist),
+        ('a', DoesNotExist),
+        (:a, DoesNotExist),
+        (true, DoesNotExist),
+        (4, DoesNotExist),
+
+        # Numbers.
+        (5.0, Float64),
+        (5.0 + 0.4im, Complex{Float64}),
+
+        # StridedArrays.
+        (randn(Float32, 3), Vector{Float32}),
+        (randn(Complex{Float64}, 2), Vector{Complex{Float64}}),
+        (randn(5, 4), Matrix{Float64}),
+        (randn(Complex{Float32}, 5, 4), Matrix{Complex{Float32}}),
+        ([randn(5, 4), 4.0], Vector{Any}),
+
+        # Tuples.
+        ((4.0, ), Composite{Tuple{Float64}}),
+        ((5.0, randn(3)), Composite{Tuple{Float64, Vector{Float64}}}),
+
+        # NamedTuples.
+        ((a=4.0, ), Composite{NamedTuple{(:a,), Tuple{Float64}}}),
+        ((a=5.0, b=1), Composite{NamedTuple{(:a, :b), Tuple{Float64, Int}}}),
+
+        # structs.
+        (sin, typeof(NO_FIELDS)),
+        (Foo(5.0, 4, rand(rng, 3)), Composite{Foo}),
+        (Foo(4.0, 3, Foo(5.0, 2, 4)), Composite{Foo}),
+
+        # LinearAlgebra types (also just structs).
+        (
+            UpperTriangular(randn(3, 3)),
+            Composite{UpperTriangular{Float64, Matrix{Float64}}},
+        ),
+        (
+            Diagonal(randn(2)),
+            Composite{Diagonal{Float64, Vector{Float64}}},
+        ),
+        (
+            SVector{2, Float64}(1.0, 2.0),
+            Composite{typeof(SVector{2, Float64}(1.0, 2.0))},
+        ),
+        (
+            SMatrix{2, 2, ComplexF64}(1.0, 2.0, 3.0, 4.0),
+            Composite{typeof(SMatrix{2, 2, ComplexF64}(1.0, 2.0, 3.0, 4.0))},
+        ),
+        (
+            Symmetric(randn(2, 2)),
+            Composite{Symmetric{Float64, Matrix{Float64}}},
+        ),
+        (
+            Hermitian(randn(ComplexF64, 1, 1)),
+            Composite{Hermitian{ComplexF64, Matrix{ComplexF64}}},
+        ),
+        (
+            Adjoint(randn(ComplexF64, 3, 3)),
+            Composite{Adjoint{ComplexF64, Matrix{ComplexF64}}},
+        ),
+        (
+            Transpose(randn(3)),
+            Composite{Transpose{Float64, Vector{Float64}}},
+        ),
+    ]
+        @test rand_tangent(rng, x) isa T_tangent
+        @test rand_tangent(x) isa T_tangent
+        @test x + rand_tangent(rng, x) isa typeof(x)
+    end
+
+    # Ensure struct fallback errors for non-struct types.
+    @test_throws ArgumentError invoke(rand_tangent, Tuple{AbstractRNG, Any}, rng, 5.0)
+end