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.