PyHGF: A Neural Network Library for Predictive Coding

PyHGF is a Python library for creating and manipulating dynamic probabilistic networks for predictive coding. These networks approximate Bayesian inference by optimising beliefs through the diffusion of predictions and precision-weighted prediction errors. The graph structure remains flexible during message-passing steps, allowing for dynamic adjustments. They can be used as a biologically plausible cognitive model in computational neuroscience or as a generalisation of Bayesian filtering for designing efficient, modular decision-making agents. With the current version you can:

• Build arbitrarily sized networks with the generalised Hierarchical Gaussian Filters (Weber et al., 2026)
• Use generalised Bayesian filtering with distributions from the exponential family (Mathys & Weber, 2020)
• Define custom planning and action selection functions throught trajectories sampling (e.g. sophisticated inference, Friston et al., 2020)
• Learn in deep predictive coding networks using a fast and scalable rethinking of prospective configuration (Song et al., 2024) from closed-form updates and volatility learning.

The framework support both a JAX and Rust backend. It is designed to be adaptable to other algorithms. The core functions are differentiable and JIT-compiled where applicable. The library is optimised for modularity and ease of use, allowing seamless integration with other libraries in the ecosystem for Bayesian inference and optimisation. You can find the method paper describing the toolbox here.

• 📖 API Documentation
• ✏️ Tutorials and examples

Getting started

Installation

The last official release can be downloaded from PIP:

pip install pyhgf

This is the default CPU version optimised for sampling nodalised networks. If you want to use a GPU or JAX >=0.7.0 please refer to the installation page.

The current version under development can be installed from the master branch of the GitHub folder:

pip install “git+https://github.com/ComputationalPsychiatry/pyhgf.git”

How does it work?

Dynamic networks are fully defined by the following variables:

• The attributes (dictionary) that store each node's states and parameters (e.g. value, precision, learning rates, volatility coupling, ...).
• The edges (tuple) that lists, for each node, the indexes of the parents and children.
• A set of update functions. An update function receive a network tuple and returns an updated network tuple.
• An update sequence (tuple) of callables (update functions) and pointers (nodes).

The generative model behind these update functions, and the tools to assemble networks from probabilistic nodes, are covered in the following tutorials:

Tutorial	Colab
Introduction to the Generalised Hierarchical Gaussian Filter
Creating and manipulating networks of probabilistic nodes

The Generalised Hierarchical Gaussian Filter

Generalised Hierarchical Gaussian Filters (gHGF) are specific instances of dynamic networks where node encodes a Gaussian distribution that can inherit its value (mean) and volatility (variance) from other nodes. The presentation of a new observation at the lowest level of the hierarchy (i.e., the input node) triggers a recursive update of the nodes' belief (i.e., posterior distribution) through top-down predictions and bottom-up precision-weighted prediction errors. The resulting probabilistic network operates as a Bayesian filter, and a response function can parametrise actions/decisions given the current beliefs. By comparing those behaviours with actual outcomes, a surprise function can be optimised over a set of free parameters. The Hierarchical Gaussian Filter for binary and continuous inputs was first described in Mathys et al. (2011, 2014), and later implemented in the Matlab HGF Toolbox (part of TAPAS (Frässle et al. 2021).

Model fitting

Here we demonstrate how to fit forwards a two-level binary Hierarchical Gaussian filter. The input time series are binary observations using an associative learning task Iglesias et al. (2013).

from pyhgf.model import Network
from pyhgf import load_data

# Load time series example data (observations, decisions)
u, y = load_data("binary")

# Create a two-level binary HGF from scratch
hgf = (
    Network()
    .add_nodes(kind="binary-state")
    .add_nodes(kind="continuous-state", value_children=0)
)

# add new observations
hgf.input_data(input_data=u)

# visualisation of the belief trajectories
hgf.plot_trajectories()

Surprise

from pyhgf.response import binary_softmax_inverse_temperature

# compute the model's surprise (-log(p))
# using the binary softmax with inverse temperature as the response model
surprise = hgf.surprise(
    response_function=binary_softmax_inverse_temperature,
    response_function_inputs=y,
    response_function_parameters=4.0,
)
print(f"Sum of surprises = {surprise.sum()}")

Model's surprise = 138.8992462158203

Generalised Bayesian filtering

The framework supports online Bayesian filtering over any distribution in the exponential family (Mathys & Weber, 2020). Because these distributions share a common mathematical form, the posterior update reduces to a simple rule over the expected sufficient statistics $\xi$ and a pseudo-count $\nu$ that acts as an inverse learning rate. When the data source is non-stationary, $\nu$ can be kept fixed for a constant learning rate, or it can be dynamically adapted through a Hierarchical Gaussian Filter, giving the agent a volatility-sensitive learning rate that speeds up when the environment changes and slows down when it is stable.

