Convolutional Probabilistic Circuits (ConvPc)

Convolutional Probabilistic Circuits (ConvPc) are a multi-layer architecture that stacks alternating SumConv and ProdConv layers on top of a leaf distribution, designed specifically for data with spatial structure like images.

Reference

Convolutional architectures for Sum-Product Networks are inspired by:

Overview

ConvPc architectures progressively reduce spatial dimensions while learning mixture weights at each level, mirroring the hierarchical structure of Convolutional Neural Networks (CNNs) while maintaining exact tractability.

Key characteristics:

  • Spatial awareness: Uses local kernels to capture spatial correlations.

  • Weight sharing: (Optionally) shares weights across spatial locations for efficiency.

  • Hierarchical composition: Recursively combines local distributions into global ones.

Implementation

The spflow.zoo.conv.ConvPc module automates the construction of these circuits for image modeling.

class spflow.zoo.conv.ConvPc(leaf, input_height, input_width, channels, depth, kernel_size=2, num_repetitions=1, use_sum_conv=False)[source]

Bases: Module

Convolutional Probabilistic Circuit.

Builds a multi-layer circuit with alternating ProdConv and SumConv layers on top of a leaf distribution. The architecture progressively reduces spatial dimensions while learning mixture weights at each level.

The layer ordering is: Leaf -> ProdConv -> SumConv -> ProdConv -> SumConv -> … -> Root Sum

Layers are constructed top-down (from root to leaves), then reversed for proper bottom-up evaluation order.

leaf

Leaf distribution module.

Type:

Module

root

Final sum layer producing scalar output per sample.

Type:

Sum

__init__(leaf, input_height, input_width, channels, depth, kernel_size=2, num_repetitions=1, use_sum_conv=False)[source]

Create a ConvPc for image modeling.

Parameters:

  • leaf (Module) – Leaf distribution module (e.g., Normal over pixels).

  • input_height (int) – Height of input image.

  • input_width (int) – Width of input image.

  • channels (int) – Number of channels per sum layer.

  • depth (int) – Number of (ProdConv, SumConv) layer pairs.

  • kernel_size (int) – Kernel size for pooling (default 2x2).

  • num_repetitions (int) – Number of independent repetitions.

  • use_sum_conv (bool) – If True, use SumConv layers with kernel-based spatial weights. If False (default), use regular Sum layers that treat features independently without spatial awareness.

Raises:

ValueError – If depth < 1.

log_likelihood(data, cache=None)[source]

Compute log likelihood through all layers.

Parameters:

  • data (Tensor) – Input data of shape (batch_size, num_pixels).

  • cache (Cache | None) – Cache for intermediate computations.

Returns:

Log-likelihood of shape (batch, 1, 1, reps).

Return type:

Tensor

marginalize(marg_rvs, prune=True, cache=None)[source]

Marginalize out specified random variables.

Parameters:

  • marg_rvs (list[int]) – List of random variable indices to marginalize.

  • prune (bool) – Whether to prune unnecessary nodes.

  • cache (Cache | None) – Optional cache for storing intermediate results.

Returns:

Marginalized module or None if fully marginalized.

Return type:

ConvPc | Module | None

sample(num_samples=None, data=None, is_mpe=False, cache=None)[source]

Generate samples by sampling top-down through layers.

Delegates sampling to the root module (RepetitionMixingLayer when num_repetitions > 1, or Sum when num_repetitions == 1), which then recursively propagates sampling to the leaf.

Parameters:

  • num_samples (int | None) – Number of samples to generate.

  • data (Tensor | None) – Data tensor with NaN values to fill with samples.

  • is_mpe (bool) – Whether to perform maximum a posteriori estimation.

  • cache (Cache | None) – Optional cache dictionary.

Returns:

Sampled values of shape (num_samples, num_pixels).

Return type:

Tensor

property feature_to_scope: ndarray

Single output feature with full scope.