don't propagate NaN/Inf if Partials are zero (#179)

* don't propagate NaN/Inf if Partials are zero

* fix Calculus.jl test failure on v0.4

* add NaN-safe mode switch

* add documentation for NaN-safe mode

Author: jrevels

.travis.yml

@@ -10,10 +10,10 @@ script:
     - if [[ -a .git/shallow ]]; then git fetch --unshallow; fi
     - if (julia -e 'VERSION < v"0.5" && exit(1)'); then
         julia -e 'include(joinpath(JULIA_HOME, Base.DATAROOTDIR, "julia", "build_sysimg.jl")); build_sysimg(force=true)';
-        julia -e 'Pkg.clone(pwd()); Pkg.build("ForwardDiff"); Pkg.test("ForwardDiff"; coverage=true)';
+        julia -e 'Pkg.clone(pwd()); Pkg.build("ForwardDiff"); Pkg.checkout("DiffBase"); Pkg.test("ForwardDiff"; coverage=true)';
         julia -O3 -e 'include(joinpath(Pkg.dir("ForwardDiff"), "test/SIMDTest.jl"))';
       else
-        julia -e 'Pkg.clone(pwd()); Pkg.build("ForwardDiff"); Pkg.test("ForwardDiff"; coverage=true)';
+        julia -e 'Pkg.clone(pwd()); Pkg.build("ForwardDiff"); Pkg.checkout("DiffBase"); Pkg.test("ForwardDiff"; coverage=true)';
       fi
 after_success:
     - julia -e 'cd(Pkg.dir("ForwardDiff")); Pkg.add("Coverage"); using Coverage; Coveralls.submit(Coveralls.process_folder())'

docs/_rst/source/advanced_usage.rst

@@ -117,6 +117,43 @@ Note that it is usually best to pick a chunk size which divides evenly into the
 dimension. Otherwise, ForwardDiff has to construct and utilize an extra "remainder" chunk to
 complete the calculation.
 
+Fixing issues with NaN/Inf return values
+----------------------------------------
+
+ForwardDiff's default behavior is to return ``NaN`` for undefined derivatives (or otherwise
+mirror the behavior of the function in ``Base``, if it would return an error). This is
+usually the correct thing to do, but in some cases can erroneously "poison" values which
+aren't sensitive to the input and thus cause ForwardDiff to incorrectly return ``NaN`` or
+``Inf`` derivatives. For example:
+
+.. code-block:: julia
+
+    # the dual number's perturbation component is zero, so this
+    # variable should not propagate derivative information
+    julia> log(ForwardDiff.Dual(0.0, 0.0))
+    Dual(-Inf,NaN) # oops, this NaN should be 0.0
+
+Here, ForwardDiff computes the derivative of ``log(0.0)`` as ``NaN`` and then propagates
+this derivative by multiplying it by the perturbation component. Usually, ForwardDiff can
+rely on the identity ``x * 0.0 == 0.0`` to prevent the derivatives from propagating when
+the perturbation component is ``0.0``. However, this identity doesn't hold if ``isnan(y)``
+or ``isinf(y)``, in which case a ``NaN`` derivative will be propagated instead.
+
+It is possible to fix this behavior by checking that the perturbation component is zero
+before attempting to propagate derivative information, but this check can noticeably
+decrease performance (~5%-10% on our benchmarks).
+
+In order to preserve performance in the majority of use cases, ForwardDiff disables this
+check by default. If your code is affected by this ``NaN`` behvaior, you can enable
+ForwardDiff's ``NaN``-safe mode by setting ``NANSAFE_MODE_ENABLED`` to ``true`` in
+ForwardDiff's source (this constant is located in ``src/ForwardDiff.jl`` in the
+package's directory).
+
+In the future, we plan on allowing users and downstream library authors to dynamically
+enable ``NaN``-safe mode via the ``AbstractConfig`` API (see `the relevant issue
+<https://github.com/JuliaDiff/ForwardDiff.jl/issues/181>`_).
+
+
 Hessian of a vector-valued function
 -----------------------------------
 

docs/_sources/advanced_usage.txt

@@ -117,6 +117,43 @@ Note that it is usually best to pick a chunk size which divides evenly into the
 dimension. Otherwise, ForwardDiff has to construct and utilize an extra "remainder" chunk to
 complete the calculation.
 
