src.model.deeplearn.layer.spconv3d_encoding_layer

Classes

SpConv3DEncodingLayer(*args, **kwargs)

class src.model.deeplearn.layer.spconv3d_encoding_layer.SpConv3DEncodingLayer(*args, **kwargs)
Author:

Alberto M. Esmoris Pena

Sparse 3D convolutional encoding layer.

The encoder produces, at every hierarchy depth \(t\), a skip link (post-wrap features at depth \(t\)) and a downsampled feature tensor at depth \(t + 1\). The block composition is preactivation BN+ReLU, pre-wrap SharedMLP, a stack of submanifold convolutions optionally followed by a residual branch, a post-wrap SharedMLP, and a final downsampling convolution. The call body operates on the concatenated global tensors emitted by DLSparseConcatSequencer and uses tf.gather against the dense neighbor tables.

The call takes a three- or four-element input list:

  1. \(\pmb{F}\) of shape \((1 + R_t, n_f)\) — the depth-\(t\) feature tensor with the shared ground row at index 0.

  2. \(\pmb{S}\) of shape \((1 + R_t, (2 w + 1)^3)\) — the submanifold neighbor table at depth \(t\).

  3. \(\pmb{D}\) of shape \((1 + R_{t+1}, w_D^3)\) — the downsampling neighbor table from depth \(t\) to depth \(t + 1\).

  4. (optional) \(\pmb{M}_t\) of shape \((R_t,)\) — the depth-\(t\) real-cell mask. When provided, every BN sublayer inside this encoder operates as a masked BN over the real cells only.

The call returns a two-element tuple (skip_link, x_down): skip_link has shape \((R_t, n_{fc})\) (the active-form post-wrap output; the matching decoder consumes it in active form directly) and x_down has shape \((1 + R_{t+1}, n_{fd})\) (the downsampled output, with the ground row re-prepended for the next-depth encoder / decoder).

BN sublayers receive training=training — real BN across all receptive fields in the batch, not instance-norm-via-BN.

__init__(w, dw, f, df, nfa, nfb, nfc, nfd, num_spconvs=1, W_initializers=None, W_regularizers=None, W_constraints=None, dW_initializer=None, dW_regularizer=None, dW_constraint=None, spconv_bn=None, spconv_bn_momentum=0.9, spconv_act=None, spconv_activation=<function relu>, preact_bn=None, preact_act=None, prewrap_bn=None, postwrap_bn=None, postwrap_bn_res=None, wrap_bn_momentum=0.99, prewrap_act=None, postwrap_act=None, prewrap_activation=None, prewrap_kernel_initializer='glorot_uniform', prewrap_kernel_regularizer=None, prewrap_kernel_constraint=None, postwrap_activation=None, postwrap_kernel_initializer='glorot_uniform', postwrap_kernel_regularizer=None, postwrap_kernel_constraint=None, residual_strategy=None, res_activation=None, res_kernel_initializer='glorot_uniform', res_kernel_regularizer=None, res_kernel_constraint=None, res_spconv_activation=<function relu>, res_spconv_bn_momentum=0.9, res_spconv_bn=None, res_spconv_act=None, post_residual_shared_mlp=False, postres_activation=<function relu>, postres_bn_momentum=0.99, postres_act=None, postres_bn=None, postres_kernel_activation=None, postres_kernel_initializer='glorot_uniform', postres_kernel_regularizer=None, postres_kernel_constraint=None, down_activation=<function relu>, down_act=None, down_bn_momentum=0.9, down_bn=None, built_W=False, built_dW=False, built_prewrap_kernel=False, built_prewrap_bias=False, built_postwrap_kernel=False, built_postwrap_bias=False, built_res_kernel=False, built_res_bias=False, built_postres_kernel=False, built_postres_bias=False, **kwargs)

See Layer and layer.Layer.__init__().

build(dim_in)

Build the per-submanifold-conv kernels, the downsampling kernel, the pre-wrap / post-wrap SharedMLP kernels and biases, the residual-branch kernel (and optional bias), and the post-residual SharedMLP if requested.

dim_in[0][-1] is the input feature dimension (n_f) — same as the previous design because the new global tensor still carries the feature axis as the last dimension.

call(inputs, training=None)

Compute the encoder forward pass on the concatenated global tensors.

Parameters:

inputs –

A 3- or 4-element list / tuple. The first three entries are always:

  • inputs[0]: \(\pmb{F}\) of shape \((1 + R_t, n_f)\) — the depth-\(t\) feature tensor with the shared ground row at index 0.

  • inputs[1]: \(\pmb{S}\) — the submanifold neighbor table at depth \(t\).

  • inputs[2]: \(\pmb{D}\) — the downsampling neighbor table from depth \(t\) to depth \(t + 1\).

When the optional fourth entry is given, it is a 1-D boolean tensor of shape \((R_t,)\) — True for real cells, False for the padded tail — and every BN in the encoder uses it to ignore the padded zero rows when computing the batch statistics. When absent the BN behavior falls back to the unmasked path (biased by padded zeros if the input is padded).

Returns:

(skip_link, x_down) with the shapes described in the class docstring.

Return type:

tuple of tf.Tensor

get_config()

Return necessary data to serialize the layer.

classmethod from_config(config)

Deserialize the layer from a config dict.

The Layer-instance keys are driven by the class attributes _LAYER_INSTANCE_KEYS (scalar sublayers) and _LAYER_INSTANCE_LIST_KEYS (lists of sublayers). Adding a new BN / activation slot requires only updating those tuples plus the matching 'foo_bn': self.foo_bn entry in get_config(); the deserialisation here picks the key up automatically.