MaterialsCoord provides an infrastructure for comparing the performance of different crystal structure bonding algorithms against a benchmark set of materials.
Atomic coordination numbers (CNs) are an important descriptor for the local environment of condensed materials. A range of algorithms for calculating coordination numbers have been proposed, the performance of which are often unknown outside the chemical domain they were designed for. MaterialsCoord allows for the benchmarking of different CN algorithms against a set of crystal structures for which the bonding environments have been experimentally determined.
The basic API of MaterialsCoord can be summarized as:
materialscoord.Benchmarkprovides the primary interface. It takes a set of structures that have been decorated with the"coordination"site property (see the Preparing crystal structures for benchmarking section).- The
Benchmark.from_structure_group()method provides a convenience function to initialize the benchmark from a list of pre-prepared structure groups. More information on the available groups is provided in the Benchmarking structure sets section. Benchmark.benchmark()accepts a list of coordination algorithms and runs them on the set of test structures.Benchmark.score()accepts a list of coordination algorithms and compares their performance against a human interpretation of crystal structure bonding.
A full introduction to using MaterialsCoord is provided in the introduction notebook.
MaterialsCoord has been designed to interface with the NearNeighbors methods
implemented in pymatgen.analysis.local_env.
A number of methods exist, including:
The benchmark includes around 95 pre-prepared test structures for which the correct coordination has been determined by a human interpreter (taken from the scientific literature). The structures have been grouped into a number of material classes, including:
"elemental": Simple elemental materials, including diamond, graphite, Ga, and α-As."common_binaries": Simple and more complex binary structures, including rocksalt NaCl, rutile TiO2, and γ-brass."ABX3": ABX3 structured ternary materials, including perovskite SrTiO3 and argonite CaCO3."ABX4": ABX4 structured ternary materials, including zircon, (ZrSiO4) and wolframite (FeWO4)."A2BX4": A2BX4 structured ternary materials, including olivine Fe2SiO4.
The full set of materials classes and crystal structures can be found in the structures directory.
MaterialsCoord supports benchmarking on custom structures. See the Preparing crystal structures for benchmarking section for more details.
The MaterialsCoord benchmark should be run using the python API. For example,
we can compare the Effective Coordination Number (ECoN) and O'Keeffe's Voronoi
CN method on the "elemental" and "common_binaries" structure groups as follows:
from pymatgen.analysis.local_env import EconNN, VoronoiNN
from materialscoord.core import Benchmark
nn_methods = [EconNN(), VoronoiNN()]
bm = Benchmark.from_structure_group(["elemental", "common_binaries"])
bm.score(nn_methods)The score function will return the results as a Pandas
DataFrame object. Further details can be found in the
introduction notebook.
MaterialsCoord uses pymatgen Structure objects to internally store the crystal
structure data. The structures provided in the default structure groups contain
an additional site property called "coordination". This property contains
information on the human interpreted coordination environment for each site.
For example, if a site is bonded to two oxygen and three chlorine atoms, the
coordination property should be a dictionary of {"O": 2, "Cl": 3}. If
multiple coordination numbers are deemed correct these should be provided as a
list. For example, if the coordination to gallium could be 4 or 12 coordinate,
the coordination property should a dictionary of {"Ga": [4, 12]}.
A full guide to preparing crystal structures for use in MaterialsCoord is in provided in the benchmarking using custom structures notebook.
A research paper has been submitted. This section will be updated when the paper has been published online.
MaterialsCoord can be installed from source using:
git clone https://github.com/hackingmaterials/materials-coord.git
cd materials-coord
pip install .MaterialsCoord requires Python 3.6+.
Track changes to MaterialsCoord through the Changelog.
MaterialsCoord is in early development but we still welcome your contributions. Please read our contribution guidelines for more information. We maintain a list of all contributors here.
MaterialsCoord is released under a modified BSD license; the full text can be found here.