Merge pull request #265 from null-a/hmc

HMC

.gitignore

@@ -6,4 +6,5 @@ npm-debug.log
 compiled/
 docs/_build
 docs/_static
-docs/_templates
+docs/_templates
+src/erp.js

Gruntfile.js

@@ -16,7 +16,7 @@ var jslintSettings = {
     src: [
       'Gruntfile.js',
       'src/header.wppl',
-      'src/**/*.js'
+      'src/**/!(erp).js'
     ]
   },
   test: {

docs/development/install.rst

@@ -5,6 +5,7 @@ Installation from GitHub
 
     git clone https://github.com/probmods/webppl.git
     cd webppl
+    ./scripts/transformERP
     npm install
     npm install -g nodeunit grunt-cli
 

docs/development/workflow.rst

@@ -1,13 +1,40 @@
 Workflow
 ========
 
-Before committing changes, run grunt (which runs tests and linting)::
+Committing changes
+------------------
+
+Before committing changes, run grunt (which runs `tests`_ and
+`linting`_)::
 
     grunt
 
 If grunt doesn’t succeed, the `continuous integration tests`_ will fail
 as well.
 
+Modifying erp.ad.js
+-------------------
+
+During development, it is necessary to transform ``src/erp.ad.js``
+after it has been modified by running::
+
+    ./scripts/transformERP
+
+This transforms ERP score functions in order to support automatic
+differentiation using `ad.js <https://github.com/iffsid/ad.js>`_.
+
+For performance reasons, not all code is transformed. All code
+relating to computing scores should therefore be implemented as some
+combination of the following:
+
+* Named functions where the name ends with ``Score`` or ``AD``. e.g.
+  ``function gaussianScore() {}``, ``function sumAD() {}``.
+* Anonymous functions defined as the ``score`` property of an object
+  literal. e.g. ``{ score: function() {} }``
+
+Tests
+-----
+
 To only run the tests, do::
 
     npm test
@@ -23,6 +50,9 @@ nodeunit can also run individual tests or test groups. For example::
 
 See the `nodeunit documentation`_ for details.
 
+Linting
+-------
+
 To only run the linter::
 
     grunt gjslint
@@ -36,6 +66,9 @@ many of them automatically using::
 
     grunt fixjsstyle
 
+Compiling for browser
+---------------------
+
 To compile webppl for use in browser, run::
 
     npm install -g browserify uglifyjs

docs/inference.rst

@@ -100,14 +100,7 @@ MCMC
 
       .. describe:: kernel
 
-         The transition kernel to use for inference. The following
-         kernels are available:
-
-         =========  ============================================
-         Option     Description
-         =========  ============================================
-         ``'MH'``   Single site Metropolis-Hastings [wingate11]_
-         =========  ============================================
+         The transition kernel to use for inference. See `Kernels`_.
 
          Default: ``'MH'``
 
@@ -138,6 +131,46 @@ MCMC
 
      MCMC(model, { samples: 1000, lag: 100, burn: 5 });
 
+Kernels
+^^^^^^^
+
+The following kernels are available:
+
+.. describe:: MH
+
+   Implements single site Metropolis-Hastings. [wingate11]_
+
+Example usage::
+
+    MCMC(model, { kernel: 'MH' });
+
+.. describe:: HMC
+
+   Implements Hamiltonian Monte Carlo. [neal11]_
+
+   As the HMC algorithm is only applicable to continuous variables,
+   ``HMC`` is a cycle kernel which includes a MH step for discrete
+   variables.
+
+   The following options are supported:
+
+   .. describe:: steps
+
+      The number of steps to take per-iteration.
+
+      Default: ``5``
+
+   .. describe:: stepSize
+
+      The size of each step.
+
+      Default: ``0.1``
+
+Example usage::
+
+    MCMC(model, { kernel: 'HMC' });
+    MCMC(model, { kernel: { HMC: { steps: 10, stepSize: 1 }}});
+
 Incremental MH
 --------------
 
@@ -224,7 +257,7 @@ SMC
 
       .. describe:: rejuvKernel
 
-         The :js:func:`MCMC` kernel to use for rejuvenation.
+         The MCMC kernel to use for rejuvenation. See `Kernels`_.
 
          Default: ``'MH'``
 
@@ -240,6 +273,9 @@ SMC
                compilation." International Conference on Artificial
                Intelligence and Statistics. 2011.
 
+.. [neal11] Radford M. Neal, "MCMC using Hamiltonian dynamics."
+            Handbook of Markov Chain Monte Carlo 2 (2011).
+
 .. [ritchie15] Daniel Ritchie, Andreas Stuhlmüller, and Noah D.
                Goodman. "C3: Lightweight Incrementalized MCMC for
                Probabilistic Programs using Continuations and Callsite

examples/ldaCollapsed.wppl

@@ -20,7 +20,7 @@ var makeDirichletDiscrete = function(pseudocounts) {
   };
   var ddObserve = function(val) {
     var pc = globalStore[ddname];  // get current sufficient stats
-    factor(discreteERP.score([util.normalizeArray(pc)], val));
+    factor(discreteERP.score([normalize(pc)], val));
     // score based on predictive distribution (normalize counts)
     globalStore[ddname] = addCount(pc, val); // update sufficient stats
   };

package.json

@@ -13,6 +13,7 @@
     "test": "tests"
   },
   "dependencies": {
+    "ad.js": "^1.4.1",
     "amdefine": "^1.0.0",
     "ast-types": "^0.8.13",
     "escodegen": "^1.7.0",
@@ -44,7 +45,8 @@
     "through2": "^2.0.0"
   },
   "scripts": {
-    "test": "nodeunit tests/test-*.js"
+    "test": "nodeunit tests/test-*.js",
+    "postinstall": "./scripts/transformERP"
   },
   "bugs": {
     "url": "https://github.com/probmods/webppl/issues"

scripts/transformERP

@@ -0,0 +1,13 @@
+#!/usr/bin/env node
+
+'use strict';
+
+var fs = require('fs');
+var path = require('path');
+var adscorers = require('../src/transforms/adscorers').adscorers;
+
+var inFile = path.join(__dirname, '../src/erp.ad.js');
+var outFile = path.join(__dirname, '../src/erp.js');
+
+var code = fs.readFileSync(inFile, 'utf8');
+fs.writeFileSync(outFile, adscorers(code));

src/ad.js

@@ -0,0 +1,8 @@
+var _ = require('underscore');
+var ad = require('ad.js')({ mode: 'r', noHigher: true });
+
+ad.isTape = function(obj) {
+  return _.has(obj, 'primal');
+};
+
+module.exports = ad;

src/aggregation.js

@@ -1,13 +1,16 @@
 'use strict';
 
+var _ = require('underscore');
 var erp = require('./erp');
 var util = require('./util');
+var ad = require('./ad');
 
 var Histogram = function() {
   this.hist = {};
 };
 
 Histogram.prototype.add = function(value) {
+  var value = untapify(value);
   var k = util.serialize(value);
   if (this.hist[k] === undefined) {
     this.hist[k] = { prob: 0, val: value };
@@ -26,6 +29,7 @@ var MAP = function(retainSamples) {
 };
 
 MAP.prototype.add = function(value, score) {
+  var value = untapify(value);
   if (this.retainSamples) {
     this.samples.push(value);
   }
@@ -45,6 +49,16 @@ MAP.prototype.toERP = function() {
   return erp;
 };
 
+// Recursively untapify objects. ad.js already does this for arrays,
+// here we extend that to other objects.
+function untapify(x) {
+  if (_.isObject(x) && !_.isArray(x) && !ad.isTape(x)) {
+    return _.mapObject(x, untapify);
+  } else {
+    return ad.untapify(x);
+  }
+}
+
 module.exports = {
   Histogram: Histogram,
   MAP: MAP