From 2d86b75169bf45f6e0b5d7b5d1ab564d435df1bc Mon Sep 17 00:00:00 2001 From: Guangyao Zhou Date: Thu, 10 Feb 2022 13:11:54 -0800 Subject: [PATCH] Links to blog post and companion paper; Documentation updates (#111) --- README.md | 20 +++++++++++--------- docs/source/conf.py | 5 +---- docs/source/examples.rst | 9 +++++++++ docs/source/index.rst | 8 +++++--- 4 files changed, 26 insertions(+), 16 deletions(-) create mode 100644 docs/source/examples.rst diff --git a/README.md b/README.md index b00843d5..0a567f74 100644 --- a/README.md +++ b/README.md @@ -6,11 +6,13 @@ # PGMax -PGMax implements general factor graphs for discrete probabilistic graphical models (PGMs), and hardware-accelerated differentiable loopy belief propagation (LBP) in [JAX](https://jax.readthedocs.io/en/latest/). +PGMax implements general [factor graphs](https://en.wikipedia.org/wiki/Factor_graph) for discrete probabilistic graphical models (PGMs), and hardware-accelerated differentiable [loopy belief propagation (LBP)](https://en.wikipedia.org/wiki/Belief_propagation) in [JAX](https://jax.readthedocs.io/en/latest/). - **General factor graphs**: PGMax supports easy specification of general factor graphs with potentially complicated topology, factor definitions, and discrete variables with a varying number of states. - **LBP in JAX**: PGMax generates pure JAX functions implementing LBP for a given factor graph. The generated pure JAX functions run on modern accelerators (GPU/TPU), work with JAX transformations (e.g. `vmap` for processing batches of models/samples, `grad` for differentiating through the LBP iterative process), and can be easily used as part of a larger end-to-end differentiable system. +See our [blog post](https://www.vicarious.com/posts/pgmax-factor-graphs-for-discrete-probabilistic-graphical-models-and-loopy-belief-propagation-in-jax/) and [companion paper](https://arxiv.org/abs/2202.04110) for more details. + [**Installation**](#installation) | [**Getting started**](#getting-started) @@ -42,6 +44,7 @@ By default the above commands install JAX for CPU. If you have access to a GPU, ## Getting Started + Here are a few self-contained Colab notebooks to help you get started on using PGMax: - [Tutorial on basic PGMax usage](https://colab.research.google.com/drive/1PQ9eVaOg336XzPqko-v_us3izEbjvWMW?usp=sharing) @@ -52,14 +55,13 @@ Here are a few self-contained Colab notebooks to help you get started on using P ## Citing PGMax -To cite this repository +Please consider citing our [companion paper](https://arxiv.org/abs/2202.04110) if you use PGMax in your work: ``` -@software{pgmax2021github, - author = {Guangyao Zhou* and Nishanth Kumar* and Miguel L\’{a}zaro-Gredilla and Dileep George}, - title = {{PGMax}: {F}actor graph on discrete variables and hardware-accelerated differentiable loopy belief propagation in {JAX}}, - howpublished={\url{http://github.com/vicariousinc/PGMax}}, - version = {0.2.2}, - year = {2022}, +@article{zhou2022pgmax, + author = {Zhou, Guangyao and Kumar, Nishanth and L{\'a}zaro-Gredilla, Miguel and Kushagra, Shrinu and George, Dileep}, + title = {{PGMax: Factor Graphs for Discrete Probabilistic Graphical Models and Loopy Belief Propagation in JAX}}, + journal = {arXiv preprint arXiv:2202.04110}, + year={2022} } ``` -where * indicates equal contribution. +First two authors contributed equally. diff --git a/docs/source/conf.py b/docs/source/conf.py index df682051..96aeff21 100644 --- a/docs/source/conf.py +++ b/docs/source/conf.py @@ -20,10 +20,7 @@ project = "PGMax" copyright = "2021, Vicarious FPC Inc" -author = ( - "Nishanth Kumar, Guangyao (Stannis) Zhou," - + " Miguel Lazaro-Gredilla, Dileep George" -) +author = "Guangyao Zhou, Nishanth Kumar, Miguel Lazaro-Gredilla, Shrinu Kushagra, Dileep George" # The full version, including alpha/beta/rc tags release = "0.2.2" diff --git a/docs/source/examples.rst b/docs/source/examples.rst new file mode 100644 index 00000000..c2e07310 --- /dev/null +++ b/docs/source/examples.rst @@ -0,0 +1,9 @@ +Examples +========= + + +Here are a few self-contained Colab notebooks to help you get started on using PGMax: + +- `Tutorial on basic PGMax usage `_ +- `Implementing max-product LBP `_ for `Recursive Cortical Networks `_ +- `End-to-end differentiable LBP for gradient-based PGM training `_ diff --git a/docs/source/index.rst b/docs/source/index.rst index 4cdbf02b..57b902ce 100644 --- a/docs/source/index.rst +++ b/docs/source/index.rst @@ -1,17 +1,19 @@ PGMax Reference Documentation ============================== -PGMax implements general factor graphs for probabilistic graphical models (PGMs) with discrete variables, and hardware-accelerated differentiable loopy belief propagation (LBP) in `JAX `_. -- General factor graphs: PGMax goes beyond pairwise PGMs, and supports arbitrary factor graph topology, including higher-order factors. -- LBP in JAX: PGMax generates pure JAX functions implementing LBP for a given factor graph. The generated pure JAX functions run on modern accelerators (GPU/TPU), work with JAX transformations (e.g. ``vmap`` for processing batches of models/samples, ``grad`` for differentiating through the LBP iterative process), and can be easily used as part of a larger end-to-end differentiable system. +PGMax implements general `factor graphs `_ for discrete probabilistic graphical models (PGMs), and hardware-accelerated differentiable `loopy belief propagation (LBP) `_ in `JAX `_. +- General factor graphs: PGMax supports easy specification of general factor graphs with potentially complicated topology, factor definitions, and discrete variables with a varying number of states. +- LBP in JAX: PGMax generates pure JAX functions implementing LBP for a given factor graph. The generated pure JAX functions run on modern accelerators (GPU/TPU), work with JAX transformations (e.g. ``vmap`` for processing batches of models/samples, ``grad`` for differentiating through the LBP iterative process), and can be easily used as part of a larger end-to-end differentiable system. +See our `blog post `_ and `companion paper `_ for more details. .. toctree:: :maxdepth: 1 :caption: Getting Started: installation + examples .. toctree:: :maxdepth: 1