initial commit of content ready for PR and technical review

Author: kieranhejmadi01

content/learning-paths/servers-and-cloud-computing/openrng-with-performix/_index.md

@@ -0,0 +1,60 @@
+---
+title: Accelerate Random Number Generation with OpenRNG and Performix
+description: Learn how to profile an example C++ data-processing workload on Arm Linux with Arm Performix, then accelerate random distribution generation using OpenRNG and Arm Performance Libraries.
+
+minutes_to_complete: 45
+
+who_is_this_for: This Learning Path is for C++ developers on Arm Linux who want to use profiling data to target optimization and speed up random number generation.
+
+learning_objectives: 
+    - Build and run a baseline C++ data-processing workload on Arm Linux
+    - Use Arm Performix Code Hotspots to identify the highest-impact optimization target
+    - Build the workload with OpenRNG and Arm Performance Libraries
+    - Validate speedups with a microbenchmark sweep across multiple data sizes
+
+prerequisites:
+    - An Arm Linux (aarch64) system, such as AWS Graviton
+    - Basic C++ and CMake knowledge
+
+author: Kieran Hejmadi
+
+### Tags
+skilllevels: Introductory
+subjects: Performance and Architecture
+armips:
+    - Neoverse
+tools_software_languages:
+    - C++
+    - CMake
+    - Arm Performix
+    - OpenRNG
+    - Arm Performance Libraries
+operatingsystems:
+    - Linux
+
+further_reading:
+    - resource:
+        title: Install Arm Performix
+        link: https://learn.arm.com/install-guides/performix/
+        type: documentation
+    - resource:
+        title: Install Arm Performance Libraries
+        link: https://learn.arm.com/install-guides/armpl/
+        type: documentation
+    - resource:
+        title: OpenRNG project repository
+        link: https://gitlab.arm.com/libraries/openrng
+        type: documentation
+    - resource:
+        title: Find Code Hotspots with Arm Performix
+        link: https://learn.arm.com/learning-paths/servers-and-cloud-computing/cpu_hotspot_performix/
+        type: documentation
+
+
+
+### FIXED, DO NOT MODIFY
+# ================================================================================
+weight: 1                       # _index.md always has weight of 1 to order correctly
+layout: "learningpathall"       # All files under learning paths have this same wrapper
+learning_path_main_page: "yes"  # This should be surfaced when looking for related content. Only set for _index.md of learning path content.
+---

content/learning-paths/servers-and-cloud-computing/openrng-with-performix/_next-steps.md

@@ -0,0 +1,8 @@
+---
+# ================================================================================
+#       FIXED, DO NOT MODIFY THIS FILE
+# ================================================================================
+weight: 21                  # The weight controls the order of the pages. _index.md always has weight 1.
+title: "Next Steps"         # Always the same, html page title.
+layout: "learningpathall"   # All files under learning paths have this same wrapper for Hugo processing.
+---

content/learning-paths/servers-and-cloud-computing/openrng-with-performix/flame-graph-detached.jpg

