system and Target data Readers

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

metatensor.models.utils.data.read_systems(filename: str, fileformat: str | None = None, dtype: dtype = torch.float32) → List[System][source]

Read system informations from a file.

Parameters:

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

  • fileformat (str | None) – format of the system file. If None the format is determined from the suffix.

  • dtype (dtype) – desired data type of returned tensor

Returns:

list of systems

Return type:

List[System]

metatensor.models.utils.data.read_targets(conf: DictConfig, dtype: dtype = torch.float32) → Dict[str, List[TensorMap]][source]

Reading all target information from a fully expanded config.

To get such a config you can use metatensor.models.utils.omegaconf.expand_dataset_config().

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 silentlty irgnored.

Parameters:

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

  • dtype (dtype) – desired data type of returned tensor

Returns:

Dictionary containing one TensorMaps for each target section in the config.

Raises:

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

Return type:

Dict[str, List[TensorMap]]

Target type specific readers

metatensor.models.utils.data.read_targets() uses sub-functions to parse supported target properties like the energy or forces. Currently we support reading the following target properties via

metatensor.models.utils.data.read_energy(filename: str, target_value: str = 'energy', fileformat: str | None = None, dtype: dtype = torch.float32) → List[TensorBlock][source]

Read energy informations from a file.

Parameters:

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

  • target_value (str) – target value key name to be parsed from the file.

  • fileformat (str | None) – format of the system file. If None the format is determined from the suffix

  • dtype (dtype) – desired data type of returned tensor

Returns:

target value stored stored as a metatensor.TensorBlock

Return type:

List[TensorBlock]

metatensor.models.utils.data.read_forces(filename: str, target_value: str = 'forces', fileformat: str | None = None, dtype: dtype = torch.float32) → List[TensorBlock][source]

Read force informations from a file.

Parameters:

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

  • target_value (str) – target value key name to be parsed from the file

  • fileformat (str | None) – format of the system file. If None the format is determined from the suffix

  • dtype (dtype) – desired data type of returned tensor

Returns:

target value stored stored as a metatensor.TensorBlock

Return type:

List[TensorBlock]

metatensor.models.utils.data.read_virial(filename: str, target_value: str = 'virial', fileformat: str | None = None, dtype: dtype = torch.float32) → List[TensorBlock][source]

Read virial informations from a file.

Parameters:

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

  • target_value (str) – target value key name to be parsed from the file.

  • fileformat (str | None) – format of the system file. If None the format is determined from the suffix.

  • dtype (dtype) – desired data type of returned tensor

Returns:

target value stored stored as a metatensor.TensorBlock

Return type:

List[TensorBlock]

metatensor.models.utils.data.read_stress(filename: str, target_value: str = 'stress', fileformat: str | None = None, dtype: dtype = torch.float32) → List[TensorBlock][source]

Read stress informations from a file.

Parameters:

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

  • target_value (str) – target value key name to be parsed from the file.

  • fileformat (str | None) – format of the system file. If None the format is determined from the suffix

  • dtype (dtype) – desired data type of returned tensor

Returns:

target value stored stored as a metatensor.TensorBlock

Return type:

List[TensorBlock]

File type specific readers

Based on the provided file_format they chose which sub-reader they use. For details on these refer to their documentation