ls1-MarDyn
ls1-MarDyn molecular dynamics code
|
This wrapper provides some convenience when you want to use some sort of compression somewhere in the project. The syntax is simple and LZ4 is already included as one compression algorithm.
To use the functionality, turn on the option ENABLE_COMPRESSION
in the CMake options. New options to turn on individual encoding algorithms will be available.
LZ4 is used by default when the wrapper was enabled.
In the code, instantiate a Compression
object, passing the requested compression algorithm as a std::string tag (see tags below), which will offer the necessary functionality. Consider the following snippet:
#include <iostream> // for std::cout #include <memory> // for std::unique_ptr #include "compression.h" // compression stuff std::vector<char> data; //your data std::vector<char> compressed; //object to store the compressed result std::vector<char> decompressed; //object to store the decompressed result std::unique_ptr<Compression> compression_instance; try { compression_instance = Compression::create("LZ4"); } catch (std::invalid_argument ia) { std::cout << ia.what() << std::endl; } compression_instance.compress(data.begin(), data.end(), compressed); //run compression algorithm
The encoded data is now stored in compressed
. The first size_t bytes (actually decltype(_uncompressedSize), see Compression class) contain the uncompressed size.
If the instance creation fails, create() will throw a std::invalid_argument (strong guarantee). The string in the error message is the string the factory received to select an encoding, which should be one of the tags in tags. If the compression fails, compress() will throw a std::exception. The error code from the message can be looked up in the errors of the documentation matching the encoding, i.e. it will show the error code returned by the library function. E.g. for lz4, you would need to go the lz4 github page and read the appropriate docs.
Decompression works similarly:
compression_instance.decompress(compressed.begin(), compressed.end(), decompressed);
Decompressed now contains exactly the same values as data
.
The decompression will throw on failure. The error code provided is again library specific. The compress and decompress methods for "LZ4" and "None" tags provide strong guarantee.
If you are having issues with any library, try using "None" as encoding tag. This will only do a copy, and therefore is less error prone.
Tag | Algorithm |
---|---|
None | No compression |
LZ4 | lz4 lz4.github.io/lz4/ |