Summary

Allow users to input general triclinic boxes and atom configurations to LAMMPS, and likewise produce general triclinic outputs. All the new enhancements are optional new features, no change to current features.

Background:

A general triclinic (tri) simulation box has arbitrary edge vectors A,B,C. LAMMPS currently only allows use of a restricted tri box where A is along the x-axis, B is in the xy plane with a +y-coord, and C has a +z-coord. This is for consistency with neighbor list building, ghost communication, and other orthogonal simulation box operations, as well as for efficient parallelization.

Any general tri box can be rotated to become a restricted tri box, so conceptually this is not a restriction. However, it can be more convenient for users to specify general tri boxes and their atoms, and also to generate output for the same.

Key idea:

Allow input and output of general tri boxes and corresponding atom properties (coordinates, per-atom vectors). Do this by performing transformations from general <--> restricted at the time of input and output. Internally, LAMMPS continues to store and perform simulations with restricted tri boxes. All other commands (e.g. velocity, region) still operate on the restricted tri simulation box and its atoms.

Restriction:

LAMMPS requires that A,B,C for a general tri box define a right-handed coordinate system. I.e. A x B is in the direction of C. This allows simple rotation matrices to convert between general and restricted triclinic representations.

Details:

(1) Domain class
add triclinic_general variable to indicate general tri box is defined
add variables for A,B,C edge vectors of box, boxlo is still used as the origin of the A,B,C vectors
store rotation matrices used for general <--> restricted rotations
add method to define the genearal triclinic box
add methods which perform general <--> restricted rotations for coords and vectors
when the restricted tri box changes (NPT, fix deform, etc) general A,B,C edge vectors are changed as well

(2) read_data command
add header keywords for avec,bvec,cvec and "abc origin"
these replace "xlo xhi", etc for orthogonal and "xy xz yz" for restricted tri
rotated quantities are the following (hence data file values are affected)
Atoms section: x, mu (DIPOLE and DIELECTRIC package), x0 (MACHDYN package), sp (SPIN package)
Velocities section: v, omega, angmom
Lines, Triangles, Ellipsoids, Bodies sections

(3) write_data command
add optional triclinic/general keyword
header keywords for avec,bvec,cvec and "abc origin"
these replace "xlo xhi", etc (for orthogonal) and "xy xz yz" for restricted tri
same quantities from read_data command are rotated for output as general tri values

(4) lattice command
add optional triclinic/general keyword
a1,a2,a3 are treated as edge vectors of a general tri unit cell
used by create_box and create_atoms command

(5) create_box command
for general tri box, region = NULL, add 6 params
6 params are multiples of general tri unit cell defined by lattice command

(6) create_atoms command
box and region styles can use a general tri lattice
this can fill the general tri box or a subset region of it
the region refers to the restricted tri box

(7) read_restart and write_restart commands
write/read triclinic_general variable and rotation_g2r 3x3 matrix

(8) dump atom and dump custom commands
new dump_modify triclinic/general keyword
affected keywords: x, xu, vx, fx, mux, omegax, angmomx, tqx
per-snapshot header binary writes avec, bvec, cvec, boxlo
per-snapshot header text is of form:
ITEM: BOX BOUNDS abc origin boundary-string
avec[0] avec[1] avec[2] boxlo[0]
bvec[0] bvec[1] bvec[2] boxlo[1]
cvec[0] cvec[1] cvec[2] boxlo[2]

(9) thermo_style custom command
new thermo_modify triclinic/general keyword
affected keywords = 6 pressure tensor values = pxx, pyy, pzz, pxy, pxz, pyz

Still to do (before no longer work-in-progress):

(a) more testing
(b) add an examples dir
(c) add thermo keywords for output of avec, bvec, cvec, origin

Ideas for future work: (probably not in this PR)

(a) read_dump support for general tri
(b) dump image support for general tri
(c) C-style lib interface support for general tri
(d) ditto for Python wrapper on lib interface
(e) add a dump_modify option to enable a compute/fix/variable which produces a per-atom vector to be output with a general tri rotation, similar to velocity

Related Issue(s)

N/A

Author(s)

Steve

Licensing

By submitting this pull request, I agree, that my contribution will be included in LAMMPS and redistributed under either the GNU General Public License version 2 (GPL v2) or the GNU Lesser General Public License version 2.1 (LGPL v2.1).

Backward Compatibility

Most of the code changes are new optional features which should not break existing inputs.
A few are new constraints on old inputs which may generate error messages for existing inputs.
An example of the latter is that for 2d systems, z coords of atoms are required to be zero, and
the simulation box extent in z needs to straddle zero. I.e. zlo < 0.0 and zhi > 0.0.

Implementation Notes

Post Submission Checklist

• The feature or features in this pull request is complete
• Licensing information is complete
• Corresponding author information is complete
• The source code follows the LAMMPS formatting guidelines
• Suitable new documentation files and/or updates to the existing docs are included
• The added/updated documentation is integrated and tested with the documentation build system
• The feature has been verified to work with the conventional build system
• The feature has been verified to work with the CMake based build system
• Suitable tests have been added to the unittest tree.
• A package specific README file has been included or updated
• One or more example input decks are included

Further Information, Files, and Links