Library / SDK
SINGROUP/dscribe avatar
SINGROUP/dscribe

dscribe turns atomic structures into fixed-size fingerprints

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

475 stars99 forksC++Apache-2.0

At a glance

What is it?
A Python package from the SINGROUP materials science group that converts an atomic structure into a numerical descriptor, with eight implementations and analytic derivatives for all of them. Installing it from source compiles a C++ extension against a vendored Eigen. The repository is C++, the package is Python.
Who is it for?
Adopt dscribe if you are feeding atomic structures into a machine learning model and want a maintained descriptor set with derivatives rather than writing the kernels yourself. Do not adopt it expecting a pure Python install to be quick from source, since the build compiles a C++ extension.
Can I use it commercially?
Yes. Apache-2.0 is a permissive licence: you can use, modify and sell software built on it, as long as you keep its copyright and licence notices.
Is it still maintained?
Activity is slowing. The repository last received commits 7 months ago.
What is it written in?
Mainly C++, according to GitHub's language statistics.

Answers come from the project's GitHub data, last synced on November 15, 2026, and from our analysis. They are not legal advice.

From daily snapshots

Star history

  • SINGROUP/dscribe475 ★ · +0
Star history
Repository2026-09-112026-11-15
SINGROUP/dscribe475475

0 Stars in the last 65 days, measured from the daily GitHub snapshot. Compare with other projects

Editorial analysis

Fixed-size is the whole point

The definition in the project description is short: DScribe transforms atomic structures into fixed-size numerical fingerprints, and these are used for machine learning, visualisation and similarity analysis.

Fixed size is the constraint that matters. An atomic structure has a variable number of atoms, so anything derived directly from it has a variable length, and a model cannot take that as input. A descriptor collapses the structure into a vector whose length depends on the descriptor's parameters and not on the structure.

The quick example makes the mechanics visible. Three molecules are built with ASE, water, nitrogen dioxide and carbon dioxide. Two descriptors are set up: a Coulomb matrix with a maximum atom count of three and a sorted L2 permutation, and a SOAP descriptor with an explicit species list, a cutoff of five, and radial and angular maxima of eight and six, with crossover enabled. Each is then asked for a value.

The SOAP call takes a `centers` argument, so it can produce one row per chosen atom rather than a single vector for the whole structure. That distinction is the difference between a structure-level fingerprint and an atom-level one, and most downstream models want the latter.

Output is either a dense NumPy array or a sparse array, which matters when the descriptor dimension is large.

All eight descriptors carry derivatives

The descriptor table has two columns, spectrum and derivatives, and both are filled for every entry.

The eight are Coulomb matrix, Sine matrix, Ewald matrix, Atom-centered Symmetry Functions, Smooth Overlap of Atomic Positions, Many-body Tensor Representation, Local Many-body Tensor Representation, and the Valle-Oganov descriptor.

Complete derivative support across the whole set is the unusual part. Most descriptor libraries give you fingerprints, and a fingerprint alone cannot be differentiated, which means it cannot give you a force or an energy. A library that ships analytic derivatives for every descriptor lets the same code compute a representation for a prediction and a gradient for a relaxation or a force field.

That is why the derivation column exists at all rather than being an afterthought for two descriptors. It is also the strongest argument for using a maintained library here: implementing a SOAP derivative correctly is not a weekend project, and reimplementing it badly produces a model that trains and a force that is wrong.

The description in the packaging metadata frames the same scope differently, calling this a package for feature transformations in machine learning applications to materials science, and the keyword list gives the four-word version: descriptor, machine learning, atomistic structure, materials science.

A C++ extension built with pybind11 and a vendored Eigen

The repository's primary language is C++, and the reason is the packaging file rather than the application code.

The extension is declared as a pybind11 extension module named `dscribe.ext`, compiled from every C++ source under `dscribe/ext/`. Include paths point at two places: the vendored Eigen headers under `dependencies/eigen`, and the package's own headers. The compiler standard is C++11, and the extra compile arguments are optimisation level three plus an include path into the Eigen directory.

So the inner loops run in C++ with Eigen's vectorised matrix types, and Python calls them through pybind11. That is a normal arrangement for a numerical library, and it is why the hot path is fast.

Two build details are worth knowing if you build from source. The compile step runs under a parallel wrapper keyed on an environment variable for the number of build jobs, which means you can control how many compiler processes start. And `zip_safe` is disabled, so the resulting distribution is not marked safe for installation as a zipped egg.

There are two build files. `pyproject.toml` declares the project metadata and points at setuptools with wheel and pybind11 as build requirements, while `setup.py` builds the extension. Python 3.9 or newer is required, and the classifiers cover 3.9 through 3.13 plus the C and C++ languages the extension is written in.

Three install routes, and the source one needs a submodule

There are three ways in, and one of them has a step that is easy to skip.

From pip it is a single command:

bash
pip install dscribe

From conda-forge:

bash
conda install -c conda-forge dscribe

And from source, which is four steps:

bash
git clone https://github.com/SINGROUP/dscribe.git
cd dscribe
git submodule update --init
pip install .

