libpressio version 0.8.0

Major Features:

- Experimental release of the python bindings. See the test cases for an
  example of usage.
- Approved for release from ANL legal department. Added license file.
- Exposed and documented `pressio_data` class interface in C++
- Breaking Change: previously compress and decompress accepted a pointer
  to a pointer, not it accepts a pointer to a data structure. This
  change was to facility the python bindings.  Propagated this change
  throughout the design.
- Breaking Change: previously the dimension interfaces were spelled
  incorrectly, this spelling change has been made across the code.
  Propagated this change throughout the design.

Minor Features:

- Documented stability guidelines
- Documented Option Name guidelines

Bug Fixes:

- Fixed Error in build instructions and examples in README
- Fixed spelling and capitalization issues.
- Fixed issues where libpressio was not properly prefixing its cmake
  export file.
- Fixed issues where headers would improperly depend on global headers
  rather than those in the repository.

CMakeLists.txt

@@ -1,5 +1,5 @@
 cmake_minimum_required(VERSION 3.14 FATAL_ERROR)
-project(libpressio VERSION "0.7.0" LANGUAGES CXX C)
+project(libpressio VERSION "0.8.0" LANGUAGES CXX C)
 
 enable_testing()
 set(CMAKE_EXPORT_COMPILE_COMMANDS ON)
@@ -10,6 +10,7 @@ find_package(ZFP REQUIRED)
 find_package(SZ REQUIRED)
 find_package(ZLIB REQUIRED)
 find_package(PkgConfig REQUIRED)
+find_package(Python COMPONENTS Interpreter Development NumPy)
 pkg_search_module(ZSTD IMPORTED_TARGET GLOBAL libzstd)
 
 
