qstack.qml.slatm

Spectrum of London and Axilrod-Teller-Muto potential (SLATM) representation.

Provides:

defaults: Default parameters for SLATM representation.

qstack.qml.slatm.get_mbtypes(qs, qml=False)[source]

Generate many-body types (elements, pairs, triples) for SLATM representation.

Parameters:

  • qs (list) – List of atomic number arrays for all molecules.

  • qml (bool) – If True, uses set ordering (QML-compatible). If False, uses sorted ordering. Defaults to False.

Returns:

Dictionary with keys 1, 2, 3 containing: - 1: Array of unique elements - 2: List of element pairs (including self-pairs) - 3: List of valid element triples

Return type:

dict

qstack.qml.slatm.get_slatm(q, r, mbtypes, qml_compatible=True, stack_all=True, global_repr=False, r0=0.1, rcut=4.8, sigma2=0.05, dgrid2=0.03, theta0=0.3490658503988659, sigma3=0.05, dgrid3=0.03)[source]

Compute SLATM representation for a single molecule.

Constructs the SLATM (Spectrum of London and Axilrod-Teller-Muto potential) representation by combining one-body (nuclear charges), two-body (London dispersion), and three-body (Axilrod-Teller-Muto) contributions.

Reference:

B. Huang, O. A. von Lilienfeld, “Quantum machine learning using atom-in-molecule-based fragments selected on the fly”, Nat. Chem. 12, 945–951 (2020), doi:10.1038/s41557-020-0527-z

Parameters:

  • q (numpy.ndarray) – Array of atomic numbers (natom,).

  • r (numpy.ndarray) – Atomic position array (natom,3) in Å.

  • mbtypes (dict) – Many-body types from get_mbtypes with keys 1, 2, 3.

  • qml_compatible (bool) – If True, maintains QML package compatibility. If False, uses condensed representation (less 0s). Defaults to True. Is set to True if global_repr is True.

  • stack_all (bool) – If True, stacks all representations into one array. Defaults to True.

  • global_repr (bool) – If True, returns molecular SLATM (sum over atoms). If False, returns atomic SLATM. Defaults to False.

  • r0 (float) – Minimum radial distance for 2-body grid. Defaults to 0.1 Å.

  • rcut (float) – Radial cutoff for 2-body and 3-body terms. Defaults to 4.8 Å.

  • sigma2 (float) – Gaussian width for 2-body term. Defaults to 0.05 Å.

  • dgrid2 (float) – Grid spacing for 2-body term. Defaults to 0.03 Å.

  • theta0 (float) – Minimum angle for 3-body grid in radians. Defaults to 20°.

  • sigma3 (float) – Gaussian width for 3-body term in radians. Defaults to 0.05.

  • dgrid3 (float) – Grid spacing for 3-body term in radians. Defaults to 0.03.

Returns:

SLATM representation. - If stack_all=True and global_repr=False, numpy ndarray of shape (natom,n_features). - If global_repr=True, numpy ndarray of shape (n_features,). - If stack_all=False, returns dict with keys 1, 2, 3 containing lists of numpy ndarrays.

Return type:

numpy.ndarray or dict

qstack.qml.slatm.get_slatm_for_dataset(molecules, progress=False, global_repr=False, qml_mbtypes=True, qml_compatible=True, stack_all=True, r0=0.1, rcut=4.8, sigma2=0.05, dgrid2=0.03, theta0=0.3490658503988659, sigma3=0.05, dgrid3=0.03)[source]

Compute the (a)SLATM representation for a set of molecules.

Generates SLATM descriptors for molecular datasets, automatically determining many-body types from all molecules.

