Miscellaneous

metatomic.torch.pick_device(model_devices: List[str], desired_device: str | None) → str

Select the best device according to the list of model_devices from a model, the user-provided desired_device and what’s available on the current machine.

If desired_device is provided, it is checked against the model_devices and the machine availability. If it contains a device index (e.g. "cuda:1"), the base device type ("cuda") is used for these checks, and the full string is returned if successful.

If desired_device is None or an empty string, the first available device from model_devices will be picked and returned.

Parameters:

• model_devices (List[str]) – list of devices supported by a model in order of preference

• desired_device (str | None) – user-provided desired device.

Return type:

str

metatomic.torch.pick_output(requested_output: str, outputs: Dict[str, ModelOutput], desired_variant: str | None = None) → str

Pick the output for the given requested_output from the availabilities of the model’s outputs, according to the optional desired_variant.

Parameters:

• requested_output (str) – name of the output to pick a variant for

• outputs (Dict[str, ModelOutput]) – all available outputs from the model

• desired_variant (str | None) – if provided, try to pick this specific variant

Return type:

str

metatomic.torch.unit_conversion_factor(from_unit: str, to_unit: str) → float

Get the multiplicative conversion factor from from_unit to to_unit.

Both from_unit and to_unit are parsed as unit expressions supporting compound forms like "kJ/mol/A^2" or "(eV*u)^(1/2)". The parser validates that both expressions have matching physical dimensions.

This function is TorchScript-compatible. The deprecated 3-argument form unit_conversion_factor(quantity, from_unit, to_unit) is available via torch.ops.metatomic.unit_conversion_factor.

The set of recognized base units is available here.

Migration from 3-argument form

The 3-argument form unit_conversion_factor(quantity, from_unit, to_unit) is deprecated. The quantity parameter is no longer needed because dimensional compatibility is checked automatically by the parser.

Before (deprecated):

factor = unit_conversion_factor("energy", "eV", "meV")
factor = unit_conversion_factor("force", "eV/A", "Hartree/Bohr")

After (recommended):

factor = unit_conversion_factor("eV", "meV")
factor = unit_conversion_factor("eV/A", "Hartree/Bohr")

The new 2-argument form also supports compound expressions that were not possible with the old API:

# Momentum conversion (fractional powers)
factor = unit_conversion_factor("(eV*u)^(1/2)", "u*A/fs")
# Complex compound expression
factor = unit_conversion_factor("kJ/mol/A^2", "Hartree/Bohr^3")

Parameters:

• from_unit (str) – current unit of the data (expression string)

• to_unit (str) – target unit of the data (expression string)

Return type:

float

The set of recognized base units is documented in the C++ API reference.

The unit_conversion_factor() function accepts any valid unit expression built from base units combined with operators. There is no need to specify a physical quantity — the parser automatically verifies dimensional compatibility between the source and target units.

Supported base units

Unit expressions are built from the following base units. Matching is case-insensitive, and whitespace is ignored.

Length:

angstrom (A), Bohr, meter (m), centimeter (cm), millimeter (mm), micrometer (um, µm), nanometer (nm)

Energy:

eV, meV, Hartree, kcal, kJ, Joule (J), Rydberg (Ry)

Time:

second (s), millisecond (ms), microsecond (us, µs), nanosecond (ns), picosecond (ps), femtosecond (fs)

Mass:

u (Dalton), kilogram (kg), gram (g), electron_mass (m_e)

Charge:

e, Coulomb (C)

Dimensionless:

mol

Derived constants:

hbar

Expression syntax

Base units can be combined using the following operators:

• Multiplication: * or whitespace (kJ mol, kJ*mol)

• Division: / (kJ/mol)

• Exponentiation: ^ (A^3, m^2)

• Parentheses: () for grouping ((eV*u)^(1/2))

Examples of valid compound expressions:

• kJ/mol — energy per mole

• eV/Angstrom^3 or eV/A^3 — pressure

• (eV*u)^(1/2) — momentum (fractional powers)

• Hartree/Bohr — force in atomic units

• nm/fs — velocity

The parser automatically checks that both unit expressions have matching physical dimensions before computing the conversion factor.