Merge pull request #136 from JuliaDiff/ox/debugmode

Add Debug Mode

Author: oxinabox

Project.toml

@@ -1,6 +1,6 @@
 name = "ChainRulesCore"
 uuid = "d360d2e6-b24c-11e9-a2a3-2a2ae2dbcce4"
-version = "0.7.1"
+version = "0.7.2"
 
 [deps]
 MuladdMacro = "46d2c3a1-f734-5fdb-9937-b9b9aeba4221"

docs/make.jl

@@ -11,7 +11,7 @@ DocMeta.setdocmeta!(
         Random.seed!(0)  # frule doctest shows output
 
         using ChainRulesCore
-        # These rules are all actually defined in ChainRules.jl, but we redefine them here to 
+        # These rules are all actually defined in ChainRules.jl, but we redefine them here to
         # avoid the dependency.
         @scalar_rule(sin(x), cos(x))  # frule and rrule doctest
         @scalar_rule(sincos(x), @setup((sinx, cosx) = Ω), cosx, -sinx)  # frule doctest
@@ -28,6 +28,7 @@ makedocs(
         "Introduction" => "index.md",
         "FAQ" => "FAQ.md",
         "Writing Good Rules" => "writing_good_rules.md",
+        "Debug Mode" => "debug_mode.md",
         "API" => "api.md",
     ],
     strict=true,

docs/src/api.md

@@ -30,4 +30,5 @@ Private = false
 ## Internal
 ```@docs
 ChainRulesCore.AbstractDifferential
+ChainRulesCore.debug_mode
 ```

docs/src/debug_mode.md

@@ -0,0 +1,13 @@
+# Debug Mode
+
+ChainRulesCore supports a *debug mode* 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 [`ChainRulesCore.debug_mode`](@ref) 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() -> Bool
+
+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