Guide to Sz

这篇文档内容主要对sz数据压缩函数库进行一个简单的介绍，同时对相关的函数接口也做一定的介绍。

[TOC]

sz 是什么

sz，全称为Squeeze，是一种以误差限定方式（error-bounded）来进行数据压缩的方法。它可以大幅度降低数据的存储量，同时保证解压后的数据与原数据误差在我们限定的范围内。

• sz可以被用来压缩不同类型的数据（主要针对的是单精度和双精度型数据），并且适用于高维数组（目前最高支持维度为5维）；
• sz十分易于使用，它提供了三种编程语言的接口：Fortran，C，以及Java（Java版本在最近的几个高版本中没有继续更新）；
• sz支持不同架构的处理器，包括x86_32位，x86_64位，ARM，SOLARIS，以及IBM BlueGene 系列。
• sz支持通过设定不同的误差方式来压缩数据，我们可以在sz.config中写明或是通过函数接口传入相关参数，关于误差方式这一部分可以参见sz配置文件详解；
• 如果我们有许多变量需要压缩，我们可以采用（作者推荐采用）批压缩方式；
• 这是作者个人主页

如何安装SZ

首先，我们可以从这个页面下载到sz的源码，作者一直在更新当中。

执行安装步骤如下：

configure --prefix=[INSTALL_DIR]
make
make install

我们可以在[INSTALL_DIR]中找到相关的头文件include/以及链接库lib/，我们可以将其加入到相关路劲中，如C_INCLUDE_PATH，至于链接库，可以在编译的时候直接指定。

注意：在MAC OS上直接按照上述步骤安装会报错，解决方法是通过homebrew安装一个gcc，然后利用这个gcc来进行编译。原因在与MAC自带的gcc实质调用的是clang编译器，而非真正的gcc编译器。

快速上手

我们可以在[sz_package]/example/中找到相关测试用例，若只想测试是否安装成功，可以直接运行test.sh这一脚本。

压缩实现

命令格式

# 基本命令格式：
# ./cmd [sz config file] [data] [r1] [r2] [r3] ...

# 3d数据
./testdouble_compress sz.config testdouble_8_8_128.dat 8 8 128
# 4d数据
./testdouble_compress sz.config testdouble_8_8_8_128.dat 8 8 8 128

./testfloat_compress sz.config testfloat_8_8_128.dat 8 8 128

解压缩实现

命令格式

# 基本命令格式：
# ./cmd [sz config file] [data] [r1] [r2] [r3] ...

# 3d
./testdouble_decompress sz.config testdouble_8_8_128.dat.sz 8 8 128
# 4d
./testdouble_decompress sz.config testdouble_8_8_8_128.dat.sz 8 8 8 128

./testfloat_decompress sz.config testfloat_8_8_128.dat.sz 8 8 128

在解压缩过程中，我们不需要提供误差限定信息，因为这些信息已经包含在了解压缩数据流中了。

API接口

sz提供两种应用程序接口——C和Fortran（在SZ-0.x版本中还提供了Java接口）。这些接口在不同编程语言中是相近的，但是也存在一些不同，如在C中，我们需要声明数据类型（SZ_FLOAT或是SZ_DOUBLE），但是在Fortran接口中不需要这个参数。

关键的三个接口：

• SZ_Init()：初始化压缩或是解压缩
• SZ_compress()/SZ_decompress()：压缩数据或是解压缩数据
• SZ_Finalize()：结束压缩

C压缩与解压缩接口

1. SZ_Init and SZ_Init_Params

   作用：初始化压缩。在对多个变量进行压缩过程中，SZ_Init()只需被调用一次。

   原型：void SZ_Init(char *configFilePath);

   参数：

   • configFilePath：配置文件路径，一般我们都是直接将配置文件与程序放在同一文件夹下，进而路径只需要填写配置文件的文件名即可(such as example/sz.config)

   返回：none

   /* 另一个用于初始化的函数，但是不常用 */
   Synopsis: void SZ_Init_Params(sz_params * params);
   Input: params the configuration variable that contains the initialization information.
   Return: none.
   zz_params data structure:
   typedef struct sz_params
   {
   unsigned int quantization_intervals; //default value: 0
   int dataEndianType; //what is the endian type of the original data set?
   int sysEndianType; //sysEndianType can be ignored, because it can be
   detected autumnally by our compressor based on the system architectures.
   int sol_ID; //default value: #define SZ 101
   int layers; //default value: 1
   int sampleDistance; //default value: 50
   float preThreshold; //default value: 0.97
   int offset; //default value: 0
   int szMode; //default value: #define SZ_BEST_COMPRESSION 1
   int gzipMode; //default value: Gzip_BEST_SPEED
   int errorBoundMode; //4 options: ABS, REL, ABS_AND_REL, ABS_OR_REL
   double absErrBound; //example: 0.0001
   double relBoundRatio; //example: 0.001
   } sz_params;

