Metadata-Version: 2.4
Name: pyhgf
Version: 0.3.1
Classifier: Programming Language :: Rust
Classifier: Programming Language :: Python :: Implementation :: CPython
Classifier: Programming Language :: Python :: Implementation :: PyPy
Requires-Dist: numpy>=2.0.0
Requires-Dist: matplotlib>=3.4.0
Requires-Dist: seaborn>=0.13.2
Requires-Dist: arviz>=1.0.0
Requires-Dist: pymc>=6.0.0
Requires-Dist: jax>=0.4.26,<0.7
Requires-Dist: jaxlib>=0.4.26,<0.7
Requires-Dist: graphviz>=0.20.3
Requires-Dist: equinox>=0.11.10
Requires-Dist: optax>=0.2.5
Requires-Dist: jax[cuda12]>=0.4.26 ; sys_platform == 'linux' and extra == 'cuda12'
Provides-Extra: cuda12
License-File: LICENSE
Summary: Dynamic neural networks for predictive coding
Keywords: reinforcement learning,predictive coding,neural networks,graphs,variational inference,active inference,causal inference
Author-email: Nicolas Legrand <nicolas.legrand@cas.au.dk>
License-Expression: GPL-3.0
Requires-Python: >=3.12, <3.14
Description-Content-Type: text/markdown; charset=UTF-8; variant=GFM
Project-URL: documentation, https://computationalpsychiatry.github.io/pyhgf/learn.html
Project-URL: homepage, https://computationalpsychiatry.github.io/pyhgf/
Project-URL: repository, https://github.com/ComputationalPsychiatry/pyhgf

<p align="center">
  <img src="https://raw.githubusercontent.com/ComputationalPsychiatry/pyhgf/master/docs/source/images/logo.png" alt="hgf" width="160">
</p>

<h1 align="center">PyHGF: A Neural Network Library for Predictive Coding</h1>

<p align="center">
  <a href="https://github.com/pre-commit/pre-commit"><img src="https://img.shields.io/badge/pre--commit-enabled-brightgreen?logo=pre-commit&logoColor=white" alt="pre-commit"></a>
  <a href="https://github.com/ComputationalPsychiatry/pyhgf/blob/master/LICENSE"><img src="https://img.shields.io/badge/License-MIT-blue.svg" alt="license"></a>
  <a href="https://codecov.io/gh/ComputationalPsychiatry/pyhgf"><img src="https://codecov.io/gh/ComputationalPsychiatry/pyhgf/branch/master/graph/badge.svg" alt="codecov"></a>
  <a href="https://github.com/astral-sh/ruff"><img src="https://img.shields.io/endpoint?url=https://raw.githubusercontent.com/astral-sh/ruff/main/assets/badge/v2.json" alt="Ruff"></a>
  <a href="http://mypy-lang.org/"><img src="http://www.mypy-lang.org/static/mypy_badge.svg" alt="mypy"></a>
  <a href="https://badge.fury.io/py/pyhgf"><img src="https://badge.fury.io/py/pyhgf.svg" alt="pip"></a>
