Organize and add examples

.github/workflows/everything.yml

@@ -448,24 +448,19 @@ jobs:
     strategy:
       fail-fast: false
       matrix:
-        code: [examples, lammps, tau]
+        code: [lammps, tau]
         include:
-          - code: examples
-            repo: ornladios/ADIOS2-Examples
-            ref: master
           - code: lammps
             repo: pnorbert/lammps
             ref: fix-deprecated-adios-init
           - code: tau
-            repo: ornladios/ADIOS2-Examples
-            ref: master
-
     defaults:
       run:
         shell: bash -c "docker exec adios2-ci bash --login -e $(echo {0} | sed 's|/home/runner/work|/__w|g')"
 
     steps:
       - uses: actions/checkout@v4
+        if: ${{ matrix.repo != '' }}
         with:
           repository: ${{ matrix.repo }}
           ref: ${{ matrix.ref }}

CMakeLists.txt

@@ -137,7 +137,11 @@ if((NOT BUILD_SHARED_LIBS) AND (NOT DEFINED CMAKE_POSITION_INDEPENDENT_CODE))
   set(CMAKE_POSITION_INDEPENDENT_CODE ON)
 endif()
 
+# Ctest creates BUILD_TESTING option and sets it to true by default
+# Here we disable BUILD_TESTING option by default
+option(BUILD_TESTING "Build testing" OFF)
 include(CTest)
+mark_as_advanced(CLEAR BUILD_TESTING)
 
 adios_option(Blosc2     "Enable support for c-blosc-2 transforms" AUTO)
 adios_option(BZip2      "Enable support for BZip2 transforms" AUTO)
@@ -176,7 +180,7 @@ if(ADIOS2_HAVE_CUDA OR ADIOS2_HAVE_Kokkos_CUDA)
         if(DEFINED Kokkos_CUDA_ARCHITECTURES)
             set(CMAKE_CUDA_ARCHITECTURES ${Kokkos_CUDA_ARCHITECTURES})
         else()
-            # Mininum common non-deprecated architecture
+            # Minimum common non-deprecated architecture
             set(CMAKE_CUDA_ARCHITECTURES 52)
         endif()
     endif()
@@ -296,8 +300,6 @@ endif()
 #------------------------------------------------------------------------------#
 # Third party libraries
 #------------------------------------------------------------------------------#
-include(CTest)
-mark_as_advanced(BUILD_TESTING)
 add_subdirectory(thirdparty)
 
 #------------------------------------------------------------------------------#
@@ -318,7 +320,7 @@ add_subdirectory(plugins)
 #------------------------------------------------------------------------------#
 # Examples
 #------------------------------------------------------------------------------#
-option(ADIOS2_BUILD_EXAMPLES "Build examples" ON)
+option(ADIOS2_BUILD_EXAMPLES "Build examples" OFF)
 if(ADIOS2_BUILD_EXAMPLES)
   add_subdirectory(examples)
 endif()

bindings/Matlab/README.txt

@@ -43,5 +43,5 @@ $ cd <your adios source>
 $ git pull
 $ mkdir build.lean
 $ cd build.lean
-$ cmake -DCMAKE_INSTALL_PREFIX=/opt/adios/lean -DADIOS2_USE_MPI=OFF -DADIOS2_USE_Fortran=OFF -DADIOS2_USE_Python=OFF -DCMAKE_BUILD_TYPE=RelWithDebInfo -DADIOS2_ENABLE_PIC=ON -DCMAKE_POSITION_INDEPENDENT_CODE=ON -DBUILD_TESTING=OFF -DADIOS2_USE_SST=OFF -DADIOS2_USE_BZip2=OFF -DADIOS2_USE_DataMan=OFF  ..
+$ cmake -DCMAKE_INSTALL_PREFIX=/opt/adios/lean -DADIOS2_USE_MPI=OFF -DADIOS2_USE_Fortran=OFF -DADIOS2_USE_Python=OFF -DCMAKE_BUILD_TYPE=RelWithDebInfo -DADIOS2_ENABLE_PIC=ON -DCMAKE_POSITION_INDEPENDENT_CODE=ON -DADIOS2_USE_SST=OFF -DADIOS2_USE_BZip2=OFF -DADIOS2_USE_DataMan=OFF  ..
 

cmake/DetectOptions.cmake

@@ -216,7 +216,7 @@ if(ADIOS2_USE_Kokkos)
         enable_language(HIP)
       endif()
       if(Kokkos_ENABLE_SYCL)
-	    set(ADIOS2_HAVE_Kokkos_SYCL TRUE)
+        set(ADIOS2_HAVE_Kokkos_SYCL TRUE)
       endif()
       set(ADIOS2_HAVE_GPU_Support TRUE)
     endif()

