Command Line Interface (CLI) Usage

Type ./fzmod or ./fzmod -h for the CLI help printout.

Usage

[...] means this setting is optional

# Compression (-z)
./fzmod -t <type> -m <mode> -e <error-bound> -i <input_file> -l <dimensions> -z [--report]
# Decompression (-x)
./fzmod -i <compressed_input> -x [--compare <orig_data>] [--report]

To use compression use the -z option which requires:

• data type
• error mode and error bound
• input data filepath
• input data dimensions

To use decompression use the -x option which requires:

• input compressed data
• to get data quality metrics, use --compare and provide the original data

---

Basic Example

Assuming using CESM CLDHGH.f32 with dimensions 3600x1800

# Compression
./fzmod -t f32 -m rel -e 2e-4 -i CLDHGH.f32 -l 3600x1800 -z --report
# Decompression
./fzmod -i CLDHGH.f32.fzmod -x --compare CLDHGH.f32 --report

# Example Output

~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
FZMod GPU Compression Library Metrics
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

~~COMPRESSION~~
Timing Metrics
Preprocessing stage:     1.052001 ms     22.946633 Gib/s
Prediction stage:        1.732525 ms     13.933352 Gib/s
Histogram stage:         0.025771 ms     936.707214 Gib/s
Encoding stage:          2.032184 ms     11.878788 Gib/s
End-end compression:     5.171205 ms     4.668135 Gib/s
File IO stage:           10.917255 ms    2.211168 Gib/s

Compression Metrics
Original size:           25920000 bytes
Compressed size:         3449228 bytes
Compression ratio:       7.514725
Num outliers:            3224
Data Length:             6480000
Data Type:               fp32
Original File Size:              24 MiB
Total Footprint (Device):        100 MiB
Total Footprint (Host):          53 MiB

~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
FZMod GPU Compression Library Metrics
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

~~DECOMPRESSION~~
Timing Metrics
Decoding Stage:          0.675137 ms 35.755531 GiB/s
Pred-Reversing Stage:    1.519332 ms 15.888483 GiB/s
End-end decompression:   3.065253 ms 7.875331 GiB/s
File IO time:            97.433968 ms 0.247756 GiB/s

~~COMPARISON~~
Data Original Min:               0.001636
Data Original Max:               0.895646
Data Original Range:             0.894011
Data Original Mean:              0.228626
Data Original Stddev:            0.156379

Data Decompressed Min:           0.001788
Data Decompressed Max:           0.895799
Data Decompressed Range:         0.894011
Data Decompressed Mean:          0.228626
Data Decompressed Stddev:        0.156379

Compression Ratio:               7.514725
Bitrate:                         4.258306
NRMSE:                           0.000115
PSNR:                            78.750319
coeff:                           1.000000

Max Error Index:                 1378921
Max Error Value:                 0.000179
Max Abs Error:                   0.000000

Full CLI Options

Option	Settings	Details
-h --help	N/A	printout
-v --version	N/A	printout
-D --dump	N/A	dump quant/hist codes to file
-R --report	N/A	report timing/comp details
-V --verbose	N/A	print config
-S --skip	write2disk	skip setting
--compare --origin	filename	compare w/ orig data
--stf	N/A	enable CUDASTF pipeline
-m --mode	rel/abs	error mode
-e --eb --error-bound	value	error bound for predictor
-p --pred --predictor	lorenzo/lorenzo_zz/spline	predictor selection
--hist --histogram	generic/sparse	histogram selection
-c1 --codec --codec1	huffman/huffman_revisit/fzg	codec selection
-c2 --codec2	none/zstd/gzip	optional secondary codec
-t --type	f32/f64	data type
-r --radius	value (default = 512)	1/2 number of quant/hist bins
-b --outlier-buffer-ratio	value (default = 0.2)	ratio of len to reserve space for
-i -input	filename	input file
-l --len --xyz	valxvalxval	dimensionality of input data
-z --zip --compress	N/A	option to compress
-x --unzip --decompress	N/A	option to decompress

---

Compression Pipelines

1. Default (Lorenzo -> Histogram -> Huffman -> None)

./fzmod -t f32 -m rel -e 1e-4 -i data.f32 -l 500x500 -z \
    --pred lorenzo --hist sparse --codec huffman

2. Quality (Spline 3D -> Histogram -> Huffman -> None)

./fzmod -t f32 -m rel -e 1e-4 -i data.f32 -l 500x500 -z \
    --pred spline --hist sparse --codec huffman

2. Speed (Lorenzo -> FZG -> None)

./fzmod -t f32 -m rel -e 1e-4 -i data.f32 -l 500x500 -z \
    --pred lorenzo --codec fzg