Damaris plugin

CMakeLists.txt

@@ -77,7 +77,7 @@ option(BUILD_TRACE_PLUGIN       "Build Trace plugin" ON)
 option(BUILD_USER_CODE_PLUGIN   "Build User-code plugin" ON)
 option(BUILD_JSON_PLUGIN        "Build JSON plugin" OFF)
 option(ENABLE_BENCHMARKING      "Activate benchmarks in the test suite" OFF)
-
+option(BUILD_DAMARIS_PLUGIN   	"Build Damaris plug-in" OFF)
 
 
 ### Default build type
@@ -122,7 +122,9 @@ if("${BUILD_DECL_HDF5_PLUGIN}")
 endif()
 set(CMAKE_MODULE_PATH "${CMAKE_MODULE_PATH}" CACHE STRING "" FORCE)
 
-
+if("${BUILD_DAMARIS_PLUGIN}")
+	list(APPEND CMAKE_MODULE_PATH "${CMAKE_CURRENT_SOURCE_DIR}/plugins/damaris/cmake")
+endif()
 
 ### Sanity check
 
@@ -513,6 +515,12 @@ sbuild_add_module(USER_CODE_PLUGIN
 	SUBSTEPS test
 )
 
+sbuild_add_module(DAMARIS_PLUGIN
+	ENABLE_BUILD_FLAG BUILD_DAMARIS_PLUGIN
+	SOURCE_DIR "${CMAKE_CURRENT_SOURCE_DIR}/plugins/damaris"
+	DEPENDS PDI
+)
+
 sbuild_add_module(PDI_EXAMPLE
 	ENABLE_BUILD_FLAG BUILD_TESTING
 	SOURCE_DIR "${CMAKE_CURRENT_SOURCE_DIR}/example"

plugins/damaris/AUTHORS

@@ -0,0 +1,18 @@
+Multiple people have contributed to PDI Damaris plugin. To show our
+appreciation for their public spirit, we list here in alphabetical order a
+condensed list of their contributions.
+
+
+Josh Bowden - Inria (joshua-charles.bowden@inria.fr)
+* Maintainer (Apr. 2024 - Aug. 2024)
+* Design and initial implementation
+
+Etienne Ndamlabin - Inria (jean-etienne.ndamlabin-mboula@inria.fr)
+* Maintainer (Oct. 2024 - ...)
+* (Re-)Design and initial implementation
+
+Jacques Morice - CEA (jacques.morice@cea.fr)
+* Developper
+
+Yushan Wang - CEA (yushan.wang@cea.fr)
+* Developper

plugins/damaris/CMakeLists.txt

@@ -0,0 +1,94 @@
+#=============================================================================
+# Copyright (C) 2015-2024 Commissariat a l'energie atomique et aux energies alternatives (CEA)
+# Copyright (C) 2024 Institut national de recherche en informatique et en automatique (Inria)
+#
+# All rights reserved.
+#
+# Redistribution and use in source and binary forms, with or without
+# modification, are permitted provided that the following conditions are met:
+# * Redistributions of source code must retain the above copyright notice,
+#   this list of conditions and the following disclaimer.
+# * 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.
+# * Neither the names of CEA, nor the names of the contributors may be used to
+#   endorse or promote products derived from this software without specific
+#   prior written  permission.
+#
+# THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
+# AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
+# IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
+# ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE
+# LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR
+# CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF
+# # SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS
+# INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN
+# CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE)
+# ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE
+# POSSIBILITY OF SUCH DAMAGE.
+#=============================================================================
+
+cmake_minimum_required(VERSION 3.16...3.29)
+project(pdi_damaris_plugin LANGUAGES C CXX)
+list(APPEND CMAKE_MODULE_PATH "${CMAKE_CURRENT_LIST_DIR}/cmake")
+
+# TODO:
+include(CTest)
+
+include(GNUInstallDirs)
+
+#Damaris
+#set(Damaris_DEPS damaris MPI::MPI_C MPI::MPI_CXX)
+set(Damaris_DEPS MPI::MPI_C MPI::MPI_CXX)
+find_package(Damaris 1.12.0 REQUIRED)
+if (Damaris_FOUND)
+    message(STATUS "The Damaris library was found (${Damaris_LIBRARIES_PATH}/libdamaris.so)")
+    # Adds the libraries used - Damaris and its dependencies to the link line
+    # target_link_libraries(mysim PUBLIC ${Damaris_LIBRARIES})
+    # This creates a definition of a pre-processor variable (PROG_HAS_DAMARIS)
+    # that can be used as a guard in the C/C++ code:
+    # target_compile_definitions(mysim PRIVATE PROG_HAS_DAMARIS)
+    list(APPEND Damaris_DEPS damaris)
+    #list(APPEND Damaris_DEPS ${Damaris_LIBRARIES})
+    include_directories(${Damaris_INCLUDE_DIRS} ${Damaris_INCLUDE_DIRS}/damaris)
+    link_directories(${Damaris_LIBRARIES_PATH})
+
+
+    message(STATUS "Embedding RPATH for Damaris: ${Damaris_LIBRARIES_PATH}")
+    set(CMAKE_INSTALL_RPATH "${Damaris_LIBRARIES_PATH}")
+    set(CMAKE_BUILD_WITH_INSTALL_RPATH TRUE)
+else()
+    message(STATUS "The Damaris library was NOT found")
+endif()
+
+# MPI
+find_package(MPI REQUIRED COMPONENTS CXX C)
+
+# PDI
+find_package(PDI 1.9.2 REQUIRED COMPONENTS plugins)
+
+# The plugin
+add_library(pdi_damaris_plugin MODULE
+		damaris.cxx
+        damaris_cfg.cxx
+        damaris_wrapper.cxx
+        damaris_api_call_handler.cxx)
+target_link_libraries(pdi_damaris_plugin PUBLIC PDI::PDI_plugins ${Damaris_DEPS})
+set_target_properties(pdi_damaris_plugin PROPERTIES CXX_VISIBILITY_PRESET hidden)
+
+# installation
+set(INSTALL_PDIPLUGINDIR "${PDI_DEFAULT_PLUGINDIR}" CACHE PATH "PDI plugins (${PDI_DEFAULT_PLUGINDIR})")
+install(TARGETS pdi_damaris_plugin
+		LIBRARY DESTINATION "${INSTALL_PDIPLUGINDIR}"
+)
+
+#[===[ TODO
+# Tests
+if("${BUILD_TESTING}")
+	add_subdirectory(tests/)
+endif()
+]===]
+
+if("${DAMARIS_BUILD_EXAMPLES}")
+    add_subdirectory(example/)
+endif()

