diff --git a/doc/modules/ROOT/nav.adoc b/doc/modules/ROOT/nav.adoc index 9828e87..ff3667f 100644 --- a/doc/modules/ROOT/nav.adoc +++ b/doc/modules/ROOT/nav.adoc @@ -54,4 +54,37 @@ ** xref:functional.adoc[] * xref:comparisons.adoc[] * xref:benchmarks.adoc[] +** xref:benchmarks.adoc#run_benchmarks_[How to run the Benchmarks] +** xref:benchmarks.adoc#benchmarks_methodology[Methodology] +** Linux +*** xref:benchmarks.adoc#linux_x64_benchmarks[x64] +**** xref:benchmarks.adoc#linux_x64_floating_point[Floating-Point] +**** xref:benchmarks.adoc#linux_x64_signed_integers[Signed Integers] +**** xref:benchmarks.adoc#linux_x64_unsigned_integers[Unsigned Integers] +*** xref:benchmarks.adoc#linux_x86_32_benchmarks[x86 (32-bit)] +**** xref:benchmarks.adoc#linux_x86_32_floating_point[Floating-Point] +**** xref:benchmarks.adoc#linux_x86_32_signed_integers[Signed Integers] +**** xref:benchmarks.adoc#linux_x86_32_unsigned_integers[Unsigned Integers] +*** xref:benchmarks.adoc#linux_arm64_benchmarks[ARM64] +**** xref:benchmarks.adoc#linux_arm64_floating_point[Floating-Point] +**** xref:benchmarks.adoc#linux_arm64_signed_integers[Signed Integers] +**** xref:benchmarks.adoc#linux_arm64_unsigned_integers[Unsigned Integers] +** macOS +*** xref:benchmarks.adoc#macos_arm64_benchmarks[ARM64] +**** xref:benchmarks.adoc#macos_arm64_floating_point[Floating-Point] +**** xref:benchmarks.adoc#macos_arm64_signed_integers[Signed Integers] +**** xref:benchmarks.adoc#macos_arm64_unsigned_integers[Unsigned Integers] +** Windows +*** xref:benchmarks.adoc#windows_x64_benchmarks[x64] +**** xref:benchmarks.adoc#windows_x64_floating_point[Floating-Point] +**** xref:benchmarks.adoc#windows_x64_signed_integers[Signed Integers] +**** xref:benchmarks.adoc#windows_x64_unsigned_integers[Unsigned Integers] +*** xref:benchmarks.adoc#windows_x86_32_benchmarks[x86 (32-bit)] +**** xref:benchmarks.adoc#windows_x86_32_floating_point[Floating-Point] +**** xref:benchmarks.adoc#windows_x86_32_signed_integers[Signed Integers] +**** xref:benchmarks.adoc#windows_x86_32_unsigned_integers[Unsigned Integers] +*** xref:benchmarks.adoc#windows_arm64_benchmarks[ARM64] +**** xref:benchmarks.adoc#windows_arm64_floating_point[Floating-Point] +**** xref:benchmarks.adoc#windows_arm64_signed_integers[Signed Integers] +**** xref:benchmarks.adoc#windows_arm64_unsigned_integers[Unsigned Integers] * xref:reference.adoc[] diff --git a/doc/modules/ROOT/pages/benchmarks.adoc b/doc/modules/ROOT/pages/benchmarks.adoc index 9ad722d..0ecc79b 100644 --- a/doc/modules/ROOT/pages/benchmarks.adoc +++ b/doc/modules/ROOT/pages/benchmarks.adoc @@ -22,8 +22,8 @@ Because the baseline differs by width, every table states the type it is measure NOTE: Boost.SafeNumerics has no floating-point type and no 128-bit type, so the floating-point and 128-bit tables list only the built-in type and Boost.SafeNumbers. See xref:comparisons.adoc[] for the details of that limitation. -== How to run the Benchmarks [#run_benchmarks_] +== How to run the Benchmarks The benchmarks live in `test/benchmarks/` and are built with https://github.com/google/benchmark[Google Benchmark]. They are not part of the default build: configure with `-DBOOST_SAFE_NUMBERS_BUILD_BENCHMARKS=ON`, which pulls Google Benchmark in with CMake `FetchContent` so no system install is required. @@ -42,6 +42,7 @@ cmake --build __build__ --config Release \ The `benchmarks.yml` GitHub Actions workflow runs the same build across a spread of native runners, emits each suite's JSON, and renders the per-platform sections below with `test/benchmarks/render_results.py`. +[#benchmarks_methodology] == Methodology Each benchmark fills a vector of 1,000,000 random values once, outside the timed region, and then for every operation evaluates `op(vec[i], vec[i + 1])` across the whole vector. @@ -65,6 +66,7 @@ NOTE: The numbers come from shared CI runners and reflect a single run each, so Run on the GitHub Actions `ubuntu-latest` runner using GCC 14 in release mode (`-O2`, pass:[C++]20). +[#linux_x64_floating_point] === Floating-Point .32-bit floating point (ratio relative to `float`) @@ -87,6 +89,7 @@ Run on the GitHub Actions `ubuntu-latest` runner using GCC 14 in release mode (` | Division | 1.41 | 1.42 | 1.00 |=== +[#linux_x64_signed_integers] === Signed Integers .8-bit signed (ratio relative to `std::int8_t`) @@ -144,6 +147,7 @@ Run on the GitHub Actions `ubuntu-latest` runner using GCC 14 in release mode (` | Modulo | 6.56 | 7.19 | 1.10 |=== +[#linux_x64_unsigned_integers] === Unsigned Integers .8-bit unsigned (ratio relative to `std::uint8_t`) @@ -206,6 +210,7 @@ Run on the GitHub Actions `ubuntu-latest` runner using GCC 14 in release mode (` Run on the GitHub Actions `ubuntu-latest` runner using GCC 14 targeting 32-bit x86 (`-m32`) in release mode (`-O2`, pass:[C++]20). +[#linux_x86_32_floating_point] === Floating-Point .32-bit floating point (ratio relative to `float`) @@ -228,6 +233,7 @@ Run on the GitHub Actions `ubuntu-latest` runner using GCC 14 targeting 32-bit x | Division | 6.32 | 6.21 | 0.98 |=== +[#linux_x86_32_signed_integers] === Signed Integers .8-bit signed (ratio relative to `std::int8_t`) @@ -285,6 +291,7 @@ Run on the GitHub Actions `ubuntu-latest` runner using GCC 14 targeting 32-bit x | Modulo | 13.47 | 16.47 | 1.22 |=== +[#linux_x86_32_unsigned_integers] === Unsigned Integers .8-bit unsigned (ratio relative to `std::uint8_t`) @@ -347,6 +354,7 @@ Run on the GitHub Actions `ubuntu-latest` runner using GCC 14 targeting 32-bit x Run on the GitHub Actions `ubuntu-24.04-arm` runner using GCC 14 in release mode (`-O2`, pass:[C++]20). +[#linux_arm64_floating_point] === Floating-Point .32-bit floating point (ratio relative to `float`) @@ -369,6 +377,7 @@ Run on the GitHub Actions `ubuntu-24.04-arm` runner using GCC 14 in release mode | Division | 1.48 | 1.75 | 1.19 |=== +[#linux_arm64_signed_integers] === Signed Integers .8-bit signed (ratio relative to `std::int8_t`) @@ -426,6 +435,7 @@ Run on the GitHub Actions `ubuntu-24.04-arm` runner using GCC 14 in release mode | Modulo | 5.04 | 5.18 | 1.03 |=== +[#linux_arm64_unsigned_integers] === Unsigned Integers .8-bit unsigned (ratio relative to `std::uint8_t`) @@ -488,6 +498,7 @@ Run on the GitHub Actions `ubuntu-24.04-arm` runner using GCC 14 in release mode Run on the GitHub Actions `macos-latest` runner (Apple Silicon) using Apple Clang in release mode (`-O2`, pass:[C++]20). +[#macos_arm64_floating_point] === Floating-Point .32-bit floating point (ratio relative to `float`) @@ -510,6 +521,7 @@ Run on the GitHub Actions `macos-latest` runner (Apple Silicon) using Apple Clan | Division | 3.64 | 3.69 | 1.01 |=== +[#macos_arm64_signed_integers] === Signed Integers .8-bit signed (ratio relative to `std::int8_t`) @@ -567,6 +579,7 @@ Run on the GitHub Actions `macos-latest` runner (Apple Silicon) using Apple Clan | Modulo | 7.20 | 7.92 | 1.10 |=== +[#macos_arm64_unsigned_integers] === Unsigned Integers .8-bit unsigned (ratio relative to `std::uint8_t`) @@ -629,6 +642,7 @@ Run on the GitHub Actions `macos-latest` runner (Apple Silicon) using Apple Clan Run on the GitHub Actions `windows-latest` runner using MSVC in release mode (`/O2`, pass:[C++]20). +[#windows_x64_floating_point] === Floating-Point .32-bit floating point (ratio relative to `float`) @@ -651,6 +665,7 @@ Run on the GitHub Actions `windows-latest` runner using MSVC in release mode (`/ | Division | 3.82 | 3.91 | 1.02 |=== +[#windows_x64_signed_integers] === Signed Integers .8-bit signed (ratio relative to `std::int8_t`) @@ -708,6 +723,7 @@ Run on the GitHub Actions `windows-latest` runner using MSVC in release mode (`/ | Modulo | 15.63 | 17.36 | 1.11 |=== +[#windows_x64_unsigned_integers] === Unsigned Integers .8-bit unsigned (ratio relative to `std::uint8_t`) @@ -770,6 +786,7 @@ Run on the GitHub Actions `windows-latest` runner using MSVC in release mode (`/ Run on the GitHub Actions `windows-latest` runner using MSVC targeting 32-bit x86 in release mode (`/O2`, pass:[C++]20). +[#windows_x86_32_floating_point] === Floating-Point .32-bit floating point (ratio relative to `float`) @@ -792,6 +809,7 @@ Run on the GitHub Actions `windows-latest` runner using MSVC targeting 32-bit x8 | Division | 3.82 | 17.36 | 4.55 |=== +[#windows_x86_32_signed_integers] === Signed Integers .8-bit signed (ratio relative to `std::int8_t`) @@ -849,6 +867,7 @@ Run on the GitHub Actions `windows-latest` runner using MSVC targeting 32-bit x8 | Modulo | 26.04 | 31.25 | 1.20 |=== +[#windows_x86_32_unsigned_integers] === Unsigned Integers .8-bit unsigned (ratio relative to `std::uint8_t`) @@ -911,6 +930,7 @@ Run on the GitHub Actions `windows-latest` runner using MSVC targeting 32-bit x8 Run on the GitHub Actions `windows-11-arm` runner using MSVC in release mode (`/O2`, pass:[C++]20). +[#windows_arm64_floating_point] === Floating-Point .32-bit floating point (ratio relative to `float`) @@ -933,6 +953,7 @@ Run on the GitHub Actions `windows-11-arm` runner using MSVC in release mode (`/ | Division | 2.08 | 3.65 | 1.75 |=== +[#windows_arm64_signed_integers] === Signed Integers .8-bit signed (ratio relative to `std::int8_t`) @@ -990,6 +1011,7 @@ Run on the GitHub Actions `windows-11-arm` runner using MSVC in release mode (`/ | Modulo | 7.81 | 8.33 | 1.07 |=== +[#windows_arm64_unsigned_integers] === Unsigned Integers .8-bit unsigned (ratio relative to `std::uint8_t`) diff --git a/test/benchmarks/render_results.py b/test/benchmarks/render_results.py index 4b6af25..0776be1 100755 --- a/test/benchmarks/render_results.py +++ b/test/benchmarks/render_results.py @@ -205,6 +205,7 @@ def render_section(title, anchor, desc, unsigned_json, signed_json, float_json): if float_json: data = load_ns_per_op(float_json) + out.append(f"[#{anchor}_floating_point]") out.append("=== Floating-Point") out.append("") for bits in FLOAT_BITS: @@ -212,6 +213,7 @@ def render_section(title, anchor, desc, unsigned_json, signed_json, float_json): if signed_json: data = load_ns_per_op(signed_json) + out.append(f"[#{anchor}_signed_integers]") out.append("=== Signed Integers") out.append("") for bits in INT_BITS: @@ -219,6 +221,7 @@ def render_section(title, anchor, desc, unsigned_json, signed_json, float_json): if unsigned_json: data = load_ns_per_op(unsigned_json) + out.append(f"[#{anchor}_unsigned_integers]") out.append("=== Unsigned Integers") out.append("") for bits in INT_BITS: