libpressio version 0.57.0

Major Changes:

+ BREAKING CHANGE - removed the ftk plugin in favor of using it from the
  external metrics plugin.  This change reduces complexity and code
  duplication between this library and the ftk command line application
  this also prevents the frequent internals changes in FTK from breaking
  libpressio's build. closes #12
+ libpressio now has JSON support with the following features:
  + pressio_options structures can be serialized to and from JSON.  NOTE
    when serializing options that use  pressio_option_userptr_type are
    omitted because by definition they cannot be serialized.
  + external metrics can now read a JSON based format when using the
    `external:api=json:1` version.  This allows returning complex
    datatypes from metrics.
  + an experimental hdf5_filter which provides another way to use
    compressors supported with libpressio. The JSON support is used in
    serializing options where relevant.

Minor Changes:

+ Moved the python bindings to `tools/swig`
+ Added the ability to not produce man page links and install docs when
  documentation is built
+ renamed the imagemagick check to be imagemagick_longlong to more clear
  about what it was testing for.

Bug Fixes:

+ Added missing headers to CMakeLists to improve clangd and clion
  autocompetion.
+ Fixed all current documentation warnings and compiler warnings

CMakeLists.txt

@@ -1,5 +1,5 @@
 cmake_minimum_required(VERSION 3.13 FATAL_ERROR)
-project(libpressio VERSION "0.56.2" LANGUAGES CXX C)
+project(libpressio VERSION "0.57.0" LANGUAGES CXX C)
 
 #correct was to set a default build type
 # https://blog.kitware.com/cmake-and-the-default-build-type/
@@ -77,18 +77,18 @@ add_library(libpressio
 
   #public headers
   include/libpressio.h
-  include/libpressio_ext/cpp/configurable.h
-  include/libpressio_ext/cpp/versionable.h
-  include/libpressio_ext/cpp/errorable.h
   include/libpressio_ext/cpp/compressor.h
+  include/libpressio_ext/cpp/configurable.h
   include/libpressio_ext/cpp/data.h
+  include/libpressio_ext/cpp/errorable.h
+  include/libpressio_ext/cpp/io.h
   include/libpressio_ext/cpp/libpressio.h
   include/libpressio_ext/cpp/metrics.h
   include/libpressio_ext/cpp/options.h
   include/libpressio_ext/cpp/pressio.h
   include/libpressio_ext/cpp/printers.h
   include/libpressio_ext/cpp/subgroup_manager.h
-  include/libpressio_ext/cpp/io.h
+  include/libpressio_ext/cpp/versionable.h
   include/libpressio_ext/io/posix.h
   include/libpressio_ext/io/pressio_io.h
   include/pressio.h
@@ -241,7 +241,7 @@ if(LIBPRESSIO_HAS_MAGICK)
   try_compile(
     LIBPRESSIO_COMPAT_HAS_IMAGEMAGICK_LONGLONG
     ${CMAKE_BINARY_DIR}
-    SOURCES "${CMAKE_SOURCE_DIR}/checks/imagemagick.cc"
+    SOURCES "${CMAKE_SOURCE_DIR}/checks/imagemagick_longlong.cc"
     LINK_LIBRARIES PkgConfig::Magick++
   )
   message(STATUS "Checking for Magick::LongLong: ${LIBPRESSIO_COMPAT_HAS_IMAGEMAGICK_LONGLONG}")
@@ -291,17 +291,6 @@ if(LIBPRESSIO_HAS_MPI)
   target_link_libraries(libpressio PRIVATE MPI::MPI_CXX)
 endif()
 
-option(LIBPRESSIO_HAS_FTK "build the FTK metrics modules" OFF)
-if(LIBPRESSIO_HAS_FTK)
-  find_package(FTK)
-  target_sources(
-    libpressio
-    PRIVATE
-    ${CMAKE_CURRENT_SOURCE_DIR}/src/plugins/metrics/ftk_critical_points.cc
-    )
-  target_include_directories(libpressio PRIVATE ${FTK_INCLUDE_DIRS})
-endif()
-
 
 option(LIBPRESSIO_HAS_PETSC "build the petsc io plugin" OFF)
 if(LIBPRESSIO_HAS_PETSC)
@@ -342,10 +331,25 @@ if(LIBPRESSIO_HAS_LIBDISTRIBUTED)
     ${CMAKE_CURRENT_SOURCE_DIR}/src/serializable.cc
     ${CMAKE_CURRENT_SOURCE_DIR}/src/pressio_distributed_manager.cc
     ${CMAKE_CURRENT_SOURCE_DIR}/include/libpressio_ext/cpp/distributed_manager.h
+    ${CMAKE_CURRENT_SOURCE_DIR}/include/libpressio_ext/cpp/serializable.h
 
     )
 endif()
 
