coupling_utils

Utility functions for calculation of ACE coupling coefficients.

Some of the functions here are specifically related to the PA basis set, and formerly lived in the pa_gen.py or pa_lib.py files, before these were unified.

apply_ladder_relationships(lin, nin, combined_labs, parity_span, parity_span_labs, full_span)

Apply ladder relationships. From Goff 2024. For input angular function indices and radial function indices, apply ladder relationships to overcomplete set of L to remove redundant functions.

These ladder relationships are derived from repeatedly applying raising/lowering relationships to the generalized coupling coefficients in https://doi.org/10.1016/j.jcp.2024.113073.

Parameters:

• nin (List) – radial indices to resort according to frequency and return the mapping to do so

• lin (List) – angular indices to resort according to frequency and return the mapping to do so

• combined_labs (List) – blocks of lL generated based on frequency partition

• parity_span (List) – span of young subgroup * SO(3) after parity constraints applied

• parity_span_labs (List) – labels spanning young subgroup * SO(3) after parity constraints applied

• full_span (List) – span of full young subgroup * SO(3) group

Returns:

funcs – reduced set of permutation-adapted functions

Return type:

List

build_and_write_to_tabulated(rank, all_max_n, all_max_l, label_file, L_R=0, M_R=0)

Build a tabulated PA ACE descriptor label file.

This only matters for rank >=4. The json files build in this function are saved in the acelib directory and read in the process of computing the labels/coupling coefficients.

Parameters:

• rank (int) – body order of angular ace descriptor labels to be generated

• L_R (int) – Resultant angular momentum quantum number. This determines the equivariant character of the rank N descriptor after reduction. L_R=0 corresponds to a rotationally invariant feature, L_R=1 corresponds to a feature that transforms like a vector, L_R=2 a tensor, etc.

• M_R (int) – Resultant projection quantum number. This also determines the equivariant character of the rank N descriptor after reduction. M_R must obey -L_R <= M_R <= L_R

• all_max_n (int) – max radial basis function index (with possible shift according to max chemical basis index)

• all_max_l (int) – max angular basis function index

• label_file (str) – file name to contain PA labels

Returns:

None – Labels are written to file.

Return type:

None

build_tree_for_l_intermediates(l, L_R=0)

Build the “intermediate” angular momenta. When coupling N quantum angular momenta (and reducing product of N spherical harmonics in ACE), only 2 quantum angular momenta can be added at a time with traditional clebsch-gordan coefficients.

Any more, and they must be reduced to an ‘intermediate’, and the intermediates added. The allowed intermediates are those determined by repeated quantum angular momentum addition rules (a.k.a. triangle conditions).

This function gets all possible sets of intermediates given a set of N angular momentum quantum numbers. This is described in more detail in https://doi.org/10.1016/j.jcp.2024.113073.

More detail about the intermediates may be found following Eq. 7 in the above reference.

Parameters:

• l (List) – list (multiset) of angular momentum indices l1,l2,…lN. These correspond to the N spherical harmonics in the ACE descriptor(s).

• L_R (int) – Resultant angular momentum quantum number. This determines the equivariant character of the rank N descriptor after reduction. L_R=0 corresponds to a rotationally invariant feature, L_R=1 corresponds to a feature that transforms like a vector, L_R=2 a tensor, etc.

Returns:

full_inter_tuples – List of all possible “intermediate” angular momenta allowed by polygon conditions. See discussion following Eq. 7 in above reference.

Return type:

List

calculate_highest_coupling_representation(lp, lref)

Find the partition of N that has the biggest cycles that are multiples of 2.

This is used to help define the recursion relationships assigned per frequency partition.

Parameters:

• lp (List) – permutation of l indices

• lref (List) – sorted indices of l

Returns:

highest_rep – partition of N with maximized cycles which are powers of 2

Return type:

tuple

calculate_mu_n_l(nu_in, return_L=False)

Given an ACE descriptor label, nu, return the chemical basis function indices, radial basis function indices, and angular basis function indices.

Parameters:

• nu_in (str) – ACE descriptor label in FitSNAP/LAMMPS format mu0_mu1,mu2…muN,n1,n2…nN,l1,l2…lN_L1-L2-…-L_{N-3}-L_{N-2}

• return_L (bool) – Flag to return multiset of intermediate angular indices

Returns:

mu_n_l – Tuple containing mu0, mu, n and l (and L, if return_L is True).

Return type:

tuple

calculate_mu_nu_rank(nu_in)

Calculate mu-nu rank from nu. Given an ACE descriptor label in FitSNAP/LAMMPS format, return the rank of the descriptor.

Parameters:

nu_in (str) – ACE descriptor label in FitSNAP/LAMMPS format mu0_mu1,mu2…muN,n1,n2…nN,l1,l2…lN_L1-L2-…-L_{N-3}-L_{N-2}

Returns:

mu_nu_rank – Rank computed from label.

Return type:

int

