Merge pull request #228 from ComputationalRadiationPhysics/dev

Release: 1.3.1

Author: f-schmitt-zih

.travis.yml

@@ -44,7 +44,8 @@ before_script:
   - ls -hal /usr/include
 # PPA providing hdf5 >= 1.8.6 and OpenMPI >= 1.5.1
 # -> remove legacy hdf5 and mpi packages/deps from travis
-  - sudo apt-get remove -qq libhdf5* libopenmpi* openmpi-bin
+  - sudo apt-get remove -qq libhdf5*
+  - sudo apt-get remove -qq libopenmpi* openmpi-bin || { echo "OpenMPI not installed"; }
   - echo "yes" | sudo add-apt-repository ppa:james-page/openmpi
   - echo "yes" | sudo add-apt-repository ppa:axel-huebl/libsplash
   - sudo apt-get update -qq

CHANGELOG.md

@@ -1,6 +1,31 @@
 Change Log for libSplash
 ================================================================
 
+Release 1.3.1
+-------------
+**Date:** 2016-04-12
+
+This release contains bug fixes and serveral internal code
+clean-ups.
+
+**Bug Fixes**
+
+ - `readMeta` now returns the correct `CollectionType` if more then
+   one entry was used per iteration, detection for `ColTypeBool` was
+   broken #224
+ - exception parameters are now catched consequently by const
+   reference #213
+
+
+**Misc**
+
+ - remove tabs and EOL white spaces #216 #217 #218
+ - remove `_` prefixes from a few include guards #214
+ - add example for the `ParallelDataCollector` class #14
+ - remove beta notice for parallel HDF5 support #209
+ - update travis-ci script #212
+
+
 Release 1.3.0
 -------------
 **Date:** 2015-11-12

CMakeLists.txt

@@ -1,22 +1,22 @@
  #
  # Copyright 2013-2015 Felix Schmitt, Axel Huebl
  #
- # This file is part of libSplash. 
- # 
- # libSplash is free software: you can redistribute it and/or modify 
- # it under the terms of of either the GNU General Public License or 
- # the GNU Lesser General Public License as published by 
- # the Free Software Foundation, either version 3 of the License, or 
+ # This file is part of libSplash.
+ #
+ # libSplash is free software: you can redistribute it and/or modify
+ # it under the terms of of either the GNU General Public License or
+ # the GNU Lesser General Public License as published by
+ # the Free Software Foundation, either version 3 of the License, or
  # (at your option) any later version.
  #
- # libSplash is distributed in the hope that it will be useful, 
- # but WITHOUT ANY WARRANTY; without even the implied warranty of 
- # MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the 
- # GNU General Public License and the GNU Lesser General Public License 
- # for more details. 
- # 
- # You should have received a copy of the GNU General Public License 
- # and the GNU Lesser General Public License along with libSplash. 
+ # libSplash is distributed in the hope that it will be useful,
+ # but WITHOUT ANY WARRANTY; without even the implied warranty of
+ # MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+ # GNU General Public License and the GNU Lesser General Public License
+ # for more details.
+ #
+ # You should have received a copy of the GNU General Public License
+ # and the GNU Lesser General Public License along with libSplash.
  # If not, see <http://www.gnu.org/licenses/>.
 
 cmake_minimum_required(VERSION 2.8.5)
@@ -48,7 +48,7 @@ set(CMAKE_MODULE_PATH ${CMAKE_CURRENT_SOURCE_DIR}/cmake/ ${CMAKE_MODULE_PATH})
 IF(CMAKE_INSTALL_PREFIX_INITIALIZED_TO_DEFAULT)
     SET(CMAKE_INSTALL_PREFIX "${PROJECT_BINARY_DIR}" CACHE PATH "install prefix"
         FORCE)
-ENDIF(CMAKE_INSTALL_PREFIX_INITIALIZED_TO_DEFAULT) 
+ENDIF(CMAKE_INSTALL_PREFIX_INITIALIZED_TO_DEFAULT)
 
 #-------------------------------------------------------------------------------
 
