Poisson

This example is designed to be used as a template for creating FleCSI-based application codes and is intended as the last example in the tutorial. As such, this example provides the following components:

a basic CMake build system
a simple control policy
a standard FleCSI-based main function

We discuss each of these individually. However, in general, to use this example as a template for a real application, you should just change all occurrences of poisson to whatever namespace name you would like to use for your project.

Build system

The build system uses standard CMake and is entirely defined in CMakeLists.txt:

#------------------------------------------------------------------------------#

cmake_minimum_required(VERSION 3.13...3.20)

#------------------------------------------------------------------------------#
# Set the project name.
#------------------------------------------------------------------------------#

project(poisson LANGUAGES CXX C)

#------------------------------------------------------------------------------#
# FleCSI currently depends on C++17.
#------------------------------------------------------------------------------#

set(CXX_STANDARD_REQUIRED ON)
set(CMAKE_CXX_STANDARD 17)

#------------------------------------------------------------------------------#
# Find the FleCSI installation.
#
# The easiest way to help CMake find FleCSI is to install it,
# and add the location to the CMAKE_PREFIX_PATH environment variable.
#------------------------------------------------------------------------------#

find_package(FleCSI REQUIRED)

#------------------------------------------------------------------------------#
# Unit tests
#------------------------------------------------------------------------------#

option(ENABLE_UNIT_TESTS "Enable unit tests" OFF)
mark_as_advanced(ENABLE_UNIT_TESTS)

if(ENABLE_UNIT_TESTS)
  enable_testing()
endif()

function(add_unit name)
  set(options)
  set(one_value_args)
  set(multi_value_args ARGUMENTS)

  cmake_parse_arguments(unit "${options}" "${one_value_args}"
    "${multi_value_args}" ${ARGN})

  add_test(NAME ${name}
  COMMAND
     ${MPIEXEC_EXECUTABLE} ${MPIEXEC_NUMPROC_FLAG} 1 $<TARGET_FILE:${name}> ${unit_ARGUMENTS}
     WORKING_DIRECTORY
      ${CMAKE_BINARY_DIR}
  )

endfunction()

#------------------------------------------------------------------------------#
# App
#------------------------------------------------------------------------------#

add_subdirectory(app)

To prepare this file for your project, you should do the following:

Change poisson to the name of your project wherever it occurs.
Update and add source files to the project.
Add any dependencies.

For the most part, if you wish to extend this tutorial in any way, you will need a working knowledge of CMake. Documentation for CMake is here.

Control policy

The control policy for this example is located in specialization/control.hh. This implementation is consistent with the examples in Control Model Tutorial.

../../_images/poisson.svg — Fig. 13 Control Policy for the Poisson Stand-Alone Application.

Main function

The main function for this example is located in poisson.cc. Unless you need to initialize additional runtimes that are not handled internally by FleCSI, you can likely use this file as is (with a different namespace name).

#include "poisson.hh"
#include "analyze.hh"
#include "finalize.hh"
#include "initialize.hh"
#include "options.hh"
#include "problem.hh"
#include "solve.hh"
#include "specialization/control.hh"
#include "state.hh"

#include <flecsi/execution.hh>
#include <flecsi/flog.hh>

int
main(int argc, char ** argv) {
  flecsi::util::annotation::rguard<main_region> main_guard;

  flecsi::getopt()(argc, argv);
  const flecsi::run::dependencies_guard dg;
  flecsi::run::config cfg;
#if FLECSI_BACKEND == FLECSI_BACKEND_legion &&                                 \
  (defined(KOKKOS_ENABLE_CUDA) || defined(KOKKOS_ENABLE_HIP))
  cfg.legion = {"", "-ll:gpu", "1"};
#endif
  const flecsi::runtime run(cfg);
  flecsi::flog::add_output_stream("clog", std::clog, true);
  return run.control<poisson::control>();
} // main

Building the Poisson application

Build & Install FleCSI somewhere on your system and make sure that the location is set in your CMAKE_PREFIX_PATH environment variable. Then, you can build this example like:

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