Merge pull request #161 from JuliaDiff/ox/check_equal

Rename check_equals to test_approx

Author: oxinabox

Project.toml

@@ -1,6 +1,6 @@
 name = "ChainRulesTestUtils"
 uuid = "cdddcdb0-9152-4a09-a978-84456f9df70a"
-version = "0.6.14"
+version = "0.6.15"
 
 [deps]
 ChainRulesCore = "d360d2e6-b24c-11e9-a2a3-2a2ae2dbcce4"

docs/src/index.md

@@ -124,13 +124,13 @@ Inserting inappropriate zeros can thus hide errors.
 
 ## Custom finite differencing
 
-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.
+If a package is using a custom finite differencing method of testing the `frule`s and `rrule`s, `test_approx` 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 `ZeroTangent()`, `NoTangent()`, and `Tangent`, such that the error messages are helpful.
 
 For example,
 ```julia
-check_equal((@thunk 2*2.0), 4.1)
+test_approx((@thunk 2*2.0), 4.1)
 ```
 shows both the expression and the evaluated `thunk`s
 ```julia

src/ChainRulesTestUtils.jl

@@ -14,7 +14,7 @@ import FiniteDifferences: rand_tangent
 const _fdm = central_fdm(5, 1; max_range=1e-2)
 
 export TestIterator
-export check_equal, test_scalar, test_frule, test_rrule, generate_well_conditioned_matrix
+export test_approx, test_scalar, test_frule, test_rrule, generate_well_conditioned_matrix
 export ⊢
 
 

src/check_result.jl

@@ -4,7 +4,7 @@
 # Note that this must work well both on Differential types and Primal types
 
 """
-    check_equal(actual, expected, [msg]; kwargs...)
+    test_approx(actual, expected, [msg]; kwargs...)
 
 `@test`'s  that `actual ≈ expected`, but breaks up data such that human readable results
 are shown on failures.
@@ -15,7 +15,7 @@ give bread-crumbs into nested structures.
 
 All keyword arguments are passed to `isapprox`.
 """
-function check_equal(
+function test_approx(
     actual::Union{AbstractArray{<:Number},Number},
     expected::Union{AbstractArray{<:Number},Number},
     msg="";
@@ -25,26 +25,26 @@ function check_equal(
 end
 
 for (T1, T2) in ((AbstractThunk, Any), (AbstractThunk, AbstractThunk), (Any, AbstractThunk))
-    @eval function check_equal(actual::$T1, expected::$T2, msg=""; kwargs...)
-        return check_equal(unthunk(actual), unthunk(expected), msg; kwargs...)
+    @eval function test_approx(actual::$T1, expected::$T2, msg=""; kwargs...)
+        return test_approx(unthunk(actual), unthunk(expected), msg; kwargs...)
     end
 end
 
-check_equal(::ZeroTangent, x, msg=""; kwargs...) = check_equal(zero(x), x, msg; kwargs...)
-check_equal(x, ::ZeroTangent, msg=""; kwargs...) = check_equal(x, zero(x), msg; kwargs...)
-check_equal(x::ZeroTangent, y::ZeroTangent, msg=""; kwargs...) = @test true
+test_approx(::ZeroTangent, x, msg=""; kwargs...) = test_approx(zero(x), x, msg; kwargs...)
+test_approx(x, ::ZeroTangent, msg=""; kwargs...) = test_approx(x, zero(x), msg; kwargs...)
+test_approx(x::ZeroTangent, y::ZeroTangent, msg=""; kwargs...) = @test true
 
 # remove once https://github.com/JuliaDiff/ChainRulesTestUtils.jl/issues/113
-check_equal(x::NoTangent, y::Nothing, msg=""; kwargs...) = @test true
-check_equal(x::Nothing, y::NoTangent, msg=""; kwargs...) = @test true
+test_approx(x::NoTangent, y::Nothing, msg=""; kwargs...) = @test true
+test_approx(x::Nothing, y::NoTangent, msg=""; kwargs...) = @test true
 
 # Checking equality with `NotImplemented` reports `@test_broken` since the derivative has intentionally
 # not yet been implemented
 # `@test_broken x == y` yields more descriptive messages than `@test_broken false`
-check_equal(x::ChainRulesCore.NotImplemented, y, msg=""; kwargs...) = @test_broken x == y
-check_equal(x, y::ChainRulesCore.NotImplemented, msg=""; kwargs...) = @test_broken x == y
+test_approx(x::ChainRulesCore.NotImplemented, y, msg=""; kwargs...) = @test_broken x == y
+test_approx(x, y::ChainRulesCore.NotImplemented, msg=""; kwargs...) = @test_broken x == y
 # In this case we check for equality (messages etc. have to be equal)
-function check_equal(
+function test_approx(
     x::ChainRulesCore.NotImplemented, y::ChainRulesCore.NotImplemented, msg=""; kwargs...
 )
     return @test_msg msg x == y
@@ -53,7 +53,7 @@ end
 """
     _can_pass_early(actual, expected; kwargs...)
 Used to check if `actual` is basically equal to `expected`, so we don't need to check deeper
-and can just report `check_equal` as passing.
+and can just report `test_approx` as passing.
 
 If either `==` or `≈` return true then so does this.
 The `kwargs` are passed on to `isapprox`
@@ -69,33 +69,33 @@ function _can_pass_early(actual, expected; kwargs...)
     return false
 end
 
-function check_equal(actual::AbstractArray, expected::AbstractArray, msg=""; kwargs...)
+function test_approx(actual::AbstractArray, expected::AbstractArray, msg=""; kwargs...)
     if _can_pass_early(actual, expected)
         @test true
     else
         @test_msg "$msg: indices must match" eachindex(actual) == eachindex(expected)
         for ii in eachindex(actual)
             new_msg = "$msg $(typeof(actual))[$ii]"
-            check_equal(actual[ii], expected[ii], new_msg; kwargs...)
+            test_approx(actual[ii], expected[ii], new_msg; kwargs...)
         end
     end
 end
 
-function check_equal(actual::Tangent{P}, expected::Tangent{P}, msg=""; kwargs...) where {P}
+function test_approx(actual::Tangent{P}, expected::Tangent{P}, msg=""; kwargs...) where {P}
     if _can_pass_early(actual, expected)
         @test true
     else
         all_keys = union(keys(actual), keys(expected))
         for ii in all_keys
             new_msg = "$msg $P.$ii"
-            check_equal(
+            test_approx(
                 getproperty(actual, ii), getproperty(expected, ii), new_msg; kwargs...
             )
         end
     end
 end
 
-function check_equal(
+function test_approx(
     ::Tangent{ActualPrimal}, expected::Tangent{ExpectedPrimal}, msg=""; kwargs...
 ) where {ActualPrimal,ExpectedPrimal}
     # this will certainly fail as we have another dispatch for that, but this will give as
@@ -104,7 +104,7 @@ function check_equal(
 end
 
 # Some structual differential and a natural differential
-function check_equal(actual::Tangent{P,T}, expected, msg=""; kwargs...) where {T,P}
+function test_approx(actual::Tangent{P,T}, expected, msg=""; kwargs...) where {T,P}
     if _can_pass_early(actual, expected)
         @test true
     else
@@ -114,42 +114,42 @@ function check_equal(actual::Tangent{P,T}, expected, msg=""; kwargs...) where {T
         # the natural differential is allowed to have other properties that we ignore
         for ii in propertynames(actual)
             new_msg = "$msg $P.$ii"
-            check_equal(
+            test_approx(
                 getproperty(actual, ii), getproperty(expected, ii), new_msg; kwargs...
             )
         end
     end
 end
-check_equal(x, y::Tangent, msg=""; kwargs...) = check_equal(y, x, msg; kwargs...)
+test_approx(x, y::Tangent, msg=""; kwargs...) = test_approx(y, x, msg; kwargs...)
 
 # This catches comparisons of Tangents and Tuples/NamedTuple
 # and gives an error message complaining about that. the `@test` will definitely fail
 const LegacyZygoteCompTypes = Union{Tuple,NamedTuple}
-function check_equal(x::Tangent, y::LegacyZygoteCompTypes, msg=""; kwargs...)
+function test_approx(x::Tangent, y::LegacyZygoteCompTypes, msg=""; kwargs...)
     @test_msg "$msg: for structural differentials use `Tangent`" typeof(x) === typeof(y)
 end
-function check_equal(x::LegacyZygoteCompTypes, y::Tangent, msg=""; kwargs...)
-    return check_equal(y, x, msg; kwargs...)
+function test_approx(x::LegacyZygoteCompTypes, y::Tangent, msg=""; kwargs...)
+    return test_approx(y, x, msg; kwargs...)
 end
 
 # Generic fallback, probably a tuple or something
-function check_equal(actual::A, expected::E, msg=""; kwargs...) where {A,E}
+function test_approx(actual::A, expected::E, msg=""; kwargs...) where {A,E}
     if _can_pass_early(actual, expected)
         @test true
     else
         c_actual = collect(actual)
         c_expected = collect(expected)
         if (c_actual isa A) && (c_expected isa E)  # prevent stack-overflow
-            throw(MethodError, check_equal, (actual, expected))
+            throw(MethodError, test_approx, (actual, expected))
         end
-        check_equal(c_actual, c_expected; kwargs...)
+        test_approx(c_actual, c_expected; kwargs...)
     end
 end
 
 ###########################################################################################
 
 """
-_check_add!!_behaviour(acc, val)
+_test_add!!_behaviour(acc, val)
 
 This checks that `acc + val` is the same as `add!!(acc, val)`.
 It matters primarily for types that overload `add!!` such as `InplaceableThunk`s.
@@ -159,25 +159,25 @@ It matters primarily for types that overload `add!!` such as `InplaceableThunk`s
 
 `kwargs` are all passed on to isapprox
 """
-function _check_add!!_behaviour(acc, val; kwargs...)
+function _test_add!!_behaviour(acc, val; kwargs...)
     # Note, we don't test that `acc` is actually mutated because it doesn't have to be
     # e.g. if it is immutable. We do test the `add!!` return value.
     # That is what people should rely on. The mutation is just to save allocations.
     acc_mutated = deepcopy(acc)  # prevent this test changing others
-    return check_equal(add!!(acc_mutated, val), acc + val, "in add!!"; kwargs...)
+    return test_approx(add!!(acc_mutated, val), acc + val, "in add!!"; kwargs...)
 end
 
 # Checking equality with `NotImplemented` reports `@test_broken` since the derivative has
 # intentionally not yet been implemented
 # `@test_broken x == y` yields more descriptive messages than `@test_broken false`
-function _check_add!!_behaviour(acc_mutated, acc::ChainRulesCore.NotImplemented; kwargs...)
+function _test_add!!_behaviour(acc_mutated, acc::ChainRulesCore.NotImplemented; kwargs...)
     return @test_broken acc_mutated == acc
 end
-function _check_add!!_behaviour(acc_mutated::ChainRulesCore.NotImplemented, acc; kwargs...)
+function _test_add!!_behaviour(acc_mutated::ChainRulesCore.NotImplemented, acc; kwargs...)
     return @test_broken acc_mutated == acc
 end
 # In this case we check for equality (not implemented messages etc. have to be equal)
-function _check_add!!_behaviour(
+function _test_add!!_behaviour(
     acc_mutated::ChainRulesCore.NotImplemented,
     acc::ChainRulesCore.NotImplemented;
     kwargs...,

src/deprecated.jl

@@ -1,4 +1,4 @@
-# TODO remove these in version 0.6
+# TODO remove these in version 0.7
 # We are silently deprecating them as there is no alternative we are providing
 
 function Base.isapprox(a, b::Union{AbstractZero,AbstractThunk}; kwargs...)
@@ -35,6 +35,8 @@ end
 # Must be for same primal
 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
 @deprecate(
     rrule_test(f, ȳ, inputs::Tuple{Any,Any}...; kwargs...),
@@ -45,3 +47,6 @@ Base.isapprox(d_ad::Tangent{P}, d_fd::Tangent{Q}; kwargs...) where {P,Q} = false
     frule_test(f, inputs::Tuple{Any,Any}...; kwargs...),
     test_frule(f, ((x ⊢ dx) for (x, dx) in inputs)...; kwargs...)
 )
+
+# renamed
+Base.@deprecate_binding check_equal test_approx

src/testers.jl

@@ -32,7 +32,7 @@ function test_scalar(f, z; rtol=1e-9, atol=1e-9, fdm=_fdm, fkwargs=NamedTuple(),
                 # check that same tangent is produced for tangent 1.0 and 1.0 + 0.0im
                 _, 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...)
+                test_approx(real_tangent, embedded_tangent; isapprox_kwargs...)
             end
         end
         if z isa Complex
@@ -53,7 +53,7 @@ function test_scalar(f, z; rtol=1e-9, atol=1e-9, fdm=_fdm, fkwargs=NamedTuple(),
                 _, back = rrule(f, z)
                 _, real_cotangent = back(real(Δu))
                 _, embedded_cotangent = back(Δu)
-                check_equal(real_cotangent, embedded_cotangent; isapprox_kwargs...)
+                test_approx(real_cotangent, embedded_cotangent; isapprox_kwargs...)
             end
         end
         if Ω isa Complex
@@ -113,7 +113,7 @@ function test_frule(
         res isa Tuple || error("The frule should return (y, ∂y), not $res.")
         Ω_ad, dΩ_ad = res
         Ω = f(deepcopy(xs)...; deepcopy(fkwargs)...)
-        check_equal(Ω_ad, Ω; isapprox_kwargs...)
+        test_approx(Ω_ad, Ω; isapprox_kwargs...)
 
         # TODO: remove Nothing when https://github.com/JuliaDiff/ChainRulesTestUtils.jl/issues/113
         ẋs_is_ignored = isa.(ẋs, Union{Nothing,NoTangent})
@@ -127,10 +127,10 @@ function test_frule(
 
         # Correctness testing via finite differencing.
         dΩ_fd = _make_jvp_call(fdm, (xs...) -> f(deepcopy(xs)...; deepcopy(fkwargs)...), Ω, xs, ẋs, ẋs_is_ignored)
-        check_equal(dΩ_ad, dΩ_fd; isapprox_kwargs...)
+        test_approx(dΩ_ad, dΩ_fd; isapprox_kwargs...)
 
         acc = output_tangent isa Auto ? rand_tangent(Ω) : output_tangent
-        _check_add!!_behaviour(acc, dΩ_ad; rtol=rtol, atol=atol, kwargs...)
+        _test_add!!_behaviour(acc, dΩ_ad; rtol=rtol, atol=atol, kwargs...)
     end  # top-level testset
 end
 
@@ -181,7 +181,7 @@ function test_rrule(
         res === nothing && throw(MethodError(rrule, typeof((f, xs...))))
         y_ad, pullback = res
         y = f(xs...; fkwargs...)
-        check_equal(y_ad, y; isapprox_kwargs...)  # make sure primal is correct
+        test_approx(y_ad, y; isapprox_kwargs...)  # make sure primal is correct
 
         ȳ = output_tangent isa Auto ? rand_tangent(y) : output_tangent
 
@@ -216,8 +216,8 @@ function test_rrule(
                 x̄_ad isa AbstractThunk && check_inferred && _test_inferred(unthunk, x̄_ad)
 
                 # The main test of the actual deriviative being correct:
-                check_equal(x̄_ad, x̄_fd; isapprox_kwargs...)
-                _check_add!!_behaviour(accumulated_x̄, x̄_ad; isapprox_kwargs...)
+                test_approx(x̄_ad, x̄_fd; isapprox_kwargs...)
+                _test_add!!_behaviour(accumulated_x̄, x̄_ad; isapprox_kwargs...)
             end
         end