Merge pull request #132 from stan-dev/bugfix/issue_48_3

Added relative tolerance documentation back (Issue #48)

Author: mitzimorris

src/functions-reference/higher-order_functions.Rmd

@@ -330,11 +330,15 @@ integrator separates parameter values, `theta`, from data values, `x_r`.
 ### Call to the 1D Integrator
 
 <!-- vector; integrate_1d; (function integrand, real a, real b, real[] theta, real[] x_r, int[] x_i); -->
+\index{{\tt \bfseries integrate\_1d }!{\tt (function integrand, real a, real b, real[] theta, real[] x\_r, int[] x\_i): vector}|hyperpage}
+
+`vector` **`integrate_1d`** `(function integrand, real a, real b, real[] theta, real[] x_r, int[] x_i)`<br>\newline
+Integrates the integrand from a to b.
 
 <!-- vector; integrate_1d; (function integrand, real a, real b, real[] theta, real[] x_r, int[] x_i), real relative_tolerance); -->
 \index{{\tt \bfseries integrate\_1d }!{\tt (function integrand, real a, real b, real[] theta, real[] x\_r, int[] x\_i, real relative\_tolerance): vector}|hyperpage}
 
-`vector` **`integrate\_1d`** `(function integrand, real a, real b, real[] theta, real[] x_r, int[] x_i, real relative_tolerance)`<br>\newline
+`vector` **`integrate_1d`** `(function integrand, real a, real b, real[] theta, real[] x_r, int[] x_i, real relative_tolerance)`<br>\newline
 Integrates the integrand from a to b with the given relative tolerance.
 
 
@@ -355,8 +359,10 @@ The arguments represent
 * *`theta`*: parameters only, type `real[]`,
 * *`x_r`*: real data only, type `real[]`,
 * *`x_i`*: integer data only, type `int[]`.
-* *`relative_tolerance`*: relative tolerance for the 1d integrator (recommended default of 1e-8), type `real`, data only.
 
+A `relative_tolerance` argument can optionally be provided for more control over the algorithm:
+
+* *`relative_tolerance`*: relative tolerance for the 1d integrator, type `real`, data only.
 
 #### Return value
 

src/stan-users-guide/one-dimensional-integrals.Rmd

@@ -85,7 +85,7 @@ model {
   target += log(integrate_1d(normal_density,
                              left_limit,
                              positive_infinity(),
-                             { mu, sigma }, x_r, x_i, 1e-8));
+                             { mu, sigma }, x_r, x_i));
 }
 ```
 
@@ -120,9 +120,11 @@ $$
   \frac{{|I_{n + 1} - I_n|}}{{|I|_{n + 1}}} < \text{relative tolerance}
 $$
 
-Following the Boost library recommendations, a sensible value for the
-`relative_tolerance` parameter is the square root of the machine epsilon
-of double precision floating point numbers (around `1e-8`).
+The `relative_tolerance` parameter can be optionally specified as the
+last argument to `integrate_1d`. By default, `integrate_1d` follows the
+Boost library recommendation of setting `relative_tolerance` to the square
+root of the machine epsilon of double precision floating point numbers
+(about `1e-8`).
 
 ### Zero-crossing Integrals {#zero-crossing}