From 3c8ea47c4ebedb9b91facad9b982f2c11622c2c5 Mon Sep 17 00:00:00 2001
From: Cameron Pfiffer <cpfiffer@gmail.com>
Date: Thu, 13 Dec 2018 06:44:02 -0800
Subject: [PATCH] Add a DynamicHMC section to the docs (#623)

* Added a DynamicHMC section.

* Added compositional inference note.
---
 docs/site/_data/navigation.yml |  2 ++
 docs/src/dynamichmc.md         | 29 +++++++++++++++++++++++++++++
 2 files changed, 31 insertions(+)
 create mode 100644 docs/src/dynamichmc.md

diff --git a/docs/site/_data/navigation.yml b/docs/site/_data/navigation.yml
index 20b19b07c..c58c845eb 100644
--- a/docs/site/_data/navigation.yml
+++ b/docs/site/_data/navigation.yml
@@ -31,6 +31,8 @@ docs:
         url: /docs/guide/
       - title: "Advanced Usage"
         url: /docs/advanced/
+      - title: "Using DynamicHMC"
+        url: /docs/dynamichmc/
 
   - title: Library
     children:
diff --git a/docs/src/dynamichmc.md b/docs/src/dynamichmc.md
new file mode 100644
index 000000000..4a58ccc31
--- /dev/null
+++ b/docs/src/dynamichmc.md
@@ -0,0 +1,29 @@
+---
+title: Using DynamicHMC
+permalink: /docs/dynamichmc/
+---
+
+Turing supports the use of [DynamicHMC](https://github.com/tpapp/DynamicHMC.jl) as a sampler through the use of the `DynamicNUTS` function. This is a [faster](https://github.com/TuringLang/Turing.jl/issues/559) version of Turing's native `NUTS` implementation.
+
+`DynamicNUTS` is not appropriate for use in compositional inference. If you intend to use [Gibbs](http://turing.ml/docs/library/#-turinggibbs--type) sampling, you must use Turing's native `NUTS` function.
+
+To use the `DynamicNUTS` function, you must import the `DynamicHMC` package as well as Turing. Turing does not formally require `DynamicHMC` but will include additional functionality if both packages are present.
+
+Here is a brief example of how to apply `DynamicNUTS`:
+
+```julia
+# Import Turing and DynamicHMC.
+using DynamicHMC, Turing
+
+# Model definition.
+@model gdemo(x, y) = begin
+  s ~ InverseGamma(2,3)
+  m ~ Normal(0,sqrt(s))
+  x ~ Normal(m, sqrt(s))
+  y ~ Normal(m, sqrt(s))
+  return s, m
+end
+
+# Pull 2,000 samples using DynamicNUTS.
+chn = sample(gdemo(1.5, 2.0), DynamicNUTS(2000))
+```