Tutorial

This tutorial attempts to give a basic introduction to the design philosophy and structure of the FleCSI programming system. Each subdirectory contains example codes that can be compiled with CMake. Details on how to build the tutorials are given below.

Attention

The tutorial is primarily designed as an introduction for application developers, i.e., we do not go into the details of designing or implementing the specialization layer, and the discussion of core FleCSI features is limited to the high-level execution and data interfaces.

Because a specialization layer is necessary to use FleCSI, we have provided a simple mesh interface as part of the tutorial. Users who are interested in the basic structure of a mesh topology specialization are encouraged to examine the source code in the specialization subdirectory of this tutorial (The complete source code is in the tutorial/specialization subdirectory of the main project.)

Requirements

The tutorial assumes that you have successfully installed FleCSI somewhere on your system. Instructions for different install methods are available here: Build & Install.

Once you have built and installed FleCSI, add the path to your installation to your CMAKE_PREFIX_PATH:

$ export CMAKE_PREFIX_PATH=/path/to/flecsi/install/dir:$CMAKE_PREFIX_PATH

Building the Examples

The tutorial uses a standard CMake build system. To configure and build the examples, execute the following steps from the tutorial subdirectory of the FleCSI source:

$ mkdir build && cd build
$ cmake ..
$ make

Using the Docker Container

The tutorial is also available as a Docker container. This simplifies getting and installing FleCSI and its dependencies.

Installing a Container Engine

Some FleCSI developer tasks require a container engine, e.g., Docker. This section provides links to installation and usage documentation for Docker, and Podman.

Docker

The Docker daemon is available for a variety of platforms from the docker website.

For linux, the community engine is available for several distributions:

Podman

An alternative, drop-in replacement for Docker is Podman. Podman has the advantage that it is daemonless, and does not require root privileges to run.

Pulling the Image

To pull the tutorial image, do:

$ docker pull laristra/flecsi-tutorial:latest

This will download the image to your machine. Once the pull is complete, you can run the image like:

$ docker run -it --shm-size=512m -h tutorialhost -u flecsi laristra/flecsi-tutorial:latest

This will place you into a bash prompt, from which you can build and run the tutorial examples. The tutorials are in the top-level directory in the Docker container.

Note: You can also pull a Docker image for a specific runtime, e.g., mpi or legion. The default image latest is built against the Legion backend. To pull the MPI backend image do:

$ docker pull laristra/flecsi-tutorial:mpi