Clebsch-Gordan products

class rascaline.torch.utils.DensityCorrelations(max_angular: int, correlation_order: int, angular_cutoff: int | None = None, selected_keys: Labels | List[Labels] | None = None, skip_redundant: bool | List[bool] | None = False, output_selection: bool | List[bool] | None = None, arrays_backend: str | None = None, cg_backend: str | None = None)

Takes iterative Clebsch-Gordan (CG) tensor products of a density descriptor with itself up to the desired correlation order. Returns TensorMap corresponding to the density correlations output from the specified iteration(s).

The input density descriptor necessarily is body order 2 (i.e. correlation order 1), but can be single- or multi-center. The output is a list of density correlations for each iteration specified in output_selection, up to the target order passed in correlation_order. By default only the last correlation (i.e. the correlation of order correlation_order) is returned.

This function is an iterative special case of the more general correlate_tensors(). As a density is being correlated with itself, some redundant CG tensor products can be skipped with the skip_redundant keyword.

Selections on the angular and parity channels at each iteration can also be controlled with arguments angular_cutoff, angular_selection and parity_selection.

Parameters:

  • max_angular – The maximum angular order for which CG coefficients should be computed and stored. This must be large enough to cover the maximum angular order reached in the CG iterations on a density input to the compute() method.

  • correlation_order – The desired correlation order of the output descriptor. Must be >= 1.

  • angular_cutoff – The maximum angular channel to compute at any given CG iteration, applied globally to all iterations until the target correlation order is reached.

  • selected_keys – Labels or list of Labels specifying the angular and/or parity channels to output at each iteration. All Labels objects passed here must only contain key names "o3_lambda" and "o3_sigma". If a single Labels object is given, this is applied to the final iteration only. If a list of Labels is given, each is applied to its corresponding iteration. If None is passed, all angular and parity channels are kept at each iteration, with the global angular_cutoff applied if specified.

  • skip_redundant – Whether to skip redundant CG combinations. Defaults to False, which means all combinations are performed. If a list of bool is passed, this is applied to each iteration. If a single bool is passed, this is applied to all iterations.

  • output_selection – A list of bool specifying whether to output a TensorMap for each iteration. If a single bool is passed as True, outputs from all iterations will be returned. If a list of bool is passed, this controls the output at each corresponding iteration. If None is passed, only the final iteration is output.

  • arrays_backend – Determines the array backend, either "numpy" or "torch".

  • cg_backend –

    Determines the backend for the CG combination. It can be "python-sparse", or "python-dense". If the CG combination performs on the sparse coefficients, it means that for each (l1, l2, lambda) block the (m1, m2, mu) coefficients are stored in a sparse format only storing the nonzero coefficients. If this is not given, the most optimal choice is determined given available packages and arrays_backend.

    • "python-dense": Uses the python implementation performing the combinations with the dense CG coefficients.

    • "python-sparse": Uses the python implementation performing the combinations with the sparse CG coefficients.

Returns:

A list of TensorMap corresponding to the density correlations output from the specified iterations. If the output from a single iteration is requested, a TensorMap is returned instead.

Initialize internal Module state, shared by both nn.Module and ScriptModule.

forward(density: TensorMap) → TensorMap | List[TensorMap]

Calls the DensityCorrelations.compute() function.

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

compute(density: TensorMap) → TensorMap | List[TensorMap]

Computes the density correlations by taking iterative Clebsch-Gordan (CG) tensor products of the input density descriptor with itself.

Parameters:

density – A density descriptor of body order 2 (correlation order 1), in TensorMap format. This may be, for example, a rascaline SphericalExpansion or LodeSphericalExpansion. Alternatively, this could be multi-center descriptor, such as a pair density.

compute_metadata(density: TensorMap) → TensorMap | List[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.

Parameters:

density – A density descriptor of body order 2 (correlation order 1), in TensorMap format. This may be, for example, a rascaline SphericalExpansion or LodeSphericalExpansion. Alternatively, this could be multi-center descriptor, such as a pair density.