+option(LIBPRESSIO_HAS_JSON "build the options json serialization support" OFF)
+if(LIBPRESSIO_HAS_JSON)
+  set(LIBPRESSIO_FEATURES "${LIBPRESSIO_FEATURES} json")
+  find_package(nlohmann_json REQUIRED)
+  target_link_libraries(libpressio PRIVATE nlohmann_json::nlohmann_json)
+  target_sources(libpressio
+    PRIVATE
+    ${CMAKE_CURRENT_SOURCE_DIR}/src/pressio_options_json.cc
+    ${CMAKE_CURRENT_SOURCE_DIR}/include/libpressio_ext/json/pressio_options_json.h
+    ${CMAKE_CURRENT_SOURCE_DIR}/include/libpressio_ext/cpp/json.h
+    )
+
+endif()
+
 option(LIBPRESSIO_HAS_REMOTELAUNCH "build the remote external launch plugin" OFF)
 if(LIBPRESSIO_HAS_REMOTELAUNCH)
   set(LIBPRESSIO_FEATURES "${LIBPRESSIO_FEATURES} remotelaunch")
@@ -368,6 +372,10 @@ configure_file(
   ${CMAKE_CURRENT_BINARY_DIR}/libpressio.pc
   @ONLY
   )
+target_sources(libpressio
+  PRIVATE
+  ${CMAKE_CURRENT_BINARY_DIR}/include/pressio_version.h
+)
 
 option(USE_CLANG_TIDY "include clang-tidy warnings in the build log" OFF)
 if(USE_CLANG_TIDY)
@@ -401,13 +409,22 @@ endif()
 
 option(BUILD_PYTHON_WRAPPER "build python wrapper" OFF)
 if(BUILD_PYTHON_WRAPPER)
-  add_subdirectory(swig)
+  add_subdirectory(tools/swig)
+endif()
+
+if(LIBPRESSIO_HAS_JSON AND LIBPRESSIO_HAS_HDF)
+  add_subdirectory(tools/hdf5_filter)
 endif()
 
 option(BUILD_DOCS "build the documetation" OFF)
 if(BUILD_DOCS)
+  option(BUILD_DOCS_LINKS "build the documetation" ON)
   find_package(Doxygen REQUIRED dot)
-  set(DOXYGEN_MAN_LINKS YES)
+  if(BUILD_DOCS_LINKS)
+    set(DOXYGEN_MAN_LINKS YES)
+  else()
+    set(DOXYGEN_MAN_LINKS NO)
+  endif()
   set(DOXYGEN_GENERATE_MAN YES)
   set(DOXYGEN_GENERATE_HTML YES)
   set(DOXYGEN_EXTRACT_LOCAL_METHODS YES)

include/libpressio_ext/cpp/compressor.h

@@ -117,10 +117,8 @@ class libpressio_compressor_plugin :public pressio_configurable, public pressio_
    */
   int compress(struct pressio_data const*input, struct pressio_data* output);
   /** decompress a pressio_data buffer
-   * \param[in] in_begin iterator to the beginning of the inputs
-   * \param[in] in_end iterator to the end of the inputs
-   * \param[in,out] out_begin iterator to the beginning of the outputs
-   * \param[in,out] out_end iterator to the end of the outputs
+   * \param[in] input input buffer to compress
+   * \param[in,out] output buffer to decompress
    * \see pressio_compressor_decompress for the semantics this function should obey
    */
   int decompress(struct pressio_data const*input, struct pressio_data* output);

include/libpressio_ext/cpp/configurable.h

@@ -237,10 +237,15 @@ class pressio_configurable {
 
 
   protected:
+  /**
+   * \returns the string the metrics key name
+   * \internal
+   */
   std::string get_metrics_key_name() const {
     return std::string(prefix()) + ":metric";
   }
 
+  /** the name of the configurable used in nested hierarchies*/
   std::string name;
 };
 

include/libpressio_ext/cpp/data.h

