torchani.utils#

Misc utilities used throughout the code

Module Attributes

`SYMBOLS_1X`	Elements used in the ANI-1x and ANI-1ccx models, in order
`SYMBOLS_2X`	Elements used in the ANI-2x model, in ani2x-model-order
`SYMBOLS_2X_ZNUM_ORDER`	Elements used in the ANI-2x model, in znum order

Functions

`download_and_extract`	Download and extract a .tar.gz or .zip file form a given url
`strip_redundant_padding`	Strip padding from a sequence of padded properties
`pad_atomic_properties`	Combine a sequence of properties together into single tensor.
`sort_by_atomic_num`	Sort an iterable of chemical symbols by atomic number
`get_atomic_masses`	Convert a sequence of atomic nubmers to masses

Classes

`AtomicNumbersToChemicalSymbols`	Converts tensor of atomic numbers to list of chemical symbols
`IntsToChemicalSymbols`	Convert tensor or list of integers to list[str] of chemical symbols
`ChemicalSymbolsToInts`	Helper that can be called to convert chemical symbol string to integers
`ChemicalSymbolsToAtomicNumbers`	Converts a sequence of chemical symbols into a tensor of atomic numbers
`AtomicNumbersToMasses`	Convert a tensor of atomic numbers into a tensor of atomic masses
`EnergyShifter`	Helper class for adding and subtracting self atomic energies

torchani.utils.download_and_extract(url, file_name, dest_dir, verbose=False)[source]#

Download and extract a .tar.gz or .zip file form a given url

torchani.utils.strip_redundant_padding(properties, atomic_properties=('species', 'numbers', 'atomic_numbers', 'coordinates', 'forces', 'coefficients', 'atomic_charges', 'atomic_volumes_mbis', 'atomic_charges_mbis', 'atomic_dipole_magnitudes_mbis', 'atomic_quadrupole_magnitudes_mbis', 'atomic_octupole_magnitudes_mbis', 'atomic_dipoles', 'atomic_polarizabilities'))[source]#

Strip padding from a sequence of padded properties

torchani.utils.pad_atomic_properties(properties, padding_values=None)[source]#

Combine a sequence of properties together into single tensor.

Inputs are [{'species': tensor, ...}, {'species': tensor, ...}, ...] and the output is of the form {'species': padded_tensor, ...}.

Parameters:

properties (Sequence[Mapping[str, Tensor]]) – Sequence of properties
padding_values (Dict[str, float] | None) – Values to use for padding.

Returns:

Padded tensors.

Return type:

Dict[str, Tensor]

class torchani.utils.AtomicNumbersToChemicalSymbols[source]#

Converts tensor of atomic numbers to list of chemical symbols

On initialization, it is optional to supply the class with a dict containing custom numbers and symbols. This is not necessary, as the class is provided ATOMIC_NUMBER by default. Otherwise, the class should be supplied with a list of str.The returned instance is a callable object, which can be called an arbituary tensor of the supported atomic numbers that is converted into a list of strings.

Usage example: .. code-block:: python

# We intialize our class numbers_to_symbols = AtomicNumberstoChemicalSymbols()

# We have atomic numbers which we want to convert to a species list atomic_numbers = torch.tensor([6, 1, 1, 1])

symbols = numbers_to_symbols(atomic_numbers)

Output:
[‘C’, ‘H’, ‘H’, ‘H’]

Arguments:
atomic_numbers: tensor of atomic number values you wish to convert (must be 1-D)

class torchani.utils.IntsToChemicalSymbols(symbols)[source]#

Convert tensor or list of integers to list[str] of chemical symbols

On initialization, it is optional to supply the class with a dict containing custom numbers and symbols. This is not necessary, as the class is provided ATOMIC_NUMBER by default. Otherwise, the class should be supplied with a list of str. The returned instance is a callable object, which can be called with an arbitrary list or tensor of the supported indicies that is converted into a list of strings.

Parameters:: symbols (Sequence[str]) – A tuple or list of strings that are valid chemical symbols. (case sensitive).

# Species list used for indexing
elements = ['H','C','N','O','S','F', 'Cl']
species_converter = IntsToChemicalSymbols(elements)
species = torch.Tensor([3, 0, 0, -1, -1, -1])
species_converter(species)  # Output: ['O', 'H', 'H']

