README.md
1ZFP
2===
3[](https://travis-ci.org/LLNL/zfp)
4[](https://ci.appveyor.com/project/salasoom/zfp)
5[](https://zfp.readthedocs.io/en/release0.5.5/?badge=release0.5.5)
6[](https://codecov.io/gh/LLNL/zfp)
7
8INTRODUCTION
9------------
10
11zfp is an open source C/C++ library for compressed numerical arrays that
12support high throughput read and write random access. zfp also supports
13streaming compression of integer and floating-point data, e.g., for
14applications that read and write large data sets to and from disk.
15zfp is primarily written in C and C++ but also includes Python and
16Fortran bindings.
17
18zfp was developed at Lawrence Livermore National Laboratory and is loosely
19based on the algorithm described in the following paper:
20
21 Peter Lindstrom
22 "Fixed-Rate Compressed Floating-Point Arrays"
23 IEEE Transactions on Visualization and Computer Graphics
24 20(12):2674-2683, December 2014
25 doi:10.1109/TVCG.2014.2346458
26
27zfp was originally designed for floating-point arrays only, but has been
28extended to also support integer data and could for instance be used to
29compress images and quantized volumetric data. To achieve high compression
30ratios, zfp generally uses lossy but optionally error-bounded compression.
31Bit-for-bit lossless compression is also possible through one of zfp's
32compression modes.
33
34zfp works best for 2D and 3D arrays that exhibit spatial correlation, such as
35continuous fields from physics simulations, images, regularly sampled terrain
36surfaces, etc. Although zfp also provides a 1D array class that can be used
37for 1D signals such as audio, or even unstructured floating-point streams,
38the compression scheme has not been well optimized for this use case, and
39rate and quality may not be competitive with floating-point compressors
40designed specifically for 1D streams. zfp also supports compression of
414D arrays.
42
43zfp is freely available as open source under a BSD license, as outlined in
44the file 'LICENSE'. For more information on zfp and comparisons with other
45compressors, please see the
46[zfp website](https://computation.llnl.gov/projects/floating-point-compression).
47For bug reports, please consult the
48[GitHub issue tracker](https://github.com/LLNL/zfp/issues).
49For questions, comments, and requests, please contact
50[Peter Lindstrom](mailto:pl@llnl.gov).
51
52
53DOCUMENTATION
54-------------
55
56Full
57[documentation](http://zfp.readthedocs.io/en/release0.5.5/)
58is available online via Read the Docs. A
59[PDF](http://readthedocs.org/projects/zfp/downloads/pdf/release0.5.5/)
60version is also available.
61
62
63INSTALLATION
64------------
65
66zfp consists of three distinct parts: a compression library written in C;
67a set of C++ header files with C wrappers that implement compressed arrays;
68and a set of C and C++ examples. The main compression codec is written in
69C and should conform to both the ISO C89 and C99 standards. The C++ array
70classes are implemented entirely in header files and can be included as is,
71but since they call the compression library, applications must link with
72libzfp.
73
74On Linux, macOS, and MinGW, zfp is easiest compiled using gcc and gmake.
75CMake support is also available, e.g., for Windows builds. See below for
76instructions on GNU and CMake builds.
77
78zfp has successfully been built and tested using these compilers:
79
80 gcc versions 4.4.7, 4.9.4, 5.5.0, 6.1.0, 6.4.0, 7.1.0, 7.3.0, 8.1.0
81 icc versions 15.0.6, 16.0.4, 17.0.2, 18.0.2, 19.0.0
82 clang versions 3.9.1, 4.0.0, 5.0.0, 6.0.0
83 MinGW version 5.3.0
84 Visual Studio versions 14 (2015), 15 (2017)
85
86zfp conforms to various language standards, including C89, C99, C11,
87C++98, C++11, and C++14.
88
89NOTE: zfp requires 64-bit compiler and operating system support.
90
91## GNU builds
92
93To build zfp using gcc, type
94
95 make
96
97from this directory. This builds libzfp as a static library as well as
98utilities and example programs. See documentation for complete build
99instructions.
100
101## CMake builds
102
103To build zfp using CMake on Linux or macOS, start a Unix shell and type
104
105 mkdir build
106 cd build
107 cmake ..
108 make
109
110To also build the examples, replace the cmake line with
111
112 cmake -DBUILD_EXAMPLES=ON ..
113
114To build zfp using Visual Studio on Windows, start a DOS shell, cd to the
115top-level zfp directory, and type
116
117 mkdir build
118 cd build
119 cmake ..
120 cmake --build . --config Release
121
122This builds zfp in release mode. Replace 'Release' with 'Debug' to build
123zfp in debug mode. See the instructions for Linux on how to change the
124cmake line to also build the example programs.
125
126## Testing
127
128To test that zfp is working properly, type
129
130 make test
131
132or using CMake
133
134 ctest
135
136If the compilation or regression tests fail, it is possible that some of the
137macros in the file 'Config' have to be adjusted. Also, the tests may fail
138due to minute differences in the computed floating-point fields being
139compressed, which will be indicated by checksum errors. If most tests
140succeed and the failures result in byte sizes and error values reasonably
141close to the expected values, then it is likely that the compressor is
142working correctly.
143
){kind=link}
){kind=link}