From a2b5c379f237032bbf84bc72b725907cfb53967c Mon Sep 17 00:00:00 2001 From: Richard Berger Date: Tue, 1 Sep 2020 12:17:08 -0400 Subject: [PATCH] Update docs for COMPRESS styles --- doc/src/dump.rst | 19 ++++++++++++++----- doc/src/dump_modify.rst | 41 +++++++++++++++++++++++++++++++++++++++++ doc/src/write_dump.rst | 5 +++++ 3 files changed, 60 insertions(+), 5 deletions(-) diff --git a/doc/src/dump.rst b/doc/src/dump.rst index 36a20defb6..d225b88662 100644 --- a/doc/src/dump.rst +++ b/doc/src/dump.rst @@ -46,17 +46,19 @@ Syntax *atom* args = none *atom/gz* args = none + *atom/zstd* args = none *atom/mpiio* args = none *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/zstd* 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*\ , *custom/gz*\ , *custom/zstd* , *custom/mpiio* args = see below *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 - *local* args = see below + *local*, *local/gz*, *local/zstd* args = see below *molfile* args = discussed on :doc:`dump molfile ` doc page *movie* args = discussed on :doc:`dump image ` doc page *netcdf* args = discussed on :doc:`dump netcdf ` doc page @@ -65,9 +67,10 @@ Syntax *xtc* args = none *xyz* args = none *xyz/gz* args = none + *xyz/zstd* args = none *xyz/mpiio* args = none -* *custom* or *custom/gz* or *custom/mpiio* or *netcdf* or *netcdf/mpiio* args = list of atom attributes +* *custom* or *custom/gz* or *custom/zstd* or *custom/mpiio* or *netcdf* or *netcdf/mpiio* args = list of atom attributes .. parsed-literal:: @@ -111,7 +114,7 @@ Syntax d_name = per-atom floating point vector with name, managed by fix property/atom i_name = per-atom integer vector with name, managed by fix property/atom -* *local* args = list of local attributes +* *local* or *local/gz* or *local/zstd* args = list of local attributes .. parsed-literal:: @@ -130,6 +133,7 @@ Examples dump myDump all atom 100 dump.atom dump myDump all atom/mpiio 100 dump.atom.mpiio dump myDump all atom/gz 100 dump.atom.gz + dump myDump all atom/zstd 100 dump.atom.zst dump 2 subgroup atom 50 dump.run.bin dump 2 subgroup atom 50 dump.run.mpiio.bin dump 4a all custom 100 dump.myforce.* id type x y vx fx @@ -187,7 +191,7 @@ default. For the *dcd*\ , *xtc*\ , *xyz*\ , and *molfile* styles, sorting by atom ID is on by default. See the :doc:`dump_modify ` doc page for details. -The *atom/gz*\ , *cfg/gz*\ , *custom/gz*\ , and *xyz/gz* styles are identical +The *atom/gz*\ , *cfg/gz*\ , *custom/gz*\ , *local/gz*, and *xyz/gz* styles are identical in command syntax to the corresponding styles without "gz", however, they generate compressed files using the zlib library. Thus the filename suffix ".gz" is mandatory. This is an alternative approach to writing @@ -198,6 +202,11 @@ For the remainder of this doc page, you should thus consider the *atom* and *atom/gz* styles (etc) to be inter-changeable, with the exception of the required filename suffix. +Similarily, the *atom/zstd*\ , *cfg/zstd*\ , *custom/zstd*\ , *local/zstd*, +and *xyz/zstd* styles are identical to the gz styles, but use the Zstd +compression library instead. See the :doc:`dump_modify ` doc +page for details on how to control the compression level in both variants. + As explained below, the *atom/mpiio*\ , *cfg/mpiio*\ , *custom/mpiio*\ , and *xyz/mpiio* styles are identical in command syntax and in the format of the dump files they create, to the corresponding styles without diff --git a/doc/src/dump_modify.rst b/doc/src/dump_modify.rst index 6c7d4eb0f5..753cce703c 100644 --- a/doc/src/dump_modify.rst +++ b/doc/src/dump_modify.rst @@ -114,6 +114,21 @@ Syntax *framerate* arg = fps fps = frames per second for movie +* these keywords apply only to the */gz* and */zstd* dump styles +* keyword = *compression_level* + + .. parsed-literal:: + + *compression_level* args = level + level = integer specifying the compression level that should be used (see below for supported levels) + +* these keywords apply only to the */zstd* dump styles +* keyword = *compression_level* + + .. parsed-literal:: + + *checksum* args = *yes* or *no* (add checksum at end of zst file) + Examples """""""" @@ -962,6 +977,28 @@ images less frequently. ---------- +The COMPRESS package offers both GZ and Zstd compression variants of styles +atom, custom, local, cfg, and xyz. When using these styles the compression +level can be controlled by the :code:`compression_level` parameter. File names +with these styles have to end in either :code:`.gz` or :code:`.zst`. + +GZ supports compression levels from -1 (default), 0 (no compression), and 1 to +9. 9 being the best compression. The COMPRESS :code:`/gz` styles use 9 as +default compression level. + +Zstd offers a wider range of compression levels, including negative +levels that sacrifice compression for performance. 0 is the +default, positive levels are 1 to 22, with 22 being the most expensive +compression. Zstd promises higher compression/decompression speeds for +similar compression ratios. For more details see +`http://facebook.github.io/zstd/`. + +In addition, Zstd compressed files can have a checksum of the entire +contents. The Zstd enabled dump styles enable this feature by default and it +can be disabled with the :code:`checksum` parameter. + +---------- + Restrictions """""""""""" none @@ -1010,6 +1047,10 @@ The option defaults are * color = 140 color names are pre-defined as listed below * framerate = 24 +* compression_level = 9 (gz variants) +* compression_level = 0 (zstd variants) +* checksum = yes (zstd variants) + ---------- These are the standard 109 element names that LAMMPS pre-defines for diff --git a/doc/src/write_dump.rst b/doc/src/write_dump.rst index f0f57bd674..2e3831b40f 100644 --- a/doc/src/write_dump.rst +++ b/doc/src/write_dump.rst @@ -31,6 +31,11 @@ Examples write_dump all image snap*.jpg element element & bond atom 0.3 shiny 0.1 ssao yes 6345 0.2 size 1600 1600 & modify backcolor white element C C O H N C C C O H H S O H + write_dump all atom/gz dump.atom.gz modify compression_level 9 + write_dump flow custom/zstd dump.%.myforce.zst & + id type c_myF[3] v_ke & + modify sort id & + compression_level 15 Description """""""""""