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 occurrances 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})

 if(FleCSI_ENABLE_KOKKOS AND FleCSI_ENABLE_LEGION AND 
    (Kokkos_ENABLE_CUDA OR Kokkos_ENABLE_HIP))
    list(APPEND UNIT_FLAGS "--backend-args=-ll:gpu 1")
 endif()
 
  add_test(NAME ${name}
  COMMAND
     ${MPIEXEC_EXECUTABLE} -np 1 $<TARGET_FILE:${name}> ${unit_ARGUMENTS} ${UNIT_FLAGS}
     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. 10 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;

  auto status = flecsi::initialize(argc, argv);
  status = poisson::control::check_status(status);

  if(status != flecsi::run::status::success) {
    return status < flecsi::run::status::clean ? 0 : status;
  }

  flecsi::flog::add_output_stream("clog", std::clog, true);

  status = flecsi::start(poisson::control::execute);

  flecsi::finalize();

  return status;
} // 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 environement variable. Then, you can build this example like:

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