diff --git a/.readthedocs.yaml b/.readthedocs.yaml new file mode 100644 index 0000000000000000000000000000000000000000..e952a46c9516ffc40123749924c23e70941b2c95 --- /dev/null +++ b/.readthedocs.yaml @@ -0,0 +1,35 @@ +# Read the Docs configuration file for Sphinx projects +# See https://docs.readthedocs.io/en/stable/config-file/v2.html for details + +# Required +version: 2 + +# Set the OS, Python version and other tools you might need +build: + os: ubuntu-22.04 + tools: + python: "3.12" + # You can also specify other tool versions: + # nodejs: "20" + # rust: "1.70" + # golang: "1.20" + +# Build documentation in the "docs/" directory with Sphinx +sphinx: + configuration: docs/source/conf.py + # You can configure Sphinx to use a different builder, for instance use the dirhtml builder for simpler URLs + # builder: "dirhtml" + # Fail on all warnings to avoid broken references + # fail_on_warning: true + +# Optionally build your docs in additional formats such as PDF and ePub +# formats: +# - pdf +# - epub + +# Optional but recommended, declare the Python requirements required +# to build your documentation +# See https://docs.readthedocs.io/en/stable/guides/reproducible-builds.html +python: + install: + - requirements: docs/requirements.txt diff --git a/docs/requirements.txt b/docs/requirements.txt new file mode 100644 index 0000000000000000000000000000000000000000..6b104fb015c67247b6bf77ac9b3388341d2ceee7 --- /dev/null +++ b/docs/requirements.txt @@ -0,0 +1,2 @@ +Sphinx +sphinx-rtd-theme diff --git a/docs/source/backends.rst b/docs/source/backends.rst new file mode 100644 index 0000000000000000000000000000000000000000..43f517e11a481d5948c104c6d5b96f5a919087ed --- /dev/null +++ b/docs/source/backends.rst @@ -0,0 +1,73 @@ +.. _using_backends: + +********************** +Using Backends +********************** +In this section you can find useful information of the different backends currently implemented. + + +``Default`` +======================= + +Parallelism Properties +----------------------- +| **MPI**: :ref:`Dont care ` +| **Threading**: :ref:`Supported ` + + +Supported Nestings +-------------------- +* :ref:`ProperlyNested ` +* :ref:`NotProperlyNested ` + +Description +------------- + +The ``Default`` backend implements both **ProperlyNested** and **NotProperlyNested** versions. +This backend will just print the region name to the stdandart out and can be used to check if neSmiK is working correctly. + +Options +--------- + +This backend does not contain any options. + + + +``Extrae::TypeStack`` +======================= + +Parallelism Properties +----------------------- +| **MPI**: :ref:`Aware ` +| **Threading**: :ref:`Supported ` + + +Supported Nestings +-------------------- +* :ref:`ProperlyNested ` + +Requirements +------------- + +* ``-DWITH_EXTRAE=ON`` + + +Description +------------- +The ``Extrae::TypeStack`` provides a way to display your annotations in paraver. + + +Options +--------- + +This backend does not contain any options. + + + +``TALP`` +======================= + + + +``TALP::Tree`` +======================= diff --git a/docs/source/concepts.rst b/docs/source/concepts.rst new file mode 100644 index 0000000000000000000000000000000000000000..5941df5a69ab54d6b7a51b210e6a68a77bf1feda --- /dev/null +++ b/docs/source/concepts.rst @@ -0,0 +1,54 @@ +.. _theory: + +********************** +A bit of theory +********************** + +.. _theory_nesting: + +Nesting of regions +===================== + +.. _properly_nested: + +ProperlyNested +---------------- + + +.. _not_properly_nested: + +NotProperlyNested +------------------- + + + + +Parallelism awareness +====================== + +.. _parallelism_mpi: + +MPI +---- + + +**Dont Care:** + + +**Aware:** + + +**Required:** + + + + +.. _parallelism_threading: + +Threading +----------- + +**Not supported:** + + +**Supported:** diff --git a/docs/source/conf.py b/docs/source/conf.py index 336b1fe591eee28bbd85fc35829ce1936caab3ab..90cbac9fc2d72fb57139daf552bf3de0c73e4a19 100644 --- a/docs/source/conf.py +++ b/docs/source/conf.py @@ -16,8 +16,10 @@ release = '0.0.1' extensions = [ 'sphinx_rtd_theme', + #'sphinx_rtd_size', ] +#sphinx_rtd_size_width = "80%" diff --git a/docs/source/how-to-guides.rst b/docs/source/how-to-guides.rst new file mode 100644 index 0000000000000000000000000000000000000000..ddb1d39e3c8ab212e64a9c833339841c8f45e99b --- /dev/null +++ b/docs/source/how-to-guides.rst @@ -0,0 +1,105 @@ +****************** +How to guides +****************** + +First steps +=========================== + +Installation +-------------- + +If neSmiK is not already available in the machine, you need to install it yourself. Please consult the :ref:`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 :ref:`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: + + +.. code-block:: cmake + + 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( PRIVATE nesmik::nesmik) # Link your application privatly with nesmik to 1) include the header and 2) link libnesnik + target_compile_definitions( 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 )`` 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 `` similar to: + +.. code-block:: bash + + [user@machine build]$ ldd ./ + linux-vdso.so.1 (0x00007ffd7555f000) + libnesmik.so => /lib/libnesmik.so (0x00007387972bc000) + + + +After this you can start to :ref:`annotate ` you're application. + +.. _annotate-applications: + +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 bakcends 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 learn more about these concepts you can have a look at: :ref:`theory_nesting` + + +Using existing annotation +------------------------- + +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. + +The most crucial part is to call the neSmiK ``init("?","Default")`` and ``finalize()`` methods. +In MPI applications, we consider it good practice to put the nesmik ``init`` directly after the ``MPI_Init()``. +If you compiled with MPI support, neSmiK required MPI to be already initialized upon the time its initializer is called. +In non-MPI applications it just needs to be enshured, that the call to ``init`` is done **before** any other nesmik calls are issued. + +To finalize nesmik in MPI-Applications please put the ``finalize()`` before the ``MPI_Finalize()``. +In other applications just make sure, that the call to ``finalize()`` is **after** all calls to the neSmiK API. + +After that its as easy as intercepting the calls of the internal solution and returning early after calling neSmiK. +Its more encouraged to be using the explicit annotation api TODO: ref than the one that assumes that its properly nested. + + + + +Creating your own annotation +-------------------------------- + +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. + +After this just insert the corresponding neSmiK API calls. + + +Using different backends +=========================== diff --git a/docs/source/index.rst b/docs/source/index.rst index 250579625b030a803ea1877e4366d599719864e2..569d023d9089e9e2783bf1e890cd7c337db9e73b 100644 --- a/docs/source/index.rst +++ b/docs/source/index.rst @@ -3,18 +3,26 @@ You can adapt this file completely to your liking, but it should at least contain the root `toctree` directive. -Welcome to nesmik's documentation! -================================== +Welcome the documentation of neSmiK +==================================== + +In this documentation we try to follow the `diataxis concept `_. +We are also happy about feedback or contributions to this documentation. +Feel free to consult our GitLab page for more information on how to contribute. + .. toctree:: :maxdepth: 2 - :caption: Contents: + :caption: I wanna use neSmiK: + + install + how-to-guides + backends + concepts -Indices and tables -================== -* :ref:`genindex` -* :ref:`modindex` -* :ref:`search` +.. toctree:: + :maxdepth: 2 + :caption: I want to contribute to neSmiK: diff --git a/docs/source/install.rst b/docs/source/install.rst new file mode 100644 index 0000000000000000000000000000000000000000..dc8979b044144233098250d7bb4f1bfa91091d54 --- /dev/null +++ b/docs/source/install.rst @@ -0,0 +1,81 @@ +.. _installation-guide: + +********************** +How to install neSmiK +********************** + +In the following we describe the process to install the neSmiK. +Currently, we only support GNU/Linux based systems. +We will firstly introduce the requirements needed to install neSmiK, followed by a quick overview of the configuration options +and a guide on how to install neSmiK. + +Requirements +============= + +* The source files of nesmik e.g downloaded via a `git clone` or a release `.tar.gz` file. +* CMake >= 3.27 +* C++ 17 compatible compiler +* Internet connection during install (to fetch nlohmann_json automagically) + +Optional dependencies +====================== + +Backends +--------- + +* `DLB `_ to enable the DLB backends +* `Extrae `_ to enable the Extrae Backends + + +Bindings +--------- + +* Fortran compiler to generate the neSmiK module. (*Be aware that Fortran modules are compiler specific, so you should compiler your application with the same Fortran compiler as neSmiK*) + + +Configuration options +======================= +Currently, as neSmiK is a rapidly changing code, please take these options as not exhaustive. +We try to keep the documentation up-to-date, but newer versions may contain more or less options. + + +.. list-table:: + :widths: 25 25 50 + :header-rows: 1 + + * - Option + - Default + - Description + * - ENABLE_EXTRAE + - OFF + - Enables the Extrae based backends + * - ENABLE_DLB + - OFF + - Enables the DLB-TALP based backends + * - BUILD_C_FORTRAN + - ON + - Builds the Fortran module and C Bindings + * - SPLIT_FORTRAN_LIBRARY + - OFF + - **EXPERIMENTAL** Splits the fortran symbols into a different static library `nesmik_f` + * - INSTALL_WITH_RPATH + - OFF + - leaves the RUNPATH of dependencies in the shared object upon installation. + * - WITH_MPI + - OFF + - Enables MPI-awareness (If you wanna use neSmiK in an MPI program, please enable) + + + +Installation steps +======================= + +* Get a copy of neSmiK either via a ``git clone`` or downloading a release version. +* Use the same environment and compilers you used to compiler your application with. (This is mainly important to ensure thread safety, as we use thread_local storage) +* create a build directory like inside the neSmiK source folder: ``mkdir build && cd build`` +* configure the project with a command similar to, depending on your needs: ``cmake .. -DCMAKE_INSTALL_PREFIX= -DENABLE_EXTRAE=ON`` +* by default cmake will generate a ``Makefile``, so as a next step run ``make && make install`` +* In order to run the small test suite you can invoke ``ctest`` in the build folder. + + +**Congrats!** Now you can move forward to TODO: integrate neSmiK into your `projects build system` and `start annotation code`