From 95b4613e16145868e84ac3ef916e75bc22328125 Mon Sep 17 00:00:00 2001 From: Podhorszki Norbert Date: Fri, 3 Jan 2020 14:52:54 -0500 Subject: [PATCH] Added documentation for 'read_dump ... format adios' command and fixed links and names for 'dump atom/adios' and 'dump custom/adios' commands. --- doc/src/Commands_all.rst | 12 +++++----- doc/src/Packages_details.rst | 9 ++++++-- doc/src/dump.rst | 14 +++++++----- doc/src/dump_adios.rst | 7 +++--- doc/src/read_dump.rst | 43 ++++++++++++++++++++++++++++++++++-- 5 files changed, 68 insertions(+), 17 deletions(-) diff --git a/doc/src/Commands_all.rst b/doc/src/Commands_all.rst index 5ad8fff44c..f5444205a4 100644 --- a/doc/src/Commands_all.rst +++ b/doc/src/Commands_all.rst @@ -46,7 +46,8 @@ An alphabetic list of all general LAMMPS commands. * :doc:`dimension ` * :doc:`displace_atoms ` * :doc:`dump ` - * :doc:`dump adios ` + * :doc:`dump atom/adios ` + * :doc:`dump custom/adios ` * :doc:`dump image ` * :doc:`dump movie ` * :doc:`dump netcdf ` @@ -131,10 +132,11 @@ An alphabetic list of all general LAMMPS commands. * :doc:`units ` * :doc:`variable ` * :doc:`velocity ` - * :doc:`write_coeff ` - * :doc:`write_data ` - * :doc:`write_dump ` - * :doc:`write_restart ` + * :doc:`write\_coeff ` + * :doc:`write\_data ` + * :doc:`write\_dump ` + * :doc:`write\_restart ` + * * * * diff --git a/doc/src/Packages_details.rst b/doc/src/Packages_details.rst index 62615a8fb7..376bc0acda 100644 --- a/doc/src/Packages_details.rst +++ b/doc/src/Packages_details.rst @@ -1096,8 +1096,9 @@ USER-ADIOS package **Contents:** ADIOS is a high-performance I/O library. This package implements the -dump "atom/adios" and dump "custom/adios" commands to write data using -the ADIOS library. +:doc:`dump atom/adios `, :doc:`dump custom/adios ` and +:doc:`read_dump ... format adios ` +commands to write and read data using the ADIOS library. **Authors:** Norbert Podhorszki (ORNL) from the ADIOS developer team. @@ -1111,6 +1112,10 @@ This package has :ref:`specific installation instructions ` on the : * src/USER-ADIOS/README * examples/USER/adios * https://github.com/ornladios/ADIOS2 +* :doc:`dump atom/adios ` +* :doc:`dump custom/adios ` +* :doc:`read_dump ` + ---------- diff --git a/doc/src/dump.rst b/doc/src/dump.rst index e07100bb19..c76b8efbad 100644 --- a/doc/src/dump.rst +++ b/doc/src/dump.rst @@ -21,8 +21,11 @@ dump command :doc:`dump movie ` command ====================================== -:doc:`dump adios ` command -====================================== +:doc:`dump atom/adios ` command +=========================================== + +:doc:`dump custom/adios ` command +============================================= Syntax """""" @@ -45,12 +48,12 @@ Syntax *atom* args = none *atom/gz* args = none *atom/mpiio* args = none - *atom/adios* args = none, discussed on :doc:`dump adios ` doc page + *atom/adios* args = none, discussed on :doc:`dump atom/adios ` doc page *cfg* args = same as *custom* args, see below *cfg/gz* args = same as *custom* args, see below *cfg/mpiio* args = same as *custom* args, see below *custom*\ , *custom/gz*\ , *custom/mpiio* args = see below - *custom/adios* args = same as *custom* args, discussed on :doc:`dump adios ` doc page + *custom/adios* args = same as *custom* args, discussed on :doc:`dump custom/adios ` doc page *dcd* args = none *h5md* args = discussed on :doc:`dump h5md ` doc page *image* args = discussed on :doc:`dump image ` doc page @@ -713,7 +716,8 @@ LAMMPS was built with that package. See the :doc:`Build package Related commands """""""""""""""" -:doc:`dump adios ` :doc:`dump h5md `, :doc:`dump image `, +:doc:`dump atom/adios `, :doc:`dump custom/adios `, +:doc:`dump h5md `, :doc:`dump image `, :doc:`dump molfile `, :doc:`dump\_modify `, :doc:`undump ` diff --git a/doc/src/dump_adios.rst b/doc/src/dump_adios.rst index b0db9f5aed..e3cb74e978 100644 --- a/doc/src/dump_adios.rst +++ b/doc/src/dump_adios.rst @@ -1,6 +1,7 @@ -.. index:: dump atoms/adios +.. index:: dump atom/adios +.. index:: dump custom/adios -dump atoms/adios command +dump atom/adios command ========================= dump custom/adios command @@ -12,7 +13,7 @@ Syntax .. parsed-literal:: - dump ID group-ID atoms/adios N file.bp + dump ID group-ID atom/adios N file.bp dump ID group-ID custom/adios N file.bp args diff --git a/doc/src/read_dump.rst b/doc/src/read_dump.rst index d8f6a5015d..704c938e51 100644 --- a/doc/src/read_dump.rst +++ b/doc/src/read_dump.rst @@ -43,6 +43,7 @@ Syntax *format* values = format of dump file, must be last keyword if used *native* = native LAMMPS dump file *xyz* = XYZ file + *adios* = dump file written by the :doc:`dump adios ` command *molfile* style path = VMD molfile plugin interface style = *dcd* or *xyz* or others supported by molfile plugins path = optional path for location of molfile plugins @@ -65,6 +66,7 @@ Examples read_dump dump.xyz 10 x y z box no format molfile xyz ../plugins read_dump dump.dcd 0 x y z format molfile dcd read_dump dump.file 1000 x y z vx vy vz format molfile lammpstrj /usr/local/lib/vmd/plugins/LINUXAMD64/plugins/molfile + read_dump dump.bp 5000 x y z vx vy vz format adios Description """"""""""" @@ -136,6 +138,14 @@ contain multiple directories separated by a colon (or semi-colon on windows). The *path* keyword is optional and defaults to ".", i.e. the current directory. +The *adios* format supports reading data that was written by the +:doc:`dump adios ` command. The +entire dump is read in parallel across all the processes, dividing +the atoms evenly amongs the processes. The number of writers that +has written the dump file does not matter. Using the adios style for +dump and read_dump is a convenient way to dump all atoms from *N* +writers and read it back by *M* readers. + Support for other dump format readers may be added in the future. @@ -147,7 +157,19 @@ and box information. The dump file is scanned for a snapshot with a timestamp that matches the specified *Nstep*\ . This means the LAMMPS timestep the dump file -snapshot was written on for the *native* format. Note that the *xyz* +snapshot was written on for the *native* or *adios* formats. + +The list of timestamps available in an adios .bp file is stored in the +variable *ntimestep*: + +.. parsed-literal:: + + $ bpls dump.bp -d ntimestep + uint64_t ntimestep 5*scalar + (0) 0 50 100 150 200 + + +Note that the *xyz* and *molfile* formats do not store the timestep. For these formats, timesteps are numbered logically, in a sequential manner, starting from 0. Thus to access the 10th snapshot in an *xyz* or *mofile* @@ -160,7 +182,8 @@ and the current simulation box is orthogonal or vice versa. A warning will be generated if the snapshot box boundary conditions (periodic, shrink-wrapped, etc) do not match the current simulation boundary conditions, but the boundary condition information in the snapshot is -otherwise ignored. See the "boundary" command for more details. +otherwise ignored. See the "boundary" command for more details. The +*adios* reader does the same as the *native* format reader. For the *xyz* format, no information about the box is available, so you must set the *box* flag to *no*\ . See details below. @@ -231,6 +254,18 @@ consistent from snapshot to snapshot in the molfile dump file. See the :doc:`dump\_modify sort ` command if the dump file was written by LAMMPS. +The *adios* format supports all fields that the *native* format supports +except for the *q* charge field. +The list of fields stored in an adios .bp file is recorded in the attributes +*columns* (array of short strings) and *columnstr* (space-separated single string). + +.. parsed-literal:: + + $ bpls -la dump.bp column* + string columns attr = {"id", "type", "x", "y", "z", "vx", "vy", "vz"} + string columnstr attr = "id type x y z vx vy vz " + + ---------- @@ -357,10 +392,14 @@ The *molfile* dump file formats are part of the USER-MOLFILE package. They are only enabled if LAMMPS was built with that packages. See the :doc:`Build package ` doc page for more info. +To write and read adios .bp files, you must compile LAMMPS with the +:ref:`USER-ADIOS ` package. + Related commands """""""""""""""" :doc:`dump `, :doc:`dump molfile `, +:doc:`dump adios `, :doc:`read\_data `, :doc:`read\_restart `, :doc:`rerun `