Skip to content

DScribe is a python package for creating machine learning descriptors for atomistic systems.


Notifications You must be signed in to change notification settings


Repository files navigation

Build status Coverage Status Ruff

DScribe is a Python package for transforming atomic structures into fixed-size numerical fingerprints. These fingerprints are often called "descriptors" and they can be used in various tasks, including machine learning, visualization, similarity analysis, etc.


For more details and tutorials, visit our documentation at:

You can find even more details in the following articles:

Quick Example

import numpy as np
from import molecule
from dscribe.descriptors import SOAP
from dscribe.descriptors import CoulombMatrix

# Define atomic structures
samples = [molecule("H2O"), molecule("NO2"), molecule("CO2")]

# Setup descriptors
cm_desc = CoulombMatrix(n_atoms_max=3, permutation="sorted_l2")
soap_desc = SOAP(species=["C", "H", "O", "N"], r_cut=5, n_max=8, l_max=6, crossover=True)

# Create descriptors as numpy arrays or sparse arrays
water = samples[0]
coulomb_matrix = cm_desc.create(water)
soap = soap_desc.create(water, centers=[0])

# Easy to use also on multiple systems, can be parallelized across processes
coulomb_matrices = cm_desc.create(samples)
coulomb_matrices = cm_desc.create(samples, n_jobs=3)
oxygen_indices = [np.where(x.get_atomic_numbers() == 8)[0] for x in samples]
oxygen_soap = soap_desc.create(samples, oxygen_indices, n_jobs=3)

# Descriptors also allow calculating derivatives with respect to atomic
# positions
der, des = soap_desc.derivatives(samples, return_descriptor=True)

Currently implemented descriptors

Descriptor Spectrum Derivatives
Coulomb matrix ✔️ ✔️
Sine matrix ✔️ ✔️
Ewald matrix ✔️ ✔️
Atom-centered Symmetry Functions (ACSF) ✔️ ✔️
Smooth Overlap of Atomic Positions (SOAP) ✔️ ✔️
Many-body Tensor Representation (MBTR) ✔️ ✔️
Local Many-body Tensor Representation (LMBTR) ✔️ ✔️
Valle-Oganov descriptor ✔️ ✔️


In-depth installation instructions can be found in the documentation, but in short:


pip install dscribe


conda install -c conda-forge dscribe

From source

git clone
cd dscribe
git submodule update --init
pip install .