{"id":9269,"library":"quests","title":"Quick Uncertainty and Entropy from STructural Similarity (QUESTS)","description":"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.","status":"active","version":"2026.2.22","language":"en","source_language":"en","source_url":"https://github.com/dskoda/quests","tags":["chemistry","materials science","machine learning","atomistic","uncertainty quantification","entropy","descriptors","ase"],"install":[{"cmd":"pip install quests","lang":"bash","label":"PyPI stable release"},{"cmd":"git clone https://github.com/dskoda/quests.git && cd quests && pip install .","lang":"bash","label":"From source"}],"dependencies":[{"reason":"Required for handling atomic structures (Atoms objects) used in descriptor generation.","package":"ase","optional":false},{"reason":"Fundamental package for numerical computation.","package":"numpy","optional":false},{"reason":"Used for efficient nearest neighbor search in descriptor calculation.","package":"pynndescent","optional":false},{"reason":"Machine learning tools, likely for clustering or other data processing.","package":"scikit-learn","optional":false},{"reason":"Used for accelerating numerical operations with JIT compilation.","package":"numba","optional":false},{"reason":"Data manipulation and analysis.","package":"pandas","optional":false},{"reason":"Likely used for hyperparameter tuning within the library.","package":"bayesian-optimization","optional":false},{"reason":"For creating command-line interfaces.","package":"click","optional":false},{"reason":"Enables GPU-accelerated entropy calculations.","package":"torch","optional":true},{"reason":"May be used alongside torch for specific functionalities, often for computer vision tasks, but listed as optional for GPU functionality.","package":"torchvision","optional":true}],"imports":[{"symbol":"get_atomic_descriptors","correct":"from quests.descriptors import get_atomic_descriptors"},{"note":"The `quests.gpu` module requires `torch` as an optional dependency. Attempting to import from it without `torch` installed will result in a `ModuleNotFoundError`.","wrong":"from quests.gpu.entropy import dataset_entropy # if torch is not installed","symbol":"dataset_entropy","correct":"from quests.entropy import dataset_entropy"}],"quickstart":{"code":"import numpy as np\nfrom ase.atoms import Atoms\nfrom quests.descriptors import get_atomic_descriptors\nfrom quests.entropy import dataset_entropy\n\n# 1. Create a list of ASE Atoms objects\n# In a real application, you would load these from .xyz, .cif, etc.\natoms1 = Atoms('H2O', positions=[(0, 0, 0), (0.75, 0.75, 0), (0.75, -0.75, 0)])\natoms2 = Atoms('H2O', positions=[(0, 0, 0), (0.8, 0.6, 0), (0.6, -0.8, 0)])\n# For illustrative purposes, let's create a list of two 'molecules'\natoms_list = [atoms1, atoms2]\n\n# 2. Generate atomic descriptors for the dataset\n# rc (cutoff radius) is a critical parameter. Adjust based on your system.\ndescriptors = get_atomic_descriptors(atoms_list, rc=5.0)\n\n# 3. Compute the dataset entropy\nentropy_value = dataset_entropy(descriptors)\n\nprint(f\"Generated {len(descriptors)} descriptors.\")\nprint(f\"Computed dataset entropy: {entropy_value:.4f}\")\n\n# Example for GPU (requires 'torch' to be installed via `pip install quests[gpu]`)","lang":"python","description":"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."},"warnings":[{"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]`.","message":"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`).","severity":"gotcha","affected_versions":"All versions"},{"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.","message":"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.","severity":"gotcha","affected_versions":"All versions"}],"env_vars":null,"last_verified":"2026-04-16T00:00:00.000Z","next_check":"2026-07-15T00:00:00.000Z","problems":[{"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.","cause":"Attempting to import from `quests.gpu` when the `torch` (PyTorch) library, an optional dependency for GPU functionality, is not installed.","error":"ModuleNotFoundError: No module named 'quests.gpu'"},{"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]`.","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.","error":"TypeError: 'Atoms' object is not iterable / AttributeError: 'list' object has no attribute 'get_positions'"},{"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.","cause":"The cutoff radius (`rc`) provided to `get_atomic_descriptors` was zero or negative, which is physically impossible and not allowed by the library.","error":"ValueError: Invalid parameter 'rc' provided. rc must be positive."}]}