@@ -113,7 +113,7 @@ SET(SPLASH_LIBS z ${HDF5_LIBRARIES})
 # serial or parallel version of libSplash
 SET(SPLASH_CLASSES logging DCAttribute DCDataSet DCGroup HandleMgr SerialDataCollector DomainCollector SDCHelper)
 IF(HDF5_IS_PARALLEL)
-    #parallel version 
+    #parallel version
     MESSAGE(STATUS "Parallel HDF5 found. Building parallel version")
 
     OPTION(COLLECTIVE_IO "use HDF5 collective IO" ON)
@@ -361,7 +361,7 @@ ELSE(HDF5_IS_PARALLEL)
   SET(CPACK_DEBIAN_PACKAGE_DEPENDS
       "libhdf5-serial-dev (>= 1.8.6)"
      )
-  IF(TOOLS_MPI)	
+  IF(TOOLS_MPI)
     SET(CPACK_DEBIAN_PACKAGE_DEPENDS
         "${CPACK_DEBIAN_PACKAGE_DEPENDS}, lib${MPI_FLAVOR}-dev (>= ${MPI_FLAVOR_MINVERSION})"
        )

INSTALL.md

@@ -100,6 +100,43 @@ endif(Splash_FOUND)
 # target_link_libraries(yourBinary ${LIBS})
 ```
 
+Examples
+--------
+
+To build the examples in the `examples` subdirectory, just run the following
+commands in an empty build directory:
+
+```bash
+cmake -DWITH_MPI=ON <yourPathTo>/libSplash/examples/
+make
+```
+
+`WITH_MPI` will enable/disable MPI based tests. Parallel libSplash examples
+will require a parallel HDF5 install.
+
+```bash
+# MPI based serial (posix) writer
+#   -> creates four h5_X_Y_Z.h5 files
+#      depending on MPI topology;
+#      iterations are appended in these files
+mpiexec -n 4 ./domain_write_mpi.cpp.out h5 2 2 1
+
+# MPI based serial (posix) reader
+#    -> reads h5_X_Y_Z.h5 files
+mpiexec -n 4 ./domain_read_mpi.cpp.out h5 2 2 1
+# serial (posix) reader
+#   -> reads h5_X_Y_Z.h5 files
+./domain_read.cpp.out h5
+
+# MPI based parallel (MPI-I/O) writer
+#   -> creates ph5_10.h5 (iteration = 10);
+#      each iteration creates a new file but
+#      MPI parallel chunks of the same iteration
+#      are aggregated to one file
+mpiexec -n 4 ./parallel_domain_write.cpp.out ph5 2 2 1
+```
+
+
 Tests
 -----
 
@@ -122,14 +159,16 @@ You can create your own version of the HTML documentation by running
 Parallel libSplash
 ------------------
 
-libSplash has **beta** support for parallel I/O.
+libSplash has support for parallel I/O creating a single, aggregated file per iteration.
 To build the parallel version, you need to build a parallel HDF5 library first.
 Commonly, it should be sufficient to configure HDF5 `$ configure --enable-shared --enable-parallel ...`.
 Running [cmake](#Compiling), libSplash will automatically detect the parallel HDF5
 capabilities and informs you with a status message
 `Parallel HDF5 found. Building parallel version`.
 
 This builds the *ParallelDataCollector* and *ParallelDomainCollector* classes.
-*Please note that this feature is beta stage and not fully tested!*
-See *IParallelDataCollector* and *IParallelDomainCollector* interfaces for further
-information on how to use the parallel version.
+See
+[IParallelDataCollector](https://computationalradiationphysics.github.io/libSplash/classsplash_1_1_i_parallel_data_collector.html)
+and
+[IParallelDomainCollector](https://computationalradiationphysics.github.io/libSplash/classsplash_1_1_i_parallel_domain_collector.html)
+interfaces for further information on how to use the parallel version.

examples/CMakeLists.txt

@@ -1,21 +1,21 @@
+ # Copyright 2013-2015 Felix Schmitt, Axel Huebl
  #
- # Copyright 2013 Felix Schmitt
+ # This file is part of libSplash.
  #
- # This file is part of libSplash. 
- # 
- # libSplash is free software: you can redistribute it and/or modify 
- # it under the terms of of either the GNU General Public License or 
- # the GNU Lesser General Public License as published by 
- # the Free Software Foundation, either version 3 of the License, or 
- # (at your option) any later version. 
- # libSplash is distributed in the hope that it will be useful, 
- # but WITHOUT ANY WARRANTY; without even the implied warranty of 
- # MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the 
- # GNU General Public License and the GNU Lesser General Public License 
- # for more details. 
- # 
- # You should have received a copy of the GNU General Public License 
- # and the GNU Lesser General Public License along with libSplash. 
+ # libSplash is free software: you can redistribute it and/or modify
+ # it under the terms of of either the GNU General Public License or
+ # the GNU Lesser General Public License as published by
+ # the Free Software Foundation, either version 3 of the License, or
+ # (at your option) any later version.
+ #
+ # libSplash is distributed in the hope that it will be useful,
+ # but WITHOUT ANY WARRANTY; without even the implied warranty of
+ # MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+ # GNU General Public License and the GNU Lesser General Public License
+ # for more details.
+ #
+ # You should have received a copy of the GNU General Public License
+ # and the GNU Lesser General Public License along with libSplash.
  # If not, see <http://www.gnu.org/licenses/>.
 
 cmake_minimum_required(VERSION 2.8.5)
@@ -40,6 +40,7 @@ OPTION(WITH_MPI "build MPI examples" OFF)
 
 SET(EXAMPLES domain_read/domain_read)
 SET(MPI_EXAMPLES domain_read/domain_read_mpi domain_write/domain_write_mpi)
+SET(PARALLEL_EXAMPLES parallel_domain_write/parallel_domain_write)
 
 FOREACH(EXAMPLE_NAME ${EXAMPLES})
     SET(EXAMPLE_FILES "${EXAMPLE_FILES};${EXAMPLE_NAME}.cpp")
@@ -48,6 +49,9 @@ ENDFOREACH()
 FOREACH(EXAMPLE_NAME ${MPI_EXAMPLES})
     SET(MPI_EXAMPLE_FILES "${MPI_EXAMPLE_FILES};${EXAMPLE_NAME}.cpp")
 ENDFOREACH()
+FOREACH(PARALLEL_EXAMPLE_NAME ${PARALLEL_EXAMPLES})
+    SET(PARALLEL_EXAMPLE_FILES "${PARALLEL_EXAMPLE_FILES};${PARALLEL_EXAMPLE_NAME}.cpp")
+ENDFOREACH()
 
 #-------------------------------------------------------------------------------
 
@@ -66,8 +70,8 @@ INCLUDE_DIRECTORIES("${SPLASH_ROOT_DIR}/include")
 
 # link static
 ADD_LIBRARY(splash_static STATIC IMPORTED)
-SET_TARGET_PROPERTIES(splash_static PROPERTIES 
-	IMPORTED_LOCATION "${SPLASH_ROOT_DIR}/lib/libsplash.a")
+SET_TARGET_PROPERTIES(splash_static PROPERTIES
+    IMPORTED_LOCATION "${SPLASH_ROOT_DIR}/lib/libsplash.a")
 SET(LIBS splash_static ${LIBS})
 
 # link dynamic
@@ -102,6 +106,10 @@ ENDFOREACH()
 
 # build all MPI examples
 IF(WITH_MPI)
+    # add parallel examples
+    IF(HDF5_IS_PARALLEL)
+        SET(MPI_EXAMPLE_FILES ${MPI_EXAMPLE_FILES} ${PARALLEL_EXAMPLE_FILES})
+    ENDIF(HDF5_IS_PARALLEL)
     MESSAGE(STATUS "Building MPI examples")
     FOREACH(EXAMPLE_FILE ${MPI_EXAMPLE_FILES})
         GET_FILENAME_COMPONENT(FILE ${EXAMPLE_FILE} NAME)

examples/domain_read/domain_read.cpp

@@ -1,23 +1,23 @@
 /**
  * Copyright 2013 Felix Schmitt
  *
- * This file is part of libSplash. 
- * 
- * libSplash is free software: you can redistribute it and/or modify 
- * it under the terms of of either the GNU General Public License or 
- * the GNU Lesser General Public License as published by 
- * the Free Software Foundation, either version 3 of the License, or 
- * (at your option) any later version. 
+ * This file is part of libSplash.
  *
- * libSplash is distributed in the hope that it will be useful, 
- * but WITHOUT ANY WARRANTY; without even the implied warranty of 
- * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the 
- * GNU General Public License and the GNU Lesser General Public License 
- * for more details. 
- * 
- * You should have received a copy of the GNU General Public License 
- * and the GNU Lesser General Public License along with libSplash. 
- * If not, see <http://www.gnu.org/licenses/>. 
+ * libSplash is free software: you can redistribute it and/or modify
+ * it under the terms of of either the GNU General Public License or
+ * the GNU Lesser General Public License as published by
+ * the Free Software Foundation, either version 3 of the License, or
+ * (at your option) any later version.
+ *
+ * libSplash is distributed in the hope that it will be useful,
+ * but WITHOUT ANY WARRANTY; without even the implied warranty of
+ * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+ * GNU General Public License and the GNU Lesser General Public License
+ * for more details.
+ *
+ * You should have received a copy of the GNU General Public License
+ * and the GNU Lesser General Public License along with libSplash.
+ * If not, see <http://www.gnu.org/licenses/>.
  */
 
 #include <iostream>
@@ -30,7 +30,7 @@ using namespace splash;
  * This libSplash example demonstrates on how to use the DomainCollector class
  * to read multiple, domain-annotated libSplash files transparently as a single
  * file.
- * 
+ *
  * The program expects the base part to a distributed libSplash file, i.e.
  * 'my_data', given that you have files like 'my_data_0_0_0.h5', ...
  */
@@ -113,7 +113,7 @@ int main(int argc, char **argv)
         Dimensions size = subdomain->getSize();
 
         std::cout << "subdomain " << d << " has size " << size.toString() << std::endl;
-        
+
         // access the underlying buffer of a subdomain
         void *elements = subdomain->getData();
     }

examples/domain_read/domain_read_mpi.cpp

@@ -1,23 +1,23 @@
 /**
  * Copyright 2013 Felix Schmitt
  *
- * This file is part of libSplash. 
- * 
- * libSplash is free software: you can redistribute it and/or modify 
- * it under the terms of of either the GNU General Public License or 
- * the GNU Lesser General Public License as published by 
- * the Free Software Foundation, either version 3 of the License, or 
- * (at your option) any later version. 
+ * This file is part of libSplash.
  *
- * libSplash is distributed in the hope that it will be useful, 
- * but WITHOUT ANY WARRANTY; without even the implied warranty of 
- * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the 
- * GNU General Public License and the GNU Lesser General Public License 
- * for more details. 
- * 
- * You should have received a copy of the GNU General Public License 
- * and the GNU Lesser General Public License along with libSplash. 
- * If not, see <http://www.gnu.org/licenses/>. 
+ * libSplash is free software: you can redistribute it and/or modify
+ * it under the terms of of either the GNU General Public License or
+ * the GNU Lesser General Public License as published by
+ * the Free Software Foundation, either version 3 of the License, or
+ * (at your option) any later version.
+ *
+ * libSplash is distributed in the hope that it will be useful,
+ * but WITHOUT ANY WARRANTY; without even the implied warranty of
+ * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+ * GNU General Public License and the GNU Lesser General Public License
+ * for more details.
+ *
+ * You should have received a copy of the GNU General Public License
+ * and the GNU Lesser General Public License along with libSplash.
+ * If not, see <http://www.gnu.org/licenses/>.
  */
 
 #include <mpi.h>
@@ -35,7 +35,7 @@ using namespace splash;
 /**
  * This libSplash example demonstrates on how to use the DomainCollector class
  * to read multiple, domain-annotated libSplash files using N MPI processes.
- * 
+ *
  * The program expects the base part to a distributed libSplash file, i.e.
  * 'my_data', given that you have files like 'my_data_0_0_0.h5', ...
  */
@@ -185,7 +185,7 @@ int main(int argc, char **argv)
 
             std::cout << "  " << mpi_rank << ": subdomain " << d << " has size " <<
                     size.toString() << std::endl;
-            
+
             // access the underlying buffer of a subdomain
             void *elements = subdomain->getData();
         }