combine_blocks(blocks, lin, L_R=0)

Recombine trees from multiple permutations of l.

Combines ‘blocks’ of functions after rearranging l according to frequency.

Parameters:

• blocks (dict) – labels per block (could use a new name)

• lin (List) – unique (nominally sorted) l

• L_R (int) – Resultant angular momentum quantum number. This determines the equivariant character of the rank N descriptor after reduction. L_R=0 corresponds to a rotationally invariant feature, L_R=1 corresponds to a feature that transforms like a vector, L_R=2 a tensor, etc.

Returns:

combined_labs – combined lL labels for the frequency partition of l (defining the ‘block’ of angular functions to work with).

Return type:

List

combine_muvector_nvector(mu, n)

Tuple vectors mu and n. Adds chemical basis to radial basis indices.

Parameters:

• mu (List) – multiset of chemical basis indices

• n (List) – multiset of radial basis indices

Returns:

tuppled – combined chemical and radial basis indices

Return type:

List

compute_intermediates(l1, l2)

Compute integers lying between absolute difference and sum of l1 and l2.

This function enumerates possible third angular momentum quantum numbers that obey the triangle conditions for quantum angular momentum addition.

See “Definitions” in https://doi.org/10.1016/j.jcp.2024.113073.

Parameters:

• l1 (int) – First angular momentum quantum number

• l2 (int) – Second angular momentum quantum number

Returns:

ints – List of all integers between abs(l1-l2) and l1+l2.

Return type:

List

compute_pa_labels_raw(rank, nmax, lmax, mumax, lmin=1, L_R=0, M_R=0)

