Potopt Molecular Dynamics Suite

Potopt is molecular dynamics software implemented in ISO C11 and utilizing MPI for parallel processing.

This manual documents a pre-release version of the software, made available at 2014-02-26. The details of both the implementation and user interface are still not settled, and are likely to change significantly before the first release.

Synopsis

$ perl yaml2pob.perl \
      < Initial-state.yaml > Initial-state.pob 
$ mpirun -n N \
      potopt Split [Iterations [Step [Tau2]]] \
      < Initial-state.pob > Output.log 2>&1 

Summary

Potopt is an ISO C11- and MPI-based (tested with GCC 4.8.2 and Open MPI 1.6.5, respectively) code that solves equations of motion for a system of (dimensionless) particles with user-specified masses, initial locations and velocities. The equations are based on the Morse potential, with parameters specified for each interacting pair of particles (which may mean the ones sharing a chemical bond, or otherwise related.)

The -n N parameter given to mpirun(1) specifies the number of processes to run. Refer to the documentation on the MPI implementation used for more information.

The Split argument is currently mandatory and is a whitespace-delimited string of positive integer values specifying the number of particles to simulate with each process. Naturally, these numbers should sum up to a total number of particles in the system considered, such as 22 for modelling the 22-atom graphene sample system below within a single process (-n 1), '11 11' for two processes (-n 2), '7 8 7' for three (-n 3), etc.

Iterations is the number of iterations to do, and defaults to 64. A value of 65536 or greater may be more practical.

Step is the initial time step, in seconds, and defaults to 1e-18 (or 1 as), although the values of around 2e-19 may be a more suitable choice. Nevertheless, the software will continuously try to find an optimal time step, based on the constraints set within main_loop () (check the redo_p local variable there.)

Tau2 is the characteristic time the system should lose half of its kinetic energy, and defaults to 4e-18 (or 4 as.)

YAML-based input format

The simulation code requires a stream in an ad-hoc (and possibly platform-dependent) binary encoding, which is produced from a YAML stream with a helper yaml2pob.perl Perl script.

The input YAML stream may look as follows (for a single six-membered carbon ring, ignoring the hydrogen atoms.)

---
xyz:
  - { a: 0, xyz: [ 0.0, 7.104999999999999e-11, 0 ] }
  - { a: 1, xyz: [ 1.2306220987776874e-10, 0.0, 0 ] }
  - { a: 2, xyz: [ 2.461244197555375e-10, 7.104999999999999e-11, 0 ] }
  - { a: 3, xyz: [ 0.0, 2.1315e-10, 0 ] }
  - { a: 4, xyz: [ 1.2306220987776874e-10, 2.842e-10, 0 ] }
  - { a: 5, xyz: [ 2.461244197555375e-10, 2.1315e-10, 0 ] }
bonds:
  - { a: 0, b: 1 }
  - { a: 0, b: 3 }
  - { a: 1, b: 2 }
  - { a: 2, b: 5 }
  - { a: 3, b: 4 }
  - { a: 4, b: 5 }

The xyz section specifies the particles (atoms), while bonds specifies the parameters to the w:Morse potential used to model chemical bonds.

The parameters are as follows.

Particles

• a – unique particle identifier (may be any string);
• xyz – particle’s initial location;
• v – (optional) particle’s initial velocity; defaults to a zero vector;
• m – (optional) particle’s mass; defaults to 1.660539e-27, or 1.660539 × 10⁻²⁷ g, which is a possible approximation for the mass of a single w:Carbon atom.

Bonds

• a, b – the identifiers of the particles sharing the bond;
• aa, r, D – (optional) Morse potential parameters; default to 2.625e10, 1.421e-10, and 6.03105e-19, respectively, which are possible values for the C─C single bond.

Please note that apart from the representation conversion, the Perl helper described will slightly alter both the initial locations and velocities of the particles, as per the $perturb and $pert_v variables (specifying the standard deviations for the respective changes) within the code. This is intended as both a testing measure and a possible way to push the system off a local minimum, should the initial state correspond to one.

The output

The resulting system state is sent to stdout, formatted as whitespace-separated values. The values are mass, location (3 values), and velocity (3 values.)

Building

The Potopt executable can be built with a GNU C compiler, being run under GNU Make as follows. (No Makefile required.)

$ cp -- ns8xrqxiojtkiin4drpx4ne19y.c potopt.c 
$ LC_ALL=C make CC=mpicc CFLAGS='-g -O2 -Wall -std=gnu11' \
      LDFLAGS=-lm   potopt 

Alternatively, the following simplistic GNUmakefile file can be used, with the GNU Make invocation becoming $ LC_ALL=C make potopt.

VPATH   = $(srcdir)
CC      = mpicc
CFLAGS  = -g -O2 -Wall -std=gnu11
LDFLAGS = -lm

all: potopt

Bugs

The Split argument should be made optional.

The simulation code reads a binary file in an ad-hoc, and possibly platform-dependent, encoding. Using encodings specified in X.690 (DER or BER), or perhaps NetCDF, may be a better choice.

Worse still, while the simulation code reads the initial system state from a binary file (which, in turn, could be created from a YAML-based text stream), the resulting state is saved instead in a Awk- and Gnuplot-friendly whitespace-separated values form, which requires a separate program (not hereby provided) to convert it into something suitable to continue the simulation.

Some details are reported to stderr on each iteration in a somewhat verbose and not readily parsable (with, say, Awk or Gnuplot) text format. For tens of thousands of iterations, the size of the resulting stream may end up being tens of mebibytes.

There’s no proper error reporting. The code instead relies on a bunch of assert () macro invocations.

There’s no proper command line interface, either.

Check also the FIXME: comments within the code.

Availability

The pre-release versions of the Potopt components, as documented here, are available from the following locations:

• http://am-1.org/~ivan/src/ns8xrqxiojtkiin4drpx4ne19y.c – the simulation code itself;
• http://am-1.org/~ivan/src/gpqfyhge73tgcr4dkfp9xydju8.perl – the YAML to binary conversion code;
• http://am-1.org/~ivan/doc-files/qdzyppoeigu1f8gj4mh3m41b1d.yaml – a sample 22-atom graphene system.

Author

Potopt is written by Ivan Shmakov.

Potopt is free software: you can redistribute it and/or modify its current version under the terms of the BSD-like license, as included within the code. Please note, however, that the license is likely to be changed to GNU General Public License version 3 sometime prior or at the time of the 0.1 release.

This documentation is a free collaborative project going on at Wikibooks, and is available under the Creative Commons Attribution/Share-Alike License (CC BY-SA) version 3.0.

The contents of this page is based on the author’s earlier posting to news:alt.sources, which, as it seems, has failed to propagate.

See also

• w:Graphene
• v:User:Ivan Shmakov/Potopt 2014
• v:ru:Участник:Ivan Shmakov/Параллельные вычисления в моделировании графена 2014