pyhgf.model.conv.conv_block#

pyhgf.model.conv.conv_block(in_channels, out_channels, in_height, in_width, filter_shape=(3, 3), strides=(1, 1), padding='SAME', pool_size=(2, 2), pool_stride=None, pool_kind='avg', optimiser=None, learning_kind='precision_weighted', learning_kwargs=None, update_precisions=False, time_step=1.0, key=None, leaf_kwargs=None, layer_kwargs=None, network_kwargs=None, patch_net=None)[source]#

Assemble one conv layer as a part tree: im2col, shared kernel, GELU, pool.

A conv layer has one weight table (attention has four), so it is composed from the primitives above with PCSequential rather than through a dedicated class.

Parameters:

  • in_channels (int) – Channels of the incoming feature map, whose shape is (batch, in_channels, in_height, in_width).

  • out_channels (int) – Feature maps this block produces, one per kernel.

  • in_height (int) – Height of the incoming feature map. Fixed at build time: the reshape back to spatial layout is sized from it, so feeding a different height fails.

  • in_width (int) – Width of the incoming feature map, fixed at build time like in_height.

  • filter_shape (tuple[int, int]) – Kernel size (kh, kw).

  • strides (tuple[int, int]) – Convolution strides (sh, sw), one step per output position.

  • padding (str | tuple[tuple[int, int], tuple[int, int]]) – "SAME" (output size is the input size divided by the stride, rounded up), "VALID" (no padding) or an explicit ((top, bottom), (left, right)).

  • pool_size (tuple[int, int]) – Pooling window (ph, pw). Use (1, 1) for no pooling. Must fit within the convolution’s output size.

  • pool_stride (tuple[int, int] | None) – Step between pooling windows, defaulting to pool_size (non overlapping windows).

  • pool_kind (str) – "avg" for avg_pool_adapter() or "max" for max_pool_adapter().

  • optimiser (GradientTransformation | None) – Optax optimiser for the shared kernel. None freezes the weights (the layer beliefs still update) under every learning_kind except "synaptic_uncertainty", which carries its own step size and leaves the optimiser unused either way.

  • learning_kind (str) – Weight-gradient mode, forwarded to DeepNetworkAdapter. Under "synaptic_uncertainty" each weight also carries a belief whose variance is the step size, so no optimiser is needed and the kernel keeps learning without one.

  • learning_kwargs (dict | None) – Settings of the learning rule, used by learning_kind="synaptic_uncertainty", which requires at least {"window": N}.

  • update_precisions (bool) – Whether the kernel’s precision state adapts across batches. Defaults to False, the setting used for exact comparisons against backpropagation.

  • time_step (float) – Inference time step, forwarded to the adapter: one batch counts as one observation of this duration.

  • key (Array | None) – PRNG key for initialising a fresh kernel. Ignored when patch_net is given.

  • leaf_kwargs (dict | None) – Extra add_layer keyword arguments for the kernel network’s bottom (output) layer, such as the backprop-parity configuration.

  • layer_kwargs (dict | None) – Extra add_layer keyword arguments for its top (input) layer.

  • network_kwargs (dict | None) – Constructor arguments for the shared-kernel DeepNetwork, such as feedforward_uncertainty. Ignored when patch_net is given, since that network is already built.

  • patch_net (DeepNetwork | None) – A pre-built shared-kernel network to use in place of a freshly initialised conv_patch_network(), such as one built by from_conv() from a trained or externally initialised kernel. When given, key is ignored.

Raises:

ValueError – If pool_kind is not "avg" or "max", or if pool_size is larger than the feature map the convolution produces.

Returns:

  • part – The PCSequential to place in a larger pipeline.

  • out_shape – (out_channels, pooled_height, pooled_width), to pass on as the next block’s in_channels, in_height and in_width.

Return type:

tuple[PCSequential, tuple[int, int, int]]