2. SZ_compress

   作用：用于压缩浮点数数组。我们可以采用两类压缩接口（3种函数接口）来实现数据压缩。

   原型：

   // 第一类第一种 
   char *SZ_compress(int dataType, void *data, int *outSize, int r5, int r4, int r3, int r2,
   int r1);
   // 第二类第一种
   char *SZ_compress_args(int dataType, void *data, int *outSize,int errBoundMode, double absErrBound, double relBoundRatio,int r5, int r4, int r3, int r2, int r1);
   // 第二类第二种
   int SZ_compress_args2(int dataType, void data, char compressed_bytes,int *outSize,int errBoundMode, double absErrBound, double relBoundRatio,int r5, int r4, int r3, int r2, int r1);

   参数：

   • datatype：数据类型，有两种选择SZ_FLOAT或是SZ_DOUBLE
   • data：将要被压缩的数组指针，从原型中可以看出，数组指针为一维指针，因而我们只能将一维数组传递过去。在testdouble_compress.c中，程序先是从二进制文件中读取数据，然后讲相关数据指针传递给data，但是在实际编程过程中，我们可以直接将内存中的一维数组指针传给data，不需要额外进行转换（作者转换的原因是考虑到了不同机器编码方式不同）
   • compressed_bytes：用于存放压缩后数据的内存空间
   • outSize：压缩后数据流的大小（单位为字节）
   • r[1-5]：分别对应[1-5]维的维度，若是维数不到5维，则不到的维度数值为0

   返回：压缩数据流（以字节计）

3. SZ_decompress

   作用：解压缩数据，我们可以有两类接口用于解压

   原型：

   //第一类
   void *SZ_decompress(int dataType, char *bytes, int byteLength,int r5, int r4, int r3, int r2, int r1);
   //第二类
   int SZ_decompress_args(int dataType, char *bytes, int byteLength,void* decompressed_array,int r5, int r4, int r3, int r2, int r1);

   参数：

   • datatype：同上
   • bytes：将要被解压的压缩数据流
   • byteLength：压缩数据流的长度
   • decompressed_array：用于存储被解压后的数据地址
   • r[1-5]：同上

   返回：解压后的数据流

4. SZ_batchAddVar

   作用：将某一变量以批处理的方式和其他变量一起进行压缩

   原型：

   void SZ_batchAddVar(char* varName, int dataType, void* var,int r5, int r4, int r3, int r2, int r1,int errBoundMode, double absErrBound, double relBoundRatio);

5. SZ_batchDelVar

   作用：将某一个变量从要压缩列表中删除

   原型：

   int SZ_batchDelVar(char* varName);

   参数：

   • varName：不进行批压缩的变量

   返回：0-成功；1-没用找到相应的变量

6. SZ_batch_compress

   作用：以批处理的方式压缩数据，所有声明要批处理压缩的数据会一起进行压缩（好处是提高了压缩率）

   原型：

   char* SZ_batch_compress(int *outSize);

   参数：

   • outSize：压缩后的数据流（以字节计）

   返回：压缩后的数据流

7. SZ_batch_decompress

   作用：解压缩进行批压缩的数据流

   原型：

   SZ_VarSet* SZ_batch_decompress (char* compressedStream,int compressedLength);

   参数：

   • compressedStream：被批压缩的数据流
   • compressedLength：被批压缩的数据流的长度（以字节计）

   返回：包含有多个变量的解压缩后的数据结构体，可以参见VarSet.h查看更多细节。全局的SZ_VarSet定义在sz.h中。

8. SZ_Finalize

   作用：释放内存以及结束压缩环境

   原型：int SZ_Finalize();

   参数：none

   返回：none

