Technical review of QuantLib LP

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

@@ -10,24 +10,22 @@ layout: learningpathall
 
 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.
+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:
+The workflow uses:
 
-- Ubuntu Server 22.04 LTS
+- Ubuntu Server 22.04 LTS (also tested on 24.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
+## Benchmark workflow
 
-This Learning Path follows a simple workflow:
+The steps follow a practical benchmark flow:
 
 1. Create and connect to an Arm64 Azure Cobalt virtual machine
 2. Install the tools needed to build QuantLib
@@ -39,6 +37,22 @@ This Learning Path follows a simple workflow:
 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 %}}
 
+## What the benchmark tests
+
+The benchmark executable runs approximately 85 tests drawn directly from QuantLib's own test suite, covering five domains:
+
+- **Equity and FX**: American and European option pricing, Heston and Bates model calibration, convertible bonds, Andreasen-Huge volatility interpolation
+- **Interest rates**: Short rate models, Bermudan swaptions, Libor market model, piecewise yield curves, overnight indexed swaps, Markov functional models, SABR and ZABR volatility
+- **Credit derivatives**: Nth-to-default pricing and credit default swap calibration
+- **Energy**: Swing options and virtual power plant pricing
+- **Math**: Gaussian quadratures, low-discrepancy sequences, statistics, and special functions
+
+Each test has a fixed iteration count built in. Some run once per task, others run hundreds or thousands of times to produce a measurable signal. The `--size` argument multiplies the entire set: `--size=2` runs each test twice, `--size=5` runs it five times, and so on. Doubling `--size` doubles runtime while leaving throughput unchanged — this is the expected weak scaling behavior of the benchmark.
+
+The `--nProc` argument controls the number of worker processes. Because QuantLib is not thread-safe, the benchmark uses separate processes rather than threads, coordinated through Boost IPC. Before timing begins, the benchmark runs every test once through the Boost unit test framework to verify correctness — this is what produces the `*** No errors detected` line in the output.
+
+**System Throughput** is calculated as `(size × number_of_tests) / total_runtime`. It is the primary metric for comparing runs across thread counts and system configurations.
+
 ## 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.
@@ -48,4 +62,4 @@ 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
+- recording commands and results so runs can be reproduced later

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

@@ -6,70 +6,47 @@ weight: 3
 layout: learningpathall
 ---
 
-## Create an Arm64 Azure Cobalt virtual machine
+## Create and connect to 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`
+| Setting | Value |
+|---|---|
+| 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 |
+| SSH public key name | `quantlib-cobalt-vm_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:
+Before connecting, update the permissions on the private key from your local machine. SSH refuses to use keys that are readable by other users:
 
 ```bash
 chmod 600 ~/Downloads/quantlib-cobalt-vm_key.pem
 ```
 
-Then connect using SSH:
+Connect to the VM using the key and the public IP address shown in the Azure portal:
 
 ```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:
+Replace `<VM_PUBLIC_IP>` with the public IP address of your VM.
 
-```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:
+After logging in, verify the architecture before installing packages. The rest of this Learning Path assumes you are on an Arm64 system:
 
 ```bash
 uname -m
@@ -83,9 +60,9 @@ 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
+## Install dependencies and download QuantLib
 
-Update the package index and install required packages:
+Update the package index and install the required packages:
 
 ```bash
 sudo apt update
@@ -94,29 +71,16 @@ 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:
+Set the QuantLib version as an environment variable, then download the release archive. Keeping the version in `QL_VER` makes later commands easier to repeat or adapt for a newer release:
 
 ```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:
+Check that the file exists and has a non-zero size:
 
 ```bash
 ls -lh QuantLib-$QL_VER.tar.gz
@@ -130,61 +94,85 @@ You should see output showing the file name and size, for example:
 
 If the file is missing or has size 0, re-run the curl command.
 
-## Verify the file type
+## Verify and extract the source archive
+
+Use the `file` command to confirm that the archive is a gzip-compressed tar file:
 
-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:
+Expected output is similar to:
+
 ```bash
 QuantLib-1.41.tar.gz: gzip compressed data, max compression, from Unix, original size modulo 2^32 42721280
 ```
 
-### (Optional) Test archive integrity
+Once confirmed, extract it and move into the extracted directory:
 
-To check that the archive is not corrupted, run:
 ```bash
