Source-linked AI summary
DScribe: Library of Descriptors for Machine Learning in Materials Science
Lauri Himanen, Marc O. J. Jäger, Eiaki V. Morooka, Filippo Federici Canova, Yashasvi S. Ranawat, David Z. Gao, Patrick Rinke, Adam S. Foster
TL;DR
Atomistic machine learning requires suitable descriptors because raw atomic positions and nuclear charges lack key invariances. DScribe provides a model-independent library of common descriptors and demonstrates it on formation-energy and charge-prediction tasks, with reported performance patterns across descriptor choices and charge species.
Problem
Raw nuclear charges and atomic positions are unsuitable machine-learning inputs because they are not rotationally or translationally invariant.
Method
DScribe implements common atomistic descriptors with a Python interface and compiled routines, separating descriptor construction from learning models.
Results
DScribe is demonstrated for formation-energy prediction in crystals and charge prediction in molecules, with charge MAEs around 0.005-0.01 e using 10 000 samples per species.
Takeaways & Limitations
The package provides reusable descriptors compatible with general-purpose and unsupervised machine-learning tasks.
Takeaways & Limitations
Descriptor performance depends on descriptor variants, parameter choices, datasets, and the selected machine-learning model.
Abstract
from arXiv · showhide
DScribe is a software package for machine learning that provides popular feature transformations ("descriptors") for atomistic materials simulations. DScribe accelerates the application of machine learning for atomistic property prediction by providing user-friendly, off-the-shelf descriptor implementations. The package currently contains implementations for Coulomb matrix, Ewald sum matrix, sine matrix, Many-body Tensor Representation (MBTR), Atom-centered Symmetry Function (ACSF) and Smooth Overlap of Atomic Positions (SOAP). Usage of the package is illustrated for two different applications: formation energy prediction for solids and ionic charge prediction for atoms in organic molecules. The package is freely available under the open-source Apache License 2.0.
PROGRAM SUMMARY
DScribe addresses the lack of consistent descriptor implementations that hinders atomistic materials machine learning by providing a library of common feature transformations. It combines a Python interface with compiled routines, documentation, tutorials, and automated regression testing.
- Problem and solution: DScribe provides a library for creating common descriptors used in machine learning for materials science.The package includes Coulomb matrix, Ewald sum matrix, sine matrix, MBTR, ACSF, and SOAP implementations.
- Implemented descriptors: The package implements Coulomb matrix, Ewald sum matrix, sine matrix, MBTR, ACSF, and SOAP descriptors.
- Implementation: Python interfaces expose computationally intensive descriptor routines written in C or C++.
- Implementation: Online source code, tutorials, documentation, and continuous integration support reproducible package use and regression testing.
1. Introduction
Atomistic machine learning needs descriptors because raw nuclear charges and positions are unsuitable inputs that would require learning geometric invariances from data. DScribe organizes descriptor construction separately from learning models so researchers can test combinations across structure-property prediction tasks.
- Motivation: Atomistic machine learning uses surrogate models to learn relationships between atomic structures and properties across applications including solids, molecules, catalysts, and complex structures.
- Workflow: A typical workflow transforms an atomic structure into a descriptor, feeds it to a trained model, and predicts a property.
- Motivation: Raw nuclear charges and atomic positions are not rotationally or translationally invariant, so they must be transformed into machine-learning descriptors.
- Descriptor requirements: Good descriptors should be invariant, unique, continuous, compact, and computationally cheap while retaining sufficient predictive information.
- DScribe design: DScribe decouples vectorial descriptor creation from learning models, enabling parallel testing of combinations and applications such as clustering and materials maps.
- Descriptor scope: Global descriptors encode whole structures for properties such as molecular energies, formation energies, and band gaps.
2. Descriptors
DScribe implements global and local atomistic descriptors that transform structures into machine-learning features, including matrix, distribution-based, symmetry-function, and orbital-based representations. The section describes their construction, periodic-system handling, output organization, and limitations such as matrix non-uniqueness.
- DScribe introduces Coulomb, Ewald sum, sine, MBTR, ACSF, and SOAP descriptors for transforming atomic structures into machine-learning features.The implementations are presented with adaptations made for computational or other practical reasons.
- Matrix descriptors: The Coulomb matrix encodes atomic species and pairwise distances, while the Ewald sum matrix extends this construction to periodic systems using lattice-vector sums and neutralizing-background corrections.The Ewald summation converges through the Ewald technique and a neutralizing background charge; its implementation also corrects an off-diagonal contribution so total elements are independent of the screening parameter.
- Matrix descriptors: The sine matrix captures periodicity and infinite overlap energy at reduced computational cost, although its functional form has no physical interpretation.Unlike the Coulomb matrix, the Ewald sum and sine matrices encode identical periodic environments for equivalent carbon atoms in diamond.
- Matrix descriptors: Matrix representations are not unique because periodic crystals admit different cell sizes and row or column orderings.The section notes that subsequent methods are needed to address this non-uniqueness.
- Distribution-based descriptors: MBTR represents structures as element-grouped distributions of one-, two-, and three-body motifs based on atomic numbers, inverse distances, and angular cosines.For periodic systems, neighboring-cell copies are included, with at least one atom in each motif belonging to the original cell; weighting controls term importance and ensures convergence.
- Distribution-based descriptors: MBTR outputs can be arranged as k-dimensional grids or concatenated into a flattened vector, while chemical-element correlations can be introduced during postprocessing without losing generality.Symmetry reduction avoids duplicate element-order combinations and reduces computation and feature count.
- Orbital-based descriptors: SOAP uses spherical harmonics with radial basis functions, and the implementation provides Gaussian-type orbitals by default while comparing them with polynomial alternatives.Gaussian basis functions depend on angular degree l, whereas polynomial basis functions are independent of l; their cutoff behavior also differs.
3. Software structure
DScribe provides a Python-facing, extensible interface for configuring descriptors, querying feature dimensions, and generating outputs from one or more atomic structures. The package also supports sparse outputs, parallel creation, testing, documentation, and community contributions.
- Interface: Python serves as the default interface, while computationally intensive routines can be implemented in high-performance static languages.The interface uses Python libraries for creating and manipulating atomic structures without restricting implementations to Python.
- Descriptor workflow: Each descriptor is represented by a configurable class whose objects expose get number of features and create methods.The feature count can be queried before supplying a structure, while create returns the descriptor output for machine-learning applications.
- Output handling: Descriptor outputs can be dense or sparse, enabling large sparsely populated feature spaces associated with datasets containing many chemical elements.Sparse matrices can be used with machine-learning algorithms that provide sparse-data linear algebra routines.
- Parallelization: Descriptor creation accepts one or multiple atomic structures and can distribute independent samples across multiple processes using the n jobs parameter.The workflow uses ase.Atoms objects to represent atomic structures.
- Extensibility and validation: A Python base class and abstract interfaces make it possible to add descriptors, while standard tests check invariance properties and other behavior.The source code, tutorials, documentation, and installation package are provided online.
4. Results and discussion
DScribe’s descriptors are evaluated with kernel ridge regression for formation-energy prediction in inorganic crystals and ionic-charge prediction in organic molecules. The results show descriptor-specific performance patterns, including strong combined MBTR performance and accurate local-charge prediction.
- Evaluation tasks: DScribe’s supervised-learning examples predict inorganic-crystal formation energies and organic-molecule ionic charges using descriptor vectors with KRR.The descriptor outputs are not tied to KRR and can also support other regressors.
- Formation-energy prediction: Formation-energy models use OQMD crystals, filtered to structures with at most 10 atoms per cell and six elements, and train at sizes from 1024 to 16384.Predictions are repeated three times on different training sets to estimate variance.
- Interpretation: Descriptor comparisons require care because descriptor variants, local-SOAP aggregation, MBTR geometry functions, cutoff choices, and learning models affect performance.The reported learning-rate patterns therefore apply to the tested configurations and model choices.
- Formation-energy prediction: 0.36 eV MAE for the Ewald sum matrix and 0.24 eV for the sine matrix are obtained with 3276 training samples, with the sine matrix performing better.The authors attribute differences from an earlier comparison to dataset contents while recovering the same ordering trend.
- Formation-energy prediction: MBTR k = 2 distance terms outperform the k = 1 composition and k = 3 angle terms individually, while combining all three terms gives the best MBTR performance.The tested MBTR configurations normalize each term to unit length, and the combined configuration includes k = 1, 2, 3.
- Ionic-charge prediction: For ionic charges, local SOAP and ACSF descriptors learn CCSD-level charges with an average MAE of around 0.005-0.01 e using 10 000 samples per species.Multivalent C, N, and O charges vary more and are harder to predict than low-valence H and F charges.
- Ionic-charge prediction: SOAP’s gaussian type orbital basis is over four times faster to calculate than its polynomial basis under identical settings, despite little difference in predictive performance.The speed difference largely originates from numerical radial integration required for the polynomial basis.
5. Conclusions
DScribe addresses fragmented descriptor implementations by collecting several atomistic descriptors in an accessible, extensible library. The package demonstrates compatibility with supervised and unsupervised learning and supports future descriptor expansion.
- Motivation: Descriptor implementations are often scattered across libraries or unavailable, making alternative descriptors difficult to test and compare.This fragmentation motivates a coherent software package for atomistic machine learning.
- Contribution: DScribe collects several descriptors behind an easy-to-use Python interface with C/C++ extensions, regression tests, source code, tutorials, and documentation.The package is designed for practical use and implementation validation.
- Applications: The demonstrated applications cover formation-energy prediction for crystals and charge prediction for molecules using general-purpose machine-learning algorithms.The descriptors can also be used for unsupervised learning tasks.
- Future extensions: Future development plans include adding descriptors such as Voronoi tessellation-based representations and welcoming external contributors.The package is presented as extensible rather than closed to the current descriptor set.