Quick Uncertainty and Entropy from STructural Similarity (QUESTS)

2026.2.22 · active · verified Thu Apr 16

QUESTS (Quick Uncertainty and Entropy via STructural Similarity) is a Python library providing model-free uncertainty and entropy estimation methods for interatomic potentials. It employs a structural descriptor and information-theoretical strategy that is fast to compute, relying only on distances between atoms within an environment. The library is actively maintained, with its latest version being 2026.2.22, and supports Python 3.8 and newer. It's primarily used for analyzing datasets in atomistic machine learning, offering metrics like dataset entropy, diversity, and information gap.

Common errors

```
ModuleNotFoundError: No module named 'quests.gpu'
```
cause Attempting to import from `quests.gpu` when the `torch` (PyTorch) library, an optional dependency for GPU functionality, is not installed.

fix Install PyTorch. For CPU-only: `pip install torch`. For GPU: `pip install torch torchvision torchaudio --index-url https://download.pytorch.org/whl/cu121` (adjust CUDA version as needed), or simply `pip install quests[gpu]` if quests bundles torch installation.
```
TypeError: 'Atoms' object is not iterable / AttributeError: 'list' object has no attribute 'get_positions'
```
cause The `get_atomic_descriptors` function expects a list of `ase.Atoms` objects, not a single `Atoms` object or a list of other types. Passing an incorrect data structure can lead to these errors.

fix Ensure the input to `get_atomic_descriptors` is always a Python list where each element is an instance of `ase.Atoms`. For example: `atoms_list = [my_atom_object1, my_atom_object2]`.
```
ValueError: Invalid parameter 'rc' provided. rc must be positive.
```
cause The cutoff radius (`rc`) provided to `get_atomic_descriptors` was zero or negative, which is physically impossible and not allowed by the library.

fix Provide a positive floating-point value for `rc` (cutoff radius). For example, `rc=5.0` or `rc=6.5`. Choose a value relevant to the interatomic distances in your system.

Warnings

gotcha Using GPU-accelerated functions without 'torch' installed. The `quests.gpu` module provides GPU-accelerated versions of some functions (e.g., `quests.gpu.entropy.dataset_entropy`). These require PyTorch to be installed as an optional dependency (e.g., `pip install quests[gpu]` or `pip install torch`).
Fix: Ensure `torch` is installed if you intend to use `quests.gpu` modules. Otherwise, use functions from `quests.entropy` for CPU-based computation. `pip install torch` or `pip install quests[gpu]`.
gotcha Incorrect selection of parameters for `get_atomic_descriptors`, particularly the cutoff radius (`rc`). The `rc` parameter significantly influences the descriptor's representation and the resulting entropy/uncertainty. An inappropriate `rc` can lead to physically meaningless results or poor performance.
Fix: Carefully consider the physical context of your materials when choosing `rc`. It should typically be larger than the longest bond lengths in your system but not excessively large to avoid unnecessary computation. Refer to the documentation or literature on structural descriptors for guidance on appropriate values for your specific application.

Install

pip install quests PyPI stable release
git clone https://github.com/dskoda/quests.git && cd quests && pip install . From source

Imports

get_atomic_descriptors

from quests.descriptors import get_atomic_descriptors

dataset_entropy
wrong:
```
from quests.gpu.entropy import dataset_entropy # if torch is not installed
```
correct:
```
from quests.entropy import dataset_entropy
```
The `quests.gpu` module requires `torch` as an optional dependency. Attempting to import from it without `torch` installed will result in a `ModuleNotFoundError`.

Quickstart

This quickstart demonstrates how to generate atomic descriptors from a list of `ase.Atoms` objects and then calculate the dataset's entropy. The `ase` library is a core dependency for handling atomic structures. The `rc` parameter (cutoff radius) in `get_atomic_descriptors` is crucial and should be chosen appropriately for your specific materials system.

import numpy as np
from ase.atoms import Atoms
from quests.descriptors import get_atomic_descriptors
from quests.entropy import dataset_entropy

# 1. Create a list of ASE Atoms objects
# In a real application, you would load these from .xyz, .cif, etc.
atoms1 = Atoms('H2O', positions=[(0, 0, 0), (0.75, 0.75, 0), (0.75, -0.75, 0)])
atoms2 = Atoms('H2O', positions=[(0, 0, 0), (0.8, 0.6, 0), (0.6, -0.8, 0)])
# For illustrative purposes, let's create a list of two 'molecules'
atoms_list = [atoms1, atoms2]

# 2. Generate atomic descriptors for the dataset
# rc (cutoff radius) is a critical parameter. Adjust based on your system.
descriptors = get_atomic_descriptors(atoms_list, rc=5.0)

# 3. Compute the dataset entropy
entropy_value = dataset_entropy(descriptors)

print(f"Generated {len(descriptors)} descriptors.")
print(f"Computed dataset entropy: {entropy_value:.4f}")

# Example for GPU (requires 'torch' to be installed via `pip install quests[gpu]`)

view raw JSON →