ZhuSuan
ZhuSuan is a python probabilistic programming library for Bayesian deep learning, which conjoins the complimentary advantages of Bayesian methods and deep learning. ZhuSuan is built upon Tensorflow. Unlike existing deep learning libraries, which are mainly designed for deterministic neural networks and supervised tasks, ZhuSuan provides deep learning style primitives and algorithms for building probabilistic models and applying Bayesian inference. The supported inference algorithms include:
- Variational inference with programmable variational posteriors, various objectives and advanced gradient estimators (SGVB, REINFORCE, VIMCO, etc.).
- Importance sampling for learning and evaluating models, with programmable proposals.
- Hamiltonian Monte Carlo (HMC) with parallel chains, and optional automatic parameter tuning.
Installation
ZhuSuan is still under development. Before the first stable release (1.0), please clone the repository and run
pip install .
in the main directory. This will install ZhuSuan and its dependencies automatically. ZhuSuan also requires Tensorflow version 1.0 or later. Because users should choose whether to install the cpu or gpu version of Tensorflow, we do not include it in the dependencies. See Installing Tensorflow.
If you are developing ZhuSuan, you may want to install in an "editable" or "develop" mode. Please refer to the Contribution section below.
Documentation
- Tutorials and API Docs: zhusuan.readthedocs.io
- White Paper: ZhuSuan: A Library for Bayesian Deep Learning
Examples
We provide examples on traditional hierarchical Bayesian models and recent deep generative models.
To run the provided examples, you may need extra dependencies to be installed. This can be done by:
pip install ".[examples]"
- Gaussian: HMC
- Toy 2D Intractable Posterior: SGVB
- Bayesian Neural Networks: SGVB
- Variational Autoencoder (VAE): SGVB, IWAE
- Convolutional VAE: SGVB
- Semi-supervised VAE (Kingma, 2014): SGVB, RWS
- Deep Sigmoid Belief Networks RWS, VIMCO
- Logistic Normal Topic Model: HMC
Citing ZhuSuan
If you find ZhuSuan useful, please consider citing it in your publications. We provide a BibTeX entry of the ZhuSuan white paper below.
@ARTICLE{zhusuan2017, title={ZhuSuan: A Library for Bayesian Deep Learning}, author={Shi, Jiaxin and Chen, Jianfei. and Zhu, Jun and Sun, Shengyang and Luo, Yucen and Gu, Yihong and Zhou, Yuhao}, journal={arXiv preprint arXiv:1709.05870}, year=2017, }
Contribution
To install ZhuSuan in an "editable" or "develop" mode, run
pip install -e .
in the main directory. This installation is removable by:
python setup.py develop --uninstall
Additional dependencies for developments can be installed by:
pip install ".[dev]"
Tests
This command will run automatic tests in the main directory:
python -m unittest discover -v
Test Coverage
After running tests, to ensure test coverage over the developments, run:
coverage report --include="zhusuan/*"
PEP8 Code Style Check
We follow PEP8 python code style. To check, in the main directory, run:
pep8 .
Docs
Docs are written under docs/
directory as RestructuredText (.rst
)
files. index.rst
is the main page. A Tutorial on RestructuredText can be
found here.
API References are automatically generated by
Sphinx. They are under doc/api/
directory and should be regenerated each time when any code changes:
make api
To compile docs into webpages, Run
make html
under docs/
directory. The generated webpages are in docs/_build
and
can be viewed with browsers.