Atomic structure analysis algorithms

A small program code to demonstrate the implementation of various atomic structure analysis algorithms discussed in the article

A. Stukowski:
"Structure identification methods for atomistic simulations of crystalline materials"
Modelling Modelling and Simulation in Materials Science and Engineering 20 (2012), 045021

Download

Source code (v1.0.1, 30-Sep-2017)

Readme.txt

===================================================================================
Structure Analysis Tool for Atomistic Simulation Data

Version: 1.0.0 (May 2012)
Author:  Alexander Stukowski (stukowski (at) mm.tu-darmstadt.de)

================================= Reference =======================================

This program code has been published together with the article 

  A. Stukowski
  Structure identification methods for atomistic simulations of crystalline materials
  Modelling and Simulation in Materials Science and Engineering 20 (2012), 045021

Contact: stukowski (at) mm.tu-darmstadt.de
Website: http://asa.ovito.org/

================================== Purpose ========================================

This analysis code provides basic implementations of the structure
identification algorithms discussed in the MSMSE article. Its main purpose 
is to demonstrate these common techniques and to provide a starting point
for further developments.

If you are rather looking for an easy-to-use analysis and visualization tool
for atomistic simulation data, please have a look at OVITO, which
is for every day use. OVITO is freely available at http://ovito.org/ and provides 
the common neighbor analysis and the bond angle analysis. The upcoming version will 
also feature the adaptive common neighbor analysis introduced in the article.

This code is distributed under an Open Source license. I invite you to 
extend it, play with it, share it, or just run it. The code is free software; you 
can redistribute it and/or modify under the terms of the GNU General Public License 
as published by Free Software Foundation. See the file LICENSE.txt.

============================== Compiling the code ==================================

The code is platform independent and should compile on most platforms and operating systems.
I have tested it only on Linux and with the g++ compiler though. 
You will need a C++ compiler to compile the code and the CMake makefile generator tool to 
generate a Unix Makefile out of the project file. CMake is included in most Linux distributions and 
is freely available from the website http://www.cmake.org/.  

To build the executable, create an empty build directory first. In this directory, run

    cmake [path_to_source]

where [path_to_source] should point to the src/ directory in this source distribution.
After the CMake tool has successfully created the makefile, run

    make

to build the executable, which is called "StructureAnalysisTool".

================================= Running the code ==================================

The analysis tool reads in a single snapshot from a LAMMPS dump file.
Run 

	./StructureAnalysisTool
	
to see a list of command line options. For usage examples see the script 
file 'examples.sh' in the tests/ directory.

====================================== Notes ========================================

The following analysis types are implemented in the code:

	cna    = Common neighbor analysis with fixed cutoff radius
	acna   = Adaptive common neighbor analysis
	baa    = Bond angle analysis
	bop    = Bond order parameter analysis
	cspfcc = Centrosymmetry analysis (using 12 NN for fcc)
	cspbcc = Centrosymmetry analysis (using 8 NN for bcc)
	voro   = Voronoi analysis
	nda    = Neighbor distance analysis

The tool will always generate a neighbor list first for each atom. For this
you have to specify a cutoff radius using the --cutoff command line option.
The cutoff should be large enough to include enough neighbors as needed to identify the
atomic structure. For instance, for fcc and hcp it should be larger than
then nearest neighbor distance, while for bcc, it should be larger than the second
nearest neighbor distance. The analysis algorithms [acna,baa,cspfcc,cspbcc,voro,nda]
sort the neighbor list and pick only as many neighbors as required for the 
identification. Thus, you can safely specify an excessively large cutoff radius without
affecting the analysis results. The algorithms [cna,bop], however, rely on an
exact cutoff as discussed in the article. That is, you need to choose it with more care. 

The [voro] algorithm is deactivated in the code by default. To make it available, you have to enable
the corresponding option in the CMake settings program and recompile the code. 
This feature requires the Voro++ library, which is available at http://math.lbl.gov/voro++/.

The two CSP variants [cspfcc,cspbcc] differ in the number of nearest neighbors they take into
account. Choose the algorithm that matches you crystal structure at hand. 

Note that the algorithms [bop,cspfcc,cspbcc] do not assign a structural type to atoms. 
The code just computes the corresponding signatures, but doesn't use them to classify an atom.
These algorithms have only been implemented for demonstration purposes and for benchmarking.
The CSP values are, however, written to the output file and can be visualized and used for filtering
in OVITO or otherwise.

================================= Version history =======================================

Release 1.0.0 (29-May-2012): 
  - Initial public Release

Release 1.0.1 (30-Sep-2017): 
  - Fixed bug in the a-CNA routine: An exceesively large cutoff radius led to wrong results
    when the neighbor list of an atom exceeded 32 entries.