docs/user_guide/source/setting_up/source/cmake.rst

@@ -103,8 +103,8 @@ In addition to the ``ADIOS2_USE_Feature`` options, the following options are als
  CMake VAR Options                       Values                                       Description                                                                          |
 ==================================== =============================================== ===============================
 ``BUILD_SHARED_LIBS``                  **ON**/OFF                                     Build shared libraries.
-``ADIOS2_BUILD_EXAMPLES``              **ON**/OFF                                     Build examples.
-``BUILD_TESTING``                      **ON**/OFF                                     Build test code.
+``ADIOS2_BUILD_EXAMPLES``              ON/**OFF**                                     Build examples.
+``BUILD_TESTING``                      ON/**OFF**                                     Build test code.
 ``CMAKE_INSTALL_PREFIX``               /path/to/install (``/usr/local``)              Installation location.
 ``CMAKE_BUILD_TYPE``                   Debug/**Release**/RelWithDebInfo/MinSizeRel    Compiler optimization levels.
 ==================================== =============================================== ===============================

examples/CMakeLists.txt

@@ -5,24 +5,6 @@
 
 add_subdirectory(basics)
 add_subdirectory(hello)
-add_subdirectory(query)
-add_subdirectory(useCases)
-add_subdirectory(inlineMWE)
 add_subdirectory(plugins)
-add_subdirectory(fides)
-
-if(ADIOS2_HAVE_MPI)
-  add_subdirectory(heatTransfer)
-endif()
-
-
-if(ADIOS2_HAVE_CUDA OR ADIOS2_HAVE_Kokkos_CUDA)
-  add_subdirectory(cuda)
-endif()
-
-
-if(ADIOS2_HAVE_MPI AND ADIOS2_HAVE_HDF5)
-  if(HDF5_VERSION VERSION_GREATER_EQUAL 1.14)
-    add_subdirectory(h5subfile)
-  endif()
-endif()
+add_subdirectory(simulations)
+add_subdirectory(useCases)

examples/ReadMe.md

@@ -0,0 +1,16 @@
+# ADIOS2 Examples
+
+This directory contains examples of how to use ADIOS2 in different scenarios.
+The examples are written mostly in C++, but also C, Fortran, Python, and Julia.
+
+They can be found in the following subdirectories, and they should be explored in the order that they are listed:
+
+1. [hello](hello): The _hello_ examples are meant to introduce you to ADIOS2's IO capabilities and engines.
+2. [basics](basics): The _basics_ examples are meant to introduce you to basic concepts of ADIOS2, such as
+   global/joined/local arrays, values, and variables shapes.
+3. [useCases](useCases): The _useCases_ examples are meant to demonstrate how to use ADIOS2 in different scenarios,
+   such as in situ visualization, and fides schema.
+4. [plugins](plugins): The _plugins_ examples are meant to introduce you to the plugin capabilities of ADIOS2, such as
+   how to develop your own engine or operators.
+5. [simulations](simulations): The _simulations_ examples are meant to demonstrate how to integrate ADIOS2 within your
+   simulation code to read, write and/or stream your simulation data.

examples/basics/CMakeLists.txt

@@ -3,7 +3,12 @@
 # accompanying file Copyright.txt for details.
 #------------------------------------------------------------------------------#
 
-add_subdirectory(globalArray)
+if(ADIOS2_HAVE_MPI)
+  add_subdirectory(globalArray1D)
+endif()
+add_subdirectory(globalArrayND)
 add_subdirectory(joinedArray)
 add_subdirectory(localArray)
+add_subdirectory(queryWorker)
 add_subdirectory(values)
+add_subdirectory(variablesShapes)

examples/basics/ReadMe.md

@@ -0,0 +1,29 @@
+## ADIOS2 basics examples
+
+The _basics_ examples are meant to introduce you to basic concepts of ADIOS2, such as
+global/joined/local arrays, values, and variables shapes.
+
+They can be found in the following subdirectories, and they should be explored in the order that they are listed:
+
+1. [globalArray1D](globalArray1D): The _globalArray1D_ example demonstrates how to read and write an
+   1-D global array with constant dimensions over time from multiple processors using ADIOS2's BP engine.
+   * Languages: C, Fortran
+2. [globalArrayND](globalArrayND): The _globalArrayND_ example demonstrates how to write an N-D global array with
+   constant dimensions over time from multiple processors using ADIOS2's BP engine.
+   * Languages: C++
+3. [localArray](localArray): The _localArray_ example demonstrates how to write and read a local array per processor
+   with the same name from multiple processors using ADIOS2's BP engine.
+   * Languages: C++
+4. [joinedArray](joinedArray): The _joinedArray_ example demonstrates how to write local array that is different only in
+   one dimension so that it can be joined into a global array with the same name from multiple processors at read time
+   using ADIOS2's ADIOS2's BP engine.
+   * Languages: C++
+5. [values](values): The _values_ example demonstrates how to write and read a multiple types of variables with a single
+   value, such as global constant, global value, local constant, and local value using ADIOS2's BP engine.
+   * Languages: C++, Fortran
+6. [variablesShapes](variablesShapes): The _variablesShapes_ example demonstrates how to write supported variables
+   shapes using stepping and ADIOS2's BP engine.
+   * Languages: C++, C++ using high-level API
+7. [queryWorker](queryWorker): The _queryWorker_ example demonstrates how to read variables using ADIOS2's BP engine
+   and perform queries on the read data and streams the results.
+   * Languages: C++

