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.
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.)
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.
The Docker daemon is available for a variety of platforms from the docker website.
For linux, the community engine is available for several distributions:
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 backend, 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
The tutorial examples are designed to guide the reader through basic to more advanced FleCSI concepts.
- Runtime Model
- Example 1: Minimal
- Example 2: Program Options
- Example 3: FLOG (FleCSI Logging Utility)
- Example 4: Caliper Annotations
- Control Model
- Execution Model
- Data Model
- Distributed and shared memory parallelism