Visualization of dislocations by two-dimensional differential displacement maps

This program visualizes dislocations in crystals using the so-called differential displacement maps. If dislocations are present in the crystal, the atoms close to its core are displaced from their positions in the ideal crystal. The change in the separations of neighboring atoms is depicted by arrows whose lengths correspond to the magnitudes of the changes of their separation relative to their distance in the ideal crystal.

The main features implemented in ddplot are:
  • plotting of atomic structure
  • visualization of screw and edge components around a dislocation line
  • projection of relative displacements into an arbitrary direction
  • scaling of arrows (for the plotting of edge components)
  • automatic finding of the first to fifth nearest neighbors
  • unrelaxed/relaxed configuration
  • coordinate transformations
  • output to Postscript, .XYZ (JMol), standard .CFG (AtomEye)
  • group loading of a set of plot files
  • internal .DD format containing the coordinate system, position of the dislocation, lattice parameter, etc.
  • creating a .GIF animation from the uploaded blocks
  • changing colors, line thickness and radii of atoms and arrows
  • distinguishing atomic layers or atomic types
  • user-defined settings can be stored in ~/.ddplot or loaded at the start

Click on the pictures below to see their actual size.

Snapshot of ddplot showing a block of Mo atoms with a 1/2[111] screw dislocation that has moved from the center by the action of applied shear stress parallel to the slip direction. The arrows correspond to the screw displacements perpendicular to the plane of the figure. The gray lines are traces of planes that make angles 0, 15, 30, 45, 60, 75 and 90 deg with the (-101) plane.

Snapshot of Mo atoms in the bcc structure showing the atoms colored according to the number of neighboring atoms (see the color bar on the right). The list of atomic planes is shown on the left (they can be turned on and off to make calculations only for a given slab of atoms).

In the version 5.0+ ddplot allows to find the dislocation position and dislocation pathways, for example from a series of atomic configurations obtained by the Nudged Elastic Band method. This snapshot shows such calculation for 17 atomic blocks of bcc Mo. The little green triangles are approximations of dislocation positions. The green curve is the calculated dislocation pathway.


version 5.0 (released on October 29, 2017)

Linux x86_64

Mac OS X (10.12+)

Source code (Qt4+)
  • significant speed up after optimizing the manipulations with arrays
  • fixing the problems with too small fonts under Mac OS X
  • completed implementation of the calculation of the dislocation position using the generalized Peierls-Nabarro model
  • new 3D rendering of atoms, incl. antialiasing
  • the properties of atoms can be assigned to all atoms in the selected set
  • the code can be given a number of files to open at once or even plot*.dat
  • setting the background color in .ddplot and in GUI
  • completely reworked calculation of the Burgers vector by the Burgers circuit construction
  • moving up/down in the list of Z-layers using Alt+Up, Alt+Down
  • improved export to postscript
  • distinguishing atoms according to atomic types and numbers of neighbors
  • probing relative atomic displacements
  • native installers for Mac OS X and Windows
  • color maps when distinguishing the atoms according to atomic types and the number of neighbors
  • fixed bug in plotting arrows to account for the existence of periodicity in the Z-direction (the arrows are plotted only between first neighbors)

version 4.0 (src | win)
(released on March 7, 2011)
  • corrected printing of the magnitudes of arrows - the text is not affected by scaling of the lengths of arrows
  • no plotting of arrows of zero length (i.e. the messy dots)
  • animation into a dynamic .gif done using export to .eps and significantly improved
  • status bar made permanent (explicit in Qt4)
  • magnitudes of relative displacements plotted along the arrows (i.e. they are rotated by the same angle as is the angle of the corresponding arrow)
  • possibility of inputting the Burgers vector of the dislocation; this is necessary to plot the lengths of arrows correctly (their plotted length must be the physical length modulo the Burgers vector). It is not clear what to do when the block contains more than 1 dislocation.
  • when saving to .dd the program does not ask for the coordinate system if it has not been defined
  • when exporting the program asks for the file name
  • the coordinate system can now be set for all selected plots at once
  • added moving forward and backward in the list of plots