That third line is the one to notice. A `.gitmodules` entry and a `dependencies/` directory at the repository root mean the Eigen headers are carried as a submodule, so a clone without the submodule step leaves the include path pointing at nothing and the extension build fails.

The package version in the packaging metadata is 2.1.2, and there are no GitHub releases, so the version number is the only marker of what you have. It is classified as production and stable, targeted at science and research as well as developers, and licensed under Apache-2.0.

Its runtime dependencies are short and worth naming: NumPy, SciPy, ASE at 3.19 or newer, scikit-learn, joblib and the sparse package. ASE is the atomic simulation toolkit the structures come from, which means the input format is an ASE object rather than a coordinate array.

Sparse output is a first-class path

One dependency and one example file together tell you what kind of problem this package expects.

The `sparse` package is a runtime requirement rather than an extra, and there is an example named for sparse output. That combination says the descriptors are expected to be large enough that a dense array is often wasteful, and that the library commits to supporting the sparse form rather than leaving it to you.

The scaling is arithmetic. A SOAP descriptor with a radial maximum of eight and an angular maximum of six has a substantial number of components per atom once the species count and the coefficients are involved, and a cell containing a few hundred atoms multiplies that. Dense arrays of that shape are where a memory budget disappears.

The example directory also includes a multiple-structures file in the extended XYZ format and two single-structure files, a salt lattice and a water molecule, which is the input convention: structures come from files or from ASE builders.

The quick example's closing comment is that it is easy to use on multiple systems as well. That is the intended shape of the work: build a list of structures, build a descriptor once, create values for each.

The examples are the list of use cases

Reading the example directory tells you what the library is expected to be used for, because the directories are named after tasks rather than after descriptors.

`clustering/` is one. `kernels/` is another, which is the machine learning side: similarity measures between structures derived from their descriptors. `forces_and_energies/` is the derivative side, and it exists as its own directory precisely because that is a distinct task from producing a fingerprint. `visualization/` covers the third use named in the description.

Alongside those there is one file per descriptor, so the SOAP, ACSF, MBTR, LMBTR, Coulomb matrix, Sine matrix, Ewald sum matrix and Valle-Oganov each have a runnable starting point.

Two other files are worth noticing. `basics.py` is the general introduction, and `readme.py` is the quick example as a script, which is a small courtesy that makes it easy to check that your install works before writing anything.

Two publications are cited as the deeper reading: the original DScribe paper in the journal of Chemical Physics and its Data Brief, and a follow-up on new descriptors and derivatives. For a package whose behaviour you will be validating against reference implementations, those two documents are where the definitions are argued rather than summarised.

Editorial conclusion

Adopt dscribe if you are feeding atomic structures into a machine learning model and want a maintained descriptor set with derivatives rather than writing the kernels yourself. Do not adopt it expecting a pure Python install to be quick from source, since the build compiles a C++ extension. Verify two things first. Check your atomic simulation package, because the package depends on ASE objects rather than raw coordinates, so a pipeline that keeps structures elsewhere needs a conversion step. Then read the derivative path for your chosen descriptor, since forces and energies only come out of the analytic derivatives and the example directory treats that as its own task.

Frequently asked questions

What does dscribe do?

It transforms atomic structures into fixed-size numerical fingerprints called descriptors, for use in machine learning, visualisation and similarity analysis. Eight descriptors are implemented, and every one of them supports derivatives as well as spectra.

How do I install dscribe from source?

Clone the repository, change into the directory, run git submodule update --init, then pip install . The submodule step is required because the Eigen headers are carried as a submodule under dependencies/eigen and the extension build needs them.

Which descriptors does dscribe provide?

Coulomb matrix, Sine matrix, Ewald matrix, Atom-centered Symmetry Functions, SOAP, Many-body Tensor Representation, Local Many-body Tensor Representation, and the Valle-Oganov descriptor. Both spectrum and derivatives are supported for all eight.

Why does dscribe need a compiler?

The package ships a pybind11 extension module named dscribe.ext, compiled from C++ sources under dscribe/ext/ against the vendored Eigen headers, at C++11 with optimisation enabled. The build also declares pybind11 as a build requirement.

What does dscribe need as input?

ASE atomic structures, since the package depends on ASE 3.19 or newer. Alongside NumPy, SciPy, scikit-learn, joblib and the sparse package, which is why the example directory ships structures in the extended XYZ format.

Official sources

  1. Issues
  2. License: Apache-2.0
  3. Project website
  4. README
  5. SINGROUP/dscribe on GitHub
Add this badge to your README

If you maintain this project, the badge below links readers to this analysis and shows its maintenance status from the daily GitHub snapshot. Paste the markdown into your README; add ?metric=license or ?metric=stars to the image URL for a different field.

Add this badge to your README

markdown
[![Hysen Labs](https://hysenlabs.com/badge/singroup-dscribe.svg)](https://hysenlabs.com/projects/singroup-dscribe)

Star history chart for your README

markdown
[![Star history](https://hysenlabs.com/chart/singroup-dscribe.svg)](https://hysenlabs.com/projects/singroup-dscribe)

Was this useful?