+Fixing issues with NaN/Inf return values
+----------------------------------------
+
+ForwardDiff's default behavior is to return ``NaN`` for undefined derivatives (or otherwise
+mirror the behavior of the function in ``Base``, if it would return an error). This is
+usually the correct thing to do, but in some cases can erroneously "poison" values which
+aren't sensitive to the input and thus cause ForwardDiff to incorrectly return ``NaN`` or
+``Inf`` derivatives. For example:
+
+.. code-block:: julia
+
+    # the dual number's perturbation component is zero, so this
+    # variable should not propagate derivative information
+    julia> log(ForwardDiff.Dual(0.0, 0.0))
+    Dual(-Inf,NaN) # oops, this NaN should be 0.0
+
+Here, ForwardDiff computes the derivative of ``log(0.0)`` as ``NaN`` and then propagates
+this derivative by multiplying it by the perturbation component. Usually, ForwardDiff can
+rely on the identity ``x * 0.0 == 0.0`` to prevent the derivatives from propagating when
+the perturbation component is ``0.0``. However, this identity doesn't hold if ``isnan(y)``
+or ``isinf(y)``, in which case a ``NaN`` derivative will be propagated instead.
+
+It is possible to fix this behavior by checking that the perturbation component is zero
+before attempting to propagate derivative information, but this check can noticeably
+decrease performance (~5%-10% on our benchmarks).
+
+In order to preserve performance in the majority of use cases, ForwardDiff disables this
+check by default. If your code is affected by this ``NaN`` behvaior, you can enable
+ForwardDiff's ``NaN``-safe mode by setting ``NANSAFE_MODE_ENABLED`` to ``true`` in
+ForwardDiff's source (this constant is located in ``src/ForwardDiff.jl`` in the
+package's directory).
+
+In the future, we plan on allowing users and downstream library authors to dynamically
+enable ``NaN``-safe mode via the ``AbstractConfig`` API (see `the relevant issue
+<https://github.com/JuliaDiff/ForwardDiff.jl/issues/181>`_).
+
+
 Hessian of a vector-valued function
 -----------------------------------
 

docs/_static/basic.css

@@ -4,7 +4,7 @@
  *
  * Sphinx stylesheet -- basic theme.
  *
- * :copyright: Copyright 2007-2015 by the Sphinx team, see AUTHORS.
+ * :copyright: Copyright 2007-2016 by the Sphinx team, see AUTHORS.
  * :license: BSD, see LICENSE for details.
  *
  */
@@ -52,6 +52,8 @@ div.sphinxsidebar {
     width: 230px;
     margin-left: -100%;
     font-size: 90%;
+    word-wrap: break-word;
+    overflow-wrap : break-word;
 }
 
 div.sphinxsidebar ul {
@@ -83,10 +85,6 @@ div.sphinxsidebar #searchbox input[type="text"] {
     width: 170px;
 }
 
-div.sphinxsidebar #searchbox input[type="submit"] {
-    width: 30px;
-}
-
 img {
     border: 0;
     max-width: 100%;
@@ -187,6 +185,13 @@ div.genindex-jumpbox {
 
 /* -- general body styles --------------------------------------------------- */
 
+div.body p, div.body dd, div.body li, div.body blockquote {
+    -moz-hyphens: auto;
+    -ms-hyphens: auto;
+    -webkit-hyphens: auto;
+    hyphens: auto;
+}
+
 a.headerlink {
     visibility: hidden;
 }

docs/_static/css/theme.css

@@ -4,7 +4,7 @@
  *
  * Sphinx JavaScript utilities for all documentation.
  *
- * :copyright: Copyright 2007-2015 by the Sphinx team, see AUTHORS.
+ * :copyright: Copyright 2007-2016 by the Sphinx team, see AUTHORS.
  * :license: BSD, see LICENSE for details.
  *
  */
@@ -124,6 +124,7 @@ var Documentation = {
     this.fixFirefoxAnchorBug();
     this.highlightSearchWords();
     this.initIndexTable();
+    
   },
 
   /**
@@ -252,6 +253,29 @@ var Documentation = {
     });
     var url = parts.join('/');
     return path.substring(url.lastIndexOf('/') + 1, path.length - 1);
+  },
+
+  initOnKeyListeners: function() {
+    $(document).keyup(function(event) {
+      var activeElementType = document.activeElement.tagName;
+      // don't navigate when in search box or textarea
+      if (activeElementType !== 'TEXTAREA' && activeElementType !== 'INPUT' && activeElementType !== 'SELECT') {
+        switch (event.keyCode) {
+          case 37: // left
+            var prevHref = $('link[rel="prev"]').prop('href');
+            if (prevHref) {
+              window.location.href = prevHref;
+              return false;
+            }
+          case 39: // right
+            var nextHref = $('link[rel="next"]').prop('href');
+            if (nextHref) {
+              window.location.href = nextHref;
+              return false;
+            }
+        }
+      }
+    });
   }
 };
 
@@ -260,4 +284,4 @@ _ = Documentation.gettext;
 
 $(document).ready(function() {
   Documentation.init();
-});
+});