I/O Checks: Molecule

I/O Checks: Molecule#

This module contains various checkers for the molecule that is read/written.

In particular,the following checks can be done: - coldfusion_check (interatomic distances) - content_checks (atomic numbers) - deflatable_check (clash between padding and coordinates)

Note

The check deflatable_check attempts to catch cases, in which the padding value (default: 0) is the same as a triple of atomic positions, which would obscure the distinction between padding and actual atomic positions in batched calculations. This primarily occurs for single atoms, which are usually placed at the origin. The behavior of this check is best controlled through keyword arguments of the respective readers. The available keyword arguments are: - padding_value (float | int, default: 0): Value for padding used in check - raise_padding_exception (bool, default: False): Raise an exception (or just a warning) - raise_padding_warning (bool, default: True): Raise a warning - shift_for_last (bool, default: False): Automatically shift all positions by a constant if a clash is detected - shift_value (float | int, default: 1.0): Constant for shift.

For more details and examples, check test/test_io/test_deflatable.py.

tad_mctc.io.checks.molecule.coldfusion_check(numbers, positions, threshold=None)[source]#

Check if interatomic distances are large enough (no fusion of atoms).

Parameters:

  • numbers (Tensor) – A 1D tensor containing atomic numbers or symbols.

  • positions (Tensor) – A 2D tensor of shape (n_atoms, 3) containing atomic positions.

  • threshold (Tensor | float | int | None, optional) – Threshold for acceptable interatomic distances. Defaults to None, which resolves to torch.tensor(torch.finfo(dtype).eps ** 0.75, **dd).

Returns:

True of atoms are not too close.

Return type:

bool

Raises:

MoleculeError – Interatomic distances are too close.

tad_mctc.io.checks.molecule.content_checks(numbers, positions, max_element=118, allow_batched=True)[source]#

Check the content of the numbers and positions tensors.

This function should be asserted as it returns True on success and raises an error on failure.

Parameters:

  • numbers (Tensor) – Atomic numbers for all atoms in the system of shape (..., nat).

  • positions (Tensor) – Cartesian coordinates of all atoms (shape: (..., nat, 3)).

  • max_element (int, optional) – Maximum atomic number allowed. Defaults to tad_mctc.data.pse.MAX_ELEMENT.

  • allow_batched (bool, optional) – Allow batched tensors. Defaults to True.

Returns:

True if content is correct.

Return type:

bool

Raises:

MoleculeError – Atomic number too large or too small.

tad_mctc.io.checks.molecule.deflatable_check(positions, fileobj=None, **kwargs)[source]#

Check for the last coordinate being at the origin as this might clash with padding.

This function should be asserted as it returns True on success and raises an error on failure.

Parameters:

  • positions (Tensor) – A 2D tensor of shape (nat, 3) containing atomic positions.

  • fileobj (IO[Any] | None, optional) – The file-like object from which is read (only for printing).

Returns:

True if content is correct.

Return type:

bool

Raises:

MoleculeError – Padding clashes with coordinates. Requires the keyword argument raise_padding_exception=True.

tad_mctc.io.checks.molecule.dimension_check(x, min_ndim=-1, max_ndim=9999)[source]#

Check if the number of dimensions of a tensor is within a certain range.

Parameters:

  • x (Any) – The tensor to check.

  • min_ndim (int, optional) – Minimum number of dimensions for the tensor. Defaults to -1.

  • max_ndim (int, optional) – Maximum number of dimensions for the tensor. Defaults to 9999.

Returns:

Returns None if the tensor has the correct number of dimensions.

Return type:

None | NoReturn

Raises:

  • TypeError – If the input is not a tensor.

  • RuntimeError – If the number of dimensions is not within the specified range.

Examples

>>> import torch
>>> from tad_mctc.io.checks.molecule import dimension_check
>>> x = torch.tensor([1, 2, 3])
>>> dimension_check(x, min_ndim=1, max_ndim=1)
True
>>> dimension_check(x, min_ndim=2, max_ndim=2)
Traceback (most recent call last):
...
RuntimeError: The tensor should not fall below '2' dimensions.
Contents