Merge pull request ArmDeveloperEcosystem#3252 from ArmDeveloperEcosystem/quantlib-learning-path

Quantlib learning path

Author: pareenaverma

content/learning-paths/servers-and-cloud-computing/quantlib/1-overview.md

@@ -0,0 +1,51 @@
+---
+title: Understand the QuantLib benchmark workflow on Azure Cobalt
+weight: 2
+
+### FIXED, DO NOT MODIFY
+layout: learningpathall
+---
+
+## What is QuantLib?
+
+QuantLib is an open-source C++ library for quantitative finance. It provides tools for pricing, modeling, trading, and risk management, and is widely used as both a development library and a representative financial computing workload.
+
+Because QuantLib is a substantial C++ codebase with realistic compute behavior, it is also useful as a benchmark when evaluating cloud systems and processor architectures.
+
+In this Learning Path, you will build QuantLib from source and run its benchmark executable on an Arm-based Azure Cobalt virtual machine.
+
+## Why use Azure Cobalt?
+
+Azure Cobalt provides Arm64 virtual machines for cloud-native development and performance evaluation. Running QuantLib on Azure Cobalt gives you a practical way to measure how a real C++ finance workload behaves on Arm-based cloud infrastructure.
+
+The workflow in this Learning Path uses:
+
+- Ubuntu Server 22.04 LTS
+- an Arm64 Azure Cobalt virtual machine
+- a source build of QuantLib
+- QuantLib's benchmark executable for repeatable performance testing
+
+## What you'll do
+
+This Learning Path follows a simple workflow:
+
+1. Create and connect to an Arm64 Azure Cobalt virtual machine
+2. Install the tools needed to build QuantLib
+3. Download and compile QuantLib from source
+4. Run benchmark workloads with different problem sizes and thread counts
+5. Compare and record results
+
+{{% notice Note %}}
+This Learning Path focuses on building and benchmarking QuantLib on Azure Cobalt. It is not a general introduction to quantitative finance or QuantLib development.
+{{% /notice %}}
+
+## Benchmarking goals
+
+When benchmarking a workload such as QuantLib, the goal is not just to obtain one runtime number. You want a repeatable process that lets you compare runs across system sizes, thread counts, software versions, and compiler settings.
+
+For that reason, this Learning Path emphasizes:
+
+- using a known VM configuration
+- keeping the software environment consistent
+- changing one benchmark variable at a time
+- recording commands and results so runs can be reproduced later

content/learning-paths/servers-and-cloud-computing/quantlib/2-setup-environment.md

@@ -0,0 +1,190 @@
+---
+title: Set up the Azure Cobalt environment
+weight: 3
+
+### FIXED, DO NOT MODIFY
+layout: learningpathall
+---
+
+## Create an Arm64 Azure Cobalt virtual machine
+
+To run QuantLib on Azure Cobalt, first create an Arm64 Ubuntu virtual machine in the Azure portal.
+
+Use the following settings:
+
+- **Virtual machine name:** `quantlib-cobalt-vm`
+- **Region:** a Cobalt-supported region such as **West US 2**
+- **Availability options:** **No infrastructure redundancy required**
+- **Security type:** **Standard**
+- **Image:** **Ubuntu Server 22.04 LTS**
+- **VM architecture:** **Arm64**
+- **Size:** **Standard_D4ps_v5**
+- **Authentication type:** **SSH public key**
+- **Username:** `azureuser`
+
+For storage, a `64 GB` OS disk is sufficient for this workflow.
+
+For networking, allow inbound SSH on port `22`. Restricting the source to **My IP** is recommended.
+
+After creating the VM, download the generated private key in `.pem` format if Azure provides one during setup.
+
+## Connect to the virtual machine
+
+On your local machine, update the permissions on the private key:
+
+```bash
+chmod 600 ~/Downloads/quantlib-cobalt-vm_key.pem
+```
+
+Then connect using SSH:
+
+```bash
+ssh -i ~/Downloads/quantlib-cobalt-vm_key.pem azureuser@<VM_PUBLIC_IP>
+```
+
+Replace <VM_PUBLIC_IP> with the public IP address of your VM.
+
+### (Optional) Reconnect to cobalt frequently
+
+If you’ll reconnect often, add a shortcut entry to your SSH config:
+
+```bash
+nano ~/.ssh/config
+```
+
+Add: 
+
+```bash
+Host quantlib-cobalt
+    HostName <VM_PUBLIC_IP>
+    User azureuser
+    IdentityFile ~/Downloads/quantlib-cobalt-vm_key.pem
+```
+
+Then connect with:
+
+```bash
+ssh quantlib-cobalt
+```
+
+## Confirm that the system is Arm64
+
+After logging in, verify the architecture:
+
+```bash
+uname -m
+```
+
+The expected output is:
+
+```bash
+aarch64
+```
+
+If you do not see aarch64, check that you created the VM with Arm64 architecture and selected an Azure Cobalt-compatible instance type.
+
+## Install build dependencies
+
+Update the package index and install required packages:
+
+```bash
+sudo apt update
+sudo apt install -y build-essential cmake curl libboost-all-dev
+```
+
+These packages provide the compiler toolchain, build system support, download tools, and Boost libraries needed to build QuantLib.
+
+## Optional: use tmux for remote builds
+
+If you want the build to continue even if your SSH session disconnects, install tmux:
+
+```bash
+sudo apt update
+sudo apt install -y tmux
+tmux
+```
+
+## Download QuantLib
+
+Set the version and download the release archive:
+
+```bash
+export QL_VER=1.41
+
+cd ~
+curl -L -o QuantLib-$QL_VER.tar.gz \
+https://github.com/lballabio/QuantLib/releases/download/v$QL_VER/QuantLib-$QL_VER.tar.gz
+```
+
+Check that the file exists. Run:
+
+```bash
+ls -lh QuantLib-$QL_VER.tar.gz
+```
+
+You should see output showing the file name and size, for example:
+
+```bash
+-rw-r--r-- 1 azureuser azureuser 41M QuantLib-1.41.tar.gz
+```
+
+If the file is missing or has size 0, re-run the curl command.
+
+## Verify the file type
+
+Use the file command to confirm that the archive is a valid gzip-compressed tar file:
+```bash
+file QuantLib-$QL_VER.tar.gz
+```
+
+Expected output is simlar to:
+```bash
+QuantLib-1.41.tar.gz: gzip compressed data, max compression, from Unix, original size modulo 2^32 42721280
+```
+
+### (Optional) Test archive integrity
+
+To check that the archive is not corrupted, run:
+```bash
+tar -tzf QuantLib-$QL_VER.tar.gz > /dev/null
+```
+
+If the command completes without errors, the archive is valid.
+
+If you see errors such as:
+
+```bash
+gzip: stdin: unexpected end of file
+tar: Unexpected EOF in archive
+```
+
+the download is incomplete or corrupted.l Delete the file and download it again.
+
+## Extract the archive
+
+Once the archive is verified, extract it:
+```bash
+tar -xzf QuantLib-$QL_VER.tar.gz
+```
+
+Then move into the extracted directory:
+```bash
+cd QuantLib-$QL_VER
+```
+
+## Confirm the extracted contents
+
+List the contents:
+```bash
+ls
+```
+
+You should see files and directories such as:
+```bash
+configure
+Makefile.am
+ql/
+test-suite/
+```
+
+This confirms that the source code has been unpacked correctly and is ready to configure and build.