class torchani.utils.ChemicalSymbolsToInts(symbols, device=None)[source]#

Helper that can be called to convert chemical symbol string to integers

On initialization the class should be supplied with a list of str. The returned instance is a callable object, which can be called with an arbitrary list of the supported species that is converted into an integer tensor. Usage example:

from torchani.utils import ChemicalSymbolsToInts
# We initialize ChemicalSymbolsToInts with the supported species
elements = ['H', 'C', 'N', 'O', 'S', 'F', 'Cl']
species_to_tensor = ChemicalSymbolsToInts(elements)
species_convert = ['C', 'S', 'O', 'F', 'H', 'H']
# We have a species list which we want to convert to an index tensor
index_tensor = species_to_tensor(species_convert)
# index_tensor is now [1, 4, 3, 5, 0, 0]

Parameters:: symbols (Sequence[str]) – A tuple or list of strings that are valid chemical symbols. (case sensitive).

class torchani.utils.ChemicalSymbolsToAtomicNumbers(device=None)[source]#

Converts a sequence of chemical symbols into a tensor of atomic numbers

On initialization, it is optional to supply the class with a dict containing custom numbers and symbols. This is not necessary, as the class is provided ATOMIC_NUMBER by default. Output is an integer tensor. Usage example:

# We have a species list which we want to convert to atomic numbers
symbols_to_numbers = ChemicalSymbolsToAtomicNumbers()
species_convert = ['C', 'S', 'O', 'F', 'H', 'H']
atomic_numbers = symbols_to_numbers(species_convert)
# atomic_numbers is now torch.tensor([ 6, 16,  8,  9,  1,  1])

class torchani.utils.AtomicNumbersToMasses(masses=(), device=None, dtype=None)[source]#

Convert a tensor of atomic numbers into a tensor of atomic masses

forward(atomic_numbers)[source]#

Perform conversion to atomic masses

Parameters:: atomic_numbers (Tensor) – An int tensor that stores the atomic numbers of a batch of molecules. Shape is (molecules, 3).
Returns:: Tensor of atomic masses, with the same shape as the input.
Return type:: Tensor

torchani.utils.sort_by_atomic_num(it)[source]#

Sort an iterable of chemical symbols by atomic number

Parameters:: it (Iterable[str]) – Iterable of chemical symbols
Returns:: Sorted tuple of chemical symbols
Return type:: Tuple[str, …]

class torchani.utils.EnergyShifter(self_energies, fit_intercept=False)[source]#

Helper class for adding and subtracting self atomic energies

Deprecated:: This class is part of the Legacy API. Please use torchani.sae.SelfEnergy, which has equivalent functionality, instead.

Parameters:

self_energies (list[float]) – Sequence of floating numbers for the self energy of each atom type. The numbers should be in order, i.e. self_energies[i] should be atom type i.
fit_intercept (bool) – Whether to calculate the intercept during the LSTSQ fit. The intercept will also be taken into account to shift energies.

sae(species)[source]#

Compute self energies for molecules.

Padding atoms are automatically excluded.

Parameters:: species (Tensor) – An int torch.Tensor that stores the element indices of a batch of molecules, (for example after conversion with torchani.nn.SpeciesConverter). Shape is (molecules, 3).
Returns:: 1D tensor of shape (molecules,) with molecular self-energies
Return type:: Tensor

forward(species_energies, cell=None, pbc=None)[source]#

Transforms a species_energies tuples by adding self-energies

torchani.utils.get_atomic_masses(atomic_numbers, dtype=torch.float32)#

Convert a sequence of atomic nubmers to masses

Convenience wrapper over AtomicNumbersToMasses. Non-jittable.

torchani.utils.SYMBOLS_1X: Tuple[str, ...] = ('H', 'C', 'N', 'O')#: Elements used in the ANI-1x and ANI-1ccx models, in order

torchani.utils.SYMBOLS_2X: Tuple[str, ...] = ('H', 'C', 'N', 'O', 'S', 'F', 'Cl')#: Elements used in the ANI-2x model, in ani2x-model-order

torchani.utils.SYMBOLS_2X_ZNUM_ORDER: Tuple[str, ...] = ('H', 'C', 'N', 'O', 'F', 'S', 'Cl')#: Elements used in the ANI-2x model, in znum order