Skip to content

Decoders

A decoder turns equivariant model features into an output whose axes and transformation rules match a physical quantity. Cartesian readouts produce scalars, vectors, or tensors; orbital readouts use a basis set to determine shell ordering and output sizes.

The readout also determines how atomic contributions form a sample-level prediction. The scalar decoder sums node contributions, while the symmetric tensor decoder averages them. Orbital decoders return the packed data structures used for batches with different numbers of orbitals or atom-pair blocks.

These classes are available from elfes.modules.decoders and are also re-exported by elfes.modules. Their complete reference is collected here.

Cartesian outputs

These readouts use the scalar, vector, or degree-2 parts of spherical node features to produce the corresponding Cartesian output.

ScalarDecoder

ScalarDecoder(node_channels: int, hidden_channels: int)

Bases: Module

Decode spherical node features into one additive scalar per sample.

The decoder maps each node's l=0 features to a scalar contribution and sums the contributions over the nodes belonging to each sample.

Parameters:

  • node_channels (int) –

    Channel multiplicity of the spherical node features.

  • hidden_channels (int) –

    Width of the scalar readout MLP.

forward

forward(node_features: Tensor, batch: Tensor, ptr: Tensor) -> Tensor

Parameters:

  • node_features (Tensor) –

    [N_atom, (l_max+1)**2, C_node].

  • batch (Tensor) –

    [N_atom].

  • ptr (Tensor) –

    [B+1].

Returns:

  • scalars ( Tensor ) –

    [B].

AtomCartesianVectorDecoder

AtomCartesianVectorDecoder(node_channels: int)

Bases: Module

Decode l=1 node features into atom-level Cartesian vectors.

The same channel-mixing weights act on all three l=1 components, which makes the readout SO(3)-equivariant. ELFES spherical tensors use (y, z, x) order at l=1; returned Cartesian vectors use ordinary (x, y, z) order.

Parameters:

  • node_channels (int) –

    Channel multiplicity of the spherical node features.

forward

forward(node_features: Tensor) -> Tensor

Parameters:

  • node_features (Tensor) –

    [N_atom, (l_max+1)**2, C_node].

Returns:

  • vectors ( Tensor ) –

    [N_atom, 3].

SymmetricTensorDecoder

SymmetricTensorDecoder(node_channels: int, hidden_channels: int)

Bases: Module

Decode intensive symmetric Cartesian tensors [B,3,3] by atom mean.

A scalar MLP predicts the isotropic coefficient; a shared channel linear maps l=2 to the five traceless coefficients in ELFES real harmonics. The six Cartesian basis tensors are orthonormal under the Frobenius product.

Orbital outputs

The vector decoder reads node features into orbital coefficients. The matrix decoder combines node and edge features for requested atom-pair blocks and currently produces real, spinless matrices. Orbital transforms provide related coordinate and scale conversions.

OrbVectorDecoder

OrbVectorDecoder(node_channels: int, basis_set: BasisSet)

Bases: Module

Decode dense spherical node features into packed orbital vectors.

Each output shell uses a species- and shell-specific linear combination of the input channels. The same weights act on every component within the shell's l block, so the readout is SO(3)-equivariant. Output components follow the atomic-basis shell order and the ELFES real spherical-harmonic convention within each shell.

Attributes:

  • weight –

    Channel-mixing weights for every species shell, with shape [sum_s n_shells(s), node_channels].

  • orb_counts (Tensor) –

    Number of orbital components per atom for each model species, with shape [num_species].

  • species_offsets (Tensor) –

    Leading-zero prefix sum of orb_counts, with shape [num_species + 1].

  • value_component_indices (Tensor) –

    Spherical component for every species orbital component, with shape [sum_s n_orb(s)].

  • value_weight_indices (Tensor) –

    Shell-weight row for every species orbital component, with shape [sum_s n_orb(s)].

forward

forward(
    node_features: Tensor, species_indices: Tensor, batch: Tensor, ptr: Tensor
) -> OrbData

Parameters:

  • node_features (Tensor) –

    [N_atom, (l_max+1)**2, C_node].

  • species_indices (Tensor) –

    [N_atom].

  • batch (Tensor) –

    [N_atom].

  • ptr (Tensor) –

    [B+1].

Returns:

  • orb_data ( OrbData ) –

    values_real: [N_orb]. num_values: [B].

BlockSparseOrbMatrixDecoder

BlockSparseOrbMatrixDecoder(
    node_channels: int,
    edge_channels: int,
    basis_set: BasisSet,
    l_max: int,
    m_max: int | None = None,
    *,
    hermitian: bool = False,
    output_transform: BlockSparseAffineTransform | None = None,
)

Bases: Module

Decode real spinless atom-pair blocks, optionally enforcing Hermiticity.

Nodes use global l-major features; edges use local m-major features and global-to-local Wigner matrices. The basis set determines ordered species, shell pairs, coupled irreps and packed output sizes. Outputs contain only requested atom pairs, in request order, independent of connectivity order. With hermitian=True, both directed edges must exist even when only one member of a Hermitian pair is requested. Zero-shift onsite blocks read nodes. Nonzero-shift pairs with equal atom indices read edges.

l_max must cover all output coupled degrees. Truncated local modes are zero-filled before rotation; this restricts the offsite readout function. SO(2) real/imaginary components are converted to real spherical components, not physical values_imag. No spin or SOC coupling is performed.

output_transform optionally restores physical scales in global coupled coordinates before CG composition and Hermitian averaging. It must use the same basis set and scalar values (extra_shape=()). Its canonical path policy applies to Hermitian targets only.

forward

forward(
    node_features: Tensor,
    edge_features: Tensor,
    species_indices: Tensor,
    edge_index: Tensor,
    edge_shifts: Tensor,
    wigner_matrices: Tensor,
    atom_pair_index: Tensor,
    pair_shifts: Tensor,
    batch: Tensor,
    ptr: Tensor,
) -> BlockSparseOrbData

Parameters:

  • node_features (Tensor) –

    [N, (l_max+1)**2, C_node].

  • edge_features (Tensor) –

    [E, K, C_edge] in m-major layout.

  • species_indices (Tensor) –

    [N], in basis-set species order.

  • edge_index (Tensor) –

    [2, E].

  • edge_shifts (Tensor) –

    [E, 3], integer cell shifts.

  • wigner_matrices (Tensor) –

    [E, sum_l (2*l+1)**2].

  • atom_pair_index (Tensor) –

    [2, P], batch-global atom indices.

  • pair_shifts (Tensor) –

    [P, 3], integer cell shifts.

  • batch (Tensor) –

    [N].

  • ptr (Tensor) –

    [B+1].

Returns:

  • matrix ( BlockSparseOrbData ) –

    Requested packed blocks, values_real: [V]. Requests are grouped by sample, with arbitrary order within it.