rename differential types (#153)

* replace DoesNotExist

* replace Composite

* replace Zero

* bump version and compat

Author: mzgubic

Project.toml

@@ -1,6 +1,6 @@
 name = "ChainRulesTestUtils"
 uuid = "cdddcdb0-9152-4a09-a978-84456f9df70a"
-version = "0.6.11"
+version = "0.6.12"
 
 [deps]
 ChainRulesCore = "d360d2e6-b24c-11e9-a2a3-2a2ae2dbcce4"
@@ -11,7 +11,7 @@ Random = "9a3f8284-a2c9-5f02-9a11-845980a1fd5c"
 Test = "8dfed614-e22c-5e08-85e1-65c5234f0b40"
 
 [compat]
-ChainRulesCore = "0.9.39"
+ChainRulesCore = "0.9.44"
 Compat = "3"
 FiniteDifferences = "0.12"
 julia = "1"

docs/src/index.md

@@ -26,7 +26,7 @@ using ChainRulesCore
 
 function ChainRulesCore.frule((Δf, Δx1, Δx2), ::typeof(two2three), x1, x2)
     y = two2three(x1, x2)
-    ∂y = Composite{Tuple{Float64, Float64, Float64}}(Zero(), 2.0*Δx1, 3.0*Δx2)
+    ∂y = Tangent{Tuple{Float64, Float64, Float64}}(ZeroTangent(), 2.0*Δx1, 3.0*Δx2)
     return y, ∂y
 end
 # output
@@ -117,11 +117,11 @@ Test.DefaultTestSet("test_scalar: relu at -0.5", Any[Test.DefaultTestSet("with t
 [`test_frule`](@ref) and [`test_rrule`](@ref) allow you to specify the tangents used for testing.
 This is done by passing in `x ⊢ Δx`, where `x` is the primal and `Δx` is the tangent, in the place of the primal inputs.
 If this is not done the tangent will be automatically generated via `FiniteDifferences.rand_tangent`.
-A special case of this is that if you specify it as `x ⊢ DoesNotExist()` then finite differencing will not be used on that input.
+A special case of this is that if you specify it as `x ⊢ NoTangent()` then finite differencing will not be used on that input.
 Similarly, by setting the `output_tangent` keyword argument, you can specify the tangent for the primal output.
 
 This can be useful when the default provided `FiniteDifferences.rand_tangent` doesn't produce the desired tangent for your type.
-For example the default tangent for an `Int` is `DoesNotExist()`.
+For example the default tangent for an `Int` is `NoTangent()`.
 Which is correct e.g. when the `Int` represents a discrete integer like in indexing.
 But if you are testing something where the `Int` is actually a special case of a real number, then you would want to specify the tangent as a `Float64`.
 
@@ -134,7 +134,7 @@ Inserting inappropriate zeros can thus hide errors.
 
 If a package is using a custom finite differencing method of testing the `frule`s and `rrule`s, `check_equal` function provides a convenient way of comparing [various types](https://www.juliadiff.org/ChainRulesCore.jl/dev/design/many_differentials.html#Design-Notes:-The-many-to-many-relationship-between-differential-types-and-primal-types.) of differentials.
 
-It is effectively `(a, b) -> @test isapprox(a, b)`, but it preprocesses `thunk`s and `ChainRules` differential types `Zero()`, `DoesNotExist()`, and `Composite`, such that the error messages are helpful.
+It is effectively `(a, b) -> @test isapprox(a, b)`, but it preprocesses `thunk`s and `ChainRules` differential types `ZeroTangent()`, `NoTangent()`, and `Tangent`, such that the error messages are helpful.
 
 For example,
 ```julia

src/check_result.jl

@@ -25,13 +25,13 @@ for (T1, T2) in ((AbstractThunk, Any), (AbstractThunk, AbstractThunk), (Any, Abs
     end
 end
 
-check_equal(::Zero, x; kwargs...) = check_equal(zero(x), x; kwargs...)
-check_equal(x, ::Zero; kwargs...) = check_equal(x, zero(x); kwargs...)
-check_equal(x::Zero, y::Zero; kwargs...) = @test true
+check_equal(::ZeroTangent, x; kwargs...) = check_equal(zero(x), x; kwargs...)
+check_equal(x, ::ZeroTangent; kwargs...) = check_equal(x, zero(x); kwargs...)
+check_equal(x::ZeroTangent, y::ZeroTangent; kwargs...) = @test true
 
 # remove once https://github.com/JuliaDiff/ChainRulesTestUtils.jl/issues/113
-check_equal(x::DoesNotExist, y::Nothing; kwargs...) = @test true
-check_equal(x::Nothing, y::DoesNotExist; kwargs...) = @test true
+check_equal(x::NoTangent, y::Nothing; kwargs...) = @test true
+check_equal(x::Nothing, y::NoTangent; kwargs...) = @test true
 
 # Checking equality with `NotImplemented` reports `@test_broken` since the derivative has intentionally
 # not yet been implemented
@@ -75,7 +75,7 @@ function check_equal(actual::AbstractArray, expected::AbstractArray; kwargs...)
     end
 end
 
-function check_equal(actual::Composite{P}, expected::Composite{P}; kwargs...) where P
+function check_equal(actual::Tangent{P}, expected::Tangent{P}; kwargs...) where P
     if _can_pass_early(actual, expected)
         @test true
     else
@@ -87,7 +87,7 @@ function check_equal(actual::Composite{P}, expected::Composite{P}; kwargs...) wh
 end
 
 function check_equal(
-    ::Composite{ActualPrimal}, expected::Composite{ExpectedPrimal}; kwargs...
+    ::Tangent{ActualPrimal}, expected::Tangent{ExpectedPrimal}; kwargs...
 ) where {ActualPrimal, ExpectedPrimal}
     # this will certainly fail as we have another dispatch for that, but this will give as
     # good error message
@@ -96,26 +96,26 @@ end
 
 
 # Some structual differential and a natural differential
-function check_equal(actual::Composite{P, T}, expected; kwargs...) where {T, P}
+function check_equal(actual::Tangent{P, T}, expected; kwargs...) where {T, P}
     if _can_pass_early(actual, expected)
         @test true
     else
         @assert (T <: NamedTuple)  # it should be a structual differential if we hit this
 
-        # We are only checking the properties that are in the Composite
+        # We are only checking the properties that are in the Tangent
         # the natural differential is allowed to have other properties that we ignore
         @testset "$P.$ii" for ii in propertynames(actual)
             check_equal(getproperty(actual, ii), getproperty(expected, ii); kwargs...)
         end
     end
 end
-check_equal(x, y::Composite; kwargs...) = check_equal(y, x; kwargs...)
+check_equal(x, y::Tangent; kwargs...) = check_equal(y, x; kwargs...)
 
-# This catches comparisons of Composites and Tuples/NamedTuple
+# This catches comparisons of Tangents and Tuples/NamedTuple
 # and gives an error message complaining about that
 const LegacyZygoteCompTypes = Union{Tuple,NamedTuple}
-check_equal(::C, ::T; kwargs...) where {C<:Composite,T<:LegacyZygoteCompTypes} = @test C === T
-check_equal(::T, ::C; kwargs...) where {C<:Composite,T<:LegacyZygoteCompTypes} = @test T === C
+check_equal(::C, ::T; kwargs...) where {C<:Tangent,T<:LegacyZygoteCompTypes} = @test C === T
+check_equal(::T, ::C; kwargs...) where {C<:Tangent,T<:LegacyZygoteCompTypes} = @test T === C
 
 # Generic fallback, probably a tuple or something
 function check_equal(actual::A, expected::E; kwargs...) where {A, E}

src/deprecated.jl

@@ -3,30 +3,30 @@
 
 Base.isapprox(a, b::Union{AbstractZero, AbstractThunk}; kwargs...) = isapprox(b, a; kwargs...)
 Base.isapprox(d_ad::AbstractThunk, d_fd; kwargs...) = isapprox(extern(d_ad), d_fd; kwargs...)
-Base.isapprox(d_ad::DoesNotExist, d_fd; kwargs...) = error("Tried to differentiate w.r.t. a `DoesNotExist`")
-# Call `all` to handle the case where `Zero` is standing in for a non-scalar zero
-Base.isapprox(d_ad::Zero, d_fd; kwargs...) = all(isapprox.(extern(d_ad), d_fd; kwargs...))
+Base.isapprox(d_ad::NoTangent, d_fd; kwargs...) = error("Tried to differentiate w.r.t. a `NoTangent`")
+# Call `all` to handle the case where `ZeroTangent` is standing in for a non-scalar zero
+Base.isapprox(d_ad::ZeroTangent, d_fd; kwargs...) = all(isapprox.(extern(d_ad), d_fd; kwargs...))
 
 isapprox_vec(a, b; kwargs...) = isapprox(first(to_vec(a)), first(to_vec(b)); kwargs...)
-Base.isapprox(a, b::Composite; kwargs...) = isapprox(b, a; kwargs...)
-function Base.isapprox(d_ad::Composite{<:Tuple}, d_fd::Tuple; kwargs...)
+Base.isapprox(a, b::Tangent; kwargs...) = isapprox(b, a; kwargs...)
+function Base.isapprox(d_ad::Tangent{<:Tuple}, d_fd::Tuple; kwargs...)
     return isapprox_vec(d_ad, d_fd; kwargs...)
 end
 function Base.isapprox(
-    d_ad::Composite{P, <:Tuple}, d_fd::Composite{P, <:Tuple}; kwargs...
+    d_ad::Tangent{P, <:Tuple}, d_fd::Tangent{P, <:Tuple}; kwargs...
 ) where {P <: Tuple}
     return isapprox_vec(d_ad, d_fd; kwargs...)
 end
 
 function Base.isapprox(
-    d_ad::Composite{P, <:NamedTuple{T}}, d_fd::Composite{P, <:NamedTuple{T}}; kwargs...,
+    d_ad::Tangent{P, <:NamedTuple{T}}, d_fd::Tangent{P, <:NamedTuple{T}}; kwargs...,
 ) where {P, T}
     return isapprox_vec(d_ad, d_fd; kwargs...)
 end
 
 
 # Must be for same primal
-Base.isapprox(d_ad::Composite{P}, d_fd::Composite{Q}; kwargs...) where {P, Q} = false
+Base.isapprox(d_ad::Tangent{P}, d_fd::Tangent{Q}; kwargs...) where {P, Q} = false
 
 
 # From when primal and tangent was passed as a tuple

src/finite_difference_calls.jl

@@ -92,7 +92,7 @@ end
 
 # TODO: remove after https://github.com/JuliaDiff/FiniteDifferences.jl/issues/97
 # For functions which return a tuple, FD returns a tuple to represent the differential. Tuple
-# is not a natural differential, because it doesn't overload +, so make it a Composite.
-_maybe_fix_to_composite(::P, x::Tuple) where {P} = Composite{P}(x...)
-_maybe_fix_to_composite(::P, x::NamedTuple) where {P} = Composite{P}(;x...)
+# is not a natural differential, because it doesn't overload +, so make it a Tangent.
+_maybe_fix_to_composite(::P, x::Tuple) where {P} = Tangent{P}(x...)
+_maybe_fix_to_composite(::P, x::NamedTuple) where {P} = Tangent{P}(;x...)
 _maybe_fix_to_composite(::Any, x) = x

src/iterator.jl

@@ -44,7 +44,7 @@ function Base.hash(iter::TestIterator{<:Any,IT,IS}) where {IT,IS}
 end
 
 # To make it a valid differential: needs at very least `zero` and `+`
-Base.zero(::Type{<:TestIterator}) = Zero()
+Base.zero(::Type{<:TestIterator}) = ZeroTangent()
 function Base.:+(iter1::TestIterator{T,IS,IE}, iter2::TestIterator{T,IS,IE}) where {T,IS,IE}
     return TestIterator{T,IS,IE}(map(+, iter1.data, iter2.data))
 end

src/testers.jl

@@ -30,8 +30,8 @@ function test_scalar(f, z; rtol=1e-9, atol=1e-9, fdm=_fdm, fkwargs=NamedTuple(),
             test_frule(f, z ⊢ Δx; rule_test_kwargs...)
             if z isa Complex
                 # check that same tangent is produced for tangent 1.0 and 1.0 + 0.0im
-                _, real_tangent = frule((Zero(), real(Δx)), f, z; fkwargs...)
-                _, embedded_tangent = frule((Zero(), Δx), f, z; fkwargs...)
+                _, real_tangent = frule((ZeroTangent(), real(Δx)), f, z; fkwargs...)
+                _, embedded_tangent = frule((ZeroTangent(), Δx), f, z; fkwargs...)
                 check_equal(real_tangent, embedded_tangent; isapprox_kwargs...)
             end
         end
@@ -75,7 +75,7 @@ end
 - `inputs` either the primal inputs `x`, or primals and their tangents: `x ⊢ ẋ`
    - `x`: input at which to evaluate `f` (should generally be set to an arbitary point in the domain).
    - `ẋ`: differential w.r.t. `x`, will be generated automatically if not provided
-   Non-differentiable arguments, such as indices, should have `ẋ` set as `DoesNotExist()`.
+   Non-differentiable arguments, such as indices, should have `ẋ` set as `NoTangent()`.
 
 # Keyword Arguments
    - `output_tangent` tangent to test accumulation of derivatives against
@@ -114,11 +114,11 @@ function test_frule(
         check_equal(Ω_ad, Ω; isapprox_kwargs...)
 
         # TODO: remove Nothing when https://github.com/JuliaDiff/ChainRulesTestUtils.jl/issues/113
-        ẋs_is_ignored = isa.(ẋs, Union{Nothing, DoesNotExist})
+        ẋs_is_ignored = isa.(ẋs, Union{Nothing, NoTangent})
         if any(ẋs .== nothing)
             Base.depwarn(
                 "test_frule(f, k ⊢ nothing) is deprecated, use " *
-                "test_frule(f, k ⊢ DoesNotExist()) instead for non-differentiable ks",
+                "test_frule(f, k ⊢ NoTangent()) instead for non-differentiable ks",
                 :test_frule
             )
         end
@@ -142,7 +142,7 @@ end
 - `inputs` either the primal inputs `x`, or primals and their tangents: `x ⊢ ẋ`
     - `x`: input at which to evaluate `f` (should generally be set to an arbitary point in the domain).
     - `x̄`: currently accumulated cotangent, will be generated automatically if not provided
-    Non-differentiable arguments, such as indices, should have `x̄` set as `DoesNotExist()`.
+    Non-differentiable arguments, such as indices, should have `x̄` set as `NoTangent()`.
 
 # Keyword Arguments
  - `output_tangent` the seed to propagate backward for testing (techncally a cotangent).
@@ -191,24 +191,24 @@ function test_rrule(
 
         # Correctness testing via finite differencing.
         # TODO: remove Nothing when https://github.com/JuliaDiff/ChainRulesTestUtils.jl/issues/113
-        x̄s_is_dne = isa.(accumulated_x̄, Union{Nothing, DoesNotExist})
+        x̄s_is_dne = isa.(accumulated_x̄, Union{Nothing, NoTangent})
         if any(accumulated_x̄ .== nothing)
             Base.depwarn(
                 "test_rrule(f, k ⊢ nothing) is deprecated, use " *
-                "test_rrule(f, k ⊢ DoesNotExist()) instead for non-differentiable ks",
+                "test_rrule(f, k ⊢ NoTangent()) instead for non-differentiable ks",
                 :test_rrule
             )
         end
 
         x̄s_fd = _make_j′vp_call(fdm, (xs...) -> f(xs...; fkwargs...), ȳ, xs, x̄s_is_dne)
         for (accumulated_x̄, x̄_ad, x̄_fd) in zip(accumulated_x̄, x̄s_ad, x̄s_fd)
-            if accumulated_x̄ isa Union{Nothing, DoesNotExist}  # then we marked this argument as not differentiable # TODO remove once #113
+            if accumulated_x̄ isa Union{Nothing, NoTangent}  # then we marked this argument as not differentiable # TODO remove once #113
                 @assert x̄_fd === nothing  # this is how `_make_j′vp_call` works
-                x̄_ad isa Zero && error(
-                    "The pullback in the rrule for $f function should use DoesNotExist()" *
-                    " rather than Zero() for non-perturbable arguments."
+                x̄_ad isa ZeroTangent && error(
+                    "The pullback in the rrule for $f function should use NoTangent()" *
+                    " rather than ZeroTangent() for non-perturbable arguments."
                 )
-                @test x̄_ad isa DoesNotExist  # we said it wasn't differentiable.
+                @test x̄_ad isa NoTangent  # we said it wasn't differentiable.
             else
                 x̄_ad isa AbstractThunk && check_inferred && _test_inferred(unthunk, x̄_ad)
 

test/check_result.jl

@@ -1,11 +1,11 @@
 
-struct FakeNaturalDiffWithIsApprox  # For testing overloading isapprox(::Composite) works:
+struct FakeNaturalDiffWithIsApprox  # For testing overloading isapprox(::Tangent) works:
     x
 end
-function Base.isapprox(c::Composite, d::FakeNaturalDiffWithIsApprox; kwargs...)
+function Base.isapprox(c::Tangent, d::FakeNaturalDiffWithIsApprox; kwargs...)
     return isapprox(c.x, d.x, kwargs...)
 end
-function Base.isapprox(d::FakeNaturalDiffWithIsApprox, c::Composite; kwargs...)
+function Base.isapprox(d::FakeNaturalDiffWithIsApprox, c::Tangent; kwargs...)
     return isapprox(c.x, d.x, kwargs...)
 end
 
@@ -15,7 +15,7 @@ end
         check = ChainRulesTestUtils._check_add!!_behaviour
 
         check(10.0, 2.0)
-        check(11.0, Zero())
+        check(11.0, ZeroTangent())
         check([10.0, 20.0],  @thunk([2.0, 0.0]))
 
         check(12.0, InplaceableThunk(@thunk(2.0), X̄ -> error("Should not have in-placed")))
@@ -39,7 +39,7 @@ end
             check_equal(1.0, 1.0+1e-10)  # isapprox _behaviour
             check_equal((1.5, 2.5, 3.5), (1.5, 2.5, 3.5 + 1e-10))
 
-            check_equal(Zero(), 0.0)
+            check_equal(ZeroTangent(), 0.0)
 
             check_equal([1.0, 2.0], [1.0, 2.0])
             check_equal([[1.0], [2.0]], [[1.0], [2.0]])
@@ -51,46 +51,46 @@ end
             check_equal(@not_implemented("a"), @not_implemented("a"))
 
             check_equal(
-                Composite{Tuple{Float64, Float64}}(1.0, 2.0),
-                Composite{Tuple{Float64, Float64}}(1.0, 2.0)
+                Tangent{Tuple{Float64, Float64}}(1.0, 2.0),
+                Tangent{Tuple{Float64, Float64}}(1.0, 2.0)
             )
 
             diag_eg = Diagonal(randn(5))
             check_equal( # Structual == Structural
-                Composite{typeof(diag_eg)}(diag=diag_eg.diag),
-                Composite{typeof(diag_eg)}(diag=diag_eg.diag)
+                Tangent{typeof(diag_eg)}(diag=diag_eg.diag),
+                Tangent{typeof(diag_eg)}(diag=diag_eg.diag)
             )
             check_equal( # Structural == Natural
-                Composite{typeof(diag_eg)}(diag=diag_eg.diag),
+                Tangent{typeof(diag_eg)}(diag=diag_eg.diag),
                 diag_eg
             )
 
             T = (a=1.0, b=2.0)
             check_equal(
-                Composite{typeof(T)}(a=1.0),
-                Composite{typeof(T)}(a=1.0, b=Zero())
+                Tangent{typeof(T)}(a=1.0),
+                Tangent{typeof(T)}(a=1.0, b=ZeroTangent())
             )
             check_equal(
-                Composite{typeof(T)}(a=1.0),
-                Composite{typeof(T)}(a=1.0+1e-10, b=Zero())
+                Tangent{typeof(T)}(a=1.0),
+                Tangent{typeof(T)}(a=1.0+1e-10, b=ZeroTangent())
             )
 
             check_equal(
-                Composite{FakeNaturalDiffWithIsApprox}(; x=1.4),
+                Tangent{FakeNaturalDiffWithIsApprox}(; x=1.4),
                 FakeNaturalDiffWithIsApprox(1.4)
             )
             check_equal(
                 FakeNaturalDiffWithIsApprox(1.4),
-                Composite{FakeNaturalDiffWithIsApprox}(; x=1.4)
+                Tangent{FakeNaturalDiffWithIsApprox}(; x=1.4)
             )
         end
         @testset "negative case" begin
             @test fails(()->check_equal(1.0, 2.0))
             @test fails(()->check_equal(1.0 + im, 1.0 - im))
             @test fails(()->check_equal((1.5, 2.5, 3.5), (1.5, 2.5, 4.5)))
 
-            @test fails(()->check_equal(Zero(), 20.0))
-            @test fails(()->check_equal(10.0, Zero()))
+            @test fails(()->check_equal(ZeroTangent(), 20.0))
+            @test fails(()->check_equal(10.0, ZeroTangent()))
 
             @test fails(()->check_equal([1.0, 2.0], [1.0, 3.9]))
             @test fails(()->check_equal([[1.0], [2.0]], [[1.1], [2.0]]))
@@ -102,12 +102,12 @@ end
         @testset "type negative" begin
             @test fails() do  # these have different primals so should not be equal
                 check_equal(
-                    Composite{Tuple{Float32, Float32}}(1f0, 2f0),
-                    Composite{Tuple{Float64, Float64}}(1.0, 2.0)
+                    Tangent{Tuple{Float32, Float32}}(1f0, 2f0),
+                    Tangent{Tuple{Float64, Float64}}(1.0, 2.0)
                 )
             end
             @test fails() do
-                check_equal((1.0, 2.0), Composite{Tuple{Float64, Float64}}(1.0, 2.0))
+                check_equal((1.0, 2.0), Tangent{Tuple{Float64, Float64}}(1.0, 2.0))
             end
         end