Convolutional Modules

Convolutional layers for modeling spatial structure in image data with probabilistic circuits.

SumConv

Convolutional sum layer that applies learned weighted sums over input channels within spatial patches. Enables mixture modeling with spatial structure.

class spflow.modules.conv.SumConv(inputs, out_channels, kernel_size, num_repetitions=1)

Bases: Module

Convolutional sum layer for probabilistic circuits.

Applies weighted sum over input channels within spatial patches. Weights are learned and normalized to sum to one per patch position, maintaining valid probability distributions. Useful for modeling spatial structure in image data.

The layer expects input with spatial structure and applies shared weights across all spatial patches of the same position within the kernel.

inputs

Input module providing log-likelihoods.

Type:

Module

kernel_size

Size of the spatial kernel (kernel_size x kernel_size).

Type:

int

in_channels

Number of input channels.

Type:

int

out_channels

Number of output channels (mixture components).

Type:

int

logits

Unnormalized log-weights for gradient optimization.

Type:

Parameter

__init__(inputs, out_channels, kernel_size, num_repetitions=1)

Create a SumConv module for spatial mixture modeling.

Parameters:

• inputs (Module) – Input module providing log-likelihoods with spatial structure.

• out_channels (int) – Number of output mixture components.

• kernel_size (int) – Size of the spatial kernel (kernel_size x kernel_size).

• num_repetitions (int) – Number of independent repetitions.

Raises:

ValueError – If out_channels < 1 or kernel_size < 1.

log_likelihood(data, cache=None)

Compute log likelihood using convolutional weighted sum.

Applies weighted sum over input channels within spatial patches. Each kernel position gets its own set of mixture weights. Uses logsumexp for numerical stability.

Parameters:

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

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

Returns:

Log-likelihood of shape (batch, features, out_channels, reps).

Return type:

Tensor

marginalize(marg_rvs, prune=True, cache=None)

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:

SumConv | Module | None

property feature_to_scope: ndarray

Per-pixel scopes are preserved from input.

property log_weights: Tensor

Returns the log weights normalized to sum to one over input channels.

Returns:

Log weights of shape (out_c, in_c, k, k, reps).

Return type:

Tensor

property weights: Tensor

Returns the weights normalized to sum to one over input channels.

Returns:

Weights of shape (out_c, in_c, k, k, reps).

Return type:

Tensor

ProdConv

Convolutional product layer that computes products over spatial patches, reducing spatial dimensions by the kernel size factor. Aggregates scopes within patches while maintaining proper probabilistic semantics.

class spflow.modules.conv.ProdConv(inputs, kernel_size_h, kernel_size_w, padding_h=0, padding_w=0)

Bases: Module

Convolutional product layer for probabilistic circuits.

Computes products over spatial patches, reducing spatial dimensions by the kernel size factor. This is equivalent to summing log-likelihoods within patches. No learnable parameters.

Scopes are aggregated per patch: a 2×2 patch containing Scope(0), Scope(1), Scope(2), Scope(3) produces Scope([0,1,2,3]).

inputs

Input module providing log-likelihoods.

Type:

Module

kernel_size_h

Kernel height.

Type:

int

kernel_size_w

Kernel width.

Type:

int

padding_h

Padding in height dimension.

Type:

int

padding_w

Padding in width dimension.

Type:

int

__init__(inputs, kernel_size_h, kernel_size_w, padding_h=0, padding_w=0)

Create a ProdConv module for spatial product operations.

Parameters:

• inputs (Module) – Input module providing log-likelihoods with spatial structure.

• kernel_size_h (int) – Height of the pooling kernel.

• kernel_size_w (int) – Width of the pooling kernel.

• padding_h (int) – Padding in height dimension (added on both sides).

• padding_w (int) – Padding in width dimension (added on both sides).

Raises:

ValueError – If kernel sizes are < 1.

log_likelihood(data, cache=None)

Compute log likelihood by summing within patches.

Uses depthwise convolution with ones kernel to efficiently sum log-probabilities within patches.

Parameters:

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

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

Returns:

Log-likelihood of shape (batch, out_features, channels, reps).

Return type:

Tensor

marginalize(marg_rvs, prune=True, cache=None)

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:

ProdConv | Module | None

property feature_to_scope: ndarray

Aggregated scopes per output feature.

Each output feature’s scope is the join of all input scopes within its patch.

Returns:

2D array of Scope objects (features, repetitions).

Return type:

np.ndarray