@@ -31,6 +31,7 @@ namespace {
   size_t data_size_in_bytes(pressio_dtype type, T const dimensions, T const dims[]) {
     return data_size_in_elements(dimensions, dims) * pressio_dtype_size(type);
   }
+
 }
 
 /**
@@ -477,6 +478,10 @@ struct pressio_data {
    */
   pressio_data transpose(std::vector<size_t> const& axis = {}) const;
 
+  /** 
+   * \param[in] rhs the object to compare against
+   * \returns true if the options are equal */
+  bool operator==(pressio_data const& rhs) const;
 
   private:
   /**

include/libpressio_ext/cpp/distributed_manager.h

@@ -22,14 +22,27 @@
  * build an array of workers, tries to be fault tolerant in degenerate cases
  */
 compat::optional<std::vector<size_t>> distributed_build_groups(const unsigned int size, const unsigned int n_workers_groups, const unsigned int n_masters, const unsigned int root);
+
+/**
+ * \returns the size of MPI_COMM_WORLD
+ */
 int distributed_world_size();
 
 /**
  * helper class for interacting with libdistributed
  */
 class pressio_distributed_manager: public pressio_configurable, public pressio_errorable {
   public:
+  /**
+   * a variable used to indicate there is no bound applied
+   */
   static size_t unlimited;
+  /**
+   * constructs a distributed_manager
+   *
+   * \param[in] max_ranks_per_worker the maximum numbers of workers to use
+   * \param[in] max_masters the maximum number master processes to use
+   */
   pressio_distributed_manager(unsigned int max_ranks_per_worker = 1, unsigned int max_masters = 1):
     groups(*distributed_build_groups(distributed_world_size(), 0, 0, 0)),
     max_masters(max_masters),
@@ -38,6 +51,13 @@ class pressio_distributed_manager: public pressio_configurable, public pressio_e
     n_masters(0)
   {}
 
+  /**
+   * create a work_queue from the provided configuration
+   * \param[in] begin the first task in the queue
+   * \param[in] end the last task in the queue
+   * \param[in] workerfn the function worker tasks should execute
+   * \param[in] masterfn the function master tasks should execute
+   */
   template <class TaskRandomIt, class MasterFn, class WorkerFn>
   void work_queue(TaskRandomIt begin, TaskRandomIt end, WorkerFn&& workerfn, MasterFn&& masterfn) {
     distributed::queue::work_queue_options<typename distributed::queue::iterator_to_request_type<TaskRandomIt>::type> options(comm);
@@ -46,38 +66,76 @@ class pressio_distributed_manager: public pressio_configurable, public pressio_e
     distributed::queue::work_queue( options, begin, end, std::forward<WorkerFn>(workerfn), std::forward<MasterFn>(masterfn));
   }
 
+  /**
+   * helper function for send
+   * \param[in] t the value to send
+   * \param[in] dest the destination 
+   * \param[in] tag the tag to use
+   * \returns an error code
+   */
   template <class T>
   int send(T const& t, int dest, int tag=0) {
     return distributed::comm::send(t, dest, tag, comm);
   }
 
+
+  /**
+   * helper function for recv
+   * \param[out] t the value to recv
+   * \param[in] source the source 
+   * \param[in] tag the tag to use
+   * \param[out] s the optional status value to use
+   * \returns an error code
+   */
   template <class T>
   int recv(T& t, int source, int tag=0, MPI_Status* s=nullptr) {
     return distributed::comm::recv(t, source, tag, comm, s);
   }
 
+
+  /**
+   * helper function for recv
+   * \param[in,out] t the value to bcast
+   * \param[in] bcast_root the destination 
+   * \returns an error code
+   */
   template <class T>
   int bcast(T& t, int bcast_root) {
     return distributed::comm::bcast(t, bcast_root, comm);
   }
 
+  /**
+   * helper function for recv
+   * \param[in,out] t the value to bcast
+   * \returns an error code
+   */
   template <class T>
   int bcast(T& t) {
     return distributed::comm::bcast(t, root, comm);
   }
 
+  /**
+   * \returns the size of the managed communicator
+   */
   int comm_size() const {
     int size;
     MPI_Comm_size(comm, &size);
     return size;
   }
 
+  /**
+   * \returns the rank of the managed communicator
+   */
   int comm_rank() const {
     int rank;
     MPI_Comm_rank(comm, &rank);
     return rank;
   }
 
+  /**
+   * provides options for the manager for the user to configure
+   * \returns the options
+   */
   struct pressio_options 	get_options () const override {
     pressio_options opts;
     set(opts, "distributed:mpi_comm", (void*)comm);
@@ -92,6 +150,10 @@ class pressio_distributed_manager: public pressio_configurable, public pressio_e
     }
     return opts;
   }
