Readers

Parsers for obtaining system and target information from files. Currently, metatrain support the following libraries for reading data

Library	Supported targets	Linked file formats
ase	system, energy, forces, stress, virials	.xyz, .extxyz
metatensor	system, energy, forces, stress, virials	.mts

If the reader parameter is not set, the library is determined from the file extension. Overriding this behavior is in particular useful if a file format is not listed here but might be supported by a library.

Below the synopsis of the reader functions in details.

System and target data readers

The main entry point for reading system and target information are the reader functions.

metatrain.utils.data.read_systems(filename: str, reader: str | None = None) → List[System]

Read system informations from a file.

Parameters:

• filename (str) – name of the file to read

• reader (str | None) – reader library for parsing the file. If None the library is is tried to determined from the file extension.

• dtype – desired data type of returned tensor

Returns:

list of systems determined from the file extension.

Raises:

ValueError – if no reader is found or data not in double precision

Return type:

List[System]

metatrain.utils.data.read_targets(conf: DictConfig) → Tuple[Dict[str, List[TensorMap]], Dict[str, TargetInfo]]

Reading all target information from a fully expanded config.

To get such a config you can use expand_dataset_config. All targets are stored in double precision.

This function uses subfunctions like read_energy() to parse the requested target quantity. Currently only energy is a supported target property. But, within the energy section gradients such as forces, the stress or the virial can be added. Other gradients are silently ignored.

Parameters:

conf (DictConfig) – config containing the keys for what should be read.

Returns:

Dictionary containing a list of TensorMaps for each target section in the config as well as a Dict[str, TargetInfo] object containing the metadata of the targets.

Raises:

ValueError – if the target name is not valid. Valid target names are those that either start with mtt:: or those that are in the list of standard outputs of metatomic (see https://docs.metatensor.org/metatomic/latest/outputs/)

Return type:

Tuple[Dict[str, List[TensorMap]], Dict[str, TargetInfo]]

These functions dispatch the reading of the system and target information to the appropriate readers, based on the file extension or the user-provided library.

In addition, the read_targets function uses the user-provided information about the targets to call the appropriate target reader function (for energy targets or generic targets).

ASE

This section describes the parsers for the ASE library.

metatrain.utils.data.readers.ase.read(filename: str | PurePath | IO, *args, **kwargs) → List[Atoms]

Wrapper around the ase.io.read() function.

The wrapper provides a more informative error message in case of failure. Additionally, it will make the keys "energy", "forces" and "stress" available from the calculator and the info/arrays dictionary.

Warning

Lists of atoms read with this function can NOT be written back to a file with ase.io.write() because of the duplicated keys.

Parameters:

• filename (str | PurePath | IO) – Name of the file to read from or a file descriptor.

• args – additional positional arguments for ase.io.read()

• kwargs – additional keyword arguments for ase.io.read()

Returns:

A list of atoms

Return type:

List[Atoms]

metatrain.utils.data.readers.ase.read_systems(filename: str) → List[System]

Store system informations using ase.

Parameters:

filename (str) – name of the file to read

Returns:

A list of systems

Return type:

List[System]

metatrain.utils.data.readers.ase.read_energy(target: DictConfig) → Tuple[List[TensorMap], TargetInfo]

Parameters:

target (DictConfig)

Return type:

Tuple[List[TensorMap], TargetInfo]

metatrain.utils.data.readers.ase.read_generic(target: DictConfig) → Tuple[List[TensorMap], TargetInfo]

Parameters:

target (DictConfig)

Return type:

Tuple[List[TensorMap], TargetInfo]

It should be noted that metatrain.utils.data.readers.ase.read_energy() currently uses sub-functions to parse the energy and its gradients like forces, virial and stress.

Metatensor

This section describes the parsers for the metatensor library. As the systems and/or targets are already stored in the metatensor format, these reader functions mainly perform checks and return the data.

metatrain.utils.data.readers.metatensor.read_systems(filename: str) → List[System]

Read system information using metatensor.

Parameters:

filename (str) – name of the file to read

Raises:

NotImplementedError – Serialization of systems is not yet available in metatensor.

Return type:

List[System]

metatrain.utils.data.readers.metatensor.read_energy(target: DictConfig) → Tuple[TensorMap, TargetInfo]

Parameters:

target (DictConfig)

Return type:

Tuple[TensorMap, TargetInfo]

metatrain.utils.data.readers.metatensor.read_generic(target: DictConfig) → Tuple[List[TensorMap], TargetInfo]

Parameters:

target (DictConfig)

Return type:

Tuple[List[TensorMap], TargetInfo]