Fortran压缩与解压缩接口

1. SZ_Init

   作用：同 C

   原型：SZ_Init(configFilePath, ierr);

   参数：

   • configFilePath：in，配置文件路径，定义方式为：CHARACTER(len=32) :: configFilePath
   • ierr：out，成功返回0，失败返回1，定义方式为：INTEGER(Kind=4) :: ierr

2. SZ_Compress

   作用：同 C

   原型：

   • SZ_compress(data, bytes, outSize);

     参数：

     • data：in，将要被压缩的数组数据，定义方式为：REAL(KIND=8), DIMENSION(:,:,:) ::data
     • bytes：out，压缩之后的字节流，定义方式为：INTEGER(kind=1), DIMENSION(:), allocatable :: bytes
     • outsize：out，字节流大小（以字节计），定义方式为：INTEGER(kind=4) :: OutSize

   • SZ_Compress (data, bytes, outSize,errBoundMode, absErrBound, relBoundRatio);

     参数：

     • errBoundMode：in，误差限定模式，可以取值为：ABS, REL, ABS_AND_REL, ABS_OR_REL，定义方式为：INTEGER(kind=4) :: ErrBoundMode
     • absErrBound：in，绝对误差数值，定义方式为：REAL(kind=4 or 8) :: absErrBound
     • relBoundRatio：in，相对误差数值，定义方式为：REAL(kind=4 or 8) :: relBoundRatio，关于误差限定的详细内容可以参见上面

3. SZ_Decompress

   作用：同 C

   原型：SZ_Decompress(bytes, data, [r1,r2,…])

   参数：

   • bytes：in，要被解压缩的压缩数据流，定义方式为：INTEGER(kind=1), DIMENSION(:) :: Bytes
   • data：out，解压后的数据，定义方式为：REAL(KIND=4 or 8), DIMENSION(:,:,…:,:), allocatable :: data
   • r[1-5]：in，分别对应[1-5]维的数据维度，若维数不到5维，则不到的维度赋值为0，定义方式：INTEGER(kind=4) :: r1[, r2, r3, r4, r5]，也可以在接口中不填入没有数值的维度，如3维只填3个维度数值

4. SZ_BatchAddVar

   作用：同 C

   原型：void SZ_batchAddVar(varName, var,errBoundMode, absErrBound, relBoundRatio);

   参数：

   • varName：in，将要进行批处理压缩的变量的名字，定义方式为：CHARACTER(len=128) :: varName
   • var：in，将要进行批处理压缩的变量
   • errBoundMode：in，误差限定模式，可选：ABS, REL, ABS_AND_REL, ABS_OR_REL，定义方式为：INTEGER(kind=4) :: ErrBoundMode
   • absErrBound：in，绝对误差数值，定义方式为：REAL(kind=4 or 8) :: absErrBound
   • relBoundRatio：in，相对误差数值，定义方式为：`REAL(kind=4 or 8) :: relBoundRatio

5. SZ_BatchDelVar

   作用：同 C

   原型：void SZ_batchDelVar(varName, ierr);

   参数：

   • varName：in，将要被删除的变量名，定义方式：CHARACTER(len=128) :: varName
   • ierr：out，成功返回0，没有找到相应变量返回1，定义方式：INTEGER(kind=4) :: ierr

6. SZ_Batch_Compress

   作用：同 C

   原型：void SZ_Batch_Compress(bytes, outSize)

   参数：

   • bytes：out，压缩后产生的数据流，定义方式为：INTEGER(kind=1), DIMENSION(:), allocatable :: bytes
   • outsize：out，压缩后数据流的大小（以字节计），定义方式为：INTEGER(kind=4) :: OutSize

7. SZ_Batch_Decompress

   作用：同 C

   原型：void SZ_Batch_Decompress(bytes, outSize)

   参数：

   • bytes：in，将要被解压缩的数据流，定义方式为：INTEGER(kind=1), DIMENSION(:) :: Bytes
   • outsize：in，解压后数据流大小，定义方式为：INTEGER(kind=4) :: OutSize

8. SZ_Finalize

   作用：同 C

   原型：SZ_Finalize();

   参数：none

   返回：none

参考：

• [SZ_package]/doc/sz-1.4-user-guide.pdf