examples/basics/globalArray1D/CMakeLists.txt

@@ -0,0 +1,80 @@
+#------------------------------------------------------------------------------#
+# Distributed under the OSI-approved Apache License, Version 2.0.  See
+# accompanying file Copyright.txt for details.
+#------------------------------------------------------------------------------#
+
+cmake_minimum_required(VERSION 3.12)
+project(ADIOS2BasicsGlobalArray1DExample)
+
+if(NOT TARGET adios2_core)
+  set(_components C)
+
+  include(CheckLanguage)
+  check_language(Fortran)
+  if(CMAKE_Fortran_COMPILER)
+    enable_language(Fortran)
+  endif()
+  if(CMAKE_Fortran_COMPILER_LOADED)
+    list(APPEND _components Fortran)
+  endif()
+
+  find_package(MPI COMPONENTS ${_components})
+  if(MPI_FOUND)
+    # Workaround for various MPI implementations forcing the link of C++ bindings
+    add_definitions(-DOMPI_SKIP_MPICXX -DMPICH_SKIP_MPICXX)
+
+    list(APPEND _components MPI)
+  endif()
+
+  find_package(ADIOS2 REQUIRED COMPONENTS ${_components})
+endif()
+
+if(ADIOS2_HAVE_MPI)
+  add_library(adios2_basics_globalArray1D_mpivars_c OBJECT mpivars.c)
+  target_link_libraries(adios2_basics_globalArray1D_mpivars_c MPI::MPI_C)
+  install(TARGETS adios2_basics_globalArray1D_mpivars_c RUNTIME DESTINATION ${CMAKE_INSTALL_BINDIR})
+
+  add_library(adios2_basics_globalArray1D_decomp_c OBJECT decomp.c)
+  target_link_libraries(adios2_basics_globalArray1D_decomp_c
+    adios2_basics_globalArray1D_mpivars_c MPI::MPI_C)
+  install(TARGETS adios2_basics_globalArray1D_decomp_c RUNTIME DESTINATION ${CMAKE_INSTALL_BINDIR})
+
+  add_executable(adios2_basics_globalArray1DWrite_c globalArray1DWrite.c)
+  target_link_libraries(adios2_basics_globalArray1DWrite_c
+    adios2_basics_globalArray1D_mpivars_c
+    adios2_basics_globalArray1D_decomp_c
+    adios2::c_mpi MPI::MPI_C)
+  install(TARGETS adios2_basics_globalArray1DWrite_c RUNTIME DESTINATION ${CMAKE_INSTALL_BINDIR})
+
+  add_executable(adios2_basics_globalArray1DRead_c globalArray1DRead.c)
+  target_link_libraries(adios2_basics_globalArray1DRead_c
+    adios2_basics_globalArray1D_mpivars_c
+    adios2_basics_globalArray1D_decomp_c
+    adios2::c_mpi MPI::MPI_C)
+  install(TARGETS adios2_basics_globalArray1DRead_c RUNTIME DESTINATION ${CMAKE_INSTALL_BINDIR})
+
+  if(ADIOS2_HAVE_Fortran)
+    add_library(adios2_basics_globalArray1D_mpivars_f OBJECT mpivars.F90)
+    target_link_libraries(adios2_basics_globalArray1D_mpivars_f MPI::MPI_Fortran)
+    install(TARGETS adios2_basics_globalArray1D_mpivars_f RUNTIME DESTINATION ${CMAKE_INSTALL_BINDIR})
+
+    add_library(adios2_basics_globalArray1D_decomp_f OBJECT decomp.F90)
+    target_link_libraries(adios2_basics_globalArray1D_decomp_f
+      adios2_basics_globalArray1D_mpivars_f MPI::MPI_Fortran)
+    install(TARGETS adios2_basics_globalArray1D_decomp_f RUNTIME DESTINATION ${CMAKE_INSTALL_BINDIR})
+
+    add_executable(adios2_basics_globalArray1DWrite_f globalArray1DWrite.F90)
+    target_link_libraries(adios2_basics_globalArray1DWrite_f
+      adios2_basics_globalArray1D_mpivars_f
+      adios2_basics_globalArray1D_decomp_f
+      adios2::fortran_mpi MPI::MPI_Fortran)
+    install(TARGETS adios2_basics_globalArray1DWrite_f RUNTIME DESTINATION ${CMAKE_INSTALL_BINDIR})
+
+    add_executable(adios2_basics_globalArray1DRead_f globalArray1DRead.F90)
+    target_link_libraries(adios2_basics_globalArray1DRead_f
+      adios2_basics_globalArray1D_mpivars_f
+      adios2_basics_globalArray1D_decomp_f
+      adios2::fortran_mpi MPI::MPI_Fortran)
+    install(TARGETS adios2_basics_globalArray1DRead_f RUNTIME DESTINATION ${CMAKE_INSTALL_BINDIR})
+  endif()
+endif()

