Models

Most of the code in metatensor.torch.atomistic is here to define and export models and to store model metadata. The corresponding classes are documented below:

• Exporting models
• Information about models

We also provide a couple of functions to work with the models:

metatensor.torch.atomistic.read_model_metadata(path: str) → ModelMetadata

Read metadata of a saved metatenor atomistic model.

This function allows to access the metadata of a model without loading it in advance.

Parameters:

path (str) – path to the exported model file

Return type:

ModelMetadata

metatensor.torch.atomistic.load_atomistic_model(path, extensions_directory=None) → MetatensorAtomisticModel

Check and then load the metatensor atomistic model at the given path.

This function calls metatensor.torch.atomistic.check_atomistic_model() and metatensor.torch.atomistic.load_model_extensions() before attempting to load the model.

Parameters:

• path – path to an exported metatensor model

• extensions_directory – path to a directory containing all extensions required by the exported model

Return type:

MetatensorAtomisticModel

metatensor.torch.atomistic.check_atomistic_model(path: str)

Check that the file at path contains an exported metatensor atomistic model, and that this model can be loaded in the current process.

This function should be called before torch.jit.load() when loading an existing model.

Parameters:

path (str) – path to the exported model file

metatensor.torch.atomistic.load_model_extensions(path: str, extensions_directory: str | None = None)

Load the TorchScript extensions (and their dependencies) that the model at path uses.

If extensions_directory is provided, we look for the extensions and their dependencies in there first. If this function fails to load some library, it will produce a warning using Torch’s warnings infrastructure. Users can set the METATENSOR_DEBUG_EXTENSIONS_LOADING environment variable to get more informations about a failure in the standard error output.

Parameters:

• path (str) – path to the exported model file

• extensions_directory (str | None) – path to a directory containing the extensions. This directory will typically be created by calling MetatensorAtomisticModel.export() with collect_extensions=extensions_directory.

metatensor.torch.atomistic.unit_conversion_factor(quantity: str, from_unit: str, to_unit: str)

Get the multiplicative conversion factor from from_unit to to_unit. Both units must be valid and known for the given physical quantity. The set of valid quantities and units is available here.

Parameters:

• quantity (str) – name of the physical quantity

• from_unit (str) – current unit of the data

• to_unit (str) – target unit of the data

Known quantities and units

The following quantities and units can be used with metatensor models. Adding new units and quantities is very easy, please contact us if you need something else! In the mean time, you can create metatensor.torch.atomistic.ModelOutput with quantities that are not in this table. A warning will be issued and no unit conversion will be performed.

When working with one of the quantity in this table, the unit you use must be one of the registered unit.

quantity	units
length	angstrom (A), Bohr, meter, centimeter (cm), millimeter (mm), micrometer (um, µm), nanometer (nm)
energy	eV, meV, Hartree, kcal/mol, kJ/mol, Joule (J), Rydberg (Ry)