Add integer-bench: a standalone bigint comparison benchmark crate

.github/workflows/tests.yml

@@ -127,6 +127,24 @@ jobs:
       - run: cargo build --features gmp
         working-directory: benchmark
 
+  smoke-test-integer-bench:
+    name: Smoke-test integer benchmarks
+    runs-on: ubuntu-latest
+    env:
+      RUSTFLAGS: -D warnings
+    steps:
+      - uses: actions/checkout@v4
+      - uses: dtolnay/rust-toolchain@master
+        with:
+          toolchain: stable
+      # Build every bench and run each one once (criterion `--test`): no
+      # measurement and no numbers reported, since CI is far too noisy for real
+      # benchmarking. This only checks the benches still compile and run.
+      # Pure-Rust backends only — the optional `gmp`/rug backend needs the GMP
+      # toolchain and is left out to keep this fast and dependency-free.
+      - run: cargo bench -- --test
+        working-directory: integer-bench
+
   build-aarch64:
     name: Build aarch64
     runs-on: ubuntu-latest

.gitignore

@@ -4,3 +4,5 @@
 /.vscode/settings.json
 benchmark/Cargo.lock
 benchmark/target
+integer-bench/Cargo.lock
+integer-bench/target

Cargo.toml

@@ -26,7 +26,7 @@ members = [
     "python",
     "rational",
 ]
-exclude = ["benchmark"]
+exclude = ["benchmark", "integer-bench"]
 default-members = ["base", "integer", "float", "rational", "macros"]
 
 [features]

integer-bench/Cargo.toml

@@ -0,0 +1,60 @@
+# Standalone benchmark crate comparing dashu-int against other bigint
+# libraries. Kept out of the dashu workspace (see the root `exclude`) so it
+# never gets pulled into dashu-int's `--all-features` builds or its MSRV check
+# — this crate can require a newer toolchain (malachite needs Rust 1.90).
+#
+# Run (pure-Rust backends, no toolchain needed):
+#   cargo bench --manifest-path integer-bench/Cargo.toml
+# Add the rug (GNU GMP) backend (needs the GMP toolchain):
+#   cargo bench --manifest-path integer-bench/Cargo.toml --features gmp
+[package]
+name = "integer-bench"
+version = "0.0.0"
+edition = "2021"
+publish = false
+license = "MIT OR Apache-2.0"
+rust-version = "1.90" # malachite 0.9 is edition 2024 / MSRV 1.90
+
+# Don't run libtest on the lib target under `cargo bench` — only the criterion
+# `[[bench]]` targets below should run, and they take criterion's CLI args.
+[lib]
+bench = false
+
+[features]
+default = []
+# Adds rug (links libgmp/libmpfr/libmpc) as an extra backend.
+gmp = ["dep:rug"]
+
+[dependencies]
+dashu-int = { path = "../integer", features = ["rand"] }
+rand_v08 = { version = "0.8.3", package = "rand" }
+
+# Comparison libraries (pure Rust; always built).
+ibig = "0.3.6"
+num-bigint = "0.4.6"
+num-integer = "0.1.46"
+num-traits = "0.2.19"
+malachite-nz = "0.9.1"
+malachite-base = "0.9.1"
+
+# rug links the system/GMP toolchain, so it is optional behind `gmp`.
+rug = { version = "1.30", optional = true }
+
+[dev-dependencies]
+criterion = { version = "0.5.1", features = ["html_reports"] }
+
+[[bench]]
+name = "primitive"
+harness = false
+
+[[bench]]
+name = "small_int"
+harness = false
+
+[[bench]]
+name = "workload"
+harness = false
+
+[[bench]]
+name = "shrinker"
+harness = false

integer-bench/README.md

@@ -0,0 +1,63 @@
+Criterion benchmarks comparing [`dashu-int`](../integer) against other Rust
+big-integer libraries. Each bench body is written once, generic over a
+`Backend`, and run for every library, with the backend name as a `BenchmarkId`
+dimension — so a single run reports all libraries side-by-side in one group.
+
+This is a standalone crate, deliberately kept out of the dashu workspace (see
+the root `Cargo.toml` `exclude`). That means it never gets pulled into
+`dashu-int`'s `--all-features` builds or its MSRV check, and it is free to
+require a newer toolchain than dashu (malachite needs Rust 1.90).
+
+## Libraries
+
+| Library                                          | Version | Notes                                          |
+| -------                                          | ------- | -----                                          |
+| [dashu-int](https://crates.io/crates/dashu-int)  | (path)  | The library under test. Pure Rust, no_std      |
+| [ibig](https://crates.io/crates/ibig)            | 0.3     | Pure Rust, no_std. dashu-int's ancestor        |
+| [num-bigint](https://crates.io/crates/num-bigint)| 0.4     | Pure Rust. The de-facto standard               |
+| [malachite](https://crates.io/crates/malachite)  | 0.9     | Pure Rust, LGPL, derived from GMP and FLINT    |
+| [rug](https://crates.io/crates/rug)              | 1.30    | Links [GMP](https://gmplib.org/); `gmp` feature |
+
+The pure-Rust backends (dashu, ibig, num-bigint, malachite) are always built.
+rug is added under the `gmp` feature, which needs the GMP toolchain.
+
+## Benchmarks
+
+| Bench       | What it covers                                                                 |
+| -----       | -------------                                                                  |
+| `primitive` | Bit-width sweep (10^1..10^4 bits): add/sub/mul/div, gcd, pow, radix, modular   |
+| `small_int` | Small / inline-magnitude values (≤ 128 bits) the bit-width sweep under-covers  |
+| `workload`  | Generator/shrinker-style scenarios: running sums, string round-trips, op mixes |
+| `shrinker`  | The bigint operations a property-based-testing shrinker performs               |
+
+The `workload` and `shrinker` shapes were drawn from profiling
+[hegel-rust](https://github.com/hegeldev/hegel-rust) but are written to stand on
+their own.
+
+The `primitive` `ubig_modulo_*` benches measure each library's plain
+multiply-then-reduce and native modpow (nothing precomputed), for a
+like-for-like comparison.
+
+## Usage
+
+Run from the repository root with `--manifest-path`, or from inside this
+directory:
+
+```sh
+# All pure-Rust backends (no toolchain needed):
+cargo bench --manifest-path integer-bench/Cargo.toml
+
+# A single bench, quickly:
+cargo bench --manifest-path integer-bench/Cargo.toml --bench small_int -- --quick
+
+# Include the rug (GMP) backend (needs the GMP toolchain):
+cargo bench --manifest-path integer-bench/Cargo.toml --features gmp
+
+# Smoke test only — build and run each bench once, no measurement:
+cargo bench --manifest-path integer-bench/Cargo.toml -- --test
+```
+
+## License
+
+Part of the [dashu](..) project; dual-licensed under
+[MIT](../LICENSE-MIT) or [Apache-2.0](../LICENSE-APACHE).