.. SPDX-FileCopyrightText: 2021 Intel Corporation
..
.. SPDX-License-Identifier: CC-BY-4.0

.. _compression_modes:

Compression Modes
=================

The compression mode of ZFP algorithm must be specified by 4 parameters included in ``zfp_compressed_stream`` structure (see :ref:`structure description <input_output_streams>`). This approach allows implementation to meet various constraints on the precision and size of the output. The description of these parameters is given below:

* zfp_compressed_stream.\ **maxbits** - The maximum number of compressed bits used to represent a block. This parameter sets the hard upper bound on compressed block size, and governs the rate in fixed-rate mode. It may also be used as an upper storage limit to prevent implementation from buffer overruns in combination with the accuracy constraints given by ``zfp_compressed_stream.maxprec`` and ``zfp_compressed_stream.minexp``.

* zfp_compressed_stream.\ **minbits** - The minimum number of compressed bits used to represent a block. It is recommended to set this parameter to one bit, unless each block is to be stored using a fixed number of bits to facilitate random access (in this case it must be set to the same value as ``zfp_compressed_stream.maxbits``).

* zfp_compressed_stream.\ **maxprec** - The maximum number of bit planes encoded. This parameter governs the number of most significant uncompressed bits encoded per transform coefficient. This parameter specifies the precision in fixed-precision mode, as well as provides a mechanism for controlling the relative error.

* zfp_compressed_stream.\ **minexp** - The smallest absolute bit plane number encoded. The place value of each transform coefficient bit depends on the common floating-point exponent, `e`, that scales the integer coefficients. If the most significant coefficient bit has place value 2\ :sup:`e`, then the number of bit planes encoded is (one plus) the difference between `e` and ``zfp_compressed_stream.minexp``.

The oneDTL library interface must allow user to choose 1 of 4 compression modes:

.. doxygenenum:: oneapi::dtl::data_compression::zfp_mode
  :project: oneDTL

For now, only the ``fixed-rate`` mode is implemented. ``fixed-precision`` mode has only a public interface but has no implementation.

.. _fixed_rate:

Fixed-rate Compression Mode
++++++++++++++++++++++++++++

In ``fixed-rate`` mode, each d-dimensional compressed block of 4\ :sup:`d` values must be stored using a fixed number of bits given by parameters ``zfp_compressed_stream.maxbits`` and ``zfp_compressed_stream.minbits``. oneDTL library provides a structure for specifying this mode:

.. doxygenstruct:: oneapi::dtl::data_compression::zfp_fixed_rate
  :project: oneDTL
  :members:

Accordingly, the compression parameters will be as follows:

::

    minbits = maxbits = ((1 << (2 * d)) * rate) + 0.5
    maxprec = ZFP_MAX_PREC
    minexp = ZFP_MIN_EXP

.. _fixed_precision:

Fixed-precision Compression Mode
+++++++++++++++++++++++++++++++++

In ``fixed-precision`` mode, the number of bits used to encode a block may vary, but the number of bit planes (i.e., the precision) encoded for the transform coefficients must be fixed. Fixed-precision mode is recommended when relative rather than absolute errors matter. oneDTL structure for specifying this mode:

.. doxygenstruct:: oneapi::dtl::data_compression::zfp_fixed_precision
  :project: oneDTL
  :members:

And compression parameters looks like:

::

    minbits = ZFP_MIN_BITS
    maxbits = ZFP_MAX_BITS
    maxprec = zfp_fixed_precision.maxprec
    minexp = ZFP_MIN_EXP

Default Compression Parameter Settings
+++++++++++++++++++++++++++++++++++++++

The default recommended compression parameter settings that impose no constraints:

::

	ZFP_MAX_BITS = 16658
	ZFP_MIN_BITS = 1
	ZFP_MAX_PREC = 64
	ZFP_MIN_EXP = -1074