{"id":8965,"library":"dscribe","title":"DScribe: Machine Learning Descriptors for Atomistic Systems","description":"DScribe is a Python package (current version 2.1.2) designed for generating fixed-size numerical fingerprints, known as descriptors, from atomic structures. These descriptors are crucial for various applications in materials science, including machine learning, visualization, and similarity analysis. The library maintains an active development status with regular updates, including new descriptors and derivative functionalities. [1, 2, 5]","status":"active","version":"2.1.2","language":"en","source_language":"en","source_url":"https://github.com/SINGROUP/dscribe","tags":["materials science","machine learning","descriptors","atomistic simulations","cheminformatics","physics","ASE"],"install":[{"cmd":"pip install dscribe","lang":"bash","label":"PyPI (recommended)"},{"cmd":"conda install -c conda-forge dscribe","lang":"bash","label":"Conda (conda-forge)"},{"cmd":"git clone https://github.com/SINGROUP/dscribe.git\ncd dscribe\ngit submodule update --init\npip install .","lang":"bash","label":"From source (development version)"}],"dependencies":[],"imports":[{"symbol":"SOAP","correct":"from dscribe.descriptors import SOAP"},{"symbol":"CoulombMatrix","correct":"from dscribe.descriptors import CoulombMatrix"},{"symbol":"ACSF","correct":"from dscribe.descriptors import ACSF"},{"symbol":"MBTR","correct":"from dscribe.descriptors import MBTR"}],"quickstart":{"code":"import numpy as np\nfrom ase.build import molecule\nfrom dscribe.descriptors import SOAP, CoulombMatrix\n\n# Define atomic structures\nsamples = [molecule(\"H2O\"), molecule(\"NO2\"), molecule(\"CO2\")]\n\n# Setup CoulombMatrix descriptor\ncm_desc = CoulombMatrix(n_atoms_max=3, permutation=\"sorted_l2\")\n\n# Setup SOAP descriptor (using modern parameter names and compression)\nsoap_desc = SOAP(species=[\"C\", \"H\", \"O\", \"N\"], r_cut=5, n_max=8, l_max=6, compression=\"crossover\")\n\n# Create descriptors for a single system\nwater = samples[0]\ncoulomb_matrix_h2o = cm_desc.create(water)\nsoap_h2o = soap_desc.create(water, centers=[0])\n\nprint(\"Coulomb Matrix for H2O:\\n\", coulomb_matrix_h2o)\nprint(\"SOAP for Oxygen in H2O:\\n\", soap_h2o)\n\n# Create descriptors for multiple systems (can be parallelized)\ncoulomb_matrices_all = cm_desc.create(samples, n_jobs=2)\noxygen_indices = [np.where(x.get_atomic_numbers() == 8)[0] for x in samples]\noxygen_soap_all = soap_desc.create(samples, oxygen_indices, n_jobs=2)\n\nprint(\"Coulomb Matrices for all samples shape:\", coulomb_matrices_all.shape)\nprint(\"SOAP for Oxygen in all samples shape:\", oxygen_soap_all.shape)\n\n# Descriptors also allow calculating derivatives\nder, des = soap_desc.derivatives(samples[0], return_descriptor=True)\nprint(\"SOAP derivatives shape:\", der.shape)\nprint(\"SOAP descriptor from derivatives shape:\", des.shape)","lang":"python","description":"This quickstart demonstrates how to initialize and use CoulombMatrix and SOAP descriptors for single and multiple atomic structures (represented by ASE Atoms objects). It also shows how to compute derivatives for a descriptor. Note the use of modern parameter names like `r_cut`, `n_max`, `l_max`, and the `compression` parameter for SOAP. [2, 3, 6]"},"warnings":[{"fix":"Replace `positions` with `centers` when calling `.create()` or `.derivatives()` methods for local descriptors.","message":"In DScribe 2.0.0, the `positions` argument for local descriptors was renamed to `centers`. Code using `positions` will break. [1]","severity":"breaking","affected_versions":">=2.0.0"},{"fix":"Adjust code expecting specific output shapes. Outputs are consistently flattened by default.","message":"In DScribe 2.0.0, global descriptors (CoulombMatrix, EwaldSumMatrix, SineMatrix, MBTR, LMBTR) no longer support 'unflattened' outputs. All global descriptors now produce 1D flattened output and local descriptors produce 2D flattened output. [1]","severity":"breaking","affected_versions":">=2.0.0"},{"fix":"Update descriptor initialization to use the new parameter names (e.g., `r_cut` instead of `rcut`).","message":"In DScribe 2.0.0, several SOAP descriptor parameters were renamed: `rcut` -> `r_cut`, `nmax` -> `n_max`, `lmax` -> `l_max`. Similarly for EwaldSumMatrix: `rcut` -> `r_cut`, `gcut` -> `g_max`. [1]","severity":"breaking","affected_versions":">=2.0.0"},{"fix":"Replace `crossover=True` with `compression=\"crossover\"` in SOAP descriptor initialization. If `crossover=False` was used, either omit `compression` (defaults to 'off') or explicitly set `compression='off'`.","message":"In DScribe 2.1.0, the `crossover` parameter in SOAP has been removed. Its functionality is now controlled by the `compression` parameter. [1, 3]","severity":"breaking","affected_versions":">=2.1.0"},{"fix":"Convert your atomic structures to `ase.Atoms` objects before passing them to DScribe descriptors.","message":"DScribe relies on the Atomic Simulation Environment (ASE) for handling atomic structures. Ensure your atomic structures are correctly represented as `ase.Atoms` objects. [5]","severity":"gotcha","affected_versions":"All"}],"env_vars":null,"last_verified":"2026-04-16T00:00:00.000Z","next_check":"2026-07-15T00:00:00.000Z","problems":[{"fix":"Install `pybind11` explicitly before installing `dscribe`: `pip install pybind11`","cause":"DScribe depends on C++ extensions compiled during installation, which require `pybind11` headers. Although specified, `pip` may not correctly find or install `pybind11` beforehand. [4]","error":"fatal error: pybind11/pybind11.h: No such file or directory"},{"fix":"Install the Python development package for your specific Python version. For example, on Ubuntu: `sudo apt install python3.x-dev` (replace `x` with your minor Python version).","cause":"The C/C++ extensions for DScribe require Python development headers (e.g., `Python.h`) which are missing on the system. [4]","error":"fatal error: Python.h: No such file or directory"},{"fix":"Install Xcode Command Line Tools: `xcode-select --install`","cause":"Compiling C++ extensions on macOS requires Xcode Command Line Tools, which may not be installed. [4]","error":"Installation errors on MacOS related to C++ compilation"},{"fix":"Update your code to use the `centers` argument instead of `positions` (e.g., `descriptor.create(system, centers=...)`).","cause":"This error occurs in DScribe versions 2.0.0 and newer when using the outdated `positions` argument with local descriptors. [1]","error":"TypeError: create() got an unexpected keyword argument 'positions'"}]}