</p>

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](https://doi.org/10.7554/eLife.110174.1 ))
- Use **generalised Bayesian filtering** with distributions from the exponential family ([Mathys & Weber, 2020](https://doi.org/10.1007/978-3-030-64919-7_7))
- Define custom **planning** and **action selection** functions throught trajectories sampling (e.g. sophisticated inference, [Friston et al., 2020](https://doi.org/10.1162/neco_a_01351))
- Learn in **deep predictive coding networks** using a fast and scalable rethinking of prospective configuration ([Song et al., 2024](https://doi.org/10.1038/s41593-023-01514-1)) 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](https://doi.org/10.1371/journal.pcbi.1014340).

* 📖 [API Documentation](https://computationalpsychiatry.github.io/pyhgf/api.html)  
* ✏️ [Tutorials and examples](https://computationalpsychiatry.github.io/pyhgf/learn.html)  

## 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](https://computationalpsychiatry.github.io/pyhgf/install.html).

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).

<img src="https://raw.githubusercontent.com/ComputationalPsychiatry/pyhgf/master/docs/source/images/graph_network.svg" align="center" alt="networks" style="width:100%; height:auto;">


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](https://computationalpsychiatry.github.io/pyhgf/notebooks/0.1-Theory.html) | [![Open In Colab](https://colab.research.google.com/assets/colab-badge.svg)](https://colab.research.google.com/github/ComputationalPsychiatry/pyhgf/blob/master/docs/source/notebooks/0.1-Theory.ipynb) |
| [Creating and manipulating networks of probabilistic nodes](https://computationalpsychiatry.github.io/pyhgf/notebooks/0.2-Creating_networks.html) | [![Open In Colab](https://colab.research.google.com/assets/colab-badge.svg)](https://colab.research.google.com/github/ComputationalPsychiatry/pyhgf/blob/master/docs/source/notebooks/0.2-Creating_networks.ipynb) |


### 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](https://translationalneuromodeling.github.io/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).

<details>
<summary>Creating and fitting a binary HGF</summary>

```python
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()
```
</details>

![png](https://raw.githubusercontent.com/ComputationalPsychiatry/pyhgf/master/docs/source/images/trajectories.png)

#### Surprise

<details>
<summary>Computing the model's surprise</summary>

```python
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()}")
```
</details>  

`Model's surprise = 138.8992462158203`

### Generalised Bayesian filtering

The framework supports online Bayesian filtering over any distribution in the [exponential family](https://en.wikipedia.org/wiki/Exponential_family) ([Mathys & Weber, 2020](https://doi.org/10.1007/978-3-030-64919-7_7)). 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.

<details>
<summary>Tracking a bivariate normal distribution</summary>

```python
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)
)
```
</details>

<p align="center">
  <img src="https://raw.githubusercontent.com/ComputationalPsychiatry/pyhgf/master/docs/source/images/multivariate_normal.gif" alt="multivariate normal" width="100%">
</p>

| Tutorial | Colab |
| --- | --- |
| [Generalised Bayesian Filtering of exponential family distributions](https://computationalpsychiatry.github.io/pyhgf/notebooks/0.3-Generalised_filtering.html) | [![Open In Colab](https://colab.research.google.com/assets/colab-badge.svg)](https://colab.research.google.com/github/ComputationalPsychiatry/pyhgf/blob/master/docs/source/notebooks/0.3-Generalised_filtering.ipynb) |

### 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](https://doi.org/10.1162/neco_a_01351)).

<img src="https://raw.githubusercontent.com/ComputationalPsychiatry/pyhgf/master/docs/source/images/planning.png" align="center" alt="planning" style="width:100%; height:auto;">

| Tutorial | Colab |
| --- | --- |
| [Planning and acting with predictive coding networks](https://computationalpsychiatry.github.io/pyhgf/notebooks/0.4-Planning_and_acting.html) | [![Open In Colab](https://colab.research.google.com/assets/colab-badge.svg)](https://colab.research.google.com/github/ComputationalPsychiatry/pyhgf/blob/master/docs/source/notebooks/0.4-Planning_and_acting.ipynb) |

### Learning in deep predictive coding networks

The framework extends predictive coding to deep neural networks through *prospective configuration* ([Song et al., 2024](https://doi.org/10.1038/s41593-023-01514-1)): 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.

<p align="center">
  <img src="https://raw.githubusercontent.com/ComputationalPsychiatry/pyhgf/master/docs/source/images/deep_networks_theory.svg" alt="deep networks theory" width="100%">
</p>

| Tutorial | Colab |
| --- | --- |
| [Learning in deep predictive coding networks: the theory](https://computationalpsychiatry.github.io/pyhgf/notebooks/0.5-Deep_networks_theory.html) | [![Open In Colab](https://colab.research.google.com/assets/colab-badge.svg)](https://colab.research.google.com/github/ComputationalPsychiatry/pyhgf/blob/master/docs/source/notebooks/0.5-Deep_networks_theory.ipynb) |
| [Learning in deep networks with prospective configuration](https://computationalpsychiatry.github.io/pyhgf/notebooks/0.6-Prospective_configuration.html) | [![Open In Colab](https://colab.research.google.com/assets/colab-badge.svg)](https://colab.research.google.com/github/ComputationalPsychiatry/pyhgf/blob/master/docs/source/notebooks/0.6-Prospective_configuration.ipynb) |

<p align="center">
  <img src="https://raw.githubusercontent.com/ComputationalPsychiatry/pyhgf/master/docs/source/images/three_spirals_training.gif" alt="three spirals training" width="100%">
</p>

| Tutorial | Colab |
| --- | --- |
| [Building custom deep network architectures](https://computationalpsychiatry.github.io/pyhgf/notebooks/0.7-Deep_networks_implementation.html) | [![Open In Colab](https://colab.research.google.com/assets/colab-badge.svg)](https://colab.research.google.com/github/ComputationalPsychiatry/pyhgf/blob/master/docs/source/notebooks/0.7-Deep_networks_implementation.ipynb) |
| [Convolutional predictive coding networks](https://computationalpsychiatry.github.io/pyhgf/notebooks/0.8-Convolutional_networks.html) | [![Open In Colab](https://colab.research.google.com/assets/colab-badge.svg)](https://colab.research.google.com/github/ComputationalPsychiatry/pyhgf/blob/master/docs/source/notebooks/0.8-Convolutional_networks.ipynb) |
| [Transformer predictive coding networks](https://computationalpsychiatry.github.io/pyhgf/notebooks/0.9-Transformers.html) | [![Open In Colab](https://colab.research.google.com/assets/colab-badge.svg)](https://colab.research.google.com/github/ComputationalPsychiatry/pyhgf/blob/master/docs/source/notebooks/0.9-Transformers.ipynb) |


## Acknowledgments

This implementation of the Hierarchical Gaussian Filter was inspired by the original [Matlab HGF Toolbox](https://translationalneuromodeling.github.io/tapas). A Julia implementation of the gHGF is also available [here](https://github.com/ComputationalPsychiatry/HGF.jl).

The development of PyHGF is supported by:

<p align="center">
  <a href="https://www.au.dk"><img src="https://raw.githubusercontent.com/ComputationalPsychiatry/pyhgf/master/docs/source/images/au.svg" height="80" alt="Aarhus University"></a>
  &nbsp;&nbsp;&nbsp;
  <a href="https://chc.au.dk"><img src="https://raw.githubusercontent.com/ComputationalPsychiatry/pyhgf/master/docs/source/images/chc.png" height="80" alt="Center for Humanities Computing"></a>
  &nbsp;&nbsp;&nbsp;
  <a href="https://interactingminds.au.dk"><img src="https://raw.githubusercontent.com/ComputationalPsychiatry/pyhgf/master/docs/source/images/imc.jpg" height="80" alt="Interacting Minds Centre"></a>
</p>

## 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

