---------------------------------------
Application Performance Snapshot README
---------------------------------------
Use Application Performance Snapshot (APS) for a quick view into a serial or
MPI application's use of available hardware (CPU, FPU, and Memory). 
Application Performance Snapshot analyzes your application's time spent in 
MPI, MPI and OpenMP imbalance, memory access efficiency, FPU usage, and I/O 
and memory footprint.  After analysis, it displays basic performance 
enhancement opportunities for systems using Intel(R) platforms.

Use this tool as a first step in application performance analysis to get a
simple snapshot of key optimization areas.

-------------
Prerequisites
-------------
Optional: Use the following software to get an advanced metric set when 
running Application Performance Snapshot:

* Intel(R) C/C++ or Fortran Compiler (for OpenMP* metrics support)
* Intel(R) MPI Library 2018 or later or any MPICH-based MPI implementation
  (for MPI analysis)

Optional: Enable system-wide monitoring to reduce collection overhead and 
collect memory bandwidth measurements. Use one of these options to enable 
system-wide monitoring:

* Set the /proc/sys/kernel/perf_event_paranoid value to 0 (or less), or
* Install the Intel® VTune™ Amplifier drivers. Driver sources are available in
  <APS_install_dir>/internal/sepdk/src. Installation instructions are available
  online at https://software.intel.com/en-us/vtune-amplifier-help-sep-driver
  
------------------------------
Analyzing Non-MPI Applications
------------------------------
1. Set the environment variables for the tool:
   $ source <install-dir>/apsvars.sh
2. Collect performance data:
   $ aps <my_app> <app_parameters>
3. Review the report that appears in the command window or open the
   automatically-generated HTML report aps_result.html.

--------------------------
Analyzing MPI Applications
--------------------------
1. Set the environment variables for the tool:
   $ source <install-dir>/apsvars.sh
2. Collect performance data:
   $ <mpi_launcher> <mpi_parameters> aps <my_app> <app_parameters>
   NOTE: aps must be the last MPI launcher argument.
3. Generate a report based on the data collected:
   $ aps --report=aps_result_<date>
4. Review the report that appears in the command window or open the
   automatically-generated HTML report aps_result.html.
5. If your application is MPI-bound, run the following command to 
   get more details:
   $ aps-reports <option> app_result_<date>

-----------------
Metrics Reference
-----------------
Elapsed Time: Execution time of specified application in seconds.

SP GFLOPS: Number of single precision giga-floating point operations 
calculated per second. All double operations are converted to two single 
operations. SP GFLOPS metrics are only available for 3rd Generation 
Intel® Core™ processors, 5th Generation Intel processors, and 6th 
Generation Intel processors.

Cycles per Instruction Retired (CPI): The amount of time each executed 
instruction took measured by cycles. A CPI of 1 is considered acceptable 
for high performance computing (HPC) applications, but different 
application domains will have varied expected values. The CPI value tends 
to be greater when there is long-latency memory, floating-point, or SIMD 
operations, non-retired instructions due to branch mispredictions, or 
instruction starvation at the front end.

MPI Time: Average time per process spent in MPI calls. This metric does not 
include the time spent in MPI_Finalize. High values could be caused by high 
wait times inside the library, active communications, or sub-optimal settings 
of the MPI library. The metric is available for MPICH-based MPIs.

MPI Imbalance: CPU time spent by ranks spinning in waits on communication 
operations. A high value can be caused by application workload imbalance 
between ranks, or non-optimal communication schema or MPI library settings. 
This metric is available only for Intel® MPI Library version 2017 and later.

OpenMP Imbalance: Percentage of elapsed time that your application wastes at 
OpenMP* synchronization barriers because of load imbalance. This metric is 
only available for Intel® OpenMP* Runtime Library.

CPU Utilization: Estimate of the utilization of all logical CPU cores on the 
system by your application. Use this metric to help evaluate the parallel 
efficiency of your application. A utilization of 100% means that your 
application keeps all of the logical CPU cores busy for the entire time that 
it runs. Note that the metric does not distinguish between useful application 
work and the time that is spent in parallel runtimes.

Memory Stalls: Indicates how memory subsystem issues affect application 
performance. This metric measures a fraction of slots where pipeline could 
be stalled due to demand load or store instructions. If the metric value is 
high, review the Cache and DRAM Stalls and the percent of remote accesses 
metrics to understand the nature of memory-related performance bottlenecks.
If the average memory bandwidth numbers are close to the system bandwidth
limit, optimization techniques for memory bound applications may be required
to avoid memory stalls.

FPU Utilization: The effective FPU usage while the application was running. 
Use the FPU Utilization value to evaluate the vector efficiency of your 
application. The value is calculated by estimating the percentage of 
operations that are performed by the FPU. A value of 100% means that the FPU 
is fully loaded. Any value over 50% requires additional analysis. FPU metrics 
are only available for 3rd Generation Intel Core processors, 5th Generation 
Intel processors, and 6th Generation Intel processors.

I/O Operations: The time spent by the application while reading data from the 
disk or writing data to the disk. Read and Write values denote mean and 
maximum amounts of data read and written during the elapsed time. This metric 
is only available for MPI applications.

Memory Footprint: Average per-rank and per-node consumption of both virtual
and resident memory.

--------------------
Additional Resources
--------------------
Intel(R) Performance Snapshot User Forum:
https://software.intel.com/en-us/forums/intel-performance-snapshot

Application Performance Snapshot Web Page:
https://software.intel.com/sites/products/snapshots/application-snapshot/

Application Performance Snapshot User's Guide:
https://software.intel.com/en-us/application-snapshot-user-guide

-------------------------------------------------------------------------------
Intel and the Intel logo are trademarks of Intel Corporation in the U.S. and/or
other countries.
* Other names and brands may be claimed as the property of others.
(C) Intel Corporation