Code Examples¶
The examples
directory includes five programs that make use of the
compressor.
Simple Compressor¶
The simple program is a minimal example that shows how to call
the compressor and decompressor on a double-precision 3D array. Without
the -d
option, it will compress the array and write the compressed
stream to standard output. With the -d
option, it will instead
read the compressed stream from standard input and decompress the
array:
simple > compressed.zfp
simple -d < compressed.zfp
For a more elaborate use of the compressor, see the zfp utility.
Diffusion Solver¶
The diffusion example is a simple forward Euler solver for the heat equation on a 2D regular grid, and is intended to show how to declare and work with zfp’s compressed arrays, as well as give an idea of how changing the compression rate and cache size affects the error in the solution and solution time. The usage is:
diffusion [-i] [-n nx ny] [-p] [-t nt] [-r rate] [-c blocks]
where rate specifies the exact number of compressed bits to store per
double-precision floating-point value (default = 64); nx and ny
specify the grid size (default = 100 × 100); nt specifies the number
of time steps to take (the default is to run until time t = 1); and blocks
is the number of uncompressed blocks to cache (default = nx / 2). The
-i
option enables array traversal via iterators instead of indices.
The -p
option enables OpenMP parallel execution, which makes use
of both mutable and immutable private views
for thread-safe array access. Note that this example has not been
optimized for parallel performance, but rather serves to show how to
work with zfp’s compressed arrays in a multithreaded setting.
Running diffusion with the following arguments:
diffusion -r 8
diffusion -r 12
diffusion -r 20
diffusion -r 64
should result in this output:
rate=8 sum=0.996442 error=4.813938e-07
rate=12 sum=0.998338 error=1.967777e-07
rate=20 sum=0.998326 error=1.967952e-07
rate=64 sum=0.998326 error=1.967957e-07
For speed and quality comparison, the solver solves the same problem using
uncompressed double-precision arrays when -r
is omitted.
The diffusionC program is the same example written entirely in C using the cfp wrappers around the C++ compressed array classes.
Speed Benchmark¶
The speed program takes two optional parameters:
speed [rate] [blocks]
It measures the throughput of compression and decompression of 3D double-precision data (in megabytes of uncompressed data per second). By default, a rate of 1 bit/value and two million blocks are processed.
PGM Image Compression¶
The pgm program illustrates how zfp can be used to compress grayscale images in the pgm format. The usage is:
pgm <param> <input.pgm >output.pgm
If param
is positive, it is interpreted as the rate in bits per pixel,
which ensures that each block of 4 × 4 pixels is compressed to a fixed
number of bits, as in texture compression codecs.
If param
is negative, then fixed-precision mode is used with precision
-param
, which tends to give higher quality for the same rate. This
use of zfp is not intended to compete with existing texture and image
compression formats, but exists merely to demonstrate how to compress 8-bit
integer data with zfp. See FAQs #20 and
#21 for information on the effects of setting the
precision.
In-place Compression¶
The inplace example shows how one might use zfp to perform in-place compression and decompression when memory is at a premium. Here the floating-point array is overwritten with compressed data, which is later decompressed back in place. This example also shows how to make use of some of the low-level features of zfp, such as its low-level, block-based compression API and bit stream functions that perform seeks on the bit stream. The program takes one optional argument:
inplace [tolerance]
which specifies the fixed-accuracy absolute tolerance to use during compression. Please see FAQ #19 for more on the limitations of in-place compression.
Iterators¶
The iterator example illustrates how to use zfp’s
compressed-array iterators and pointers for traversing arrays. For
instance, it gives an example of sorting a 1D compressed array
using std::sort()
. This example takes no command-line
options.