version 3.0 (src)
(released on November 11, 2009)
  • added rotation of the block around X, Y, Z by 90 deg
  • added a correction for edge displacements in calcEdgeRelDisp() which ensures that the vector sum of the arrows is zero (it applies a correction when two atoms interact through the boundary of the periodic domain)
  • started working on export to EPS (directly using the Postscript language)
  • fixed the problem that caused segfault when reading in the plot file. It was due to unitialized paintEPS (once it was true it crashed because feps was not open)
  • fixed problem when running ddplot from Finder in Mac OS X. The Mac OS X appends automatically as the first argument the process serial number "-psn_". This is disregarded now.
  • fixed settings of the plot - only that for the current plot is changed
  • added reflections through XZ, YZ and XY planes
  • flipping the block changed to 180 deg rotation about the three axes
  • fixed bug that gave wrong nearest neighbors (counted from 0 instead of from 1)
  • END_OF_LIST is changed from -1 to 0 because when nnlist is automatically enlarged, it is filled with zeros and not -1
  • fixed overflow when an atom has more neighbors than 10 (dynamic enlargement of nnlist)
  • added the .xyz format of JMol for reading (see README for details)
  • when the NeighRCut is smaller than the actual first neighbor distance it does not give allocation error but asks to increase NeighRCut in .ddplot
  • fixed segfault when saving .xyz file from structure load in as a BOP code (this was caused by accessing unallocated atomType structure). This may be related to the segfault when comparing two structures.
  • all dialog windows checked and cutting of text fields fixed under Mac OS X
  • fixed the problem with atomType - it now counts from 1
  • fixed the problem with xyzMin in pltwin-func.cpp which caused on MacOS X nan when calculating the lower bounds of the block
  • fixed bug that made it impossible to read in a block file directly from the command line
  • thickness of arrows can also be applied either to the current plot or to all selected plots
  • magnification of arrows/symbols can also be applied either to the current plot or to all selected plots
  • the menu item "Show inert atoms" can be checked and unchecked
  • the structure can be plotted without automatically calculating the differential displacements (lengths of arrows). Then, the nearest neighbor list need not be automatically calculated and the plotting is much faster. This is accomplished by setting in .ddplot: arrNeighbors,0
  • all static arrays are changed to dynamic arrays defined by the class TArray (derived types DVector, DMatrix, ...) and dynamic allocation is used instead of the static declaration of the size of these arrays
  • fixed the positions of magnitudes of edge dislocations after zooming
  • added a new feature that allows one to compare the DD maps from two plots and plot +/- between the atoms. The signs mean that the difference in arrow lengths is either positive (+) or negative (-) where the size of the sign says how much. The only requirements are:
    1. identical number of atoms in the two plots
    2. identical neighbor lists (i.e. compatible structures)
    It means that we can compare the same blocks for different metals, e.g. Mo and W, because the only difference is the lattice parameter and not the crystal structure. This comparison can be done for both edge and screw components.
  • scaling of arrows in the edge view is also precomputed in advance - see calcEdgeScaling().
  • the scaling of arrows in the screw view is now precomputed in advance and is not calculated over and over during each plot. This is done in function calcScrewScaling().
  • the nearest neighbor list is now unidirectional in that it stores only the neighbors (i,j) where j>i. This saves a lot of time when plotting the arrows (no need to check is the arrow is already plotted).

version 2.5 (src)
(released on October 28, 2005)
  • no error about MAX_NEIGHBOR occurs when NeighRCut is too large - instead ddplot asks user to input a smaller cut-off radius for the plot to be displayed
  • ddplot can display a coordinate system of the block (Ctrl+C)
  • several bugs related to the transformation of coordinates corrected
  • when started in the verbose mode 'ddplot -v', ddplot will show where in the code an error has occurred (the line starts with an exclamation mark '!')

