Add Debug Mode

Author: oxinabox

docs/src/debug_mode.md

@@ -0,0 +1,13 @@
+# Debug Mode
+
+ChainRules supports a [`debug_mode`](@ref) which you can use while writing new rules.
+It provides better error messages.
+If you are developing some new rules, and you get a weird error message,
+it is worth enabling debug mode.
+
+There is some overhead to having it enabled, so it is disabled by default.
+
+To enable redefine the `debug_mode()` function to return `true`.
+```julia
+ChainRulesCore.debug_mode() = true
+```

src/ChainRulesCore.jl

@@ -8,6 +8,7 @@ export Composite, DoesNotExist, InplaceableThunk, One, Thunk, Zero, AbstractZero
 export NO_FIELDS
 
 include("compat.jl")
+include("debug_mode.jl")
 
 include("differentials/abstract_differential.jl")
 include("differentials/abstract_zero.jl")

src/debug_mode.jl

@@ -0,0 +1,13 @@
+"""
+    debug_mode()
+
+Determines if ChainRulesCore is in `debug_mode`.
+Defaults to `false`, but if the user redefines it to return `true` then extra
+information will be shown when errors occur.
+
+Enable via:
+```
+ChainRulesCore.debug_mode() = true
+```
+"""
+debug_mode() = false

src/differential_arithmetic.jl

@@ -86,10 +86,15 @@ function Base.:+(a::Composite{P}, b::Composite{P}) where P
     return Composite{P, typeof(data)}(data)
 end
 function Base.:+(a::P, d::Composite{P}) where P
-    try
-        return construct(P, elementwise_add(backing(a), backing(d)))
-    catch err
-        throw(PrimalAdditionFailedException(a, d, err))
+    net_backing = elementwise_add(backing(a), backing(d))
+    if debug_mode()
+        try
+            return construct(P, net_backing)
+        catch err
+            throw(PrimalAdditionFailedException(a, d, err))
+        end
+    else
+        return construct(P, net_backing)
     end
 end
 Base.:+(a::Composite{P}, b::P) where P = b + a

test/differentials/composite.jl

@@ -128,8 +128,19 @@ end
     @testset "+ with Primals, with inner constructor" begin
         value = StructWithInvariant(10.0)
         diff = Composite{StructWithInvariant}(x=2.0, x2=6.0)
-        @test_throws ChainRulesCore.PrimalAdditionFailedException (value + diff)
-        @test_throws ChainRulesCore.PrimalAdditionFailedException (diff + value)
+
+        @testset "with and without debug mode" begin
+            @assert ChainRulesCore.debug_mode() == false
+            @test_throws MethodError (value + diff)
+            @test_throws MethodError (diff + value)
+
+            ChainRulesCore.debug_mode() = true  # enable debug mode
+            @test_throws ChainRulesCore.PrimalAdditionFailedException (value + diff)
+            @test_throws ChainRulesCore.PrimalAdditionFailedException (diff + value)
+            ChainRulesCore.debug_mode() = false  # disable it again
+        end
+
+
 
         # Now we define constuction for ChainRulesCore.jl's purposes:
         # It is going to determine the root quanity of the invarient