Documentation updates

Author: daboehme

README.md

@@ -7,13 +7,11 @@ Caliper: A Performance Analysis Toolbox in a Library
 
 Caliper is a performance instrumentation and profiling library for HPC
 (high-performance computing) programs. It provides source-code annotation
-APIs for marking regions of interest in C, C++, and Fortran code, as well as
-a set of built-in performance measurement recipes for a wide range of
-performance engineering use cases, such as lightweight always-on profiling,
-event tracing, or performance monitoring. Alternatively, users can create
-custom measurement configurations for specialized use cases.
+APIs for marking regions of interest in C, C++, Fortran, and Python codes,
+as well as performance measurement functionality for a wide range of use cases,
+such as runtime profiling, event tracing, and performance monitoring.
 
-Caliper can either generate simple human-readable reports or machine-readable
+Caliper can generate simple human-readable reports or machine-readable
 JSON or .cali files for automated data processing with user-provided scripts
 or analysis frameworks like [Hatchet](https://github.com/LLNL/hatchet)
 and [Thicket](https://github.com/LLNL/thicket).
@@ -29,15 +27,11 @@ Features include:
 * Flexible key:value data model to capture application-specific
   features for performance analysis
 * Fully threadsafe implementation, support for parallel programming
-  models like MPI
-* Event-based as well as sample-based performance measurements
+  models like MPI, OpenMP, Kokkos, CUDA, and ROCm
+* Event-based and sample-based performance measurements
 * Trace and profile recording
 * Connection to third-party tools, e.g. NVidia's NSight tools, AMD
   ROCProf, or Intel(R) VTune(tm)
-* Measurement and profiling functionality such as timers, PAPI
-  hardware counters, and Linux perf_events
-* Memory annotations to associate performance measurements
-  with memory regions
 
 Documentation
 ------------------------------------------
@@ -58,9 +52,8 @@ package manager:
 
     $ spack install caliper
 
-To build Caliper manually, you need cmake 3.12+ and a current
-C++11-compatible Compiler. Clone Caliper from github and proceed
-as follows:
+Building Caliper manually requires cmake 3.12+ and a C++11-compatible
+Compiler. Clone Caliper from github and proceed as follows:
 
     $ git clone https://github.com/LLNL/Caliper.git
     $ cd Caliper
@@ -156,7 +149,7 @@ Other measurement configurations besides runtime-report include:
 
 * loop-report: Print summary and time-series information for loops.
 * mpi-report: Print time spent in MPI functions.
-* callpath-sample-report: Print a time spent in functions using call-path sampling.
+* sample-report: Print time spent in functions using sampling.
 * event-trace: Record a trace of region enter/exit events in .cali format.
 * hatchet-region-profile: Record a region time profile for processing with
   [Hatchet](https://github.com/LLNL/hatchet) or cali-query.
@@ -168,47 +161,6 @@ You can also create entirely custom measurement configurations by selecting and
 configuring Caliper services manually. See the "Manual configuration" section
 in the documentation to learn more.
 
-#### ConfigManager API
-
-A distinctive Caliper feature is the ability to enable performance
-measurements programmatically with the ConfigManager API. For example, we often
-let users activate performance measurements with a command-line argument.
-
-With the C++ ConfigManager API, built-in performance measurement and
-reporting configurations can be activated within a program using a short
-configuration string. This configuration string can be hard-coded in the
-program or provided by the user in some form, e.g. as a command-line
-parameter or in the programs's configuration file.
-
-To use the ConfigManager API, create a `cali::ConfigManager` object, add a
-configuration string with `add()`, start the requested configuration
-channels with `start()`, and trigger output with `flush()`:
-
-```C++
-#include <caliper/cali-manager.h>
-// ...
-cali::ConfigManager mgr;
-mgr.add("runtime-report");
-// ...
-mgr.start(); // start requested performance measurement channels
-// ... (program execution)
-mgr.flush(); // write performance results
-```
-
-The `cxx-example` program uses the ConfigManager API to let users specify a
-Caliper configuration with the `-P` command-line argument, e.g.
-``-P runtime-report``:
-
-    $ ./examples/apps/cxx-example -P runtime-report
-    Path       Min time/rank Max time/rank Avg time/rank Time %
-    main            0.000129      0.000129      0.000129  5.952930
-      mainloop      0.000080      0.000080      0.000080  3.691740
-        foo         0.000719      0.000719      0.000719 33.179511
-      init          0.000021      0.000021      0.000021  0.969082
-
-See the [Caliper documentation](https://software.llnl.gov/Caliper) for more
-examples and the full API and configuration reference.
-
 Authors
 ------------------------------------------
 

doc/sphinx/AnnotationAPI.rst

@@ -267,8 +267,8 @@ following example shows both::
                     num_dimensions);
             ...
 
-        CALI_DATATRACKER_FREE(arrayA);
-        CALI_DATATRACKER_FREE(matA);
+        CALI_DATATRACKER_UNTRACK(arrayA);
+        CALI_DATATRACKER_UNTRACK(matA);
     }
 
 API Reference

doc/sphinx/CaliperBasics.rst

@@ -102,9 +102,9 @@ With the source-code annotations in place, we can run performance measurements.
 By default, Caliper does not record data - we have to activate performance
 profiling at runtime.
 An easy way to do this is to use one of Caliper's built-in measurement
-configurations. For example, the `runtime-report` config prints out the time
+recipes. For example, the `runtime-report` recipe prints out the time
 spent in the annotated regions. You can activate built-in measurement
-configurations with the :ref:`configmgr_api` or with the
+recipes with the :ref:`configmgr_api` or with the
 :envvar:`CALI_CONFIG` environment variable.
 Let's try this on Caliper's cxx-example program:
 
@@ -119,7 +119,7 @@ Let's try this on Caliper's cxx-example program:
         foo         0.000646      0.000646      0.000646 38.429506
       init          0.000017      0.000017      0.000017  1.011303
 
-Like most built-in configurations, the runtime-report config works for MPI and
+Like most built-in recipes, the runtime-report config works for MPI and
 non-MPI programs. By default, it reports the minimum, maximum, and average
 exclusive time (seconds) spent in each marked code region across MPI ranks
 (the three values are identical in non-MPI programs). Exclusive time is the
@@ -140,8 +140,8 @@ of exclusive region times:
         foo         0.000624      0.000624      0.000624 52.392947
       init          0.000003      0.000003      0.000003  0.251889
 
-Caliper provides many more performance measurement configurations in addition
-to `runtime-report` that make use of region annotations. For example,
+Caliper provides many more performance measurement configurations that
+make use of region annotations. For example,
 `hatchet-region-profile` writes a .cali file with region times for processing
 with `Hatchet <https://github.com/LLNL/hatchet>`_. See
 :ref:`more-on-configurations` below to learn more about different
@@ -248,12 +248,12 @@ measurements programmatically with the ConfigManager API. For example, we often
 let users activate performance measurements with a command-line argument.
 
 The ConfigManager API provides access to Caliper's built-in measurement
-configurations (see :ref:`more-on-configurations` below). The ConfigManager
+recipes (see :ref:`more-on-configurations` below). The ConfigManager
 interprets a short configuration string that can be hard-coded in the program
 or provided by the user in some form, e.g. as a command-line parameter or
 in the program's configuration file.
 
-To access and control the built-in configurations, create a
+To use the ConfigManager API, create a
 :cpp:class:`cali::ConfigManager` object. Add a configuration string with
 ``add()``, start the requested configuration channels with ``start()``,
 and trigger output with ``flush()``. In MPI programs, the ``flush()`` method
@@ -321,25 +321,20 @@ More on configurations
 --------------------------------
 
 A configuration string for the ConfigManager API or the
-:envvar:`CALI_CONFIG` environment variable is a comma-separated list of
-*configs* and *parameters*.
+:envvar:`CALI_CONFIG` environment variable is a list of
+*configs* (like `runtime-report`) and *parameters*.
+Multiple configs can be specified, separated by comma.
 
-A *config* is the name of one of Caliper's built-in measurement configurations,
-e.g. `runtime-report`. Multiple configs can be specified, separated by comma.
-
-Most configs have optional parameters, e.g. `output` to name an output file.
-Parameters can be specified as a list of key-value pairs in parentheses after
-the config name, e.g. `runtime-report(output=report.txt,io.bytes)`. For
+Parameters can configure output options or enable additional functionality.
+They can be specified as a list of key-value pairs in parentheses
+after the config name, e.g. `runtime-report(output=report.txt,io.bytes)`. For
 boolean parameters, only the key needs to be added to enable it; for example,
 `io.bytes` is equal to `io.bytes=true`. You can also add parameters outside
 of parentheses; these apply to all configs.
 
-Many optional parameters enable additional Caliper functionality. For example,
-the `profile.mpi` option enables MPI function profiling, the `io.bytes` option
-reports I/O bytes written and read, and the `mem.highwatermark` option reports
-the memory high-watermark. In the example below, the `mem.highwatermark`
-option for `runtime-report` adds the "Allocated MB" column that shows the
-maximum amount of memory that was allocated in each region:
+In the example below, we enable the `mem.highwatermark` option in
+`runtime-report`. This adds the "Allocated MB" column that shows the maximum
+amount of memory that was allocated in each region:
 
 .. code-block:: sh
 
@@ -350,12 +345,11 @@ maximum amount of memory that was allocated in each region:
         foo         0.000778      0.000778      0.000778 8.930211     0.000016
       init          0.000020      0.000020      0.000020 0.229568     0.000000
 
-You can use the cali-query program to list available configs and their parameters.
-For example, ``cali-query --help=configs`` lists all configs and their options.
-You can also query parameters for a specific config, e.g.
+You can use ``cali-query --help=configs`` to list all available recipes and their
+parameters. You can also query parameters for a specific recipe, e.g.
 ``cali-query --help=runtime-report``.
 
-Some available performance measurement configs include:
+Some available performance measurement recipes include:
 
 runtime-report
    Print a time profile for annotated regions.
@@ -429,8 +423,21 @@ Like other region annotations, loop and iteration annotations are meant for
 high-level regions, not small, frequently executed loops inside kernels.
 We recommend to only annotate top-level loops, such as the main timestepping
 loop in a simulation code.
-With the loop annotations in place, we can use the loop-report config to print
-loop performance information:
+
+With loop annotations in place, we can use the `loop.stats` option to print
+the minimum, maximum, and average time per loop iteration:
+
+.. code-block:: sh
+
+    $ ./examples/apps/cxx-example -P runtime-report,loop.stats 5000
+    Path       Time (E) Time (I) Time % (E) Time % (I) Iterations Time/iter (min) Time/iter (avg) Time/iter (max)
+    main       0.000070 8.010493   0.000870  99.995709
+      init     0.000004 0.000004   0.000047   0.000047
+      mainloop 0.172615 8.010420   2.154765  99.994792       5000        0.000110        0.001591        0.003317
+        foo    7.837805 7.837805  97.840027  97.840027
+
+More detailed loop timing information is available with the loop-report
+recipe:
 
 .. code-block:: sh
 
@@ -571,27 +578,6 @@ save global attributes in the form of key-value pairs:
     cali_set_global_int_byname("iterations", iterations);
     cali_set_global_string_byname("caliper.config", configstr.c_str());
 
-Most machine-readable output formats, e.g. the hatchet JSON format written by the
-hatchet-region-profile config, include this data:
-
-.. code-block:: sh
-
-    $ ./examples/apps/cxx-example -P hatchet-region-profile,output=stdout
-    {
-    "data": [
-        ...
-    ],
-    ...
-    "caliper.config": "hatchet-region-profile,output=stdout",
-    "iterations": "4",
-    "cali.caliper.version": "2.5.0-dev",
-    "cali.channel": "hatchet-region-profile"
-    }
-
-Note how the "iterations" and "caliper.config" attributes are stored as
-top-level attributes in the JSON output. Caliper adds some built-in metadata
-attributes as well, such as the Caliper version ("cali.caliper.version").
-
 An even better way to record metadata is the `Adiak <https://github.com/LLNL/Adiak>`_
 library. Adiak makes metadata attributes accessible to multiple tools, and
 provides built-in functionality to record common information such as user
@@ -608,7 +594,7 @@ above, and also the user name, launch date, and MPI job size:
     adiak::value("iterations", iterations);
     adiak::value("caliper.config", configstr.c_str());
 
-Most Caliper configs automatically import metadata attributes set through
+Most Caliper recipes automatically import metadata attributes set through
 Adiak (Adiak support must be enabled in the Caliper build configuration). The
 spot config for the Spot web visualization framework requires that metadata
 attributes are recorded through Adiak.

doc/sphinx/build.rst

@@ -88,6 +88,10 @@ WITH_ROCTRACER
   Enable support for ROCm/HIP performance analysis (runtime API profiling and
   GPU activity tracing).
 
+WITH_ROCPROFILER
+  Enable roctx adapters and support for ROCm/HIP performance analysis with the
+  rocprofiler-sdk API (available with ROCm 6.2 and higher).
+
 WITH_SAMPLER
   Enable time-based sampling on Linux.
 
@@ -143,8 +147,6 @@ The CMake package defines the following variables and targets:
 +----------------------------+------------------------------------------+
 | caliper                    | The Caliper runtime library (target)     |
 +----------------------------+------------------------------------------+
-| caliper-tools-util         | Utilities for caliper tools (target)     |
-+----------------------------+------------------------------------------+
 
 In most cases, just link the "caliper" target.