Some minor changes (#2643)

* Improve sample docstring

* Cast scaling in metropolis to double

* Update advi+adapt_diag_grad

* Update doc of nuts._Tree.extend

* Add adapt_diag_grad to release notes

Author: aseyboldt

RELEASE-NOTES.md

@@ -1,5 +1,10 @@
 # Release Notes
 
+## PyMC 3.3. (Unreleased)
+
+- Improve NUTS initialization `advi+adapt_diag_grad` and add `jitter+adapt_diag_grad` (#2643)
+
+
 ## PyMC3 3.2 (October 10, 2017)
 
 ### New features

pymc3/sampling.py

@@ -236,8 +236,9 @@ def sample(draws=500, step=None, init='auto', n_init=200000, start=None,
         BLAS. In those cases it might be faster to set this to one.
     tune : int
         Number of iterations to tune, if applicable (defaults to 500).
-        These samples will be drawn in addition to samples and discarded
-        unless discard_tuned_samples is set to True.
+        Samplers adjust the step sizes, scalings or similar during
+        tuning. These samples will be drawn in addition to samples
+        and discarded unless discard_tuned_samples is set to True.
     nuts_kwargs : dict
         Options for the NUTS sampler. See the docstring of NUTS
         for a complete list of options. Common options are

pymc3/step_methods/hmc/nuts.py

@@ -285,9 +285,10 @@ def extend(self, direction):
         If direction is larger than 0, extend it to the right, otherwise
         extend it to the left.
 
-        Return a tuple `(diverging, turning)` of type (bool, bool).
-        `diverging` indicates, that the tree extension was aborted because
-        the energy change exceeded `self.Emax`. `turning` indicates that
+        Return a tuple `(diverging, turning)`. `diverging` indicates if the
+        tree extension was aborted because the energy change exceeded
+        `self.Emax`. If so, it is a tuple containing details about the reason.
+        Otherwise, it will be `False`. `turning` indicates that
         the tree extension was stopped because the termination criterior
         was reached (the trajectory is turning back).
         """

pymc3/step_methods/hmc/quadpotential.py

@@ -198,21 +198,21 @@ def _update(self, var):
 
     def adapt(self, sample, grad):
         """Inform the potential about a new sample during tuning."""
-        self._grads1[:] += grad ** 2
-        self._grads2[:] += grad ** 2
+        self._grads1[:] += np.abs(grad)
+        self._grads2[:] += np.abs(grad)
         self._ngrads1 += 1
         self._ngrads2 += 1
 
         if self._n_samples <= 150:
             super().adapt(sample, grad)
         else:
-            self._update(self._ngrads1 / self._grads1)
+            self._update((self._ngrads1 / self._grads1) ** 2)
 
         if self._n_samples > 100 and self._n_samples % 100 == 50:
             self._ngrads1 = self._ngrads2
-            self._ngrads2 = 0
+            self._ngrads2 = 1
             self._grads1[:] = self._grads2
-            self._grads2[:] = 0
+            self._grads2[:] = 1
 
 
 class _WeightedVariance(object):

pymc3/step_methods/metropolis.py

@@ -112,7 +112,7 @@ def __init__(self, vars=None, S=None, proposal_dist=None, scaling=1.,
         else:
             raise ValueError("Invalid rank for variance: %s" % S.ndim)
 
-        self.scaling = np.atleast_1d(scaling)
+        self.scaling = np.atleast_1d(scaling).astype('d')
         self.tune = tune
         self.tune_interval = tune_interval
         self.steps_until_tune = tune_interval