content/learning-paths/servers-and-cloud-computing/quantlib/3-build-quantlib.md

@@ -0,0 +1,66 @@
+---
+title: Build QuantLib with benchmark support
+weight: 4
+
+### FIXED, DO NOT MODIFY
+layout: learningpathall
+---
+
+## Configure the QuantLib build
+
+From the QuantLib source directory:
+
+```bash
+cd ~/QuantLib-$QL_VER
+```
+
+Run the configure script:
+```bash
+./configure \
+--prefix=/usr/local \
+--enable-benchmark \
+--enable-parallel-unit-test-runner \
+CFLAGS="-g -O2 -mcpu=native" \
+CXXFLAGS="-g -O2 -mcpu=native"
+```
+
+This configuration:
+
+- installs QuantLib to `/usr/local`
+- enables the benchmark executable
+- enables parallel test execution
+- applies CPU-specific optimization flags
+
+
+## Build QuantLib
+
+Compile using all available cores:
+
+```bash
+make -j$(nproc)
+```
+
+{{% notice Note %}}
+The build may take 30–45 minutes on smaller instances. Use tmux to avoid losing progress if your SSH session disconnects.
+{{% /notice %}}
+
+## Install QuantLib
+
+After the build completes:
+
+```bash
+sudo make install
+sudo ldconfig
+```
+
+## Verify the build
+
+Move to the test suite:
+```bash
+cd ~/QuantLib-$QL_VER/test-suite
+```
+
+Check that the benchmark executable exists:
+```bash
+ls quantlib-benchmark
+```

content/learning-paths/servers-and-cloud-computing/quantlib/4-run-benchmarks.md

@@ -0,0 +1,70 @@
+---
+title: Run QuantLib benchmark workloads
+weight: 5
+
+### FIXED, DO NOT MODIFY
+layout: learningpathall
+---
+## Run a baseline benchmark
+
+After building QuantLib, move to the test suite directory:
+
+```bash
+cd ~/QuantLib-$QL_VER/test-suite
+```
+
+From the test suite directory, run a baseline benchmark:
+
+```bash
+./quantlib-benchmark
+```
+
+This confirms that the benchmark is working correctly on your system.
+
+## Vary thread count
+
+To understand how performance scales, run benchmarks with different numbers of threads:
+
+```bash
+./quantlib-benchmark --size=80 --nProc=1
+./quantlib-benchmark --size=80 --nProc=2
+./quantlib-benchmark --size=80 --nProc=4
+```
+
+These runs keep the workload size constant while changing the number of threads.
+
+## Vary workload size
+
+Next, vary the problem size while keeping the thread count fixed:
+
+```bash
+./quantlib-benchmark --size=1 --nProc=1
+./quantlib-benchmark --size=5 --nProc=1
+./quantlib-benchmark --size=8 --nProc=1
+```
+
+This shows how runtime changes as the workload increases.
+
+## Choose appropriate thread counts
+
+The Standard_D4ps_v5 virtual machine has a limited number of cores.
+
+Start with:
+
+* 1 thread
+* 2 threads
+* 4 threads
+
+Using larger values can oversubscribe the system and lead to inconsistent results.
+
+Your notes include larger values such as 12, 24, and 48 threads, but these are better suited for larger machines.
+
+## Keep benchmark runs controlled
+
+For meaningful comparisons:
+
+* change one parameter at a time
+* keep the environment consistent
+* repeat runs if results vary
+
+This helps ensure that differences in runtime reflect real performance changes.