Review of C++ Sample READMEs (oneapi-src#852)

bdmoore1 · web-flow · commit 74219c4fa87f · 2022-02-16T13:26:57.000-08:00
* Review of C++ Sample READMEs

For each readme in the AI-and-Analytics folder, I reviewed and updated to include consistent instructions for:

Using VS Code
sourcing or running setvars
troubleshooting with the diagnostics utility

* Shortened setvars
diff --git a/DirectProgramming/C++/CombinationalLogic/MandelbrotOMP/README.md b/DirectProgramming/C++/CombinationalLogic/MandelbrotOMP/README.md
@@ -54,13 +54,25 @@ The basic steps to build and run a sample using VS Code include:
 oneAPI toolkits using the **Generate Launch Configurations** extension.
 
 To learn more about the extensions, see
-[Using Visual Studio Code with Intel® oneAPI Toolkits](https://software.intel.com/content/www/us/en/develop/documentation/using-vs-code-with-intel-oneapi/top.html).
+[Using Visual Studio Code with Intel® oneAPI Toolkits](https://www.intel.com/content/www/us/en/develop/documentation/using-vs-code-with-intel-oneapi/top.html).
 
 After learning how to use the extensions for Intel oneAPI Toolkits, return to this readme for instructions on how to build and run a sample.
 
 
 ## Building the `Mandelbrot` Program
 
+> **Note**: If you have not already done so, set up your CLI
+> environment by sourcing  the `setvars` script located in
+> the root of your oneAPI installation.
+>
+> Linux Sudo: . /opt/intel/oneapi/setvars.sh
+>
+> Linux User: . ~/intel/oneapi/setvars.sh
+>
+> Windows: C:\Program Files(x86)\Intel\oneAPI\setvars.bat
+>
+>For more information on environment variables, see Use the setvars Script for [Linux or macOS](https://www.intel.com/content/www/us/en/develop/documentation/oneapi-programming-guide/top/oneapi-development-environment-setup/use-the-setvars-script-with-linux-or-macos.html), or [Windows](https://www.intel.com/content/www/us/en/develop/documentation/oneapi-programming-guide/top/oneapi-development-environment-setup/use-the-setvars-script-with-windows.html).
+
 Perform the following steps:
 1. Build the program using the following `make` commands.
 ```
@@ -78,6 +90,8 @@ $ make
     make clean
     ```
 
+If an error occurs, troubleshoot the problem using the Diagnostics Utility for Intel® oneAPI Toolkits.
+[Learn more](https://software.intel.com/content/www/us/en/develop/documentation/diagnostic-utility-user-guide/top.html)
 
 ## Running the Sample
 
diff --git a/DirectProgramming/C++/CompilerInfrastructure/Intrinsics/README.md b/DirectProgramming/C++/CompilerInfrastructure/Intrinsics/README.md
@@ -45,12 +45,24 @@ The basic steps to build and run a sample using VS Code include:
  - Run the sample in the VS Code terminal using the instructions below.
 
 To learn more about the extensions and how to configure the oneAPI environment, see
-[Using Visual Studio Code with Intel® oneAPI Toolkits](https://software.intel.com/content/www/us/en/develop/documentation/using-vs-code-with-intel-oneapi/top.html).
+[Using Visual Studio Code with Intel® oneAPI Toolkits](https://www.intel.com/content/www/us/en/develop/documentation/using-vs-code-with-intel-oneapi/top.html).
 
 After learning how to use the extensions for Intel oneAPI Toolkits, return to this readme for instructions on how to build and run a sample.
 
 ## Building the `Intrinsics` Program
 
+> **Note**: If you have not already done so, set up your CLI
+> environment by sourcing  the `setvars` script located in
+> the root of your oneAPI installation.
+>
+> Linux Sudo: . /opt/intel/oneapi/setvars.sh
+>
+> Linux User: . ~/intel/oneapi/setvars.sh
+>
+> Windows: C:\Program Files(x86)\Intel\oneAPI\setvars.bat
+>
+>For more information on environment variables, see Use the setvars Script for [Linux or macOS](https://www.intel.com/content/www/us/en/develop/documentation/oneapi-programming-guide/top/oneapi-development-environment-setup/use-the-setvars-script-with-linux-or-macos.html), or [Windows](https://www.intel.com/content/www/us/en/develop/documentation/oneapi-programming-guide/top/oneapi-development-environment-setup/use-the-setvars-script-with-windows.html).
+
 Perform the following steps:
 1. Build the program using the following `make` commands.
 ```
@@ -67,6 +79,8 @@ $ make (or "make debug" to compile with the -g flag)
     make clean
     ```
 
+If an error occurs, troubleshoot the problem using the Diagnostics Utility for Intel® oneAPI Toolkits.
+[Learn more](https://software.intel.com/content/www/us/en/develop/documentation/diagnostic-utility-user-guide/top.html)
 
 ### Application Parameters
 
diff --git a/DirectProgramming/C++/CompilerInfrastructure/OpenMP_Offload_Features/README.md b/DirectProgramming/C++/CompilerInfrastructure/OpenMP_Offload_Features/README.md
@@ -63,13 +63,17 @@ After learning how to use the extensions for Intel oneAPI Toolkits, return to th
 
 ## Building the Program
 
-> Note: if you have not already done so, set up your CLI
-> environment by sourcing  the setvars script located in
+> **Note**: If you have not already done so, set up your CLI
+> environment by sourcing  the `setvars` script located in
 > the root of your oneAPI installation.
 >
 > Linux Sudo: . /opt/intel/oneapi/setvars.sh
+>
 > Linux User: . ~/intel/oneapi/setvars.sh
+>
 > Windows: C:\Program Files(x86)\Intel\oneAPI\setvars.bat
+>
+>For more information on environment variables, see Use the setvars Script for [Linux or macOS](https://www.intel.com/content/www/us/en/develop/documentation/oneapi-programming-guide/top/oneapi-development-environment-setup/use-the-setvars-script-with-linux-or-macos.html), or [Windows](https://www.intel.com/content/www/us/en/develop/documentation/oneapi-programming-guide/top/oneapi-development-environment-setup/use-the-setvars-script-with-windows.html).
 
 
 ### Running Samples In DevCloud
@@ -105,6 +109,9 @@ Perform the following steps:
     make clean
     ```
 
+If an error occurs, troubleshoot the problem using the Diagnostics Utility for Intel® oneAPI Toolkits.
+[Learn more](https://software.intel.com/content/www/us/en/develop/documentation/diagnostic-utility-user-guide/top.html)
+
 ### Example of Output
 
 ```
diff --git a/DirectProgramming/C++/GraphTraversal/MergesortOMP/README.md b/DirectProgramming/C++/GraphTraversal/MergesortOMP/README.md
@@ -22,14 +22,28 @@ Performance number tabulation
 
 ## Purpose
 
-Merge sort is a highly efficient recursive sorting algorithm. Known for its greater efficiency over other common sorting algorithms, it can compute in O(nlogn) time instead of O(n^2), making it a common choice for sorting implementations that deal with large quantities of elements. While it is already a very fast algorithm-- capable of sorting lists in a fraction of the time it would take an algorithm such as quicksort or insertion sort, it can be further accelerated with parallelism using OpenMP.
+Merge sort is a highly efficient recursive sorting algorithm. Known for its
+greater efficiency over other common sorting algorithms, it can compute in
+O(nlogn) time instead of O(n^2), making it a common choice for sorting
+implementations that deal with large quantities of elements. While it is
+already a very fast algorithm-- capable of sorting lists in a fraction of the
+time it would take an algorithm such as quicksort or insertion sort, it can be
+further accelerated with parallelism using OpenMP.
 
-This code sample demonstrates how to convert a scalar implementation of merge sort into a parallelized version with minimal changes to the original, using OpenMP pragmas.
+This code sample demonstrates how to convert a scalar implementation of merge
+sort into a parallelized version with minimal changes to the original, using
+OpenMP pragmas.
 
 
 ## Key Implementation Details
 
-The OpenMP* version of the merge sort implementation uses the #pragma omp task in its recursive calls, which allows the recursive calls to be handled by different threads. The #pragma omp taskawait preceding the function call to merge() ensures the two recursive calls are completed before the merge() is executed. Through this use of OpenMP* pragmas, the recursive sorting algorithm can effectively run in parallel, where each recursion is a unique task able to be performed by any available thread.
+The OpenMP* version of the merge sort implementation uses the #pragma omp task
+in its recursive calls, which allows the recursive calls to be handled by
+different threads. The #pragma omp taskawait preceding the function call to
+merge() ensures the two recursive calls are completed before the merge() is
+executed. Through this use of OpenMP* pragmas, the recursive sorting algorithm
+can effectively run in parallel, where each recursion is a unique task able to
+be performed by any available thread.
 
 ## License
 
@@ -42,8 +56,8 @@ Third party program Licenses can be found here: [third-party-programs.txt](https
 
 ### Using Visual Studio Code*  (Optional)
 
-You can use Visual Studio Code (VS Code) extensions to set your environment, create launch configurations,
-and browse and download samples.
+You can use Visual Studio Code (VS Code) extensions to set your environment,
+create launch configurations, and browse and download samples.
 
 The basic steps to build and run a sample using VS Code include:
  - Download a sample using the extension **Code Sample Browser for Intel oneAPI Toolkits**.
@@ -58,6 +72,18 @@ After learning how to use the extensions for Intel oneAPI Toolkits, return to th
 
 ## Building the `Merge Sort` Program
 
+> **Note**: If you have not already done so, set up your CLI
+> environment by sourcing  the `setvars` script located in
+> the root of your oneAPI installation.
+>
+> Linux Sudo: . /opt/intel/oneapi/setvars.sh
+>
+> Linux User: . ~/intel/oneapi/setvars.sh
+>
+> Windows: C:\Program Files(x86)\Intel\oneAPI\setvars.bat
+>
+>For more information on environment variables, see Use the setvars Script for [Linux or macOS](https://www.intel.com/content/www/us/en/develop/documentation/oneapi-programming-guide/top/oneapi-development-environment-setup/use-the-setvars-script-with-linux-or-macos.html), or [Windows](https://www.intel.com/content/www/us/en/develop/documentation/oneapi-programming-guide/top/oneapi-development-environment-setup/use-the-setvars-script-with-windows.html).
+
 Perform the following steps:
 1. Build the program using the following `make` commands.
 ```
@@ -77,10 +103,14 @@ $ make
     make clean
     ```
 
+If an error occurs, troubleshoot the problem using the Diagnostics Utility for
+Intel® oneAPI Toolkits.
+[Learn more](https://software.intel.com/content/www/us/en/develop/documentation/diagnostic-utility-user-guide/top.html)
 
 ### Application Parameters
 
-There are two configurable options defined near the top of the code, both of which affect the program's performance:
+There are two configurable options defined near the top of the code, both of
+which affect the program's performance:
 
 - constexpr int task_threshold - This determines the minimum size of the list passed to the OpenMP merge sort function required to call itself and not the scalar version recursively. Its purpose is to reduce the threading overhead as it gets less efficient on smaller list sizes. Setting this value too small can reduce the OpenMP implementation's performance as it has more threading overhead for smaller workloads.
 - constexpr int n - This determines the size of the list used to test the merge sort functions. Setting it larger will result in longer runtime and is useful for analyzing the algorithm's runtime growth rate.
diff --git a/DirectProgramming/C++/Jupyter/OpenMP-offload-training/README.md b/DirectProgramming/C++/Jupyter/OpenMP-offload-training/README.md
@@ -3,16 +3,16 @@
 The the content of this repo is a collection of Jupyter notebooks that were
 developed to teach OpenMP Offload.
 
-The Jupyter notebooks are tested and can be run on the Intel Devcloud. Below
-are the steps to access these Jupyter notebooks on the Intel Devcloud:
+The Jupyter notebooks are tested and can be run on the Intel DevCloud. Below
+are the steps to access these Jupyter notebooks on the Intel DevCloud:
 
-1. Register with the Intel Devcloud at
-   https://intelsoftwaresites.secure.force.com/devcloud/oneapi
+1. Register with the Intel DevCloud at
+   https://intelsoftwaresites.secure.force.com/devcloud/oneapi.
 
-2. SSH into the Intel Devcloud "terminal"
+2. SSH into the Intel DevCloud "terminal".
 
 3. Type the following command to download the oneAPI-essentials series of
-   Jupyter notebooks and OpenMP offload notebooks into your devcloud account
+   Jupyter notebooks and OpenMP offload notebooks into your DevCloud account
    `/data/oneapi_workshop/get_jupyter_notebooks.sh`
 
 | Optimized for         | Description
@@ -26,8 +26,8 @@ are the steps to access these Jupyter notebooks on the Intel Devcloud:
 
 ## Running the Jupyter Notebooks
 
-1. Open "OpenMP Welcome.ipynb" with JupyterLab
-2. Start the modules of interest
+1. Open "OpenMP Welcome.ipynb" with JupyterLab.
+2. Start the modules of interest.
 3. Follow the instructions in each notebook and execute cells when instructed.
 
 ## License
@@ -45,20 +45,20 @@ Third party program Licenses can be found here:
 * Introduce Developer Training Modules
 * Describe oneAPI Tool Modules
 
-[Introduction to OpenMP Offload](intro) 
+[Introduction to OpenMP Offload](intro)
 * oneAPI Software Model Overview and Workflow
 * HPC Single-Node Workflow with oneAPI
 * Simple OpenMP Code Example
 * Target Directive Explanation
 * _Lab Exercise_: Vector Increment with Target Directive
 
-[Managing Data Transfers](datatransfer) 
+[Managing Data Transfers](datatransfer)
 * Offloading Data
 * Target Data Region
 * _Lab Exercise_: Target Data Region
 * Mapping Global Variable to Device
 
-[Utilizing GPU Parallelism](parallelism) 
+[Utilizing GPU Parallelism](parallelism)
 * Device Parallelism
 * OpenMP Constructs and Teams
 * Host Device Concurrency
diff --git a/DirectProgramming/C++/ParallelPatterns/openmp_reduction/README.md b/DirectProgramming/C++/ParallelPatterns/openmp_reduction/README.md
@@ -14,14 +14,21 @@ For comprehensive instructions see the [DPC++ Programming](https://software.inte
 | Time to complete      | 10 min
 
 ## Purpose
-This example demonstrates how to do reduction by using the CPU in serial mode, the CPU in parallel mode (using OpenMP), the GPU using OpenMP offloading.
+This example demonstrates how to do reduction by using the CPU in
+serial mode, the CPU in parallel mode (using OpenMP), the GPU using OpenMP
+offloading.
 
-All the different modes use a simple calculation for Pi. It is a well known mathematical formula that if you integrate from 0 to 1 over the function, (4.0 / (1+x*x) )dx, the answer is pi. One can approximate this integral by summing up the area of a large number of rectangles over this same range.
+All the different modes use a simple calculation for Pi. It is a well known
+mathematical formula that if you integrate from 0 to 1 over the function, (4.0
+/ (1+x*x) )dx, the answer is pi. One can approximate this integral by summing
+up the area of a large number of rectangles over this same range.
 
-Each of the different functions calculates pi by breaking the range into many tiny rectangles and then summing up the results.
+Each of the different functions calculates pi by breaking the range into many
+tiny rectangles and then summing up the results.
 
 ## Key Implementation Details
-This code shows how to use OpenMP on the CPU host as well as using target offload capabilities.
+This code shows how to use OpenMP on the CPU host
+as well as using target offload capabilities.
 
 ## License
 Code samples are licensed under the MIT license. See [License.txt](https://github.com/oneapi-src/oneAPI-samples/blob/master/License.txt) for details.
@@ -31,10 +38,14 @@ Third party program Licenses can be found here: [third-party-programs.txt](https
 ## Building the dpc_reduce program for CPU and GPU
 
 ### Include Files
-The include folder is located at `%ONEAPI_ROOT%\dev-utilities\latest\include` on your development system".
+The include folder is located at
+`%ONEAPI_ROOT%\dev-utilities\latest\include` on your development system".
 
 ### Running Samples In DevCloud
-If running a sample in the Intel DevCloud, remember that you must specify the compute node (CPU, GPU, FPGA) and whether to run in batch or interactive mode. For more information, see the [Intel® oneAPI Base Toolkit Get Started Guide](https://devcloud.intel.com/oneapi/get-started/base-toolkit/)
+If running a sample in the Intel DevCloud,
+remember that you must specify the compute node (CPU, GPU, FPGA) and whether to
+run in batch or interactive mode. For more information, see the
+[Intel® oneAPI Base Toolkit Get Started Guide](https://devcloud.intel.com/oneapi/get-started/base-toolkit/)
 
 
 ### Using Visual Studio Code*  (Optional)
@@ -49,11 +60,25 @@ The basic steps to build and run a sample using VS Code include:
  - Run the sample in the VS Code terminal using the instructions below.
 
 To learn more about the extensions and how to configure the oneAPI environment, see
-[Using Visual Studio Code with Intel® oneAPI Toolkits](https://software.intel.com/content/www/us/en/develop/documentation/using-vs-code-with-intel-oneapi/top.html).
+[Using Visual Studio Code with Intel® oneAPI Toolkits](https://www.intel.com/content/www/us/en/develop/documentation/using-vs-code-with-intel-oneapi/top.html).
 
-After learning how to use the extensions for Intel oneAPI Toolkits, return to this readme for instructions on how to build and run a sample.
+After learning how to use the extensions for Intel oneAPI Toolkits, return to
+this readme for instructions on how to build and run a sample.
 
 ### On a Linux* System
+
+> **Note**: If you have not already done so, set up your CLI
+> environment by sourcing  the `setvars` script located in
+> the root of your oneAPI installation.
+>
+> Linux Sudo: . /opt/intel/oneapi/setvars.sh
+>
+> Linux User: . ~/intel/oneapi/setvars.sh
+>
+> Windows: C:\Program Files(x86)\Intel\oneAPI\setvars.bat
+>
+>For more information on environment variables, see Use the setvars Script for [Linux or macOS](https://www.intel.com/content/www/us/en/develop/documentation/oneapi-programming-guide/top/oneapi-development-environment-setup/use-the-setvars-script-with-linux-or-macos.html), or [Windows](https://www.intel.com/content/www/us/en/develop/documentation/oneapi-programming-guide/top/oneapi-development-environment-setup/use-the-setvars-script-with-windows.html).
+
 Perform the following steps:
 ```
 mkdir build
@@ -77,6 +102,13 @@ Clean the program using:
 make clean
 ```
 
+If an error occurs, you can get more details by running `make` with the `VERBOSE=1` argument:
+``make VERBOSE=1``
+For more comprehensive troubleshooting, use the Diagnostics Utility for
+Intel® oneAPI Toolkits, which provides system checks to find missing dependencies and permissions errors.
+[Learn more](https://software.intel.com/content/www/us/en/develop/documentation/diagnostic-utility-user-guide/top.html).
+
+
 ## Running the Sample
 
 ### Application Parameters
diff --git a/DirectProgramming/C++/StructuredGrids/iso3dfd_omp_offload/README.md b/DirectProgramming/C++/StructuredGrids/iso3dfd_omp_offload/README.md