Parameters:

  • molecules (Union[List[Mol], List[str]]) – Pre-loaded molecules or paths to XYZ files. Mol can be any type with .numbers and .positions (Å) attributes, for example ASE Atoms objects.

  • progress (bool) – If True, displays progress bar. Defaults to False.

  • global_repr (bool) – If True, returns molecular SLATM (sum over atoms). If False, returns atomic SLATM (aSLATM). Defaults to False.

  • qml_mbtypes (bool) – If True, uses element ordering compatible with QML package (https://www.qmlcode.org/). If False, uses sorted ordering. Defaults to True.

  • qml_compatible (bool) – If False, uses condensed representation for local (global_repr=False) mode. Defaults to True.

  • stack_all (bool) – If True, stacks representations into one array. Defaults to True.

  • r0 (float) – Minimum radial distance for 2-body grid in Å. Defaults to 0.1.

  • rcut (float) – Radial cutoff for 2-body and 3-body terms in Å. Defaults to 4.8.

  • sigma2 (float) – Gaussian width for 2-body term in Å. Defaults to 0.05.

  • dgrid2 (float) – Grid spacing for 2-body term in Å. Defaults to 0.03.

  • theta0 (float) – Minimum angle for 3-body grid in radians. Defaults to 20° (π/9).

  • sigma3 (float) – Gaussian width for 3-body term in radians. Defaults to 0.05.

  • dgrid3 (float) – Grid spacing for 3-body term in radians. Defaults to 0.03.

Returns:

SLATM representations for all molecules.

  • If stack_all=True and global_repr=True, np.ndarray of shape (n_molecules, n_features),

  • If stack_all=True and global_repr=False, np.ndarray of shape (n_atoms_total, n_features),

  • If stack_all=False and global_repr=True, list of np.ndarrays of shape (n_features,) per molecule,

  • If stack_all=False and global_repr=False, list of lists of dicts per molecule with keys (1,2,3).

Return type:

numpy.ndarray or List[List[numpy.ndarray]]

qstack.qml.slatm.get_slatm_rxn(reactions, progress=False, qml_mbtypes=True, r0=0.1, rcut=4.8, sigma2=0.05, dgrid2=0.03, theta0=0.3490658503988659, sigma3=0.05, dgrid3=0.03)[source]

Compute the SLATM_d representation for chemical reactions.

Calculates reaction representations as the difference between product and reactant SLATM descriptors (ΔR = R_products - R_reactants), suitable for predicting reaction properties like barriers and energies.

Reference:

P. van Gerwen, A. Fabrizio, M. D. Wodrich, C. Corminboeuf, “Physics-based representations for machine learning properties of chemical reactions”, Mach. Learn.: Sci. Technol. 3, 045005 (2022), doi:10.1088/2632-2153/ac8f1a

Parameters:

  • reactions (List[rxn]) – List of reaction objects with attributes: - rxn.reactants (List[Mol]): List of reactant molecules. - rxn.products (List[Mol]): List of product molecules. Mol can be any type with .numbers and .positions (Å) attributes, for example ASE Atoms objects.

  • progress (bool) – If True, displays progress bar. Defaults to False.

  • qml_mbtypes (bool) – If True, uses element ordering compatible with QML package (https://www.qmlcode.org/). If False, uses sorted ordering. Defaults to True.

  • r0 (float) – Minimum radial distance for 2-body grid in Å. Defaults to 0.1.

  • rcut (float) – Radial cutoff for 2-body and 3-body terms in Å. Defaults to 4.8.

  • sigma2 (float) – Gaussian width for 2-body term in Å. Defaults to 0.05.

  • dgrid2 (float) – Grid spacing for 2-body term in Å. Defaults to 0.03.

  • theta0 (float) – Minimum angle for 3-body grid in radians. Defaults to 20° (π/9).

  • sigma3 (float) – Gaussian width for 3-body term in radians. Defaults to 0.05.

  • dgrid3 (float) – Grid spacing for 3-body term in radians. Defaults to 0.03.

Returns:

SLATM_d difference representations of shape (n_reactions, n_features),

where each row is the difference between product and reactant SLATM vectors.

Return type:

numpy.ndarray

qstack.qml.slatm.get_three_body(j, mbtype, q, r, dist, rcut=4.8, theta0=0.3490658503988659, sigma=0.05, dgrid=0.03)[source]

Compute three-body Axilrod-Teller-Muto contribution for atom j.

Evaluates the three-body ATM term from triple-dipole interactions, projected onto an angular grid with Gaussian broadening of bond angles.

Parameters:

  • j (int) – Index of the central atom in the triplet.

  • mbtype (tuple) – Element triple (q1, q2, q3) defining the three-body interaction type.

  • q (numpy.ndarray) – Array of atomic numbers for all atoms.

  • r (numpy.ndarray) – Atomic position array (natom,3) in Å.

  • dist (numpy.ndarray) – Pairwise distance matrix (natom,natom) in Å.

  • rcut (float) – Distance cutoff for triplet formation. Defaults to 4.8 Å.

  • theta0 (float) – Margin for angular grid in radians. Defaults to 20°.

  • sigma (float) – Gaussian width for angle broadening in radians. Defaults to 0.05.

  • dgrid (float) – Grid spacing for angular discretization in radians. Defaults to 0.03.

Returns:

Three-body contribution on angular grid (ngrid,).

Return type:

numpy.ndarray

qstack.qml.slatm.get_two_body(i, mbtype, q, dist, r0=0.1, rcut=4.8, sigma=0.05, dgrid=0.03)[source]

Compute two-body London dispersion contribution for atom i.

Evaluates the two-body term from pairwise 1/r^6 London dispersion interactions, projected onto a radial grid with Gaussian broadening of interatomic distances.

Parameters:

  • i (int) – Index of the central atom.

  • mbtype (tuple) – Element pair (q1, q2) defining the two-body interaction type.

  • q (numpy.ndarray) – Array of atomic numbers for all atoms in molecule.

  • dist (numpy.ndarray) – Pairwise distance matrix (natom,natom) in Å.

  • r0 (float) – Minimum radial distance for grid. Defaults to 0.1 Å.

  • rcut (float) – Radial cutoff distance. Defaults to 4.8 Å.

  • sigma (float) – Gaussian width for distance broadening. Defaults to 0.05 Å.

  • dgrid (float) – Grid spacing for radial discretization. Defaults to 0.03 Å.

Returns:

Two-body contribution on radial grid (ngrid,).

Return type:

numpy.ndarray