Add implementation details docs page, note on propto=True for log_den…

…sity (#192)

* Add implementation details docs page, note on propto=True for log_density

* Rephrase in terms of putting suggestions first

* Wording tweaks

docs/internals.rst

@@ -15,4 +15,4 @@ going on "behind the scenes".
     internals/development
     internals/testing
     internals/documentation
-
+    internals/details

docs/internals/details.rst

@@ -0,0 +1,46 @@
+Stan Implementation Details
+===========================
+
+
+.. _log_density_propto:
+
+Speed of the ``propto`` argument
+--------------------------------
+
+The log density function provided by a Stan model has
+the ability to drop additive constants from the calculation.
+This is indicated by the ``propto`` ("``prop``\ortional  ``to``")
+argument to function.
+
+If you are using an application such as an MCMC algorithm which requires
+gradients and only needs the log density up to a proportion, setting
+``propto=True`` will be at least as fast as setting ``propto=False``
+and is generally recommended (and the default value).
+
+However, in the case of the ``log_density`` function (which does not calculate
+derivatives), this argument has the potential to *slow down* computation, and we
+recommend setting it to ``False`` or timing it for your model of interest before
+proceeding. Note that the default value of ``propto`` is ``True`` for consistency
+with the versions of the function that do calculate gradients, so extra care is needed.
+
+Why is ``log_density`` different?
+_________________________________
+
+The implementation of the ``propto`` argument relies on the presence
+of autodiff types (``var``\s, in the terminology of Stan's math library)
+to determine what is or is not constant with respect to the parameters.
+When the argument is ``False``, the calculation of the log density is able to be
+computed using only variables of type ``double``.
+
+The consequence of this is that, if the ``propto`` argument is set to ``true``,
+the ``log_density`` function will at a minimum need to perform more allocations
+than if it were set to ``false``. There may be an even higher cost, due to functions
+such as |reduce_sum|_ or Stan's ODE integraters changing their behavior when applied
+to autodiff types and performing additional work which is thrown away when gradients
+are not needed. These additional computations can quickly overwhelm any speed up
+received by dropping additive constants in practice.
+
+
+.. |reduce_sum| replace:: ``reduce_sum``
+.. _reduce_sum: https://mc-stan.org/docs/stan-users-guide/reduce-sum.html
+