plugins/damaris/README.md

@@ -0,0 +1,154 @@
+# The Damaris plugin {#damaris_plugin}
+
+**WARNING** This documentation is a work in progress and does not reflect the
+full potential of this plugin.
+
+**Add description of damaris plugin**
+* For detailed information about the Damaris library, please refer to https://project.inria.fr/damaris/
+
+
+## Configuration grammar
+
+**WARNING** The following grammar will be changed in the next version of this plugin (see https://github.com/jmorice91/pdi/issues/42). For this reason, we won't go into the details.
+
+* `communicator`: (currently not used) A $-expression referencing an MPI communicator.
+
+* `architecture`: a key-value map.
+  * `sim_name`(string): the name of the simulation, also used as the name of output files.
+  * `domains`(integer, default: 1) : number of blocks by sub domain
+  * `dedicated`: describes what resources will be used by Damaris. Notes: for the momenet, the plugin works with either `only dedicated cores`, or `only dedicated nodes`. In the future, the mix of two modes will be supported.
+    * `core`: an integer value (default 0). Number of cores per node that will be used for Damaris
+    * `node`: an integer value (default 0). Number of nodes that will be used for Damaris. 
+
+* `client_comm_get`(string) identifier of the communicator which includes all Damaris client processes
+* `get_is_client` (string) identifier of data which differentiates the Damaris client processes from Damaris server processes (only needed with explicite use of Damaris client, c.f. section below)
+
+* `datasets`: list of `DATASET_DESC`
+  * `dataset`: a key value map that represent a datset that will be shared with damaris. It is composed with
+    * `name`(string): name of the dataset
+    * `layout`(string): name of the layout of this dataset
+    * `storage`(string): name of the storage of this dataset
+
+* `layouts`: list of `LAYOUT_DESC`.
+  * `layout:` a key value map that represent a layout defined in a `dataset`. It is composed with
+    * `name` (string) name of the layout
+    * `type` (string) type of an element of the dataset. e.g. `double`, `int`, `float`, etc
+    * `global`: Global size of the layout.
+    * `dimensions`: Local (subdomain) size of the layout with ghosts layers.
+    * `ghosts`: Number of ghost layers for each dimension. "," separates two dimensions and ":" separates left and right layers in each dimension
+    * `depends_on`: List of data used to update the layout attributes. This is necessary because Damaris servers need this data to correctly set the `global` and `dimensions` values, on its side.
+
+* `storages`: list of `STORAGE_DESC`.
+  * `storage:` a key value map that represent the storage used to save a`dataset`. It is composed with
+    * `name` (string) Name of the storage
+    * `type` Type of the output file. Currently only HDF5 is supported.
+    * `file_mode` (Collective or FilePerCore)
+    * `files_path` Path for the output files
+
+* `write`: list of data that will be write on the disk by damaris. Each data is composed with
+  * `dataset`: The dataset in which the data will be written.
+  * `position`: The starting position of the data (for each client process) with repect to the dataset.
+
+* `log`: a key value map that specifies the logger information of Damaris. This feature is optional.
+  * `file_name`(string) The beginning of the log filename. By default is the value of damaris/architecture/sim_name and the default folder is "where_you_launch_the_script/log". The suffix of the filename is `_P#proc_#iter.log` where #proc represents the MPI rank of the Damaris server process. #iter is the number of iterations.
+  * `rotation_size` (integer): 5  
+  * `log_level`(string): level of the logger. The value is one of: trace, debug, info, warning, error and fatal
+  * `flush`(true or false): Forces the log file to be flushed if set to true .
+
+**Question: what is the other type for a storage ( hdf5, ...)**
+
+* the keyword `when:` can be used in `write` to define the frequency?
+* For the layout structure, we can use the same definition as decl_hdf5 plugin to be homogenous  ==> modularity between plugin !!
+* In decl_hdf5 plugin in some sense, layout and write can be "fusioné"?
+
+All this points can be adressed in a new version in damaris plugin.
+
+## How to use the Damaris plugin with a simulation?
+
+There are two ways to initialize Damaris client from the simualtion.
+
+### Implicit use of Damaris client
+```c++
+
+MPI_Init(...);
+PDI_init(...);
+
+PDI_expose("comm", &comm, PDI_INOUT); // <-- allow plugin to set, and return Damaris client communicator
+// all simulation codes follow here
+// use comm as the default communicator for the rest of the simulation
+// only the Damaris client processes are available here
+PDI_finalize();
+MPI_Finalize(); // Damaris server processes will be finalized by the end of the damaris_plugin
+```
+
+### Explicit use of Damaris client
+```c++
+
+MPI_Init(...);
+PDI_init(...);
+int is_client;
+PDI_expose("is_client", &is_client, PDI_INOUT); // Only Damaris client will have is_client=1
+PDI_expose("comm", &comm, PDI_INOUT); // <-- allow plugin to set, and return Damaris client communicator
+if(is_client) {
+  // use comm as the default communicator for the rest of the simulation
+  // all simulation codes should be inside this block
+}
+// all MPI processes are available here (both Damaris clients and servers)
+PDI_finalize();
+MPI_Finalize();
+```
+
+With explicit use of Damaris client, one has to add a few lines in the yaml file:
+```yaml
+metadata:
+  is_client: int
+damaris:
+  get_is_client: is_client # identifier of data which differentiates the Damaris client processes from Damaris server processes
+```
+
+* [to be modified] the communicator will be split by Damaris in a communicator for the simulation code (client) 
+and for damaris execution (client).
+* `get_is_client`(string): name of `is_client` in PDI data store (optional). It is requested only with `is_client` is used.
+* `client_comm_get` (string):  name of mpi communicator of simulation code (client) in PDI data store (requested). This communicator is defined by Damaris after the split of the communicator defined in `communicator` between client and server.
+
+
+## full configuration example
+
+```yaml
+damaris:
+  architecture: 
+    sim_name: example  
+    domains: 1
+    dedicated:
+      core: 1 
+  client_comm_get: comm
+  datasets:
+    - dataset: 
+        name: main_field
+        layout: main_field_layout
+        storage: hdf5_example  
+  layouts:
+    - layout: 
+        name: main_field_layout
+        type: double
+        global: ['$psize[0]*($dsize[0]-2),$psize[1]*($dsize[1]-2)']
+        dimensions: [ '$dsize[0]', '$dsize[1]' ]
+        ghosts: '1:1,1:1'
+        depends_on: [dsize, psize]
+  storages:
+    - storage:
+        name: hdf5_example
+        type: HDF5
+        file_mode: Collective
+        files_path: ./HDF5_files_damaris/
+  write: 
+    main_field:
+      dataset: main_field 
+      when: '$iter<10'
+      position: ['($dsize[0]-2)*$pcoord[0]', '($dsize[1]-2)*$pcoord[1]']
+  log:
+    file_name: example
+    rotation_size: 5
+    log_level: info
+    flush: true
+```

plugins/damaris/cmake/DamarisPluginUtils.cmake

@@ -0,0 +1,37 @@
+# Function to compare two versions
+# Returns 1 if version1 >= version2, 0 otherwise
+function(version_greater_equal version1 version2 result)
+    string(REGEX MATCHALL "[0-9]+" v1_parts "${version1}")
+    string(REGEX MATCHALL "[0-9]+" v2_parts "${version2}")
+
+    # pad missing parts with 0
+    list(LENGTH v1_parts len1)
+    list(LENGTH v2_parts len2)
+    if(len1 LESS 3)
+        math(EXPR pad "3 - ${len1}")
+        foreach(_i RANGE ${pad})
+            list(APPEND v1_parts 0)
+        endforeach()
+    endif()
+    if(len2 LESS 3)
+        math(EXPR pad "3 - ${len2}")
+        foreach(_i RANGE ${pad})
+            list(APPEND v2_parts 0)
+        endforeach()
+    endif()
+
+    set(_result 1)
+    foreach(i RANGE 0 2)
+        list(GET v1_parts ${i} v1i)
+        list(GET v2_parts ${i} v2i)
+        if(v1i GREATER v2i)
+            set(_result 1)
+            break()
+        elseif(v1i LESS v2i)
+            set(_result 0)
+            break()
+        endif()
+    endforeach()
+
+    set(${result} ${_result} PARENT_SCOPE)
+endfunction()