@@ -76,23 +77,28 @@ target_compile_options(libpressio PRIVATE $<$<CONFIG:Debug>: -Wall -Werror -Wext
 target_link_libraries(libpressio PUBLIC zfp::zfp SZ)
 target_compile_features(libpressio PUBLIC cxx_std_17)
 
+export(TARGETS libpressio NAMESPACE LibPressio:: FILE LibPressio.cmake)
 install(TARGETS libpressio EXPORT LibPressioConfig
   ARCHIVE DESTINATION ${CMAKE_INSTALL_LIBDIR}
   LIBRARY DESTINATION ${CMAKE_INSTALL_LIBDIR}
   RUNTIME DESTINATION ${CMAKE_INSTALL_BINDIR}
   )
-install(EXPORT LibPressioConfig DESTINATION share/LibPressio/cmake)
+install(EXPORT LibPressioConfig NAMESPACE LibPressio:: DESTINATION share/LibPressio/cmake)
 install(DIRECTORY include/ DESTINATION ${CMAKE_INSTALL_INCLUDEDIR}/libpressio)
 install(FILES ${CMAKE_CURRENT_BINARY_DIR}/include/pressio_version.h DESTINATION ${CMAKE_INSTALL_INCLUDEDIR}/libpressio)
 install(FILES ${CMAKE_CURRENT_BINARY_DIR}/libpressio.pc DESTINATION ${CMAKE_INSTALL_PREFIX}/share/pkgconfig)
-export(TARGETS libpressio FILE LibPressio.cmake)
 
 option(BUILD_TESTS "build the test cases and examples" OFF)
 
 if(BUILD_TESTS)
   add_subdirectory(test)
 endif()
 
+option(BUILD_PYTHON_WRAPPER "build python wrapper" OFF)
+if(BUILD_PYTHON_WRAPPER)
+  add_subdirectory(swig)
+endif()
+
 option(BUILD_DOCS "build the documetation" OFF)
 if(BUILD_DOCS)
   find_package(Doxygen REQUIRED dot)

COPYRIGHT.txt

@@ -0,0 +1,30 @@
+Copyright © 2019 , UChicago Argonne, LLC
+All Rights Reserved
+[libpressio, Version 0.8.0]
+Robert Underwood
+Argonne National Laboratory
+
+OPEN SOURCE LICENSE (license number: SF-19-112)
+
+Redistribution and use in source and binary forms, with or without modification, are permitted provided that the following conditions are met:
+
+1. Redistributions of source code must retain the above copyright notice, this list of conditions and the following disclaimer.  Software changes, modifications, or derivative works, should be noted with comments and the author and organization's name.
+
+2. Redistributions in binary form must reproduce the above copyright notice, this list of conditions and the following disclaimer in the documentation and/or other materials provided with the distribution.
+
+3. Neither the names of UChicago Argonne, LLC or the Department of Energy nor the names of its contributors may be used to endorse or promote products derived from this software without specific prior written permission.
+
+4. The software and the end-user documentation included with the redistribution, if any, must include the following acknowledgment:
+
+   "This product includes software produced by UChicago Argonne, LLC under Contract No. DE-AC02-06CH11357 with the Department of Energy."
+
+******************************************************************************************************
+DISCLAIMER
+
+THE SOFTWARE IS SUPPLIED "AS IS" WITHOUT WARRANTY OF ANY KIND.
+
+NEITHER THE UNITED STATES GOVERNMENT, NOR THE UNITED STATES DEPARTMENT OF ENERGY, NOR UCHICAGO ARGONNE, LLC, NOR ANY OF THEIR EMPLOYEES, MAKES ANY WARRANTY, EXPRESS OR IMPLIED, OR ASSUMES ANY LEGAL LIABILITY OR RESPONSIBILITY FOR THE ACCURACY, COMPLETENESS, OR USEFULNESS OF ANY INFORMATION, DATA, APPARATUS, PRODUCT, OR PROCESS DISCLOSED, OR REPRESENTS THAT ITS USE WOULD NOT INFRINGE PRIVATELY OWNED RIGHTS.
+
+***************************************************************************************************
+
+Contact: Sheng Di ([email protected]), Robert Underwood ([email protected])

README.md

@@ -1,17 +1,19 @@
-# Libpressio
+# LibPressio
 
-Pressio is latin for compression.  Libpressio is a C++ library with C compatible bindings to abstract between different lossless and lossy compressors and their configurations.  It solves the problem of having to having to write separate application level code for each lossy compressor that is developed.  Instead, users write application level code using libpressio, and the library will make the correct underlying calls to the compressors.  It provides interfaces to represent data, compressors settings, and compressors.
+*the upstream version of this code is found at [at the CODARCode organization](https://github.com/CODARcode/libpressio)*
 
+Pressio is latin for compression.  LibPressio is a C++ library with C compatible bindings to abstract between different lossless and lossy compressors and their configurations.  It solves the problem of having to having to write separate application level code for each lossy compressor that is developed.  Instead, users write application level code using LibPressio, and the library will make the correct underlying calls to the compressors.  It provides interfaces to represent data, compressors settings, and compressors.
 
-## Configuring Libpressio
 
-Libpressio uses cmake to configure build options.  See CMake documentation to see how to configure options
+## Configuring LibPressio
+
+LibPressio uses cmake to configure build options.  See CMake documentation to see how to configure options
 
 + `CMAKE_INSTALL_PREFIX` - install the library to a local directory prefix
 + `BUILD_DOCS` - build the project documentation
 + `BUILD_TESTS` - build the test cases
 
-## Building and Installing Libpressio
+## Building and Installing LibPressio
 
 To build and install the library only.
 
@@ -31,15 +33,37 @@ To build the documentation:
 BUILD_DIR=build
 mkdir $BUILD_DIR
 cd $BUILD_DIR
-cmake . -DBUILD_DOCS=ON
+cmake .. -DBUILD_DOCS=ON
 make docs
 # the html docs can be found in $BUILD_DIR/html/index.html
 # the man pages can be found in $BUILD_DIR/man/
 ```
 
-## Using Libpressio
+To build the experimental python bindings:
+
+```
+BUILD_DIR=build
+mkdir $BUILD_DIR
+cd $BUILD_DIR
+cmake .. -DBUILD_PYTHON_WRAPPER=ON
+make
+make install
+```
+
+To build the test cases
+
+```
+BUILD_DIR=build
+mkdir $BUILD_DIR
+cd $BUILD_DIR
+cmake .. -DBUILD_TESTS=ON
+make
+ctest .
+```
+
+## Using LibPressio
 
-Here is a minimal example with error checking of how to use libpressio:
+Here is a minimal example with error checking of how to use LibPressio:
 
 
 ~~~c
@@ -55,8 +79,8 @@ int main(int argc, char *argv[])
   struct pressio_compressor* compressor = pressio_get_compressor(library, "sz");
   struct pressio_options* sz_options = pressio_compressor_get_options(compressor);
 
-  pressio_options_set_integer(sz_options, "sz:mode", ABS);
-  pressio_options_set_double(sz_options, "sz:abs_error_bound", 0.5);
+  pressio_options_set_integer(sz_options, "sz:error_bound_mode", ABS);
+  pressio_options_set_double(sz_options, "sz:abs_err_bound", 0.5);
   if(pressio_compressor_check_options(compressor, sz_options)) {
     printf("%s\n", pressio_compressor_error_msg(compressor));
     exit(pressio_compressor_error_code(compressor));
@@ -78,13 +102,13 @@ int main(int argc, char *argv[])
   struct pressio_data* decompressed_data = pressio_data_new_empty(pressio_double_dtype, 3, dims);
 
   //compress the data
-  if(pressio_compressor_compress(compressor, input_data, &compressed_data)) {
+  if(pressio_compressor_compress(compressor, input_data, compressed_data)) {
     printf("%s\n", pressio_compressor_error_msg(compressor));
     exit(pressio_compressor_error_code(compressor));
   }
 
   //decompress the data
-  if(pressio_compressor_decompress(compressor, compressed_data, &decompressed_data)) {
+  if(pressio_compressor_decompress(compressor, compressed_data, decompressed_data)) {
     printf("%s\n", pressio_compressor_error_msg(compressor));
     exit(pressio_compressor_error_code(compressor));
   }
@@ -102,3 +126,32 @@ int main(int argc, char *argv[])
 ~~~
 
 More examples can be found in `test/`
+
+## Option Names
+
+LibPressio uses a key-value system to refer to configuration settings.
+
+Each compressor may find specific configuration settings for its specific compressor with settings beginning with its compressor id as prefix (i.e. configurations for SZ begin with `sz:`).  Refer to the specific compressors documentation for further documentation for each settings.
+
+The prefixes `metrics:` and `pressio:` are reserved for future use.
+
+## Stability
+
+As of version 1.0.0, LibPressio will follow the following API stability guidelines:
+
++ The functions defined in files in `./include` excluding files in the `./include/libpressio_ext/` or its subdirectories may be considered to be stable.  Furthermore, all files in this set are C compatible.
++ The functions defined in files in `./include/libpressio_ext/` are to be considered unstable.
++ The functions and modules defined in the python bindings are unstable.
+
+Stable means:
+
++ New APIs may be introduced with the increase of the minor version number.
++ APIs may gain additional overloads for C++ compatible interfaces with an increase in the minor version number.
++ An API may change the number or type of parameters with an increase in the major version number.
++ An API may be removed with the change of the major version number
+
+Unstable means:
+
++ The API may change for any reason with the increase of the minor version number
+
+Additionally, the performance of functions, memory usage patterns may change for both stable and unstable code with the increase of the patch version.

include/libpressio_ext/cpp/compressor.h

@@ -41,11 +41,11 @@ class libpressio_compressor_plugin {
   /** compresses a pressio_data buffer
    * \see pressio_compressor_compress for the semantics this function should obey
    */
-  int compress(struct pressio_data* input, struct pressio_data** output);
+  int compress(struct pressio_data* input, struct pressio_data* output);
   /** decompress a pressio_data buffer
    * \see pressio_compressor_decompress for the semantics this function should obey
    */
-  int decompress(struct pressio_data* input, struct pressio_data** output);
+  int decompress(struct pressio_data* input, struct pressio_data* output);
   /** get a version string for the compressor
    * \see pressio_compressor_version for the semantics this function should obey
    */
@@ -123,11 +123,11 @@ class libpressio_compressor_plugin {
   /** compresses a pressio_data buffer
    * \see pressio_compressor_compress for the semantics this function should obey
    */
-  virtual int compress_impl(struct pressio_data* input, struct pressio_data** output)=0;
+  virtual int compress_impl(struct pressio_data* input, struct pressio_data* output)=0;
   /** decompress a pressio_data buffer
    * \see pressio_compressor_decompress for the semantics this function should obey
    */
-  virtual int decompress_impl(struct pressio_data* input, struct pressio_data** output)=0;
+  virtual int decompress_impl(struct pressio_data* input, struct pressio_data* output)=0;
 
   /** checks for extra arguments set for the compressor.
    * Unlike other functions, this option is NOT required