ADIOS2-Examples

This repository contains code examples of how to use the Adaptable Input Output system, ADIOS2, bindings. ADIOS2 and ADIOS2-Examples are developed as part of the U.S. Department of Energy Exascale Computing Program. The ADIOS2 source code is located at https://github.com/ornladios/ADIOS2

Examples Summary

All examples are in the source directory and are classified by language binding. Note that examples ending with hl illustrate usage of the adios2 high-level API.

source/cpp: C++ low-level and high-level API examples

• hello-world : writes and reads a simple greeting

  • hello-world.cpp uses adios2 C++ low-level API

  • hello-world-hl.cpp uses adios2 C++ high-level API

• basics : basic examples for using adios2

  • variables-shapes.cpp variables shapes support in adios2 C++ low-level API
  • variables-shapes-hl.cpp variables shapes support in adios2 C++ high-level API

• gray-scott: 3D reaction diffusion simulation in C++, includes C++ and Python analisys code.

• GrayScott.jl: 3D reaction diffusion simulation in Julia with either CPU threads, CUDA.jl or AMDGPU.jl (AMD GPU random number generation is work-in-progress) back ends and analisys code (also work in progress). Uses ADIOS2.jl Julia bindings.

source/c: C API examples

• hello-world: write and reads a simple greeting
  • hello-world.c

Package Distributions (preferred)

This is the preferred method as it includes all the dependencies (e.g. adios2, openmpi, matplotlib) required by the examples.

1. Conda installation on Linux, Mac and Windows' Linux Subsystem on a new environment:

   $ conda activate
   $ conda create --name adios2-examples
   $ conda activate adios2-examples
   $ conda install adios2-examples -c williamfgc -c conda-forge
   

Meson and CMake installations from source are provided if none of the methods above are available.

Installing from source with Meson

1. Requirements:

   • meson build >= 0.52.0, from pip3 install meson
   • ninja
   • mono-complete (might be already installed)
   • mpi: openmpi or mpich
   • adios2 mpi version:
     • macOS: brew install adios2
   • cmake >= v3.8 (optional) if adios2 is installed in non-system location (e.g. /opt)
   • python: mpi4py, numpy, matplotlib

2. Build, Test, Install:

   From the ADIOS2-Examples directory:

   if adios2 is on a standard installation (e.g. system location /usr, spack, conda, etc.)

   $ meson build-meson --prefix=/path/to/install/adios2-examples
   

   if adios2 is on a non-standard location (e.g. /opt)

   $ meson build-meson --prefix=/path/to/install/adios2-examples 
                       -DADIOS2_DIR=/path/to/adios2/lib/cmake/adios2
   

   $ cd build-meson
   $ ninja
   $ ninja test
   $ ninja install
   

Installing from source with CMake

1. Requirements:

   • mpi: openmpi or mpich
   • adios2 mpi and python version:
     • macOS: brew install adios2
   • cmake >= v3.8
   • python: mpi4py, numpy, matplotlib

2. Build, Test, Install:

   From the ADIOS2-Examples directory:

   $ mkdir build-cmake
   $ cd build-cmake
   

   if using an adios2 standard installation (e.g. system location /usr, spack, conda, etc.):

   $ cmake -DCMAKE_INSTALL_PREFIX=/path/to/install/adios2-examples ..
   

   if using an adios2 non-standard location (e.g. /opt):

   $ cmake -DCMAKE_INSTALL_PREFIX=/path/to/install/adios2-examples \
           -DADIOS2_DIR=/path/to/adios2/lib/cmake/adios2 \
           ..
   

   $ make -j
   $ ctest
   $ make install
   

Running the Examples

The final installation structure of the adios2-examples package include a bin directory for the executables and a share directory for the config files and scripts to a particular example.

adios2-examples installation structure:

bin/
    adios2-hello-world
    adios2-hello-world-hl
    ...
    adios2-gray-scott
    adios2-pdf-calc

share/adios2-examples/
    gray-scott

Each executable under bin starts with the adios2- prefix. Whereas, each share/adios2-examples directory has a ReadMe.md file with instructions.

For example, to run hello-world examples (assuming adios2-examples/bin is in the $PATH):

$ mpirun -n 4 adios2-hello-world-cpp
Hello World from ADIOS2
Hello World from ADIOS2
Hello World from ADIOS2
Hello World from ADIOS2

or for the high-level C++ API:

$ mpirun -n 4 adios2-hello-world-hl-cpp
Hello World from ADIOS2
Hello World from ADIOS2
Hello World from ADIOS2
Hello World from ADIOS2

these runs would generate corresponding bp files that can be inspected with the bpls utility in ADIOS2.

$ ls -d *.bp
hello-world-cpp.bp  hello-world-hl-cpp.bp

$ bpls hello-world-cpp.bp -lav
File info:
of variables:  1
of attributes: 0
statistics:    Min / Max

string   Greeting  scalar = "Hello World from ADIOS2"

For a more elaborated use case see gray-scott.

Credits

• William F Godoy godoywf@ornl.gov
• Norbert Podhorszki pnb@ornl.gov
• Keichi Takahashi keichi@is.naist.jp
• Hiroshi Watanabe