diff --git a/content/learning-paths/servers-and-cloud-computing/quantlib/1-overview.md b/content/learning-paths/servers-and-cloud-computing/quantlib/1-overview.md index c5db95775c..2a3b76adea 100644 --- a/content/learning-paths/servers-and-cloud-computing/quantlib/1-overview.md +++ b/content/learning-paths/servers-and-cloud-computing/quantlib/1-overview.md @@ -10,17 +10,17 @@ 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's also useful as a benchmark when evaluating cloud systems and processor architectures. In this Learning Path, you'll 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 uses: +You'll use: -- Ubuntu Server 22.04 LTS (also tested on 24.04 LTS) -- an Arm64 Azure Cobalt virtual machine -- a source build of QuantLib +- Ubuntu Server 22.04 LTS +- An Arm64 Azure Cobalt virtual machine +- A source build of QuantLib - QuantLib's benchmark executable for repeatable performance testing ## Benchmark workflow @@ -34,24 +34,24 @@ The steps follow a practical benchmark flow: 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. +The steps in this Learning Path aren't 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 +- 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. +Each test has a fixed iteration count built in. Some run once per task, and 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. +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. The tests produce 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. +`System Throughput` is calculated as `(size × number_of_tests) / total_runtime` and is the primary metric for comparing runs across thread counts and system configurations. ## Benchmarking goals @@ -59,7 +59,13 @@ When benchmarking a workload such as QuantLib, the goal is not just to obtain on 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 +- 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 + +## What you've learned and what's next + +You've now learned about QuantLib and why you'll be using Azure Cobalt in this Learning Path. You've also learned how the benchmark works and the intent behind benchmarking a workload such as QuantLib. + +Next, you'll set up your Azure Cobalt environment. \ No newline at end of file diff --git a/content/learning-paths/servers-and-cloud-computing/quantlib/2-setup-environment.md b/content/learning-paths/servers-and-cloud-computing/quantlib/2-setup-environment.md index 4ee7f53127..348cbdb2a3 100644 --- a/content/learning-paths/servers-and-cloud-computing/quantlib/2-setup-environment.md +++ b/content/learning-paths/servers-and-cloud-computing/quantlib/2-setup-environment.md @@ -8,14 +8,14 @@ layout: learningpathall ## 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. +To run QuantLib on Azure Cobalt, first create an Arm64 Ubuntu virtual machine (VM) in the Azure portal. For detailed steps, see the Azure documentation [Quickstart: Create a Linux virtual machine in the Azure portal](https://learn.microsoft.com/en-us/azure/virtual-machines/linux/quick-create-portal?tabs=ubuntu). Use the following settings: | Setting | Value | |---|---| | Virtual machine name | `quantlib-cobalt-vm` | -| Region | a Cobalt-supported region such as **West US 2** | +| 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 | @@ -25,13 +25,13 @@ Use the following settings: | SSH public key name | `quantlib-cobalt-vm_key` | | Username | `azureuser` | -For storage, a `64 GB` OS disk is sufficient for this workflow. +A `64 GB` OS disk is sufficient storage 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. -Before connecting, update the permissions on the private key from your local machine. SSH refuses to use keys that are readable by other users: +SSH refuses to use keys that are readable by other users. Before connecting to the VM, update the permissions on the private key from your local machine: ```bash chmod 600 ~/Downloads/quantlib-cobalt-vm_key.pem @@ -46,7 +46,7 @@ ssh -i ~/Downloads/quantlib-cobalt-vm_key.pem azureuser@ Replace `` with the public IP address of your VM. -After logging in, verify the architecture before installing packages. The rest of this Learning Path assumes you are on an Arm64 system: +After logging in, verify the architecture before installing packages. The rest of this Learning Path is intended to be run on an Arm64 system: ```bash uname -m @@ -54,11 +54,11 @@ uname -m The expected output is: -```bash +```output aarch64 ``` -If you do not see aarch64, check that you created the VM with Arm64 architecture and selected an Azure Cobalt-compatible instance type. +If you don't see `aarch64`, check that you created the VM with Arm64 architecture and selected an Azure Cobalt-compatible instance type. ## Install dependencies and download QuantLib @@ -86,9 +86,9 @@ Check that the file exists and has a non-zero size: ls -lh QuantLib-$QL_VER.tar.gz ``` -You should see output showing the file name and size, for example: +The output shows the file name and size, and is similar to: -```bash +```output -rw-r--r-- 1 azureuser azureuser 41M QuantLib-1.41.tar.gz ``` @@ -102,42 +102,39 @@ Use the `file` command to confirm that the archive is a gzip-compressed tar file file QuantLib-$QL_VER.tar.gz ``` -Expected output is similar to: +The output is similar to: -```bash +```output QuantLib-1.41.tar.gz: gzip compressed data, max compression, from Unix, original size modulo 2^32 42721280 ``` -Once confirmed, extract it and move into the extracted directory: +After you've confirmed, extract the archive and move into the extracted directory: ```bash tar -xzf QuantLib-$QL_VER.tar.gz cd QuantLib-$QL_VER ``` - - 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: +The output is similar to: -```bash +```output configure Makefile.am ql/ test-suite/ ``` -This confirms that the source code has been unpacked correctly and is ready to configure and build. +The output confirms that the source code has been unpacked correctly and is ready to configure and build. -{{% notice Optional Setup %}} -## Reconnect to Cobalt frequently +## (Optional) Set up shortcut for reconnecting to Cobalt frequently -If you'll reconnect often, add a shortcut entry to your SSH config: +If you'll reconnect to the VM often, add a shortcut entry to your SSH config: ```bash nano ~/.ssh/config @@ -158,7 +155,7 @@ Then connect with: ssh quantlib-cobalt ``` -## Use tmux for remote builds +## (Optional) 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`: @@ -168,11 +165,14 @@ sudo apt install -y tmux tmux ``` -Run the build commands from inside the tmux session. If your connection drops, reconnect to the VM and re-attach with: +Run the build commands from inside the tmux session. If your connection drops, reconnect to the VM and re-attach: ```bash tmux attach ``` -{{% /notice %}} -With your environment set up, move on to the next section to build QuantLib. \ No newline at end of file +## What you've accomplished and what's next + +You've now set up an Azure Cobalt virtual machine to run QuantLib on. You've also installed QuantLib dependencies and then downloaded QuantLib. + +Next, with your environment set up, you'll build QuantLib. \ No newline at end of file diff --git a/content/learning-paths/servers-and-cloud-computing/quantlib/3-build-quantlib.md b/content/learning-paths/servers-and-cloud-computing/quantlib/3-build-quantlib.md index dab74bdb99..0998c77f0d 100644 --- a/content/learning-paths/servers-and-cloud-computing/quantlib/3-build-quantlib.md +++ b/content/learning-paths/servers-and-cloud-computing/quantlib/3-build-quantlib.md @@ -8,7 +8,7 @@ layout: learningpathall ## Configure the build -Return to the QuantLib source directory. This uses the `QL_VER` variable you exported when downloading the source archive: +Return to the QuantLib source directory. The command uses the `QL_VER` variable that you exported when downloading the source archive: ```bash cd ~/QuantLib-$QL_VER @@ -24,13 +24,7 @@ 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 - +This configuration installs QuantLib to `/usr/local`. It enables the benchmark executable and parallel test execution, and it applies CPU-specific optimization flags. ## Install QuantLib @@ -41,7 +35,7 @@ make -j$(nproc) ``` {{% notice Note %}} -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. +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 [(Optional) Use tmux for remote builds](/learning-paths/servers-and-cloud-computing/quantlib/2-setup-environment/#optional-use-tmux-for-remote-builds) in the previous section. {{% /notice %}} After the build completes, install QuantLib into `/usr/local` and refresh the dynamic linker cache: @@ -58,4 +52,10 @@ cd ~/QuantLib-$QL_VER/test-suite ls quantlib-benchmark ``` -You should see `quantlib-benchmark` in the output. You will use this executable in the next section. +You should see `quantlib-benchmark` in the output. You'll use this executable in the next section. + +## What you've accomplished and what's next + +You've now completed the installation of QuantLib after building it with support for benchmarking. + +Next, you'll run benchmarks on QuantLib with different sizes and thread counts. \ No newline at end of file diff --git a/content/learning-paths/servers-and-cloud-computing/quantlib/4-run-benchmarks.md b/content/learning-paths/servers-and-cloud-computing/quantlib/4-run-benchmarks.md index 6dd7165391..30ace40134 100644 --- a/content/learning-paths/servers-and-cloud-computing/quantlib/4-run-benchmarks.md +++ b/content/learning-paths/servers-and-cloud-computing/quantlib/4-run-benchmarks.md @@ -7,14 +7,14 @@ layout: learningpathall --- ## Run a baseline benchmark -After building QuantLib, move to the test suite directory and run the benchmark with its default settings: +After building QuantLib, move to the test suite directory and run the benchmark with its default settings. The command uses the `QL_VER` variable that you exported when downloading the source archive: ```bash cd ~/QuantLib-$QL_VER/test-suite ./quantlib-benchmark ``` -This confirms that the benchmark is working correctly on your system. +Successfully running the benchmark with default settings confirms that the benchmark is working correctly on your system. To understand how performance scales across the Arm cores in the VM, keep the workload size constant and change only the number of worker processes: @@ -24,11 +24,11 @@ To understand how performance scales across the Arm cores in the VM, keep the wo ./quantlib-benchmark --size=80 --nProc=4 ``` -The Standard_D4ps_v5 virtual machine has a limited number of cores. Start with 1, 2, and 4 workers. Larger values such as 12, 24, or 48 are better suited to larger machines and can oversubscribe this VM, which makes the results harder to interpret. +The `Standard_D4ps_v5` virtual machine has a limited number of cores. Start with 1, 2, and 4 workers. Larger values such as 12, 24, or 48 are better suited to larger machines and can oversubscribe this VM, which makes the results harder to interpret. ## Vary workload size -Next, keep the thread count fixed and vary the problem size. This shows how runtime changes as the benchmark does more work: +Next, keep the thread count fixed and vary the problem size. By using varied problem sizes, you can see how runtime changes as the benchmark does more work: ```bash ./quantlib-benchmark --size=1 --nProc=1 @@ -36,11 +36,11 @@ Next, keep the thread count fixed and vary the problem size. This shows how runt ./quantlib-benchmark --size=8 --nProc=1 ``` -## Interpreting the output +## Interpret the output -The `--size=1 --nProc=1` run is the quickest of the three, completing in roughly 2 minutes 25 seconds on this configuration. It's a good first check before committing to longer runs. Adding `--verbose=2` prints a per-test runtime breakdown alongside the summary. Without it, only the summary block is printed. Verbosity levels run from 0 (summary only) to 2 (per-test detail); level 3 adds internal debug output. +The `--size=1 --nProc=1` run is the quickest of the three, completing in roughly 2 minutes 25 seconds on this configuration. It's a good first check before committing to longer runs. Adding `--verbose=2` prints a per-test runtime breakdown alongside the summary. Without it, only the summary block is printed. Verbosity levels run from 0 (summary only) to 2 (per-test detail). Level 3 adds internal debug output. -The first run with `--size=1 --nProc=1 --verbose=2` produces output similar to the following. The benchmark first confirms that all tests passed, then lists the runtime for each individual test, and finishes with a summary: +The first run with `--size=1 --nProc=1 --verbose=2` produces output similar to the following: ```output *** No errors detected @@ -64,14 +64,22 @@ Num. Worker Processes = 1 Tail Effect Ratio = 1 ``` -The **System Throughput** and **Benchmark Runtime** values are what you'll compare across runs. The individual test lines show which computations dominate total runtime — longer-running tests such as `testMultiStepCmSwapsAndSwaptions` and `testGauss` reflect the most numerically intensive parts of the workload. +The benchmark first confirms that all tests passed, then lists the runtime for each individual test, and finishes with a summary. + +The `System Throughput` and `Benchmark Runtime` values are what you'll compare across runs. The individual test lines show which computations dominate total runtime. Longer-running tests such as `testMultiStepCmSwapsAndSwaptions` and `testGauss` reflect the most numerically intensive parts of the workload. ## Keep benchmark runs controlled For meaningful comparisons: -* change one parameter at a time -* keep the environment consistent -* repeat runs if results vary +- Change one parameter at a time +- Keep the environment consistent +- Repeat runs if results vary + +Doing so ensures that differences in runtime reflect real performance changes. + +## What you've accomplished and what's next + +You've now benchmarked QuantLib with default settings and with varied workloads. You've also reviewed the output of the benchmark. -This helps ensure that differences in runtime reflect real performance changes. +Next, you'll further analyze and compare benchmark results. diff --git a/content/learning-paths/servers-and-cloud-computing/quantlib/5-analyze-results.md b/content/learning-paths/servers-and-cloud-computing/quantlib/5-analyze-results.md index d16692cb08..62f47e6963 100644 --- a/content/learning-paths/servers-and-cloud-computing/quantlib/5-analyze-results.md +++ b/content/learning-paths/servers-and-cloud-computing/quantlib/5-analyze-results.md @@ -8,7 +8,7 @@ layout: learningpathall ## Record your results -The following results were collected on a Standard_D4ps_v5 Azure Cobalt virtual machine. +The following results were collected on a `Standard_D4ps_v5` Azure Cobalt virtual machine (VM). ### Workload scaling (single thread) @@ -28,36 +28,26 @@ The following results were collected on a Standard_D4ps_v5 Azure Cobalt virtual ## Understand workload scaling -When increasing the workload size while keeping the thread count fixed: - -- runtime increases significantly as size increases -- throughput remains relatively stable +When you increase the workload size while keeping the thread count fixed, the runtime increases significantly with the size increase, and throughput remains relatively stable. For example: - `--size=1` completes in ~2 minutes 25 seconds - `--size=8` completes in ~28 minutes 55 seconds -This shows that the benchmark is scaling the amount of work, not changing execution efficiency. +The increase in runtime shows that the benchmark is scaling the amount of work, not changing execution efficiency. ## Understand thread scaling -When increasing the number of worker processes: - -- runtime decreases significantly -- throughput increases almost linearly +When increasing the number of worker processes, runtime decreases significantly +and throughput increases almost linearly. From the results: -- 1 to 2 workers: - - runtime drops from ~5h 11m to ~2h 30m - - throughput nearly doubles - -- 2 to 4 workers: - - runtime drops again to ~1h 15m - - throughput doubles again +- With 1 to 2 workers, runtime drops from ~5h 11m to ~2h 30m, and throughput nearly doubles. +- With 2 to 4 workers, runtime drops again to ~1h 15m, and throughput doubles again. -This indicates **near-linear scaling** on this system. +The decrease in runtime and increase in throughput indicates near-linear scaling on this system. ## Calculate speedup @@ -69,7 +59,7 @@ Speedup compares performance relative to a single thread. | 2 | 2h 30m | ~2.08× | | 4 | 1h 15m | ~4.16× | -This shows slightly better than linear scaling, which can occur due to improved cache utilization or measurement variability. +This shows slightly better speedup than linear scaling, which can occur due to improved cache utilization or measurement variability. ## Key observations @@ -78,15 +68,15 @@ From these results: - QuantLib scales well across multiple cores on Azure Cobalt - Throughput increases proportionally with thread count - Runtime grows with workload size, as expected -- The system shows efficient utilization of available cores +- The system shows efficient usage of available cores -{{% notice Practical guidance %}} +{{% notice Note %}} Large benchmark sizes such as `--size=80` can take several hours to complete on smaller virtual machines. For most use cases, smaller sizes such as 1, 5, or 8 are sufficient to demonstrate scaling behavior. {{% /notice %}} -## What you learned +## What you've accomplished -You built QuantLib from source on an Arm-based Azure Cobalt VM, enabled its benchmark executable, and ran controlled tests that varied one parameter at a time. You also recorded enough context to compare runs later: VM size, workload size, worker count, runtime, and throughput. +You've now analyzed benchmark results after building QuantLib from source on an Arm-based Azure Cobalt VM and running controlled tests. You've also recorded enough context to compare runs later: VM size, workload size, worker count, runtime, and throughput. -Use this workflow as a starting point for evaluating other C++ financial computing workloads on Arm cloud instances. For deeper comparisons, repeat the same benchmark process across VM sizes, compiler options, QuantLib versions, or cloud regions, and keep the command lines and environment details with the results. +Next, you can use this workflow as a starting point for evaluating other C++ financial computing workloads on Arm cloud instances. For deeper comparisons, repeat the same benchmark process across VM sizes, compiler options, QuantLib versions, or cloud regions. Keep the command lines and environment details with the results. diff --git a/content/learning-paths/servers-and-cloud-computing/quantlib/_index.md b/content/learning-paths/servers-and-cloud-computing/quantlib/_index.md index a92e62cf9a..8450e5ce05 100644 --- a/content/learning-paths/servers-and-cloud-computing/quantlib/_index.md +++ b/content/learning-paths/servers-and-cloud-computing/quantlib/_index.md @@ -1,9 +1,5 @@ --- title: Benchmark QuantLib on Azure Cobalt - -draft: true -cascade: - draft: true description: Learn how to build QuantLib on an Arm-based Azure Cobalt virtual machine and run benchmark workloads to evaluate performance on Arm64 cloud infrastructure. @@ -12,7 +8,7 @@ minutes_to_complete: 60 who_is_this_for: This is an advanced topic for developers who want to build and benchmark QuantLib on Arm-based cloud instances. learning_objectives: - - Explain why QuantLib is a useful benchmark for Arm-based cloud systems + - Understand why QuantLib is a useful benchmark for Arm-based cloud systems - Create and connect to an Arm64 Azure Cobalt virtual machine running Ubuntu - Build QuantLib from source with benchmark support enabled - Run QuantLib benchmark workloads with different sizes and thread counts @@ -27,7 +23,7 @@ author: Chris Moroney generate_summary_faq: true ### Tags -skilllevels: Introductory +skilllevels: Advanced subjects: Performance and Architecture cloud_service_providers: - Microsoft Azure