@@ -0,0 +1,49 @@
+---
+title: Get started
+weight: 2
+
+### FIXED, DO NOT MODIFY
+layout: learningpathall
+---
+
+## Prepare your environment
+
+For this learning path, you will use an Arm Linux system (aarch64), such as an AWS Graviton instance running Amazon Linux 2023; it has been tested on an AWS Graviton 3 `c7g.metal` instance with 64 Neoverse V1 cores.
+
+Install the following packages, replacing `dnf` with the package manager for your Linux distribution.
+
+```bash
+sudo dnf update -y
+sudo dnf install -y git cmake g++ environment-modules python3 python3-pip
+```
+
+Next, [install Arm Performix](https://learn.arm.com/install-guides/performix/) on the remote Arm Linux target (`c7g.metal` instance) and the graphical user interface on your local machine. There's no need to use the command-line interface (CLI).
+
+Install the prebuilt Arm Performance Libraries on your Arm Linux system using the [install guide](https://learn.arm.com/install-guides/armpl/). Follow the instructions and load the module file. A module file configures your environment by setting paths and variables so the correct software and libraries are available. To verify the module loaded successfully, run:
+
+```bash
+module list
+```
+
+You should see the output below. You'll need to load the environment module with the `module load <arm-performance-lib>` command if it isn't already loaded.
+
+```output
+Currently Loaded Modulefiles:
+ 1) arm-performance-libraries
+```
+
+{{% notice Please Note %}}
+When you open a new terminal, you will need to reload the modulefile. To simplify this, you can add the modulefile path to your `~/.bashrc` so modules can be loaded directly with the `module load <arm-performance-lib>` command
+```bash
+echo "export MODULEPATH=$MODULEPATH:/opt/arm/modulefiles" >> ~/.bashrc
+```
+{{% /notice %}}
+
+Clone and build the example project:
+
+```bash
+git clone https://github.com/arm-education/Data-Processing-Example.git
+cd Data-Processing-Example
+```
+
+In the next section, you examine what the data-processing example does and run the visualization helper.

content/learning-paths/servers-and-cloud-computing/openrng-with-performix/flame-graph.jpg

@@ -0,0 +1,83 @@
+---
+title: Run the baseline data-processing example
+weight: 3
+
+### FIXED, DO NOT MODIFY
+layout: learningpathall
+---
+
+## Understand the workflow and run the baseline
+
+This Learning Path uses an example workload to demonstrate a data-processing pattern. The workflow processes synthetic 2D point data in three steps:
+
+1. Generate two random distributions and add them.
+2. Count how many points lie inside a rectangular window.
+3. Compute the shortest distance from the origin.
+
+Although this is a toy example, these three steps represent a common pattern in analytics pipelines: generate data, filter data, and reduce data to a metric. This pattern could be seen in workloads such as geospatial event filtering or scientific simulation.
+
+In `src/main.cpp`, you can see this flow:
+
+```cpp
+    // STEP 1. Generate a distribution of 2D Points that is the sum of a Gaussian and Uniform distribution
+
+    const Vec1D distribution  = generateDistribution(NUM_POINTS, BASIC_RNG::GAUSSIAN, BASIC_RNG::UNIFORM, meanAndStdDeviationParams, minAndMaxParams);
+
+    // STEP 2. Calculate the number of points that fit within a 2D window
+
+    Rectangle window(10.0,10.0,50.0,50.0);
+    int numberOfPoints = window.countPointsInRectangle(distribution);
+    std::cout << "Number of Data Points = " << NUM_POINTS 
+              << " | Number of Points within Window ( [" 
+              << window.bottomLeft[0]  << ", " << window.bottomLeft[1] << "] , ["
+              << window.topRight[0]  << ", " << window.topRight[1]
+              << "] ) = " << numberOfPoints << std::endl;
+    
+    
+    // STEP 3. Calculate the magnitude of the smallest point within the distribution
+
+    float shortestDistance = min_length(distribution.getData());
+    std::cout << "Shortest Distance from Origin = " << shortestDistance << std::endl;
+```
+
+Manually timing specific sections of code can help identify bottlenecks, but it requires adding instrumentation and risks overlooking other hotspots that were not explicitly measured. Instead, use Arm Performix Code Hotspots in to measure the entire program and observe where CPU cycles are actually spent.
+
+Build and run the baseline executable:
+
+```bash
+cmake -S . -B build
+cmake --build build --target main
+./build/src/main
+```
+
+You should see the following output. The example generates 16,384 points on an x and y axis. The distribution is the sum of a Gaussian distribution with a mean and standard deviation of 30 and 50 respectively, and a uniform distribution with a min and max of 10 and 100. For each point, the workload checks whether it lies within a window with bottom-left and top-right coordinates of [10,10] and [50,50] respectively, then finds the point closest to the origin.
+
+```output
+Number of Data Points = 16384 | Number of Points within Window ( [10, 10] , [50, 50] ) = 586
+Shortest Distance from Origin = 1.88536
+```
+
+To confirm the data distribution is being generated correctly, we can export our data to be processed by a basic python script. 
+
+```bash
+cmake -S . -B build -DBUILD_TESTS=1
+cmake --build build --target generate_visualization_baseline
+./build/tests/generate_visualization_baseline
+```
+
+The command writes `vector_data.csv`. Next, create a Python environment and render the plot:
+
+```bash
+python3 -m venv venv
+source venv/bin/activate
+pip3 install -r scripts/requirements.txt
+python3 scripts/visualize_vectors.py
+```
+
+You should get an output image similar to this:
+
+![Scatter plot generated from vector_data.csv showing the point distribution#center](./vector_data.png)
+
+## What you've learned and what's next
+
+You validated the baseline workflow and generated output you can inspect. Next, you use Arm Performix Code Hotspots to identify the true optimization target from measured runtime data.

content/learning-paths/servers-and-cloud-computing/openrng-with-performix/hotspot-with-apl.jpg

@@ -0,0 +1,30 @@
+---
+title: Identify code hotspots with Arm Performix
+weight: 4
+
+### FIXED, DO NOT MODIFY
+layout: learningpathall
+---
+
+## Profile the baseline with Code Hotspots
+
+Arm Performix includes a **Code Hotspots** recipe that shows which functions consume the most CPU time. This helps you prioritize optimization work based on evidence instead of guess work. If you haven't come across flame graphs or sample-based profiling, see this introductory [Learning Path](https://learn.arm.com/learning-paths/servers-and-cloud-computing/cpu_hotspot_performix/).
+
+From your local machine, open the Arm Performix GUI and run Code Hotspots recipe on the baseline executable at `./build/src/main`.
+
+![Arm Performix GUI showing where to create a new Code Hotspots analysis run for the baseline executable#center](./run-code-hotspot.jpg)
+
+
+![Arm Performix GUI showing flame graph#center](./flame-graph.jpg)
+
+
+The flame graph shows CPU time distribution across the call stack, where wider blocks indicate higher cumulative execution time. The dominant feature is the wide base associated with `generateDistribution(...)`, indicating it is the primary hotspot and consumes the largest share of execution time.
+
+Drilling into that region, most of the work comes from standard library random generation routines, particularly paths involving `std::normal_distribution<float>`. Those stacks are visibly wider than those involving `std::uniform_real_distribution<float>`, indicating that Gaussian (normal) sampling is significantly more expensive in terms of CPU cycles than uniform sampling. The imbalance might not have been obvious from higher-level instrumentation, because both operations conceptually generate random numbers, but their computational cost differs.
+
+In contrast, functions related to computing properties such as counting points within a rectangle or identifying a minimum point (for example, `min_length`-type operations) occupy relatively narrow regions of the graph, contributing only a small fraction of total runtime and representing no meaningful bottleneck.
+
+
+## What you've learned and what's next
+
+You used profiling data to highlight which function to optimize. Next, you accelerate random generation by enabling OpenRNG through Arm Performance Libraries.

content/learning-paths/servers-and-cloud-computing/openrng-with-performix/how-to-1.md

@@ -0,0 +1,140 @@
+---
+title: Accelerate distribution generation with OpenRNG
+weight: 5
+
+### FIXED, DO NOT MODIFY
+layout: learningpathall
+---
+
+## Accelerate Hotspot with OpenRNG and Arm Performance Libraries
+
+In this step, you replace the baseline random-number path with OpenRNG from Arm Performance Libraries.
+
+Arm Performance Libraries includes numerical routines tuned for Arm processors. Those Arm-tuned routines can speed up execution by reducing overhead and improving throughput for compute-heavy kernels.
+
+OpenRNG is the random-number component in Arm Performance Libraries. It exposes a Vector Statistical Library (VSL) API, where *VSL* means generating distributions in vector form (many values per call) instead of one sample at a time.
+
+This Learning Path uses that vector API to generate Gaussian values in bulk. Bulk generation through a stream object lowers per-sample overhead, which is why this section can reduce runtime in the hotspot.
+
+OpenRNG is API-compatible with the Intel oneMKL VSL RNG interface, so distribution call sites remain familiar when you move between x86 and AArch64 builds. You mainly switch build configuration, not workload logic. See the [OpenRNG developer reference guide](https://developer.arm.com/documentation/101004/2601/Open-Random-Number-Generation-Reference-Guide/RNG-Introduction/An-overview-of-OpenRNG?lang=en) for details.
+
+In `src/vec1d.cpp`, the `USE_ARMPL` macro controls which implementation is compiled. In this project, enabling `USE_ARMPL` selects the AArch64 OpenRNG path:
+
+```cpp
+#if USE_ARMPL
+    #if defined(__aarch64__)
+        #include <amath.h>
+        #include <openrng.h>
+    #else
+        #error "USE_ARMPL enabled but not on AArch64"
+    #endif
+#endif
+```
+
+The OpenRNG path creates one VSL stream and fills a contiguous buffer for both coordinates. `count` is `2 * v.getSize()` because each point has `x` and `y` values:
+
+```cpp
+VSLStreamStatePtr stream;
+vslNewStream(&stream, VSL_BRNG_SFMT19937, 777);
+
+const int count = 2 * v.getSize();
+std::vector<float> tmp(count);
+```
+
+For Gaussian generation, the code calls the single-precision VSL routine `vsRngGaussian`. Here, `param_a` is the mean and `param_b` is the standard deviation:
+
+```cpp
+vsRngGaussian(
+    VSL_RNG_METHOD_UNIFORM_STD,
+    stream,
+    count,
+    tmp.data(),
+    param_a, // mean
+    param_b  // standard deviation
+);
+```
+
+After bulk generation, values are mapped back into your `Point` vector:
+
+```cpp
+auto& data = v.getData();
+for (int i = 0; i < v.getSize(); i++){
+    data[i]._x = tmp[2*i];
+    data[i]._y = tmp[2*i+1];
+}
+
+vslDeleteStream(&stream);
+```
+
+
+
+Now build and run the accelerated variant:
+
+```bash
+make clean
+cmake -S . -B build -DUSE_ARMPL=1
+cmake --build build --target main_with_apl
+./build/src/main_with_apl
+```
+
+## Analyze the flame graph
+
+Now profile the accelerated binary in the Arm Performix GUI using `./build/src/main_with_apl` as the workload.
+
+![Arm Performix GUI showing a Code Hotspots run configured for the accelerated executable main_with_apl#center](./hotspot-with-apl.jpg)
+
+{{% notice Please Note %}}
+If you encounter an error when trying to run the workload through Arm Performix, it's because the binary runs from a fresh environment without the Arm Performance Library environment module loaded. The easiest workaround is to add the `LD_LIBRARY_PATH` environment variable to your `.bashrc` file.
+
+```bash
+
+echo "export LD_LIBRARY_PATH=/opt/arm/arm-performance-libraries/lib:${LD_LIBRARY_PATH}" >> ~/.bashrc
+```
+Alternatively, if using the CLI, you can pass in the environment variable with the `--env` argument. As of Performix 2026.2.0, you are unable to pass through environment variables via the GUI.
+
+{{% /notice %}}
+
+The flame graph shows `main`, but Arm Performance Libraries functions (including OpenRNG) do not appear above it. Instead, most samples are attributed to dynamic loader functions (for example, `_dl_*`), which indicates missing symbol resolution. This often happens on Linux when pre-built shared libraries (`*.so`) do not include debug symbols. The profiler cannot resolve internal library calls, so stacks appear truncated.
+
+To fix this, rebuild openRNG from source with debug information enabled (e.g., -g), so the library functions show up correctly above main.
+
+![Arm Performix flame graph with split attribution for shared-library calls from the OpenRNG path#center](./flame-graph-detached.jpg)
+
+Run the following command from the root of the project directory to build `openrng` with debug.
+
+```bash
+git clone https://gitlab.arm.com/libraries/openrng.git && cd openrng
+cmake -S . -B build -DCMAKE_BUILD_TYPE=Debug -DCMAKE_INSTALL_PREFIX=$PWD/install
+cmake --build build -j $(nproc -1)
+cmake --install build
+```
+
+Run the command below to compile from the root of the project directory.
+
+
+```bash
+g++ --std=c++20 -g -O0 \
+  src/main.cpp src/vec1d.cpp src/point.cpp src/rectangle.cpp src/export_data.cpp \
+  -DUSE_ARMPL=1 \
+  -I./include \
+  -I./openrng/install/include \
+  -I${ARMPL_DIR}/include \
+  -L./openrng/install/lib64 \
+  -L${ARMPL_DIR}/lib \
+  -lopenrng -lamath -lm \
+  -Wl,-rpath,$PWD/openrng/install/lib64 \
+  -Wl,-rpath,${ARMPL_DIR}/lib \
+  -o ./build/debug_openrng
+```
+
+{{% notice Please Note %}}
+
+OpenRNG uses the CMake build system, so as an alternative you can update your CMake configuration to fetch from the third-party library. The direct command above is used here primarily for convenience.
+
+{{% /notice %}}
+
+From Performix, run the code hotspot recipe and target the `./build/debug_openrng` binary.
+
+![Arm Performix flame graph with OpenRNG symbols correctly resolved and stacked above the calling functions#center](./openrng_flame_graph_with_debug.jpg)
+
+You can now correctly see the OpenRNG frames appearing above your calling functions. Because hotspots are identified through periodic sampling, the measurements provide limited direct insight into exact wall-clock time. Next, you will measure the speedup of the hot function and examine how it varies across different data sizes.