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

.. _description:

ZFP
===

ZFP is a compression library for floating-point data stored in multidimensional arrays. Compression of d-dimensional (1D, 2D, 3D, and 4D) array of floating-point values is happening by partitioning the source array into cubical blocks of 4\ :sup:`d` values, i.e. 4, 16, 64, or 256 values respectively. Each such block is (de)compressed independently into a fixed or variable length bit string, and these bit strings are concatenated into a single stream of bits.

ZFP usually truncates each bit string to a fixed number of bits to meet a storage budget or to some variable length needed to meet a given error tolerance, as dictated by the compressibility of the data. The bit string representing any given block may be truncated at any point and still yield a valid approximation. 
The early bits are most important. 
The later bits progressively refine the approximation, similar to how the last few bits in a floating-point number have less significance than the first several bits and can often be discarded (zeroed) with limited impact on accuracy.

For more information about this algorithm see the `official documentation <https://zfp.readthedocs.io/en/release0.5.5/index.html>`_.

.. _onedtl_zfp_specific:

oneDTL Specific
+++++++++++++++

oneDTL ZFP compression is based on the open-source ZFP compression library. oneDTL implementation encoded bitstream must be compatible with it as well.

ZFP compressor provides multiple modes of work and data types. The implementation must support modes marked with **v** in the table below, other modes are optional but may become a requirement in the future:

.. csv-table::
  :align: center
  :header: **Compression modes**, **1D**, **2D**, **3D**, **4D**

  **fixed-rate**     ,``x``,``x``,**v**,``x``
  **fixed-precision**,``x``,``x``,``x``,``x``
  **fixed-accuracy** ,``x``,``x``,``x``,``x``
  **expert**         ,``x``,``x``,``x``,``x``

.. _zfp_chunks:

Chunks
++++++

Multiple blocks may be processed at once. Such combination of blocks is called a **chunk**.

.. _zfp_index_array:

Index Array
+++++++++++

Index array must be provided for all modes except ``fixed-rate`` to correctly perform decompression. Values of this array must point to the beginning of each block in the compressed stream.

The following types of indexing should be supported:

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

.. _contents:

Contents
++++++++

The following pages cover the oneDTL API in more details:

.. toctree::
    :maxdepth: 4


    compression_modes
    input_output_streams
    compress_decompress
    example