pyhgf.model.DeepNetwork#

class pyhgf.model.DeepNetwork(coupling_fn=<function DeepNetwork.<lambda>>, volatility_updates='unbounded', max_posterior_precision=10000000000.0, precision_clipping_value=1e-06)[source]#

Deep predictive coding network with vectorized operations.

This class implements a deep hierarchical Gaussian filter using layer-wise vectorized operations for efficient scaling to large networks.

Unlike the standard DeepNetwork which uses per-node updates with Python loops, this implementation uses JAX matrix operations to update all nodes in a layer simultaneously.

Parameters:

coupling_fn (Callable) – Coupling function applied between layers. Default is linear (identity). This function is applied to parent means before the weighted sum to predict child means.
volatility_updates (str) – The type of volatility-level posterior update. Can be "unbounded" (default), "eHGF" or "standard".
max_posterior_precision (float) – Upper bound applied to every posterior precision write. Defaults to 1e10.
precision_clipping_value (float)

Examples

>>> # Build a network with method chaining
>>> net = (
...     VectorizedDeepNetwork()
...     .add_layer(size=10)  # Output layer
...     .add_layer(size=8)   # Hidden layer 1
...     .add_layer(size=6)   # Hidden layer 2
...     .add_layer(size=4)   # Input layer
... )
>>>
>>> # Fit to data
>>> net.fit(x_train, y_train, lr=0.2)
>>>
>>> # Make predictions
>>> predictions = net.predict(x_test)

Notes

The network uses volatile nodes internally, which have two levels: - Value level (external): represents the node’s belief about its value - Volatility level (internal): represents uncertainty about the value level

Layer indexing follows the convention: - Layer 0 is the output layer (receives observations) - Layer N is the input layer (receives predictors)

__init__(coupling_fn=<function DeepNetwork.<lambda>>, volatility_updates='unbounded', max_posterior_precision=10000000000.0, precision_clipping_value=1e-06)[source]#

Initialize a VectorizedDeepNetwork.

Parameters:

coupling_fn (Callable) – Coupling function applied between layers. Default is linear (identity), matching the Rust backend and the Network class. This function is applied to parent means before the weighted sum to predict child means.
volatility_updates (str) – The type of volatility-level posterior update. Can be "unbounded" (default), "eHGF" or "standard". Matches the Network class and Rust backend.
max_posterior_precision (float) – Upper bound applied to every posterior precision write (value level and volatility level). Defaults to 1e10 and is shared with the nodalised Network and the Rust backend. Increase it to relax the cap, or lower it to be more conservative against precision blow-up.
precision_clipping_value (float) – Bound applied to binary-layer predicted means ([v, 1 - v]) so the implied binary precision \(\hat{\mu}(1 - \hat{\mu})\) never collapses. A larger value (e.g. 1e-3, matching TAPAS) stabilises the forward filter in high-volatility regimes; a very small value (default 1e-6) avoids flat, zero-gradient plateaus that hurt gradient-based inference. Shared with the nodalised Network and the Rust backend.

Methods

`__init__`([coupling_fn, volatility_updates, ...])	Initialize a VectorizedDeepNetwork.
`add_layer`(size[, kind, add_constant_input, ...])	Add a layer of nodes.
`add_layer_stack`(layer_sizes[, kind, ...])	Add multiple hidden layers at once.
`fit`(x, y, optimizer[, learning_kind, ...])	Fit network to data.
`load`(path)	Read array leaves from `path` back into `self.state`.
`plot_layers`([layers, variables, mode, ...])	Plot layer-wise parameter trajectories.
`predict`(x)	Forward pass without learning.
`reset`()	Reset the network state.
`save`(path)	Serialise `self.state` array leaves to `path`.
`to_pandas`()	Flatten `self.trajectories` into a wide-format `pd.DataFrame`.
`weight_initialisation`([strategy, key])	Initialise inter-layer weight matrices.

Attributes

`n_layers`	Number of layers in the network.
`n_nodes`	Total number of nodes in the network.