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][source]¶

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.

Returns:

list of System objects 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]][source]¶

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: Any, **kwargs: Any) → List[Atoms][source]¶

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 (Any) – additional positional arguments for ase.io.read()
**kwargs (Any) – additional keyword arguments for ase.io.read()

Returns:

A list of ase.Atoms objects

Return type:

List[Atoms]

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

Store system informations using ase.

Parameters:: filename (str) – name of the file to read
Returns:: The systems read from the file
Return type:: List[System]

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

Read energy target from an ASE-readable file.

Parameters:

target_name (str) – Name of the target to read.
target (DictConfig) – Configuration settings for the target.

Returns:

The function returns two outputs:

A list of TensorMap objects, each of them being the target for a single
system.
A TargetInfo object containing metadata about the target.

Return type:

Tuple[List[TensorMap], TargetInfo]

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

Read a generic target from an ASE-readable file.

Parameters:

target_name (str) – Name of the target to read.
target (DictConfig) – Configuration settings for the target.

Returns:

The function returns two outputs:

A list of TensorMap objects, each of them being the target for a single
system.
A TargetInfo object containing metadata about the target.

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][source]¶

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.
Returns:: list of System objects
Return type:: List[System]

metatrain.utils.data.readers.metatensor.read_energy(target_name: str, target: DictConfig) → Tuple[List[TensorMap], TargetInfo][source]¶

Read an energy target information using metatensor.

Parameters:

target_name (str) – Name of the target to read.
target (DictConfig) – Configuration settings for the target.

Returns:

The function returns two outputs:

A list of TensorMap objects, each of them being the energy target for a
single system.
A TargetInfo object containing metadata about the target.

Return type:

Tuple[List[TensorMap], TargetInfo]

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

Read target information using metatensor.

Parameters:

target_name (str) – Name of the target to read.
target (DictConfig) – Configuration settings for the target.

Returns:

The function returns two outputs:

A list of TensorMap objects, each of them being the target for a
single system.
A TargetInfo object containing metadata about the target.

Return type:

Tuple[List[TensorMap], TargetInfo]