-tar -tzf QuantLib-$QL_VER.tar.gz > /dev/null
+tar -xzf QuantLib-$QL_VER.tar.gz
+cd QuantLib-$QL_VER
 ```
 
-If the command completes without errors, the archive is valid.
 
-If you see errors such as:
+
+List the contents to confirm that the source code is ready to configure and build:
+
+```bash
+ls
+```
+
+You should see files and directories such as:
 
 ```bash
-gzip: stdin: unexpected end of file
-tar: Unexpected EOF in archive
+configure
+Makefile.am
+ql/
+test-suite/
 ```
 
-the download is incomplete or corrupted.l Delete the file and download it again.
+This confirms that the source code has been unpacked correctly and is ready to configure and build.
 
-## Extract the archive
+{{% notice Optional Setup %}}
+## Reconnect to Cobalt frequently
+
+If you'll reconnect often, add a shortcut entry to your SSH config:
 
-Once the archive is verified, extract it:
 ```bash
-tar -xzf QuantLib-$QL_VER.tar.gz
+nano ~/.ssh/config
 ```
 
-Then move into the extracted directory:
+Add:
+
 ```bash
-cd QuantLib-$QL_VER
+Host quantlib-cobalt
+    HostName <VM_PUBLIC_IP>
+    User azureuser
+    IdentityFile ~/Downloads/quantlib-cobalt-vm_key.pem
 ```
 
-## Confirm the extracted contents
+Then connect with:
 
-List the contents:
 ```bash
-ls
+ssh quantlib-cobalt
 ```
 
-You should see files and directories such as:
+## Use tmux for remote builds
+
+If your SSH session disconnects during the build, the compile job will be killed. To prevent this, install tmux and start a session before running `make`:
+
 ```bash
-configure
-Makefile.am
-ql/
-test-suite/
+sudo apt update
+sudo apt install -y tmux
+tmux
 ```
 
-This confirms that the source code has been unpacked correctly and is ready to configure and build.
+Run the build commands from inside the tmux session. If your connection drops, reconnect to the VM and re-attach with:
+
+```bash
+tmux attach
+```
+{{% /notice %}}
+
+With your environment set up, move on to the next section to build QuantLib.

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

@@ -6,15 +6,15 @@ weight: 4
 layout: learningpathall
 ---
 
-## Configure the QuantLib build
+## Configure the build
 
-From the QuantLib source directory:
+Return to the QuantLib source directory. This uses the `QL_VER` variable you exported when downloading the source archive:
 
 ```bash
 cd ~/QuantLib-$QL_VER
 ```
 
-Run the configure script:
+Run the configure script with benchmark support enabled:
 ```bash
 ./configure \
 --prefix=/usr/local \
@@ -32,35 +32,30 @@ This configuration:
 - applies CPU-specific optimization flags
 
 
-## Build QuantLib
+## Install QuantLib
 
-Compile using all available cores:
+Compile using all available cores. The `nproc` command returns the number of processing units visible to the VM, so `make -j$(nproc)` keeps the build command portable across VM sizes:
 
 ```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.
+The build may take 30–45 minutes on the Standard_D4ps_v5. If your SSH session might disconnect, set up tmux before running `make` — see the optional setup steps in the previous section.
 {{% /notice %}}
 
-## Install QuantLib
-
-After the build completes:
+After the build completes, install QuantLib into `/usr/local` and refresh the dynamic linker cache:
 
 ```bash
 sudo make install
 sudo ldconfig
 ```
 
-## Verify the build
+Move to the test suite and check that the benchmark executable was created:
 
-Move to the test suite:
 ```bash
 cd ~/QuantLib-$QL_VER/test-suite
-```
-
-Check that the benchmark executable exists:
-```bash
 ls quantlib-benchmark
 ```
+
+You should see `quantlib-benchmark` in the output. You will use this executable in the next section.