Skip to content

Latest commit

 

History

History
180 lines (122 loc) · 6.1 KB

ReadMe.md

File metadata and controls

180 lines (122 loc) · 6.1 KB
Raw

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

  • basics : basic examples for using adios2

  • 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

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