from pyhgf.model import Network
import numpy as np

# Create a generalised filter for a 2D normal distribution
bivariate_normal = (
    Network()
    .add_nodes(
        kind="ef-state",
        nus=8.0,
        learning="generalised-filtering",
        distribution="multivariate-normal",
        dimension=2,
    )
    .input_data(input_data=spiral_data)
)

Tutorial	Colab
Generalised Bayesian Filtering of exponential family distributions

Planning and acting

Filtering describes the perceptual side of an agent: how beliefs are updated once an observation arrives. The same network can also be run forwards, sampling trajectories from its own generative model to estimate the outcomes that each candidate action would produce. Actions are then selected from the relevance of those planned trajectories, which covers policies such as sophisticated inference (Friston et al., 2020).

Tutorial	Colab
Planning and acting with predictive coding networks

Learning in deep predictive coding networks

The framework extends predictive coding to deep neural networks through prospective configuration (Song et al., 2024): before updating any weight, the network first infers the most likely activations at every layer by settling prediction errors across the hierarchy, and only then adjusts the coupling strengths (weights). This two-phase infer-then-update cycle avoids the catastrophic interference that plagues standard backpropagation and naturally yields precision-weighted learning, where the balance of uncertainty between inputs and outputs controls the depth at which weights change.

Tutorial	Colab
Learning in deep predictive coding networks: the theory
Learning in deep networks with prospective configuration

Tutorial	Colab
Building custom deep network architectures
Convolutional predictive coding networks
Transformer predictive coding networks

Acknowledgments

This implementation of the Hierarchical Gaussian Filter was inspired by the original Matlab HGF Toolbox. A Julia implementation of the gHGF is also available here.

The development of PyHGF is supported by:

References

1. Legrand, N., Weber, L., Waade, P. T., Møller Daugaard, A. H., Khodadadi, M., Mikuš, N., & Mathys, C. (2026). pyhgf: A neural network library for predictive coding. PLOS Computational Biology, 22(6), Article e1014340. https://doi.org/10.1371/journal.pcbi.1014340
2. Mathys, C., Daunizeau, J., Friston, K. J., & Stephan, K. E. (2011). A Bayesian foundation for individual learning under uncertainty. Frontiers in Human Neuroscience, 5, Article 39. https://doi.org/10.3389/fnhum.2011.00039
3. Mathys, C. D., Lomakina, E. I., Daunizeau, J., Iglesias, S., Brodersen, K. H., Friston, K. J., & Stephan, K. E. (2014). Uncertainty in perception and the Hierarchical Gaussian Filter. Frontiers in Human Neuroscience, 8, Article 825. https://doi.org/10.3389/fnhum.2014.00825
4. Weber, L. A., Waade, P. T., Legrand, N., Møller, A. H., Stephan, K. E., & Mathys, C. (2026). The generalized Hierarchical Gaussian Filter. eLife, 15, Article RP110174. https://doi.org/10.7554/eLife.110174.1
5. Frässle, S., Aponte, E. A., Bollmann, S., Brodersen, K. H., Do, C. T., Harrison, O. K., Harrison, S. J., Heinzle, J., Iglesias, S., Kasper, L., Lomakina, E. I., Mathys, C., Müller-Schrader, M., Pereira, I., Petzschner, F. H., Raman, S., Schöbi, D., Toussaint, B., Weber, L. A., … Stephan, K. E. (2021). TAPAS: An open-source software package for translational neuromodeling and computational psychiatry. Frontiers in Psychiatry, 12, Article 680811. https://doi.org/10.3389/fpsyt.2021.680811
6. Iglesias, S., Kasper, L., Harrison, S. J., Manka, R., Mathys, C., & Stephan, K. E. (2021). Cholinergic and dopaminergic effects on prediction error and uncertainty responses during sensory associative learning. NeuroImage, 226, Article 117590. https://doi.org/10.1016/j.neuroimage.2020.117590
7. Mathys, C., & Weber, L. (2020). Hierarchical Gaussian filtering of sufficient statistic time series for active inference. In T. Verbelen, P. Lanillos, C. L. Buckley, & C. De Boom (Eds.), Active inference (Communications in Computer and Information Science, Vol. 1326, pp. 52–58). Springer. https://doi.org/10.1007/978-3-030-64919-7_7
8. Friston, K., Da Costa, L., Hafner, D., Hesp, C., & Parr, T. (2021). Sophisticated inference. Neural Computation, 33(3), 713–763. https://doi.org/10.1162/neco_a_01351
9. Song, Y., Millidge, B., Salvatori, T., Lukasiewicz, T., Xu, Z., & Bogacz, R. (2024). Inferring neural activity before plasticity as a foundation for learning beyond backpropagation. Nature Neuroscience, 27(2), 348–358. https://doi.org/10.1038/s41593-023-01514-1