crayon is a python plugin for performing Neighborhood Graph Analysis (NGA) via graphlet decomposition for autonomous crystal structure comparison on molecular simulation snapshots. It wraps the libgraphlet library, which in turn wraps Orca, based on the following paper: Milenkoviæ, Tijana, and Nataša Pržulj. "Uncovering biological network function via graphlet degree signatures." Cancer informatics 6 (2008): 257.

crayon is released under the Modified BSD License. Please read the license for exact terms.

Clone from the git repository and initialize the submodules. You must do this recursively to ensure all dependencies are obtained!

git clone https://github.com/wfreinhart/crayon.git
cd crayon
git submodule update --init --recursive

To build crayon, simply use cmake to install to an appropriate location:

cd /path/to/crayon
mkdir build && cd build
cmake ..
make install

• Required:
  • Python >= 2.7
  • numpy >= 1.10.0
  • scipy >= 1.0.0
  • CMake >= 3.1.0
  • C++11 compliant compiler
  • Boost graph library headers
• Included (as git submodules):
  • Eigen (header only)
  • pybind11 (header only)
  • libgraphlet (built and linked automatically)
  • Voro++ (built and linked automatically)

Some (not all) classes are unit-tested at the Python level. To run all tests from the build directory,

make test

You must make sure that your installation location is on your PYTHONPATH, and then crayon can be imported as usual:

import crayon

Each simulation Snapshot must be initialiezd with particle positions, box dimensions, and a reference to a NeighborList object:

nl = crayon.neighborlist.Voronoi()
snap = crayon.nga.Snapshot(xyz=xyz,box=box,nl=nl)

NGA is performed on an Ensemble, which is a collection of Snapshot objects. An Ensemble is be built up from a set of Snapshot objects using the insert method:

traj = crayon.nga.Ensemble()
traj.insert('my_filename.xyz',snap)

Once an Ensemble is loaded with Snapshots, a DMap can be computed to provide a low-dimensional representation of all observed structures:

traj.computeDists()
traj.buildDMap()

The coordinates in low-dimensional space can be written to files using the following convenience function:

traj.writeColors()

A .cmap file will be written for each Snapshot in the Ensemble containing the structure ID and RGB triplet for each particle. The classification can be easily visualized in Ovito using the Python script modifier with the script located in src/py/ovito.py.