Update docs for COMPRESS styles

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 <dump_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 <dump_adios>` doc page
        *dcd* args = none
        *h5md* args = discussed on :doc:`dump h5md <dump_h5md>` doc page
        *image* args = discussed on :doc:`dump image <dump_image>` doc page
-       *local* args = see below
+       *local*, *local/gz*, *local/zstd* args = see below
        *molfile* args = discussed on :doc:`dump molfile <dump_molfile>` doc page
        *movie* args = discussed on :doc:`dump image <dump_image>` doc page
        *netcdf* args = discussed on :doc:`dump netcdf <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 <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 <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

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

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
 """""""""""