+  /**
+   * sets options for the manager for the user to configure
+   * \returns an error code
+   */
   virtual int	set_options (struct pressio_options const &options) override {
     get(options, "distributed:root", &root);
     get(options, "distributed:mpi_comm", (void**)&comm);
@@ -129,6 +191,9 @@ class pressio_distributed_manager: public pressio_configurable, public pressio_e
     return 0;
   }
 
+  /**
+   * the prefix "distributed" used in introspection
+   */
   const char* prefix() const override { return "distributed"; }
 
   private:

include/libpressio_ext/cpp/io.h

@@ -139,15 +139,17 @@ struct libpressio_io_plugin: public pressio_configurable, public pressio_version
    * \param[in] data data object to populate, or nullptr to allocate it from the file if supported
    * \see pressio_io_read for the semantics this function should obey
    */
-  virtual int read_many_impl(compat::span<struct pressio_data*> const&) { 
+  virtual int read_many_impl(compat::span<struct pressio_data*> const& data) { 
+    (void)data;
     return set_error(1, "read many not supported");
   }
 
   /** writes multiple pressio_data buffers to some persistent storage
    * \param[in] data data to write
    * \see pressio_io_write for the semantics this function should obey
    */
-  virtual int write_many_impl(compat::span<struct pressio_data const*> const&) {
+  virtual int write_many_impl(compat::span<struct pressio_data const*> const& data) {
+    (void)data;
     return set_error(1, "write many not supported");
   }
 

include/libpressio_ext/cpp/json.h

@@ -0,0 +1,11 @@
+#include <nlohmann/json_fwd.hpp>
+class pressio_data;
+class pressio_option;
+class pressio_options;
+
+void to_json(nlohmann::json& j, pressio_data const& data);
+void to_json(nlohmann::json& j, pressio_option const& option);
+void to_json(nlohmann::json& j, pressio_options const& options);
+void from_json(nlohmann::json const& j, pressio_data& data);
+void from_json(nlohmann::json const& j, pressio_option& option);
+void from_json(nlohmann::json const& j, pressio_options& options);

include/libpressio_ext/cpp/metrics.h

@@ -141,6 +141,7 @@ struct pressio_metrics {
 
   /** construct a metrics wrapper*/
   pressio_metrics(std::unique_ptr<libpressio_metrics_plugin>&& metrics): plugin(std::move(metrics)) {}
+  /** construct a metrics wrapper*/
   pressio_metrics(std::shared_ptr<libpressio_metrics_plugin>&& metrics): plugin(std::move(metrics)) {}
 
   /** allow default construction*/

include/libpressio_ext/cpp/options.h

@@ -265,6 +265,13 @@ struct pressio_option final {
     }
   }
 
+  /** 
+   * \param[in] rhs the object to compare against
+   * \returns true if the options are equal */
+  bool operator==(pressio_option const& rhs) const {
+    return option == rhs.option;
+  }
+
   /**
    * converts rhs according the conversion safety specified to the type of the option and stores the result if the cast succeeds
    * \param[in] rhs the option to assign to this option
@@ -596,6 +603,10 @@ struct pressio_options final {
     options.clear();
   }
 
+  /**
+   * copies all of the options from o
+   * \param[in] o the options to copy from
+   */
   void copy_from(pressio_options const& o) {
     insert(o.begin(), o.end());
   }
@@ -631,6 +642,12 @@ struct pressio_options final {
     return options.insert(it, value);
   }
 
+  /**
+   * insert a collection of iterator
+   *
+   * \param[in] begin the iterator to the beginning
+   * \param[in] end the iterator to the end
+   */
   template <class InputIt>
   void insert(InputIt begin, InputIt end){
     options.insert(begin, end);
@@ -696,6 +713,13 @@ struct pressio_options final {
     return options.insert(value);
   }
 
+  /** 
+   * \param[in] rhs the object to compare against
+   * \returns true if the options are equal */
+  bool operator==(pressio_options const& rhs) const {
+    return options == rhs.options;
+  }
+
   /**\returns the number of set options*/
   size_t num_set() const {
     return std::count_if(std::begin(options), std::end(options), [](decltype(options)::value_type const& key_option){