Pyro Documentation

Pyro includes several specialized libraries for specific modeling problems:

• Time-Series Modeling: Use pyro.contrib.forecasting for scaling hierarchical, fully Bayesian models of multivariate time series to large datasets.
• Gaussian Processes (GP): Use pyro.contrib.gp for various exact or approximate GP models. Pyro is also compatible with GPyTorch for scalable Gaussian processes.
• Other Applications: Pyro has specialized support and tutorials for Epidemiology, Biological Sequences, Experimental Design, and Object Tracking.

Pyro's primary strengths lie in two areas:

1. Deep Generative Models: Integration with deep learning, specifically through Variational Autoencoders (VAEs) and their variants (e.g., SS-VAE, CVAE, Normalizing Flows).
2. Discrete Latent Variables: Automated exact inference for models with discrete latent variables, such as Hidden Markov Models (HMMs) and Latent Dirichlet Allocation (LDA).

For users needing to customize how inference is performed, Pyro provides tools for implementing custom variational objectives and the pyro.contrib.easyguide utility for managing complex models.

For new users, the recommended learning path is to start with introductory tutorials on probabilistic programming and variational inference, followed by the official PyTorch 'Deep Learning with PyTorch' guide. Once comfortable with PyTorch, follow the installation instructions at pyro.ai and work through the 'Practical Pyro and PyTorch' series, specifically the Bayesian regression tutorial.

Key concepts to master for smooth development include:

• Tensor Shapes: Pyro relies heavily on PyTorch's array broadcasting for parallelizing models and inference. Understanding broadcasting is essential to avoid shape errors.
• Integration: Users can integrate Pyro with existing PyTorch infrastructure using PyroModule or use specialized SVI (Stochastic Variational Inference) implementations for PyTorch or Lightning.

You can launch a Jupyter Notebook server directly from the Docker environment.

Commands:

• make notebook [img=IMAGE_NAME]: Starts a CPU-based Jupyter notebook server.
• make notebook-gpu [img=IMAGE_NAME]: Starts a GPU-enabled Jupyter notebook server.

Once started, access the notebook via the URL provided in the terminal output.

Use the Makefile in the docker directory to build CPU or CUDA-enabled Docker images for Pyro and PyTorch.

Dependencies:

• docker (>= version 17.05)
• nvidia-docker (required for CUDA/GPU images)

Build Options:

• pytorch_branch: Specify the PyTorch branch to build from source (defaults to latest released conda package).
• pyro_branch: Specify the Pyro branch to build from source (defaults to latest released PyPi wheel).
• python_version: Specify the Python version (e.g., 3.6).
• make build: Builds a CPU image.
• make build-gpu: Builds a CUDA/GPU image.

Note for Mac Users: Increase Docker memory to at least 4GB via Preferences --> Advanced before building, especially when building PyTorch from source.

After building an image, you can start a container using make run or make run-gpu.

Commands:

• make run [img=IMAGE_NAME]: Starts a container with a bash shell.
• make run-gpu [img=IMAGE_NAME]: Starts a GPU-enabled container with a bash shell.
• make run cmd=ipython [img=IMAGE_NAME]: Starts a container with an ipython shell.

Volume Mapping: There is a shared volume between the host and the container. The container path is $DOCKER_WORK_DIR and the host path is $HOST_WORK_DIR. These can be configured in the Makefile.

To generate API documentation from docstrings, use the sphinx-apidoc utility with the following syntax:

sphinx-apidoc [options] -o <output_path> <module_path> [exclude_pattern, ...]