Add MLDA stepper (#3926)

* Add basic MLDA-MCMC algorithm (proposal and step method)

* Add example scripts for MLDA

* Make coarse_models kwarg into a normal argument

* Fix docstring in MLDA class

* Fix examples code style/comments

* Remove redundant code, improve comments

* Make MLDA do block sampling by default

* Add new MLDA example with FEniCS black box component

* Small change in readme

* Add run instructions in readme

* Change example parameters in sample()

* Minor changes and comments

* Add extra parameters in readme

* Number of chains change

* Make changes to mlda example parameters, go back to compound sampling for mlda by default, edit readme accordingly

* Updated the FEniCS code so it's more efficient

* Add eigenpairs projection and change input parameters

* Edit readme to reflect projection function

* Add compound step support and improve example.py

* Update readme

* Add new tests tests, most of them failing

* Fix test_types bug

* Refactoring of MLDA to allow retaining all methods information

* Add more tests

* Pass more parameters to Metropolis init

* Complete tuning continuation, add basic block/coumpound parameter

* Remove some mlda if statements and simplify other parts

* Change example parameters

* Add and fix tests

* Add some comments and remove redundant code

* Add xfail to test_models_utils test when new pandas version are used

* Add description to test_examples for multilevel normal example

* Remove xfail related to pandas in test_models_utils, remove redundant function from test_step

* Try removing failing test

* Remove redundant code

* Skip some failing tests

* Add sine wave test in test_examples

* Change true parameters index

* Fix index j in coarse models loop to avoid warning

* Remove sine test

* Remove unused library

* Improve docstrings and remove some redundant code/comments

* Revert some pointless changes to tests

* Fix style

* Add notebook example and utility code

* Remove old mlda example and update notebook

* Update notebook again

* Change the citation and add a use example to the MLDA docstring

* Change competence to be incompatible with discrete vars, remove discrete var detection code from MLDA init

* Add young warning and change default subsampling value

* Add more comments, change sys.exit to exception, change tests to reflect that, convert coarse_models to positional argument in MLDA

* Add is_mlda_flag to prevent tuning reset when Metropolis is used as the base sampler of MLDA

* Add more extensive docstrings

* Re-run and re-render notebook after changes

* Add tuning for tune and scaling and refactor some parameter names to be consistent with what they represent

* Regenerate notebook and add .py version of it

* Delete notebook with old name

* Fix pylint errors, move .py example, fix failing test

* Add computer specs to notebook

* Change class checks to using isinstance

* Add more tests for stats, competence, etc and fix bug with tune flag not being overriden in compound sub-methods

* Remove duplicate sample_except()

* Move is_mlda_base checks for reseting inside Metropolis' reset_tuning()

* Add DEMetropolis to notebook

* Add MLDA groundwater flow notebook which uses blocked samplers only

* Add comparison with DEMCMC-Z amd longer runs for convergence in example notebook

* Add separate subsampling rates

* Edit docstring

* Fix handling of one integer for subsampling rate

* Add tests and change subsampling argument name in examples/tests

* Add notebook with extra benchmarks and tuning demo

* Change subsampling rate to rates in notebook examples (including new benchmarking one)

* Do not count stuck proposals from lower chain as accepted

* Convert base_scaling stats to one stat of type object, modify tests for stats and also test for declining acceptance rate

* Fix pm.DensityDist in notebooks/scripts by replacing with pm.Potential

This is done because of the bug described in arviz-devs/arviz#1279. The commit also changes a few parameters in the MLDA .py example to match the ones in the equivalent notebook.

* Move MLDA and RecursiveDAProposal classes to new mlda.py file, add a new MetropolisMLDA class which inherits Metropolis and just alters the reset_tuning function, modify test_step and __init__ files accordingly

* Remove MLDA notebooks and .py example script, remove code that uses fenics and delete reference to example from MLDA class docstring

* Blacken MLDA code and tests, separate MLDA type tests from other methods, fix some stylistic issues

* Add simple linear regression notebook which can serve as MLDA starting point for new users

* Modify some comments in the simple notebook and re-run

* Add typing to mlda.py

* Connect the two separate strings in mlda.py

* Modify simple linear regression notebook: coarse model uses subset of data, more comments, performance comparison with Metropolis

* Add more comments, format using PyMC3 NB style guide (blacken, watermark, arviz style, imports, etc)

* Add simple regression notebook to table of examples

* Add gravity surveying notebook

* Add MLDA line in 3.9.x release notes

* Edit notebook imports to adhere to nbqa-isort rules

* Add gravity notebook to table of contents

Co-authored-by: Mikkel Lykkegaard <[email protected]>

Author: gmingas

RELEASE-NOTES.md

@@ -11,6 +11,7 @@
 
 ### New features
 - `sample_posterior_predictive_w` can now feed on `xarray.Dataset` - e.g. from `InferenceData.posterior`. (see [#4042](https://github.com/pymc-devs/pymc3/pull/4042))
+- Add MLDA, a new stepper for multilevel sampling. MLDA can be used when a hierarchy of approximate posteriors of varying accuracy is available, offering improved sampling efficiency especially in high-dimensional problems and/or where gradients are not available (see [#3926](https://github.com/pymc-devs/pymc3/pull/3926))
 
 
 ## PyMC3 3.9.3 (11 August 2020)

docs/source/notebooks/MLDA_gravity_surveying.ipynb

@@ -58,5 +58,7 @@ Gallery.contents = {
     "GLM-hierarchical-advi-minibatch": "Variational Inference",
     "ODE_with_manual_gradients": "Inference in ODE models",
     "ODE_API_introduction": "Inference in ODE models",
-    "probabilistic_matrix_factorization": "Case Studies"
+    "probabilistic_matrix_factorization": "Case Studies",
+    "MLDA_simple_linear_regression": "MCMC",
+    "MLDA_gravity_surveying": "MCMC"
 }

docs/source/notebooks/MLDA_simple_linear_regression.ipynb

@@ -21,6 +21,7 @@
 from .metropolis import BinaryMetropolis
 from .metropolis import BinaryGibbsMetropolis
 from .metropolis import CategoricalGibbsMetropolis
+from .mlda import MLDA, MetropolisMLDA, RecursiveDAProposal
 from .metropolis import NormalProposal
 from .metropolis import CauchyProposal
 from .metropolis import LaplaceProposal

docs/source/notebooks/table_of_contents_examples.js

@@ -577,7 +577,7 @@ def __init__(self, vars=None, S=None, proposal_dist=None, lamb=None, scaling=0.0
 
         if S is None:
             S = np.ones(model.ndim)
-        
+
         if proposal_dist is not None:
             self.proposal_dist = proposal_dist(S)
         else: