repESP.equivalence module¶

Chemical equivalence relations between atoms of a molecule

class Equivalence(values: List[Optional[int]])[source]¶

Bases: object

Dataclass representing chemical equivalence relations between atoms

Atoms in a molecule are considered equivalent for the purpose of fitting partial charges when they are symmetry-related or fast-exchanging.

The equivalence information is represented as a list stored in the values attribute. The length of this list must be the same as the number of atoms in the molecule it describes. Consecutive values refer to consecutive atoms of the molecule. Each value is either None, if the described atom is not equivalenced to any other atom, or a zero-based index of the atom to which the described atom is equivalenced.

Example

Consider a methane molecule defined as follows:

>>> methane = Molecule([Atom(atomic_number) for atomic_number in [6, 1, 1, 1, 1]])

The corresponding equivalence information would be:

>>> equivalence = Equivalence([None, None, 1, 1, 1])

There are no atoms equivalent to the carbon atom, and thus its value is None. The first hydrogen atom is equivalent to the other three but those have not been specified yet, so its value is also None. The remaining three hydrogen atoms are equivalent to the first hydrogen atom, which zero-based index in the methane.atoms list is 1.

Parameters:	values (typing.List[Optional[int]]) – The list of equivalence values.
Raises:	`ValueError` – Raised when any of the values are outside of the expected bounds. In the future the initialization may further verify that there are no cyclic relations.

values¶: See initialization parameter

describe(molecule: Optional[repESP.types.Molecule[repESP.types.Atom][repESP.types.Atom]] = None) → str[source]¶

Verbosely report the equivalence information

Example

>>> print(equivalence.describe(methane))
Atom (C) number 1
Atom (H) number 2
Atom (H) number 3, equivalenced to atom 1
Atom (H) number 4, equivalenced to atom 2
Atom (H) number 5, equivalenced to atom 2

Parameters:	molecule (Optional[Molecule[Atom]], optional) – The molecule to which the equivalence information refers. This argument is optional and defaults to None. If it is provided, atom identities will be included in the output.
Raises:	`ValueError` – Raised when the number of atoms in the molecule does not match the length of the list of values in this object.
Returns:	A verbose description of the equivalence information.
Return type:	str