How to guides

First steps

Installation

If neSmiK is not already available in the machine, you need to install it yourself. Please consult the Installation Guide.

Adding neSmiK into your CMake-based project

As neSmiK also is a CMake application, it is rather straight forward to add it to your CMake-based project.

  • First, make sure neSmiK is installed properly by following the Installation Guide.

  • locate your main CMakeLists.txt of your project where other dependencies are also linked. You can look for target_link_libraries or link_libraries

  • add the following lines or adapt for your needs:

option(WITH_NESMIK "Compile with NESMIK" ON)
if(WITH_NESMIK)
    find_package(nesmik REQUIRED) # Find the nesmik package installed by cmake during the nesmik install
    target_link_libraries(<yourTarget> PRIVATE nesmik::nesmik) # Link your application privatly with nesmik to 1) include the header and 2) link libnesnik
    target_compile_definitions(<yourTarget> PRIVATE "WITH_NESMIK") # add a comile definition to let you use #ifdef WITH_NESMIK guards on e.g. the imports
endif()

Next we need to make sure that CMake can actually find our neSmiK installation. Therefore we use the installation prefix specified during the installation of neSmiK and add that to the CMAKE_PREFIX_PATH.

During the configure phase of your application add -DCMAKE_PREFIX_PATH=$(readlink -f <youreNesmikInstallPath>) to the cmake .. invocation.

If neSmiK isn’t found by CMake, please double check the installation path.

If everything worked as intended, you should see libnesmik.so show up in an ldd <your binary> similar to:

[user@machine build]$ ldd ./<yourbinary>
        linux-vdso.so.1 (0x00007ffd7555f000)
        libnesmik.so => <youreNesmikInstallPath>/lib/libnesmik.so (0x00007387972bc000)

After this you can start to annotate you’re application.

Annontating applications

In order to use neSmiK its essential to annotate your application. By annoatation we mean, that you give different coarse grain regions in your code names. These regions will then be used by the backends to provide you with different metrics about the region. Before diving into the hands-on we will shortly explain the two kinds of annotating regions. In short, the regions either form a perfectly nested hirachie, where the regions are non-overlapping in the same level. The alternative to that is an overlapping annotation. In neSmiK the first version is the one that is preferred, as its the more special case, and not all backends support the non-overlapping anntation.

To get started you wanna look at our API section where you find the APIs for C++, C and Fortran

General Usage Hints

Its very common to find some sort of region annotation in HPC-targeting codes. Normally the developers already made some effort to add region information to their code. With neSmiK it should be very easy to hook into these already existing annotations, as the API is designed to only require minimal information, namely the name.

Firstly, make sure that you properly linked your application with neSmiK. If the application is a MPI-Application you want to consider enabling MPI support in neSmiK as well.

NeSmiK does not need to be initialized, but will automatically initialize when its called the first time. In MPI-Application its important, that the first call to neSmiK happens after the MPI_Init.

To ensure correct data its important to finalize neSmiK. In MPI-Applications please put the finalization call nesmik_finalize() before the MPI_Finalize(). In other applications just make sure, that the call to nesmik_finalize() is after all calls to the neSmiK API.

If you’re application does not provide any region annotations yet, it makes sense to have a rough algorithmic overview before doing the annotation. After this you have to make the choice of either doing a properly nested annotation, which we strongly recommend, if you dont have good reasons to deviate.