version 2.4 (src)
  • it is possible to select particular Z-layer(s) for which the differential displacements are to be plotted
  • magnitudes of differential displacements are printed also for edge dislocations
  • flipping the picture about X, Y or Z axis
  • neighbors are now searched using the linked neighbor list. The same holds for the RDF => the time to plot the structure decreased tremendously for large blocks.
  • fixed wrong plotting of the atomic numbers (used to be numbered from 0, now from 1)
  • calculation of the RDF has been fixed - it is now fully 3-D
  • bounding box fixed - it is read using gs and replaced in the generated PS file
  • correct identification of the same layer if the Z-coordinate for two atoms is not exactly the same number - the tolerance is 1e-4 - e.g. atoms with Z-coordinates 0.4999 and 0.5 are taken to pertain to the same layer. This makes sure that the plot does not contain a bunch of differently colored atoms.
  • plotting of grain boundaries - automatically recognized that the .PLT file contains a grain boundary data and shows the grain boundary as a line
  • can read directly the block of BOP (e.g. block.out) - just change the wildcard at the bottom of the Open file dialog and find the block(s) you wish to display
  • information about the relaxation of the block which is inserted at the end of the .PLT file can now be displayed directly in ddplot (no editing allowed)


To install and compile ddplot from the sources above, you will first need to download the Qt library (version 3.3+ strongly recommended). You can either get the pre-compiled libraries (in case you find them for your platform somewhere on the web) or you can always download sources from the link above and compile the Qt library yourself. If you plan to do the latter on your Linux computer, you will also need the X11 development package XFree86-devel (Redhat 9) or x11-dev (Fedora Core). Mac users need to install the Apple Developer's Toolkit that comes with your MacOS X system CDs. I haven't yet figured out how to compile ddplot on Windows (ask me later or let me know if you succeed).

In case you want to compile the Qt library, I advise you to do a static build. This can be done by going into the Qt home directory (presumably /usr/local/qt*). Become the root by su root and run the following commands:
./configure -static
make install
List the contents of the bin subdirectory - you should see a lot of executable files, among them also qmake. At this point, you have successfully finished compiling the Qt library from sources.

Proceed by downloading the newest source of ddplot from above and unpack it:
tar -xzvf ddplot-*-src.tar.gz
where the asterisk (*) replaces the version number. Go to the directory ddplot where you will find many .cpp files, ddplot.pro, INSTALL and HISTORY files. You will first need to create a Makefile for your platform which will be based on the information in ddplot.pro. This is simply done by running:
If no error message appears, Makefile is successfuly created. However, if there is some error, you probably don't have gmake. This executable usually lives in the directory /usr/lib/qt/bin. If not, you have probably installed Qt from some basic binary; this time you will have to download the Qt library again (it is free for noncommercial purposes) and compile it manually as explained above. If you are the lucky one and the Makefile has been smoothly created, compile the sources by running
This will now take a while. The compiled ddplot executable for your platform will be stored in the same directory.

Feel free to make any changes to suit the code to your needs and feels. If you do some major change that you think may be of interest also for other users, send me your sources and I will prepare a new release involving your modifications and additions.

Also, review the supplied .ddplot file (it is in the ddplot directory) containing the user settings and copy it into your home directory. During the start of ddplot, the program first looks for .ddplot in your home directory and then in the current directory. If it does not find the file, the default settings will be used. You may find useful to use different settings for different plots, e.g. one .ddplot for plotting TiAl structures, another for simple bcc metals. In that case, create more .ddplot files and start ddplot as:
ddplot -f .ddplot-tial
for example. The comments in .ddplot are rather insufficient - in some later release, I shall put in all commands together with their complete description.

File formats

Following is a list of file formats that are readable by ddplot. If you want to use this code for plotting, you are supposed to prepare your data in one of the supported formats. The only format that ddplot uses for saving is the internal .dd format that whose complexity will evolve in future releases to accommodate all possible information required for effective plotting of the differential displacement maps. The underlined words are keywords and must appear as written below.

.xyz format

This is the most trivial format that does not contain any information about the orientation of the block, periodicity and like. It is entirely up to the user of ddplot to remember these parameters.

ninit number of atoms in the initial structure
el1 x(1) y(1) z(1)
el2 x(2) y(2) z(2)
: : : : coordinates of atoms in the initial configuration
: : : : (usually unrelaxed ideal lattice)
eln x(n) y(n) z(n)
el1 x(1) y(1) z(1)
el2 x(2) y(2) z(2)
: : : : coordinates of atoms in the relaxed
: : : : configuration (relaxed structure)
eln x(n) y(n) z(n)
BVECT bx by bz Burgers vector of screw dislocation (if any)