Enumerate permutation-adapted ACE descriptors (ace descriptors obeying eq. 33 in https://doi.org/10.1016/j.jcp.2024.113073).

For ranks <=3, this simply uses lexicographically ordered indices. This function enumerates all ACE descriptor labels of rank N, up to a maximumum radial index and up to a maximum angular function index (angular momentum number for spherical harmonics).

Parameters:

• rank (int) – order of the expansion, referred to as N in Drautz 2019, of the descriptors to be enumerated

• nmax (any) – maximum radial basis function index for the given descriptor rank

• lmax (any) – maximum angular momentum number for the given descriptor rank (maximum angular function index)

• mumax (any) – maximum chemical basis index for the given rank (should generally be mumax=len(ace_elements)

• lmin (any) – minimum angular momentum number for the given descriptor rank

• L_R (int) – Resultant angular momentum quantum number. This determines the equivariant character of the rank N descriptor after reduction. L_R=0 corresponds to a rotationally invariant feature, L_R=1 corresponds to a feature that transforms like a vector, L_R=2 a tensor, etc.

• M_R (int) – Resultant projection quantum number. This also determines the equivariant character of the rank N descriptor after reduction. M_R must obey -L_R <= M_R <= L_R

Returns:

all_lammps_labels – PA labels.

Return type:

List

create_unique_combinations(lrng, size)

Create all unique combinations of a size from integers in a range. Useful for enumerating index multisets where repetition of indices is allowed.

Parameters:

• lrng (range) – Range of l-values.

• size (int) – Size of combinations to be created.

Returns:

uniques – List of unique combinations.

Return type:

List

generate_l_LR(lrng, rank, L_R=0, M_R=0, use_permutations=False)

Generate the possible combinations of angular momentum quantum numbers for a given rank. This takes into account that the desired descriptors will, in general, be rotationally invariant.

In short, this function enumerates all possible angular basis function indices for a given descriptor rank (before reducing according to rules defined in Eq. 33 of https://doi.org/10.1016/j.jcp.2024.113073.

Parameters:

• lrng (List) – list of int of possible angular momentum quantum numbers. Typically, these will be (0,1,2…lmax)

• rank (int) – order of the expansion, referred to as N in Drautz 2019, of the descriptors to be enumerated

• L_R (int) – Resultant angular momentum quantum number. This determines the equivariant character of the rank N descriptor after reduction. L_R=0 corresponds to a rotationally invariant feature, L_R=1 corresponds to a feature that transforms like a vector, L_R=2 a tensor, etc.

• M_R (int) – Resultant projection quantum number. This also determines the equivariant character of the rank N descriptor after reduction. M_R must obey -L_R <= M_R <= L_R

• use_permutations (bool) – Logical flag to generate all non-repeating permutations of l for

Returns:

ls – List of angular momenta.

Return type:

List

generate_nl(rank, nmax, lmax, mumax=1, lmin=0, L_R=0, all_perms=False)

Generate lexicographically ordered n,l tuples. (useful for enumerating ACE descriptor labels up to rank 3.

Parameters:

• rank (int) – order of the expansion, referred to as N in Drautz 2019, of the descriptors to be enumerated

• nmax (any) – maximum radial basis function index for the given descriptor rank

• lmax (any) – maximum angular momentum number for the given descriptor rank

• mumax (any) – maximum chemical basis index for the given rank (should generally be mumax=len(ace_elements)

• lmin (any) – minimum angular momentum number for the given descriptor rank

• L_R (int) – Resultant angular momentum quantum number. This determines the equivariant character of the rank N descriptor after reduction. L_R=0 corresponds to a rotationally invariant feature, L_R=1 corresponds to a feature that transforms like a vector, L_R=2 a tensor, etc.

• all_perms (bool) – logical flag to include redundant permutations of ACE descriptor labels. This should only be used for testing.

Returns:

munl – List of munl vectors in string format, i.e. mu0_mu1,mu2,…muk,n1,n2,..n_k,l1,l2,..l_k_L1-L2…-LK

Return type:

List

generate_tree_labels(nin, lin, L_R=0)

Sorts nl according to frequency partitions, not necessarily lexicographically.

This is just a special ordering of n and l multisets that is more compatible with the application of quantum angular momentum “ladder opertations”.

Parameters:

• nin (List) – input collection of radial basis function indices

• lin (List) – input collection of angular basis function indices

• L_R (int) – Resultant angular momentum quantum number. This determines the equivariant character of the rank N descriptor after reduction. L_R=0 corresponds to a rotationally invariant feature, L_R=1 corresponds to a feature that transforms like a vector, L_R=2 a tensor, etc.

Returns:

tree_labels – Tuple containing max_labs, all_labs, labels_per_block and original_spans.

Return type:

tuple

get_mapped(nin, lin)

Sort n and l multisets by frequency of occurence of elements in nin and lin.

For nin, elements of nin are ordered according to their frequency, and a new index is assigned to elements of nin based on their frequency of occurence. The map between these two is saved.

For lin, elements of lin are ordered according to their frequency, and a new index is assigned to elements of lin based on their frequency of occurence. The map between these two is saved.

This function is used to avoid redundant enumeration for radial and angular function index multisets with the same frequency partitions as others.

For example n=(1,1,2,2), l=(1,1,3,5) uses the same frequency partition as n=(2,2,3,3), l=(3,3,4,6). This function makes sure these two cases are handledwith the same frequency partition.

For example, nin = [2,3,3,4] -> mappedn = [0,0,1,2], mprev_n = {0:3,1:2,2:4} and lin = [1,1,1,3] -> mappedl = [0,0,0,1], mprev = {0:1,1:3}.

Parameters:

• nin (List) – radial indices to resort according to frequency and return the mapping to do so

• lin (List) – angular indices to resort according to frequency and return the mapping to do so

Returns:

mappedn – frequency-sorted indices for nin

Return type:

tuple

get_mapped_subset(ns)

Map n indices to a new set of indices based on the frequency of elements in n rather than the values of n themselves.

This tool is to allow one to more conveniently order indices in their respective frequency partitions, as needed by Eq. 33 in https://doi.org/10.1016/j.jcp.2024.113073.

Parameters:

ns (List) – List of possible n multisets

Returns:

reduced_ns – Returns a list of n multisets that have been reordered according to the frequency of elements of n

Return type:

List

lammps_remap(PA_labels, rank, allowed_mus=[0])

Remap PA labels for LAMMPS. Takes (tabulated) PA labels enumerated with n and l multisets, and adds in chemical basis indices.

In other words, this function maps munl PA labels to nl labels compatible with lammps .yace basis.

Parameters:

• PA_labels (List) – List of PA labels to be remapped.

• rank (int) – Rank used for the remapping.

• allowed_mus (List) – Allowed mu values for the remapping.

Returns:

remapped – Tuple contain the remapped labels that are compatible with lammps descriptor calculators and, in very rare cases, labels that are not compatible.

Return type:

tuple

read_from_tabulated(mu, n, l, allowed_mus=[0], tabulated_all=None)

Read PA ACE descriptor labels from tabulated data saved to a json file (by build_tabulated).

Since functions are only tabulated for n-l a conversion is made to include chemical basis indices as well and make sure that they are permutation-adapted independent as well.

Parameters:

• mu (List) – list of chemical basis indices mu1,mu2,…muN

• n (List) – list of radial basis indices n1,n2,…nN

• l (List) – list of radial basis indices l1,l2,…lN

• allowed_mus (List) – all possible allowed chemical basis function indices. (generated by range(mumax))

• tabulated_all (dict) – optionally, pass in tabulated PA ACE descriptor labels as a dictionary

Returns:

chem_labels – Labels read from json file.

Return type:

List

simple_parity_filter(l, inters, even=True)

Filter possible couplings according to parity of intermediates.

Parameters:

• l (List) – collection of angular momentum quantum numbers [l1,l2,…lN]

• inters – possible multisets of intermediates [(L1,L2…L_{N-2}),(L1’,L2’,…L_{N-2})’ …]

• even (bool) – Control for which parity to filter according to. (For L_R=0 - will use ‘even’)

Returns:

inters_filt – Filtered multisets of intermediates obeying parity constraints.

Return type:

List