Dislocation Extraction Algorithm (DXA) tool Version 1.3.4 Copyright 2010, Alexander Stukowski (dxa@stukowski.de) All rights reserved. See License section for more information. *********************************************************************************************************** * About *********************************************************************************************************** The dislocation extraction algorithm (DXA) extracts all lattice dislocations contained in an atomistic simulation snapshot of a crystal, converts them to one-dimensional line segments and determines their Burgers vectors. The DXA method has been developed by Alexander Stukowski at the Institute of Materials Science at Darmstadt University of Technology, Germany. The algorithm is described in detail in the article [Modelling Simul. Mater. Sci. Eng. 18 (2010) 085001]. Note that the DXA tool provides extended functionality not yet described in the paper. It allows to extract partial dislocations as well as twinning dislocations from FCC crystals. In addition, polygonal representations of stacking fault planes and coherent twin planes can be extracted from such crystals. Alexander Stukowski works with Lawrence Livermore National Laboratory, Livermore, California. Contact: dxa@stukowski.de *********************************************************************************************************** * License - Terms and Conditions *********************************************************************************************************** The DXA code is made available free of charge under the following terms and conditions: 1. The code, or parts of it, in source or binary form, may not be redistributed. If you would like to share the code with someone else, point him or her to the website. 2. You may adapt the code to your personal needs. Again, however, you may not distribute the altered code to somebody else. Ask me for permission if you would like to share a modified version of the code. 3. The code may only be used for scientific purposes. Commercial usage is not permitted. 4. Scientific publications that contain data or insights obtained with the code should reference the DXA paper describing the algorithm [Modelling Simul. Mater. Sci. Eng. 18 (2010) 085001]. This program is distributed in the hope that it will be useful, but without any warranty; without even the implied warranty of merchantability or fitness for a particular purpose. *********************************************************************************************************** * Compiling the code *********************************************************************************************************** The DXA code is pretty platform independent and should compile on all major platforms and operating systems. I have tested it only on Linux and MacOS X though. The only external library it requires is the OpenGL Utilities library (libGLU), which is used for tessellation or non-convex polygons. This library should be present on most systems by default. You will need a C++ compiler and the CMake makefile generator tool to build it. The CMake tool is included in most Linux distributions and is freely available from the website http://www.cmake.org/. Some parts of the DXA algorithm have been parallelized by means of OpenMP to run faster on multi-core processor systems. OpenMP will be enabled automatically when compiling the code with GCC 4.2 or newer. I haven't added support for the Intel C++ compiler's OpenMP to the CMakeLists.txt file yet. To build a binary executable, create an empty build directory first. In this directory, run cmake [path_to_source] where [path_to_source] should be replaced by the path to the src/ directory in the DXA source distribution. After the CMake tool has successfully created the makefile, run make to build the executable, which is called "DXA". *********************************************************************************************************** * Usage *********************************************************************************************************** The DXA tool takes an atomistic simulation snapshot file as input, extracts all dislocation lines and writes them to a dislocation output file. In the current version, only FCC, HCP, and BCC crystals are supported. Partial dislocations and twinning dislocations (which are a special type of grain boundary dislocation) can only be recognized in FCC crystals. Output files (having a .vtk extension) can be visualized with the ParaView software (freely available from www.paraview.org). The different output parts (dislocations, stacking faults, defect surface) each go into their own file. The tools directory contains some Python scripts that allow to convert these ParaView files to other formats. Usage of the main analysis program: DXA [options] cna_cutoff inputfile outputfile Parameters: cna_cutoff: Cutoff radius parameter for the common neighbor analysis This parameter controls the generation of nearest neighbor bonds. For FCC and HCP lattices, the CNA cutoff should be set to a value halfway between the first and second nearest neighbor shell. For the BCC lattice, the cutoff must be between the second and third shell. Note: This parameter is ignored if a preprocessed DXA file generated by the LAMMPS module is used as input. inputfile : Input atoms file The atomistic input file for the analysis. The following formats are supported: - LAMMPS text dump files. Only the "x", "y", and "z" columns are read in; all other columns are ignored. - IMD snapshot files (ASCII format). - MD++ snapshot files. - Preprocessed files written by the DXA LAMMPS module (not available yet). The program supports non-orthogonal simulation cells. You can use the special filename "-" to let the program read the atomic coordinates from standard input (stdin). This is useful if you want to read in a compressed file and decompress it on the fly using the 'zcat' Unix command and a process pipe. outputfile: Output dislocations file (ParaView VTK file) The filename of the output file to which the extracted dislocations lines are written. I suggest to use the extension '.dislocations.vtk' for the destination file. You can use the special filename "-" to let the program write the dislocation lines to standard output (stdout). The following command line options are all optional. Output options: -dumpsurface FILE : Dump crystal defect surface to a VTK file. Specifies the file to which the extracted defect surface is written. The defect surface consist of those parts of the interface mesh, which have not been swept by elastic Burgers circuits. I suggest to use the extension '.surface.vtk' for the destination file. -dumpsurfacecap FILE : Dump surface facets at periodic boundaries to a VTK file. The cap facets close the holes in the defect surface, which show up at periodic boundaries. I suggest to use the extension '.surfacecap.vtk' for the destination file. -dumpsf FILE : Dump stacking fault planes to a VTK file. Specifies a file to which the extracted stacking fault and twin boundary planes should be written. I suggest to use the extension '.sf.vtk' for the destination file. -dumpcell FILE : Dump simulation cell geometry to a VTK file. Specifies a file to which the simulation cell geometry (as read from the input file) should be written. This is useful for visualizing the cell in ParaView. I suggest to use the extension '.cell.vtk' for the destination file. -dumpmesh FILE : Dump original interface mesh to a VTK file. Specifies a file to which the complete interface mesh should be written. This option is for debugging purposes only. -dumpatoms FILE : Dump processed atoms to a LAMMPS dump file. Specifies a file to which the atoms should be dumped after the CNA and clustering have been performed. This feature is for debugging purposes only. DXA control options: -pbc X Y Z : Activates periodic boundary conditions (X,Y,Z = 0/1) Specifies periodic boundary conditions. By default, open boundaries are assumed. To enable pbc in all three spatial directions use '-pbc 1 1 1'. -offset X Y Z : Displaces all atoms by the given vector prior to analysis. This option is useful to translate the system with respect to its periodic boundaries when you want to make the 'cut' at another position. If periodic boundary conditions are enabled, the shifted atomic positions are automatically wrapped back into the simulation cell. -scale X Y Z : Scales the entire simulation cell prior to analysis. This option is useful to 'subtract' large elastic deformation from you simulation cell, which sometimes interferes with the identification of crystalline atoms by means of the CNA. X,Y,Z are the factors by which each of the three cell axes is scaled. -maxcircuitsize N : Maximum circuit length for initial Burgers circuit search (default N=9) Specifies the maximum search depth for the initial Burgers circuit search. Dislocation segments will only be found if their core's circumference is not greater than N mesh edges. -extcircuitsize M : Extended Burgers circuit size limit (default M=16) Specifies the maximum length of elastic Burgers circuits while they are advanced along dislocation segments to find junctions. M must not be smaller than N. Smoothing options: -smoothsurface N : Smoothing level for defect surface (default N=8) The defect surface is smoothed before it is written to the output file. This option specifies the amount of smoothing applied. N=0 disables all smoothing. -smoothlines N : Smoothing level for dislocation lines (default N=4) The dislocation lines are smoothed before they are written to the output file. This option controls the amount of smoothing applied. N=0 disables all smoothing. -coarsenlines N : Coarsening level for dislocation lines (default N=4) The number of dislocation line points that are generated during dislocation tracing is usually too high. That is why the number is reduced in a coarsening step prior to smoothing. Note that a higher coarsening level usually leads to a stronger smoothing of the remaining points. -flattensf X : Flattening level for stacking fault planes (X=[0,1]; default: X=0.2) Planar stacking faults planes are bordered by dislocation lines and by parts of the defect surface. When dislocation segments are joined at nodal points, the generated line might be slightly nonplanar. This parameter controls what happens to the incident stacking fault plane in such a case. For X=0 (no flattening), the stacking fault contour exactly follows the dislocation line, effectively resulting in nonplanar stacking fault polygons. For X=1 (completely flat), all points of the stacking fault polygon are projected onto a plane, creating a perfectly flat face. Note that this might lead to a gap between the stacking fault and its bordering dislocation segments in the visualization.