From fc51c38abb2b8afe0e51de7746ff5f9d38a7e747 Mon Sep 17 00:00:00 2001 From: Axel Kohlmeyer Date: Tue, 28 Mar 2017 02:22:45 -0400 Subject: [PATCH] add some docs for the special treatment of image flags --- doc/src/Section_howto.txt | 5 +++++ doc/src/Section_python.txt | 11 ++++++++++- 2 files changed, 15 insertions(+), 1 deletion(-) diff --git a/doc/src/Section_howto.txt b/doc/src/Section_howto.txt index a378d8d088..87bd52720a 100644 --- a/doc/src/Section_howto.txt +++ b/doc/src/Section_howto.txt @@ -2013,6 +2013,11 @@ Both methods are thus a means to extract or assign (overwrite) any peratom quantities within LAMMPS. See the extract() method in the src/atom.cpp file for a list of valid per-atom properties. New names could easily be added if the property you want is not listed. +A special treatment is applied for accessing image flags via the +"image" property. Image flags are stored in a packed format with all +three image flags stored in a single integer. When signaling to access +the image flags as 3 individual values per atom instead of 1, the data +is transparently packed or unpacked by the library interface. The lammps_create_atoms() function takes a list of N atoms as input with atom types and coords (required), an optionally atom IDs and diff --git a/doc/src/Section_python.txt b/doc/src/Section_python.txt index b994a56402..ff26d18e06 100644 --- a/doc/src/Section_python.txt +++ b/doc/src/Section_python.txt @@ -698,7 +698,12 @@ method in the src/atom.cpp file for a list of valid names. Again, new names could easily be added if the property you want is missing. The vector can be used via normal Python subscripting. If atom IDs are not consecutively ordered within LAMMPS, a None is returned as -indication of an error. +indication of an error. A special treatment is applied for image flags +stored in the "image" property. All three image flags are stored in +a packed format in a single integer, so count would be 1 to retrieve +that integer, however also a count value of 3 can be used and then +the image flags will be unpacked into 3 individual integers, ordered +in a similar fashion as coordinates. Note that the data structure gather_atoms("x") returns is different from the data structure returned by extract_atom("x") in four ways. @@ -727,6 +732,10 @@ corresponding properties for each atom inside LAMMPS. This requires LAMMPS to have its "map" option enabled; see the "atom_modify"_atom_modify.html command for details. If it is not, or if atom IDs are not consecutively ordered, no coordinates are reset. +Similar as for gather_atoms() a special treatment is applied for image +flags, which can be provided in packed (count = 1) or unpacked (count = 3) +format and in the latter case, they will be packed before applied to +atoms. The array of coordinates passed to scatter_atoms() must be a ctypes vector of ints or doubles, allocated and initialized something like