Clebsch-Gordan products

class featomic.torch.utils.DensityCorrelations(*, n_correlations: int, max_angular: int, skip_redundant: bool = True, cg_backend: str | None = None, arrays_backend: str | None = None, dtype: dtype | None = None, device: device | None = None)

Takes n_correlations of iterative CG tensor products of a density with itself to produce a density auto-correlation tensor of higher correlation order.

The constructor computes and stores the CG coefficients. The compute() method computes the auto-correlation by CG tensor product of the input density.

Parameters:

  • n_correlations – int, the number of iterative CG tensor products to perform.

  • max_angular – int, the maximum angular momentum to compute CG coefficients for. This must be large enough to perform the desired number of correlations on the density passed to the compute() method.

  • skip_redundant – bool, whether to skip redundant CG combination steps without losing information in the output. Setting to True can save computation time, but does not preserve the norm of the output tensors.

  • cg_backend – str, the backend to use for the CG tensor product. If None, the backend is automatically selected based on the arrays backend.

  • arrays_backend – str, the backend to use for array operations. If None, the backend is automatically selected based on the environment. Possible values are “numpy” and “torch”.

  • dtype – the scalar type to use to store coefficients

  • device – the computational device to use for calculations. This must be "cpu" if array_backend="numpy".

compute(density: TensorMap, angular_cutoff: int | None = None, selected_keys: Labels | None = None) → TensorMap

Takes n_correlations of iterative CG tensor products of a density with itself, to generate density auto-correlations of arbitrary correlation order.

\[\rho^{\nu=n_{corr} + 1} = \rho^{\nu=1} \otimes \rho^{\nu=1} \ldots \otimes \rho^{\nu=1}\]

where rho^{nu=1} is the input density of correlation order 1 (body order 2), and rho^{nu=n_{corr} + 1} is the output density of correlation order n_correlations + 1

Before performing any correlations, the properties dimensions of density are modified to carry a “_1” suffix. At each iteration, the dimension names of the copy of the density being correlated are incremented by one each time.

selected_keys can be passed to select the keys to compute on the final iteration. If None, all keys are computed. To limit the maximum angular momenta to compute on intermediate iterations, pass angular_cutoff.

If angular_cutoff and selected_keys are both passed, angular_cutoff is ignored on the final iteration.

Parameters:

  • density – TensorMap, the input density tensor of correlation order 1.

  • angular_cutoff – int, the maximum angular momentum to compute output blocks for at each iteration. If selected_keys is passed, this parameter is applied to all intermediate (i.e. prior to the final) iterations. If selected_keys is not passed, this parameter is applied globally to all iterations. If None, all angular momenta are computed.

  • selected_keys – Labels, the keys to compute on the final iteration. If None, all keys are computed. Subsets of key dimensions can be passed to compute output blocks that match in these dimensions.

Returns:

TensorMap, the output density auto-correlation tensor of correlation order n_correlations + 1.

forward(density: TensorMap, angular_cutoff: int | None = None, selected_keys: Labels | None = None) → TensorMap

Calls the compute() method.

This is intended for torch.nn.Module compatibility, and should be ignored in pure Python mode.

See compute() for a full description of the parameters.

compute_metadata(density: TensorMap, angular_cutoff: int | None = None, selected_keys: Labels | None = None) → TensorMap

Returns the metadata-only TensorMap that would be output by the function compute() for the same calculator under the same settings, without performing the actual Clebsch-Gordan tensor products.

See compute() for a full description of the parameters.