examples/basics/globalArray1D/decomp.F90

@@ -0,0 +1,53 @@
+! Helper functions for all examples
+module decomp
+contains
+
+! random integer from {minv, minv+1, ..., maxv}
+! including minv and maxv
+function get_random(minv, maxv) result(n) 
+    implicit none
+    integer, intent(in) :: minv, maxv
+    real :: r
+    integer :: n
+    call random_number(r)
+    n = minv + FLOOR((maxv+1-minv)*r)  
+end function get_random
+
+! gather the local sizes of arrays and sum them up
+! so that each process knows the global shape
+! and its own offset in the global space
+subroutine gather_decomp_1d(mysize, myshape, myoffset)
+    use mpivars
+    implicit none
+    integer*8, intent(in) :: mysize
+    integer*8, intent(out) :: myshape, myoffset
+    integer*8, dimension(:), allocatable :: sizes
+
+    allocate(sizes(nproc))
+    call MPI_Allgather( mysize, 1, MPI_LONG_LONG, &
+                        sizes, 1, MPI_LONG_LONG, &
+                        app_comm, ierr)
+    myshape = sum(sizes)
+    myoffset = sum(sizes(1:rank))
+    deallocate(sizes)
+end subroutine gather_decomp_1d
+
+subroutine decompose_1d(globalsize, myoffset, mysize)
+    use mpivars
+    implicit none
+    integer*8, intent(in) :: globalsize
+    integer*8, intent(out) :: myoffset, mysize
+    integer*8 :: rem
+
+    mysize = globalsize/nproc
+    rem = globalsize-(nproc*mysize)
+    if (rank < rem) then
+        mysize = mysize + 1
+        myoffset = rank*mysize 
+    else
+        myoffset = rank*mysize + rem
+    endif
+end subroutine decompose_1d
+
+end module decomp
+

examples/basics/globalArray1D/decomp.c

@@ -0,0 +1,67 @@
+/*
+ * Distributed under the OSI-approved Apache License, Version 2.0.  See
+ * accompanying file Copyright.txt for details.
+ *
+ * Created by Dmitry Ganyushin ganyushindi@ornl.gov
+ *
+ * Helper functions for all examples
+ */
+#include "decomp.h"
+#include "mpivars.h"
+#include <mpi.h>
+#include <stdio.h>
+#include <stdlib.h>
+#include <time.h>
+
+/* random integer from {minv, minv+1, ..., maxv}
+ including minv and maxv */
+long long int get_random(int minv, int maxv)
+{
+    long long int n;
+    time_t t;
+    /* Intializes random number generator */
+    srand((unsigned)time(&t));
+    n = (rand() % (maxv - minv + 1)) + minv;
+    return n;
+}
+/* gather the local sizes of arrays and sum them up
+ so that each process knows the global shape
+ and its own offset in the global space */
+void gather_decomp_1d(long long int *mysize, long long int *myshape, long long int *myoffset)
+{
+    long long int *sizes;
+    int i;
+    sizes = malloc(sizeof(long long int) * (size_t)nproc);
+    MPI_Allgather(mysize, 1, MPI_LONG_LONG, sizes, 1, MPI_LONG_LONG, app_comm);
+
+    *myshape = 0;
+    for (i = 0; i < nproc; i++)
+    {
+        *myshape += sizes[i];
+    }
+    *myoffset = 0;
+    for (i = 0; i < rank; i++)
+    {
+        *myoffset += sizes[i];
+    }
+
+    free(sizes);
+    return;
+}
+
+void decomp_1d(long long int globalsize, long long int *myoffset, long long int *mysize)
+{
+    long long int rem;
+    *mysize = globalsize / nproc;
+    rem = globalsize - (nproc * *mysize);
+    if (rank < rem)
+    {
+        mysize = mysize + 1;
+        *myoffset = rank * *mysize;
+    }
+    else
+    {
+        *myoffset = rank * *mysize + rem;
+    }
+    return;
+}