src/external/tng_io/include/compression/tng_compress.h

   1 /* This code is part of the tng compression routines.
   2  *
   3  * Written by Daniel Spangberg
   4  * Copyright (c) 2010, 2013, The GROMACS development team.
   5  *
   6  *
   7  * This program is free software; you can redistribute it and/or
   8  * modify it under the terms of the Revised BSD License.
   9  */
  10
  11 #ifndef TNG_COMPRESS_H
  12 #define TNG_COMPRESS_H
  13
  14 #ifndef USE_WINDOWS
  15 #if defined(WIN32) || defined(_WIN32) || defined(WIN64) || defined(_WIN64)
  16 #define USE_WINDOWS
  17 #endif /* win32... */
  18 #endif /* not defined USE_WINDOWS */
  19
  20 #ifndef DECLSPECDLLEXPORT
  21 #ifdef USE_WINDOWS
  22 #define DECLSPECDLLEXPORT __declspec(dllexport)
  23 #else /* USE_WINDOWS */
  24 #define DECLSPECDLLEXPORT
  25 #endif /* USE_WINDOWS */
  26 #endif /* DECLSPECDLLEXPORT */
  27
  28 #ifdef __cplusplus
  29  extern "C" {
  30 #endif
  31
  32 /* tng_compress_pos expects positions to have the order:
  33    first xyz, then sorted in atom order
  34    then all the frames repeated, i.e.:
  35    nframes * [
  36     natoms* [
  37       x, y, z
  38     ]
  39    ]
  40    desired_precision what to round the numbers to, i.e. integers will be created as:
  41    round(pos[]/desired_precision).
  42
  43    algo should first be determined by calling
  44    tng_compress_pos_find_algo
  45
  46    The compressed data is returned in a malloced pointer (so free can
  47    be called to free the memory), the number of chars in the compressed
  48    data is put into *nitems.
  49
  50    If too large values are input (compared to the precision), NULL is returned.
  51 */
  52
  53 char DECLSPECDLLEXPORT *tng_compress_pos(double *pos, const int natoms, const int nframes,
  54                                          const double desired_precision,
  55                                          const int speed, int *algo,
  56                                          int *nitems);
  57
  58 char DECLSPECDLLEXPORT *tng_compress_pos_float(float *pos, const int natoms, const int nframes,
  59                                                const float desired_precision,
  60                                                const int speed, int *algo,
  61                                                int *nitems);
  62
  63 char DECLSPECDLLEXPORT *tng_compress_pos_int(int *pos, const int natoms, const int nframes,
  64                                              const unsigned long prec_hi, const unsigned long prec_lo,
  65                                              int speed,int *algo,
  66                                              int *nitems);
  67
  68 /* The tng_compress_pos_find_algo works the same as tng_compress_pos, but
  69    it performs benchmarking to find the algorithms with the best
  70    compression ratio.
  71    The search is controlled by giving speed:
  72    speed=1:  Fast algorithms only. This excludes all BWLZH algorithms and
  73              the XTC3 algorithm.
  74    speed=2:  Same as 1 and also includes the XTC3 algorithm using base compression
  75              only.
  76    speed=3:  Same as 2 and also includes the XTC3 algorithm which will use BWLZH
  77              compression when it seems likely to give better
  78              compression. Also includes the interframe BWLZH algorithm for
  79              coordinates and velocities.
  80    speed=4:  Enable the inter frame BWLZH algorithm for the coordinates.
  81              The one-to-one BWLZH algorithm is enabled for velocities.
  82    speed=5:  Enable the LZ77 part of the BWLZH algorithm.
  83    speed=6:  Enable the intra frame BWLZH algorithm for the coordinates. Always try
  84              the BWLZH compression in the XTC3 algorithm.
  85
  86    Set speed=0 to allow tng_compression to set the default speed (which is currently 2).
  87    For very good compression it makes sense to choose speed=4 or speed=5
  88
  89    The number of items required in the algorithm array can be found
  90    by calling tng_compress_nalgo
  91 */
  92
  93 char DECLSPECDLLEXPORT *tng_compress_pos_find_algo(double *pos, const int natoms, const int nframes,
  94                                                    const double desired_precision,
  95                                                    const int speed,
  96                                                    int *algo,
  97                                                    int *nitems);
  98
  99 char DECLSPECDLLEXPORT *tng_compress_pos_float_find_algo(float *pos, const int natoms, const int nframes,
 100                                                          const float desired_precision,
 101                                                          const int speed,
 102                                                          int *algo,
 103                                                          int *nitems);
 104
 105 char DECLSPECDLLEXPORT *tng_compress_pos_int_find_algo(int *pos, const int natoms, const int nframes,
 106                                                        const unsigned long prec_hi, const unsigned long prec_lo,
 107                                                        const int speed, int *algo,
 108                                                        int *nitems);
 109
 110 /* This returns the number of integers required for the storage of the algorithm
 111    with the best compression ratio. */
 112 int DECLSPECDLLEXPORT tng_compress_nalgo(void);
 113
 114 /* The following two routines does the same as the compression of the
 115    positions, but compresses velocities instead. The algorithm
 116    selection for velocities is different, so the position and
 117    velocities routines should not be mixed. */
 118
 119 char DECLSPECDLLEXPORT *tng_compress_vel(double *vel, const int natoms, const int nframes,
 120                                          const double desired_precision,
 121                                          const int speed, int *algo,
 122                                          int *nitems);
 123
 124 char DECLSPECDLLEXPORT *tng_compress_vel_float(float *vel, const int natoms, const int nframes,
 125                                                const float desired_precision,
 126                                                const int speed, int *algo,
 127                                                int *nitems);
 128
 129 char DECLSPECDLLEXPORT *tng_compress_vel_int(int *vel, const int natoms, const int nframes,
 130                                              const unsigned long prec_hi, const unsigned long prec_lo,
 131                                              int speed, int *algo,
 132                                              int *nitems);
 133
 134 char DECLSPECDLLEXPORT *tng_compress_vel_find_algo(double *vel, const int natoms, const int nframes,
 135                                                    const double desired_precision,
 136                                                    const int speed,
 137                                                    int *algo,
 138                                                    int *nitems);
 139
 140 char DECLSPECDLLEXPORT *tng_compress_vel_float_find_algo(float *vel, const int natoms, const int nframes,
 141                                                          const float desired_precision,
 142                                                          const int speed,
 143                                                          int *algo,
 144                                                          int *nitems);
 145
 146 char DECLSPECDLLEXPORT *tng_compress_vel_int_find_algo(int *vel, const int natoms, const int nframes,
 147                                                        const unsigned long prec_hi, const unsigned long prec_lo,
 148                                                        const int speed,
 149                                                        int *algo,
 150                                                        int *nitems);
 151
 152 /* From a compressed block, obtain information about
 153    whether it is a position or velocity block:
 154    *vel=1 means velocity block, *vel=0 means position block.
 155    It also gives info about the number of atoms,
 156    frames, and the precision used to compress the block, and the algorithms used to
 157    compress the block. The return value=0 if the block looks like a tng compressed block,
 158    and 1 otherwise. If the return value is 1 no information is returned. */
 159 int DECLSPECDLLEXPORT tng_compress_inquire(char *data,int *vel, int *natoms,
 160                                            int *nframes, double *precision,
 161                                            int *algo);
 162
 163 /* Uncompresses any tng compress block, positions or velocities. It determines whether it is positions or velocities from the data buffer. The return value is 0 if ok, and 1 if not.
 164 */
 165 int DECLSPECDLLEXPORT tng_compress_uncompress(char *data,double *posvel);
 166
 167 int DECLSPECDLLEXPORT tng_compress_uncompress_float(char *data,float *posvel);
 168
 169 int DECLSPECDLLEXPORT tng_compress_uncompress_int(char *data,int *posvel, unsigned long *prec_hi, unsigned long *prec_lo);
 170
 171 /* This converts a block of integers, as obtained from tng_compress_uncompress_int, to floating point values
 172    either double precision or single precision. */
 173 void DECLSPECDLLEXPORT tng_compress_int_to_double(int *posvel_int, const unsigned long prec_hi, const unsigned long prec_lo,
 174                                                   const int natoms, const int nframes,
 175                                                   double *posvel_double);
 176
 177 void DECLSPECDLLEXPORT tng_compress_int_to_float(int *posvel_int, const unsigned long prec_hi, const unsigned long prec_lo,
 178                                                  const int natoms, const int nframes,
 179                                                  float *posvel_float);
 180
 181
 182 /* Compression algorithms (matching the original trajng
 183    assignments) The compression backends require that some of the
 184    algorithms must have the same value. */
 185
 186 #define TNG_COMPRESS_ALGO_STOPBIT 1
 187 #define TNG_COMPRESS_ALGO_TRIPLET 2
 188 #define TNG_COMPRESS_ALGO_BWLZH1  8
 189 #define TNG_COMPRESS_ALGO_BWLZH2  9
 190
 191 #define TNG_COMPRESS_ALGO_POS_STOPBIT_INTER     TNG_COMPRESS_ALGO_STOPBIT
 192 #define TNG_COMPRESS_ALGO_POS_TRIPLET_INTER     TNG_COMPRESS_ALGO_TRIPLET
 193 #define TNG_COMPRESS_ALGO_POS_TRIPLET_INTRA     3
 194 #define TNG_COMPRESS_ALGO_POS_XTC2              5
 195 #define TNG_COMPRESS_ALGO_POS_TRIPLET_ONETOONE  7
 196 #define TNG_COMPRESS_ALGO_POS_BWLZH_INTER       TNG_COMPRESS_ALGO_BWLZH1
 197 #define TNG_COMPRESS_ALGO_POS_BWLZH_INTRA       TNG_COMPRESS_ALGO_BWLZH2
 198 #define TNG_COMPRESS_ALGO_POS_XTC3              10
 199 #define TNG_COMPRESS_ALGO_VEL_STOPBIT_ONETOONE  TNG_COMPRESS_ALGO_STOPBIT
 200 #define TNG_COMPRESS_ALGO_VEL_TRIPLET_INTER     TNG_COMPRESS_ALGO_TRIPLET
 201 #define TNG_COMPRESS_ALGO_VEL_TRIPLET_ONETOONE  3
 202 #define TNG_COMPRESS_ALGO_VEL_STOPBIT_INTER     6
 203 #define TNG_COMPRESS_ALGO_VEL_BWLZH_INTER       TNG_COMPRESS_ALGO_BWLZH1
 204 #define TNG_COMPRESS_ALGO_VEL_BWLZH_ONETOONE    TNG_COMPRESS_ALGO_BWLZH2
 205 #define TNG_COMPRESS_ALGO_MAX 11
 206
 207
 208
 209 /* Obtain strings describing the actual algorithms. These point to static memory, so should
 210    not be freed. */
 211 char DECLSPECDLLEXPORT *tng_compress_initial_pos_algo(int *algo);
 212 char DECLSPECDLLEXPORT *tng_compress_pos_algo(int *algo);
 213 char DECLSPECDLLEXPORT *tng_compress_initial_vel_algo(int *algo);
 214 char DECLSPECDLLEXPORT *tng_compress_vel_algo(int *algo);
 215
 216
 217
 218 #ifdef __cplusplus
 219  }
 220 #endif
 221
 222
 223 #endif