spamosaic.architectures.hg_lgcn

Heterogeneous LightGCN layers and models for SpaMosaic.

Provides a LightGCN-style convolution for heterogeneous graphs and an encoder-decoder network.

class spamosaic.architectures.hg_lgcn.HG_LGCN(*args: Any, **kwargs: Any)

Bases: Module

Heterogeneous Graph LightGCN with encoder–decoder architecture.

Uses HG_LGCN_vanilla as the feature encoder and an MLP/linear decoder for reconstruction.

Parameters:

• input_size (int) – Input feature dimensionality per node.

• output_size (int) – Latent embedding dimensionality.

• K (int, default=8) – Number of LightGCN layers.

• dec_l (int, default=1) – Number of decoder layers (1 = linear decoder).

• hidden_size (int, default=512) – Hidden size of the MLP head.

• dropout (float, default=0.2) – Dropout rate in the MLP head.

forward(feature, edge_index, edge_weight, edge_type)

Forward pass for HG_LGCN.

Parameters:

• feature (torch.Tensor) – Input node features.

• edge_index (torch.LongTensor) – COO edge list.

• edge_weight (torch.Tensor) – Edge weights.

• edge_type (torch.Tensor) – Edge type indicators.

Returns:

• L2-normalized latent representation ([N, output_size]).

• Reconstructed features ([N, input_size]).

Return type:

tuple[torch.Tensor, torch.Tensor]

class spamosaic.architectures.hg_lgcn.HG_LGCN_Conv(*args: Any, **kwargs: Any)

Bases: MessagePassing

Heterogeneous Graph LightGCN convolution layer.

Performs degree-normalized aggregation with self-loops and separates intra-group vs. inter-group message passing, then concatenates the two streams.

forward(x, edge_index, edge_weight, edge_type)

Forward pass for heterogeneous LightGCN convolution.

Parameters:

• x (torch.Tensor) – Input node features of shape (N, F).

• edge_index (torch.LongTensor) – Edge list in COO format, shape (2, E).

• edge_weight (torch.Tensor) – Edge weights, shape (E,).

• edge_type (torch.Tensor) – Edge type indicator (1 for intra-group, 0 for inter-group).

Returns:

Concatenated features from intra-group and inter-group aggregations.

Return type:

torch.Tensor

message(x_j, norm)

Compute per-edge messages.

Parameters:

• x_j (torch.Tensor) – Source-node features for each edge.

• norm (torch.Tensor) – Normalized scalar weight per edge.

Returns:

Weighted messages norm * x_j.

Return type:

torch.Tensor

class spamosaic.architectures.hg_lgcn.HG_LGCN_vanilla(*args: Any, **kwargs: Any)

Bases: Module

Stacked HG_LGCN_Conv with layer-wise feature concatenation.

Parameters:

num_layers (int) – Number of HG_LGCN_Conv layers to stack.

Notes

This class builds a list of LightGCN-style layers and concatenates the input features with the output of each layer.

forward(x, edge_index, edge_weight, edge_type)

Forward pass of stacked HG_LGCN layers.

Parameters:

• x (torch.Tensor) – Input node features.

• edge_index (torch.LongTensor) – Edge list in COO format.

• edge_weight (torch.Tensor) – Weights for each edge.

• edge_type (torch.Tensor) – Indicator for intra- vs. inter-group edges.

Returns:

Concatenated node features from all layers (including the input).

Return type:

torch.Tensor

Classes

spamosaic.architectures.hg_lgcn.HG_LGCN	Heterogeneous Graph LightGCN with encoder–decoder architecture.
spamosaic.architectures.hg_lgcn.HG_LGCN_Conv	Heterogeneous Graph LightGCN convolution layer.
spamosaic.architectures.hg_lgcn.HG_LGCN_vanilla	Stacked HG_LGCN_Conv with layer-wise feature concatenation.