.plt format

This is an old format used in one of our simulation codes. Note, that the number of atoms in the relaxed configuration should be identical to that in the perfect lattice. The relaxed configuration is usually obtained by stressing a perfect crystal, where the initial positions of atoms correspond to the perfect lattice.

nrel number of atoms in the relaxed configuration
: z-positions of atoms in the relaxed
: configuration
x(1) y(1) zlayer(1)
x(2) y(2) zlayer(2)
: : : (x,y) positions of atoms in the
: : : relaxed configuration
x(nrel) y(nrel) zlayer(nrel)
ninit number of atoms in the perfect lattice
: z-positions of atoms in the perfect lattice
x(1) y(1)
x(2) y(2)
: : (x,y) positions of atoms in the perfect
: : lattice
x(ninit) y(ninit)
0 unused, don't ask me why
yperiod periodicity in the x, y, z directions
CORE { xpos; ypos } (x,y) position of the screw dislocation

If the block does not contain any screw dislocation, simply omit the last line.

.bl format

This is another format from the same simulation code that we are using. The format is a bit complicated and is not supposed to be used any more. It is left in ddplot only for the sake of quick visualization of the results of our simulations.

xlen ylen zlen x, y and z size of the block
latpar lattice parameter
nd number of active atoms
x(1) y(1) z(1) elem(1)
x(2) y(2) z(2) elem(2) coordinates of active atoms in the
: : : : relaxed configuration and the name
: : : : of the element, e.g. Mo
x(nd) y(nd) z(nd) elem(nd)
ninert number of inert atoms
x(1) y(1) z(1) elem(1)
x(2) y(2) z(2) elem(2) coordinates of inert atoms in the
: : : : relaxed configuration and the name
: : : : of the element, e.g. Mo
x(ninert) y(ninert) z(ninert) elem(ninert)
x(1) y(1) z(1) elem(1)
x(2) y(2) z(2) elem(2) coordinates of atoms in the
: : : : perfect lattice and the name
: : : : of the element, e.g. Mo
x(nunrld) y(nunrld) z(nunrld) elem(nunrld) nurld=nd+ninert

In our simulations, the block is usually divided into two parts. Outer part of the (x,y) plane contains inert atoms into which we apply anisotropic displacements corresponding to a given stress field. The inner part then contains active atoms whose position is obtained by minimization. In the relaxed configuration, the force on each atom is essentially zero.

.dd format

This is the internal ddplot's format that contain all possible information about the block, including the orientation of the block, positions of dislocations, periodicity, etc. Each block starts with a header that is written below in capital letters. Comments begin with '#' and are ignored by ddplot. Number of spaces between each number in a row and between lines is arbitrary.

CSYS orientation of the block given by three
x1 x2 x3 vectors defined in the cube coordinate system
y1 y2 y3 [100], [010], [001]
z1 z2 z3
xperiod yperiod zperiod periodicity along x, y and z
xpos ypos (x,y) position of the screw dislocation
ninit number of atoms in the perfect lattice
x(1) y(1) z(1) elem(1)
x(2) y(2) z(2) elem(2) coordinates of atoms in the
: : : : perfect lattice and the index
: : : : of the element of this atom
x(ninit) y(ninit) z(ninit) elem(ninit) (count from 0)
nrel number of atoms in the relaxed configuration
x(1) y(1) z(1)
x(2) y(2) z(2) coordinates of atoms in the relaxed
: : : configuration
: : :
x(nrel) y(nrel) z(nrel)

The mandatory fields are NUM_UNREL, COOR_UNREL, NUM_REL, COOR_REL and PERIOD.


Roman Gröger (groger@ipm.cz)

To keep you updated about new versions of ddplot, send me your e-mail and I will add you into the ddplot mailing list. I will be glad to hear about your experience with ddplot, your suggestions but also criticism. If you have some nice figures from ddplot, please, send me .JPG or .GIF to put them here as screenshots.