From 5e18c15b096552b33f36e761e2ede5cffa87cdd5 Mon Sep 17 00:00:00 2001 From: Trecek Date: Wed, 11 Nov 2026 15:17:28 -0800 Subject: [PATCH 001/113] Phase 0: truthful baseline and release gates Repository hygiene - Track the pending .autoskillit/.gitignore entries. - Replace the 11 tracked absolute symlinks under research/ with a DATA.md per directory naming each source file and its regenerating script; add research/README.md pointing at the research-baseline-pre-0.1 tag. Manifest truth - rust-version 1.88 (let-chains), valid keywords, no documentation key, an include allow-list, docs.rs metadata reduced to rustdoc-args. - Track Cargo.lock (regenerated; rand, crossbeam-epoch and the yanked private-gemm-x86 advisories are gone). - MSRV text updated in README, user guide and the bug-report template. Portable build - Delete .cargo/config.toml (target-cpu=native). - Trustworthiness x-distance kernel: runtime AVX2+FMA dispatch instead of compile-time target_feature gating; guard the unit test and the bench. Lint and docs - Pass ComputeMode::RustNative at the 8 stale solve_eigenproblem_pub call sites in lobpcg_bench and simd_spmv_exp. - Clear every --all-targets --all-features clippy diagnostic and all rustdoc errors. Tests - Remove the 28 stale fixture-gated #[ignore] attributes. - Move the fixture-reading unit tests out of src/: scaling and operator tests become integration tests; the components tests duplicated test_comp_c_components and are dropped. CI - Add .github/scripts/check-package.sh and the package allow-list. - test.yml: no RUSTFLAGS, --locked, clippy --all-targets without -A missing_docs, docs and doctest gate, MSRV job, package gate. Co-Authored-By: Claude --- .autoskillit/.gitignore | 5 + .cargo/config.toml | 2 - .github/ISSUE_TEMPLATE/bug_report.yml | 6 +- .github/package-allowlist.txt | 26 + .github/scripts/check-package.sh | 58 + .github/workflows/test.yml | 68 +- .gitignore | 1 - Cargo.lock | 2268 +++++++++++++++++ Cargo.toml | 16 +- README.md | 4 +- benches/dist_sq_bench.rs | 25 +- benches/lobpcg_bench.rs | 26 +- benches/simd_spmv_exp.rs | 67 +- benches/spectral_bench.rs | 2 +- docs/user-guide.md | 2 +- .../data/DATA.md | 23 + .../data/merfish_10k_labels.npz | 1 - .../data/merfish_10k_pca.npy | 1 - .../data/merfish_10k_spatial.npz | 1 - .../data/merfish/DATA.md | 30 + .../data/merfish/merfish_n10000_x.npy | 1 - .../data/merfish/merfish_n10000_y.npy | 1 - .../data/merfish/merfish_n10k_x.npy | 1 - .../data/merfish/merfish_n10k_y.npy | 1 - .../data/merfish/merfish_n50000_x.npy | 1 - .../data/merfish/merfish_n50000_y.npy | 1 - .../data/merfish/merfish_n50k_x.npy | 1 - .../data/merfish/merfish_n50k_y.npy | 1 - research/README.md | 22 + src/components.rs | 186 -- src/lib.rs | 14 +- src/metrics.rs | 53 +- src/operator.rs | 112 - src/scaling.rs | 163 -- src/solvers/dense.rs | 3 +- src/solvers/lobpcg.rs | 8 +- src/solvers/mod.rs | 14 +- src/solvers/rsvd.rs | 11 +- src/solvers/sinv.rs | 8 +- tests/integration/test_adversarial_graphs.rs | 30 +- tests/integration/test_comp_c_components.rs | 10 - tests/integration/test_metrics_assess.rs | 4 +- tests/integration/test_operator_fixtures.rs | 69 + tests/integration/test_pipeline.rs | 4 - tests/integration/test_scaling_fixtures.rs | 134 + tests/integration/test_simd_lobpcg_parity.rs | 20 +- tests/integration/test_trustworthiness.rs | 1 - .../integration/test_warm_restart_benefit.rs | 4 +- 48 files changed, 2838 insertions(+), 672 deletions(-) delete mode 100644 .cargo/config.toml create mode 100644 .github/package-allowlist.txt create mode 100755 .github/scripts/check-package.sh create mode 100644 Cargo.lock create mode 100644 research/2026-04-03-merfish-param-sweep-robustness/data/DATA.md delete mode 120000 research/2026-04-03-merfish-param-sweep-robustness/data/merfish_10k_labels.npz delete mode 120000 research/2026-04-03-merfish-param-sweep-robustness/data/merfish_10k_pca.npy delete mode 120000 research/2026-04-03-merfish-param-sweep-robustness/data/merfish_10k_spatial.npz create mode 100644 research/2026-04-09-subsampled-tw-tradeoff/data/merfish/DATA.md delete mode 120000 research/2026-04-09-subsampled-tw-tradeoff/data/merfish/merfish_n10000_x.npy delete mode 120000 research/2026-04-09-subsampled-tw-tradeoff/data/merfish/merfish_n10000_y.npy delete mode 120000 research/2026-04-09-subsampled-tw-tradeoff/data/merfish/merfish_n10k_x.npy delete mode 120000 research/2026-04-09-subsampled-tw-tradeoff/data/merfish/merfish_n10k_y.npy delete mode 120000 research/2026-04-09-subsampled-tw-tradeoff/data/merfish/merfish_n50000_x.npy delete mode 120000 research/2026-04-09-subsampled-tw-tradeoff/data/merfish/merfish_n50000_y.npy delete mode 120000 research/2026-04-09-subsampled-tw-tradeoff/data/merfish/merfish_n50k_x.npy delete mode 120000 research/2026-04-09-subsampled-tw-tradeoff/data/merfish/merfish_n50k_y.npy create mode 100644 research/README.md create mode 100644 tests/integration/test_operator_fixtures.rs create mode 100644 tests/integration/test_scaling_fixtures.rs diff --git a/.autoskillit/.gitignore b/.autoskillit/.gitignore index a6d7ecd..3b77c84 100644 --- a/.autoskillit/.gitignore +++ b/.autoskillit/.gitignore @@ -1 +1,6 @@ temp/ +.secrets.yaml +.onboarded +sync_manifest.json +test-filter-manifest.yaml +validation-errors/ diff --git a/.cargo/config.toml b/.cargo/config.toml deleted file mode 100644 index ddff440..0000000 --- a/.cargo/config.toml +++ /dev/null @@ -1,2 +0,0 @@ -[build] -rustflags = ["-C", "target-cpu=native"] diff --git a/.github/ISSUE_TEMPLATE/bug_report.yml b/.github/ISSUE_TEMPLATE/bug_report.yml index 5683bab..4e95a70 100644 --- a/.github/ISSUE_TEMPLATE/bug_report.yml +++ b/.github/ISSUE_TEMPLATE/bug_report.yml @@ -39,7 +39,7 @@ body: id: rust_version attributes: label: Rust Version - placeholder: "rustc 1.85.0 (e71f9a9a9 2025-01-27)" + placeholder: "rustc 1.88.0 (6b00bc388 2025-06-23)" validations: required: true @@ -55,8 +55,8 @@ body: id: cpu_features attributes: label: CPU Features - description: Output of `RUSTFLAGS="-C target-cpu=native" cargo rustc -- --print cfg 2>&1 | grep target_feature` - placeholder: 'target_feature = "avx2"' + description: CPU model and, on x86_64, whether it supports AVX2 and FMA (Linux — `lscpu | grep -o -w -E 'avx2|fma' | sort -u`) + placeholder: "AMD Ryzen 9 7950X — avx2, fma" - type: input id: graph_size diff --git a/.github/package-allowlist.txt b/.github/package-allowlist.txt new file mode 100644 index 0000000..00428cc --- /dev/null +++ b/.github/package-allowlist.txt @@ -0,0 +1,26 @@ +.cargo_vcs_info.json +Cargo.lock +Cargo.toml +Cargo.toml.orig +LICENSE +README.md +docs/katex-header.html +examples/basic.rs +examples/compute_modes.rs +examples/from_adjacency_list.rs +src/bin/trustworthiness.rs +src/bin/tw_profiler.rs +src/components.rs +src/config.rs +src/laplacian.rs +src/lib.rs +src/metrics.rs +src/multi_component.rs +src/operator.rs +src/scaling.rs +src/selection.rs +src/solvers/dense.rs +src/solvers/lobpcg.rs +src/solvers/mod.rs +src/solvers/rsvd.rs +src/solvers/sinv.rs diff --git a/.github/scripts/check-package.sh b/.github/scripts/check-package.sh new file mode 100755 index 0000000..b6f7890 --- /dev/null +++ b/.github/scripts/check-package.sh @@ -0,0 +1,58 @@ +#!/usr/bin/env bash +# Package gate for the published crate. +# +# Checks that +# 1. `cargo package --list` equals the committed allow-list, +# 2. the .crate file is smaller than 1 MiB, +# 3. the unpacked .crate passes its own lib, example and doc tests, and +# 4. `cargo publish --dry-run` succeeds. +# +# Usage: .github/scripts/check-package.sh [extra flags for cargo package/publish] +# e.g. .github/scripts/check-package.sh --allow-dirty +set -euo pipefail + +repo_root="$(cd "$(dirname "${BASH_SOURCE[0]}")/../.." && pwd)" +cd "$repo_root" + +package="spectral-init" +allowlist=".github/package-allowlist.txt" +max_bytes=$((1024 * 1024)) + +echo "==> package file list equals ${allowlist}" +diff -u \ + <(LC_ALL=C sort "$allowlist") \ + <(cargo package -p "$package" --locked --list "$@" | LC_ALL=C sort) + +echo "==> build the .crate" +cargo package -p "$package" --locked --no-verify "$@" + +pkgid="$(cargo pkgid -p "$package")" +version="${pkgid##*#}" +version="${version##*@}" +target_dir="$(cargo metadata --format-version 1 --no-deps --locked \ + | sed -n 's/.*"target_directory":"\([^"]*\)".*/\1/p')" +crate_file="${target_dir}/package/${package}-${version}.crate" + +size="$(wc -c < "$crate_file")" +echo " ${crate_file}: ${size} bytes" +if [ "$size" -ge "$max_bytes" ]; then + echo "error: .crate is ${size} bytes; the limit is ${max_bytes}" >&2 + exit 1 +fi + +echo "==> the unpacked .crate passes its own tests" +# Unpack outside the repository: inside it, Cargo's workspace discovery would +# attach the unpacked crate to the root workspace. +workdir="$(mktemp -d)" +trap 'rm -rf "$workdir"' EXIT +tar -xzf "$crate_file" -C "$workdir" +( + cd "${workdir}/${package}-${version}" + cargo test --locked --lib --examples + cargo test --locked --doc +) + +echo "==> publish dry run" +cargo publish -p "$package" --dry-run --locked "$@" + +echo "package gate passed" diff --git a/.github/workflows/test.yml b/.github/workflows/test.yml index 13bd0c9..c4b8bf3 100644 --- a/.github/workflows/test.yml +++ b/.github/workflows/test.yml @@ -17,9 +17,6 @@ jobs: name: cargo nextest runs-on: ubuntu-latest - env: - RUSTFLAGS: "-C target-cpu=x86-64-v3" - steps: - uses: actions/checkout@v4 @@ -35,7 +32,7 @@ jobs: tool: cargo-nextest - name: Run tests (CI profile) - run: cargo nextest run --profile ci --features testing + run: cargo nextest run --locked --profile ci --features testing - name: Upload JUnit XML uses: actions/upload-artifact@v4 @@ -69,9 +66,66 @@ jobs: uses: Swatinem/rust-cache@v2 - name: Check formatting - run: cargo fmt --check + run: cargo fmt --all --check - name: Clippy - run: cargo clippy --all-features -- -D warnings -A missing_docs + run: cargo clippy --locked --all-targets --all-features -- -D warnings + + docs: + name: docs + runs-on: ubuntu-latest + + steps: + - uses: actions/checkout@v4 + + - name: Install Rust stable + uses: dtolnay/rust-toolchain@stable + + - name: Cache Rust build artifacts + uses: Swatinem/rust-cache@v2 + + - name: Build rustdoc + run: cargo doc --locked --no-deps -p spectral-init env: - RUSTFLAGS: "-C target-cpu=x86-64-v3" + RUSTDOCFLAGS: "-D warnings" + + - name: Run doctests + run: cargo test --locked --doc + + msrv: + name: msrv + runs-on: ubuntu-latest + + steps: + - uses: actions/checkout@v4 + + - name: Read rust-version from the manifest + id: msrv + run: echo "version=$(sed -n 's/^rust-version = "\(.*\)"/\1/p' Cargo.toml)" >> "$GITHUB_OUTPUT" + + - name: Install Rust ${{ steps.msrv.outputs.version }} + uses: dtolnay/rust-toolchain@master + with: + toolchain: ${{ steps.msrv.outputs.version }} + + - name: Cache Rust build artifacts + uses: Swatinem/rust-cache@v2 + + - name: Check the library on the MSRV toolchain + run: cargo check --locked --lib -p spectral-init + + package: + name: package + runs-on: ubuntu-latest + + steps: + - uses: actions/checkout@v4 + + - name: Install Rust stable + uses: dtolnay/rust-toolchain@stable + + - name: Cache Rust build artifacts + uses: Swatinem/rust-cache@v2 + + - name: Package gate + run: .github/scripts/check-package.sh diff --git a/.gitignore b/.gitignore index 88d4a4f..0c51c7d 100644 --- a/.gitignore +++ b/.gitignore @@ -1,6 +1,5 @@ # Rust /target/ -Cargo.lock # IDE .idea/ diff --git a/Cargo.lock b/Cargo.lock new file mode 100644 index 0000000..2b07456 --- /dev/null +++ b/Cargo.lock @@ -0,0 +1,2268 @@ +# This file is automatically @generated by Cargo. +# It is not intended for manual editing. +version = 4 + +[[package]] +name = "aho-corasick" +version = "1.1.5" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "c982642fa9e8606056828ee9a8505737230110bb1099153c79efe865c59d12ba" +dependencies = [ + "memchr", +] + +[[package]] +name = "alga" +version = "0.9.3" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "4f823d037a7ec6ea2197046bafd4ae150e6bc36f9ca347404f46a46823fa84f2" +dependencies = [ + "approx 0.3.2", + "num-complex 0.2.4", + "num-traits", +] + +[[package]] +name = "anes" +version = "0.1.6" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "4b46cbb362ab8752921c97e041f5e366ee6297bd428a31275b9fcf1e380f7299" + +[[package]] +name = "anstyle" +version = "1.0.14" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "940b3a0ca603d1eade50a4846a2afffd5ef57a9feac2c0e2ec2e14f9ead76000" + +[[package]] +name = "approx" +version = "0.3.2" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "f0e60b75072ecd4168020818c0107f2857bb6c4e64252d8d3983f6263b40a5c3" +dependencies = [ + "num-traits", +] + +[[package]] +name = "approx" +version = "0.5.1" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "cab112f0a86d568ea0e627cc1d6be74a1e9cd55214684db5561995f6dad897c6" +dependencies = [ + "num-traits", +] + +[[package]] +name = "ar_archive_writer" +version = "0.5.5" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "523e5e187fff36fcb8d1d19ccf0ca4ca43ec3d158316057f66dc6f72716bc5ec" +dependencies = [ + "object", +] + +[[package]] +name = "arbitrary" +version = "1.5.0" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "3bc62ac97cc33321f50863d514c3bc38a453947a8f9e781137e47c7401020aed" +dependencies = [ + "derive_arbitrary", +] + +[[package]] +name = "atomic-wait" +version = "1.1.0" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "a55b94919229f2c42292fd71ffa4b75e83193bffdd77b1e858cd55fd2d0b0ea8" +dependencies = [ + "libc", + "windows-sys 0.42.0", +] + +[[package]] +name = "autocfg" +version = "1.5.1" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "f2032f911046de80f0a198e0901378627c33f59ea0ac00e363d481118bd70a53" + +[[package]] +name = "bit-set" +version = "0.11.1" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "56d87354e4229f54a44f7bf2435906a4656dba36026ab6eaca629a2c436a691c" +dependencies = [ + "bit-vec", +] + +[[package]] +name = "bit-vec" +version = "0.10.2" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "72503af1e72be411d74ca45cd6b309878fcb35354e252fc2a3a8bda3a97082a0" +dependencies = [ + "borsh", + "serde", +] + +[[package]] +name = "bitflags" +version = "2.13.2" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "3ded4057c258ba199e2d26386d3af3780957ecaee6c4ef4041c6b4b8b97c0b06" + +[[package]] +name = "borsh" +version = "1.8.1" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "553c5d846a6ba5150c65e3b1b8ec073bcf1abc20f9b7220de384a4443ea4e20a" +dependencies = [ + "borsh-derive", + "bytes", + "cfg_aliases", +] + +[[package]] +name = "borsh-derive" +version = "1.8.1" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "12cdfe656708a01f89b451a7d36466e6fe6c414de0aa18fc54f864f6f9ca9f56" +dependencies = [ + "once_cell", + "proc-macro-crate", + "proc-macro2", + "quote", + "syn 3.0.10", +] + +[[package]] +name = "bumpalo" +version = "3.20.3" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "72f5acc6cb2ba439de613abc23857ec3d78374d8ed5ac84e9d11336e87da8649" + +[[package]] +name = "bytemuck" +version = "1.25.2" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "95832e849adfb21180ccb6826a99da14e5d266ae5c2e668e1602cf234f153797" +dependencies = [ + "bytemuck_derive", +] + +[[package]] +name = "bytemuck_derive" +version = "1.12.1" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "6a1f896587b6f2c069c73d2f0913e2d590c3990285cd2f0b6aa02b786b4c679c" +dependencies = [ + "proc-macro2", + "quote", + "syn 3.0.10", +] + +[[package]] +name = "byteorder" +version = "1.5.0" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "1fd0f2584146f6f2ef48085050886acf353beff7305ebd1ae69500e27c67f64b" + +[[package]] +name = "bytes" +version = "1.12.1" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "fc652a48c352aef3ea3aed32080501cf3ef6ed5da78602a020c991775b0aff04" + +[[package]] +name = "cast" +version = "0.3.0" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "37b2a672a2cb129a2e41c10b1224bb368f9f37a2b16b612598138befd7b37eb5" + +[[package]] +name = "cc" +version = "1.11.1" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "4ff2a8126fff0f8c839080d619675a585e61720bb12d2baceae45769fd66f155" +dependencies = [ + "find-msvc-tools", + "shlex", +] + +[[package]] +name = "cfg-if" +version = "1.0.5" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "4e7648175b45a9a48536d676f68d918270699102aa8dab5496df06904c914600" + +[[package]] +name = "cfg_aliases" +version = "0.2.2" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "f079e83a288787bcd14a6aea84cee5c87a67c5a3e660c30f557a3d24761b3527" + +[[package]] +name = "chacha20" +version = "0.10.2" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "65c35e4b699c7e15ccbe7ee35c005e4fc0a278d22238a2857e6ce2dadeda1b06" +dependencies = [ + "cfg-if", + "cpufeatures", + "rand_core 0.10.1", +] + +[[package]] +name = "ciborium" +version = "0.2.2" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "42e69ffd6f0917f5c029256a24d0161db17cea3997d185db0d35926308770f0e" +dependencies = [ + "ciborium-io", + "ciborium-ll", + "serde", +] + +[[package]] +name = "ciborium-io" +version = "0.2.2" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "05afea1e0a06c9be33d539b876f1ce3692f4afea2cb41f740e7743225ed1c757" + +[[package]] +name = "ciborium-ll" +version = "0.2.2" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "57663b653d948a338bfb3eeba9bb2fd5fcfaecb9e199e87e1eda4d9e8b240fd9" +dependencies = [ + "ciborium-io", + "half", +] + +[[package]] +name = "clap" +version = "4.6.7" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "aa8876b300ab35ba921adea3dfd70157a46249b33f95c9084ae5709785478946" +dependencies = [ + "clap_builder", +] + +[[package]] +name = "clap_builder" +version = "4.6.7" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "ec0797fb7aeb1406c84efac526901f7ec3ead2124f946b494e72879d4b54704d" +dependencies = [ + "anstyle", + "clap_lex", +] + +[[package]] +name = "clap_lex" +version = "1.1.1" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "1c133bc6a41be0d194c306b5506d15e6feeea7b1d6604bd3f8310dfb2ca96486" + +[[package]] +name = "core_detect" +version = "1.0.0" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "7f8f80099a98041a3d1622845c271458a2d73e688351bf3cb999266764b81d48" + +[[package]] +name = "cpufeatures" +version = "0.3.1" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "5ca28b0ae3115b884660db4118d803791fd6756b6e88f39c0f3f7859060d7566" +dependencies = [ + "libc", +] + +[[package]] +name = "crc32fast" +version = "1.5.5" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "2b929dd2a135771f40afabd1073f85eed59c800b7c61901e5c254270497dad64" +dependencies = [ + "cfg-if", +] + +[[package]] +name = "criterion" +version = "0.5.1" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "f2b12d017a929603d80db1831cd3a24082f8137ce19c69e6447f54f5fc8d692f" +dependencies = [ + "anes", + "cast", + "ciborium", + "clap", + "criterion-plot", + "is-terminal", + "itertools", + "num-traits", + "once_cell", + "oorandom", + "plotters", + "rayon", + "regex", + "serde", + "serde_derive", + "serde_json", + "tinytemplate", + "walkdir", +] + +[[package]] +name = "criterion-plot" +version = "0.5.0" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "6b50826342786a51a89e2da3a28f1c32b06e387201bc2d19791f622c673706b1" +dependencies = [ + "cast", + "itertools", +] + +[[package]] +name = "crossbeam" +version = "0.8.5" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "e71406cd8807725f7ac2f999a4cdd32e98f829fdf65f528343cebf945e41df1e" +dependencies = [ + "crossbeam-channel", + "crossbeam-deque", + "crossbeam-epoch", + "crossbeam-queue", + "crossbeam-utils", +] + +[[package]] +name = "crossbeam-channel" +version = "0.5.17" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "98b0cc327b5bc766e7fda9c9260cc0fa81b43a8e240440422dff70788e3f9ef1" +dependencies = [ + "crossbeam-utils", +] + +[[package]] +name = "crossbeam-deque" +version = "0.8.8" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "622f3fc73690be383c7214310406f28a90e6edeadc3cea882f9d71e495b9711a" +dependencies = [ + "crossbeam-epoch", + "crossbeam-utils", +] + +[[package]] +name = "crossbeam-epoch" +version = "0.9.21" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "dc74980687109a3b14c72fd458107bf0baa1da1a1a805e178d15501ba9b86d9d" +dependencies = [ + "crossbeam-utils", +] + +[[package]] +name = "crossbeam-queue" +version = "0.3.14" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "03e8bd762f7479489c70ed6c768ddca99d7296857de437a68dcb2a94365b3fae" +dependencies = [ + "crossbeam-utils", +] + +[[package]] +name = "crossbeam-utils" +version = "0.8.23" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "a31eee39dddec8330830986fcd7625edb5a24ec90ea038215273bbc3adb08ac6" + +[[package]] +name = "crunchy" +version = "0.2.4" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "460fbee9c2c2f33933d720630a6a0bac33ba7053db5344fac858d4b8952d77d5" + +[[package]] +name = "defer" +version = "0.2.1" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "930c7171c8df9fb1782bdf9b918ed9ed2d33d1d22300abb754f9085bc48bf8e8" + +[[package]] +name = "derive_arbitrary" +version = "1.5.0" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "1b034bd7d5f032402a2479444dcc6f74e36a03f31854d41680fb240ef682a1ac" +dependencies = [ + "proc-macro2", + "quote", + "syn 3.0.10", +] + +[[package]] +name = "dyn-stack" +version = "0.13.2" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "1c4713e43e2886ba72b8271aa66c93d722116acf7a75555cce11dcde84388fe8" +dependencies = [ + "bytemuck", + "dyn-stack-macros", +] + +[[package]] +name = "dyn-stack-macros" +version = "0.1.3" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "e1d926b4d407d372f141f93bb444696142c29d32962ccbd3531117cf3aa0bfa9" + +[[package]] +name = "either" +version = "1.19.0" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "0e9c71c2167ca323c882b99918929403426e2373ea17242ff5653e0d5e1058be" + +[[package]] +name = "enum-as-inner" +version = "0.6.1" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "a1e6a265c649f3f5979b601d26f1d05ada116434c87741c9493cb56218f76cbc" +dependencies = [ + "heck", + "proc-macro2", + "quote", + "syn 2.0.119", +] + +[[package]] +name = "equator" +version = "0.2.2" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "c35da53b5a021d2484a7cc49b2ac7f2d840f8236a286f84202369bd338d761ea" +dependencies = [ + "equator-macro 0.2.1", +] + +[[package]] +name = "equator" +version = "0.4.2" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "4711b213838dfee0117e3be6ac926007d7f433d7bbe33595975d4190cb07e6fc" +dependencies = [ + "equator-macro 0.4.2", +] + +[[package]] +name = "equator" +version = "0.6.0" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "02da895aab06bbebefb6b2595f6d637b18c9ff629b4cd840965bb3164e4194b0" +dependencies = [ + "equator-macro 0.6.0", +] + +[[package]] +name = "equator-macro" +version = "0.2.1" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "3bf679796c0322556351f287a51b49e48f7c4986e727b5dd78c972d30e2e16cc" +dependencies = [ + "proc-macro2", + "quote", + "syn 2.0.119", +] + +[[package]] +name = "equator-macro" +version = "0.4.2" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "44f23cf4b44bfce11a86ace86f8a73ffdec849c9fd00a386a53d278bd9e81fb3" +dependencies = [ + "proc-macro2", + "quote", + "syn 2.0.119", +] + +[[package]] +name = "equator-macro" +version = "0.6.0" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "2b14b339eb76d07f052cdbad76ca7c1310e56173a138095d3bf42a23c06ef5d8" + +[[package]] +name = "equivalent" +version = "1.0.3" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "00d174d5400e5e8fd687ad1049e2f578285fa914201b1af7e8b112a4546bd826" + +[[package]] +name = "errno" +version = "0.3.14" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "39cab71617ae0d63f51a36d69f866391735b51691dbda63cf6f96d042b63efeb" +dependencies = [ + "libc", + "windows-sys 0.61.2", +] + +[[package]] +name = "faer" +version = "0.24.4" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "5ab6df3dd147fe8d702a288b95bcd8fcc499ab572fc80da6828f60cd4d524d67" +dependencies = [ + "bytemuck", + "dyn-stack", + "equator 0.6.0", + "faer-traits", + "gemm", + "generativity", + "libm", + "nano-gemm", + "npyz", + "num-complex 0.4.6", + "num-traits", + "private-gemm-x86", + "pulp", + "rand 0.9.5", + "rand_distr", + "rayon", + "reborrow", + "spindle", +] + +[[package]] +name = "faer-traits" +version = "0.24.0" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "b87d23ed7ab1f26c0cba0e5b9e061a796fbb7dc170fa8bee6970055a1308bb0f" +dependencies = [ + "bytemuck", + "dyn-stack", + "generativity", + "libm", + "num-complex 0.4.6", + "num-traits", + "pulp", + "qd", + "reborrow", +] + +[[package]] +name = "fastrand" +version = "2.5.0" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "da7c62ceae207dd37ea5b845da6a0696c799f85e97da1ab5b7910be3c1c80223" + +[[package]] +name = "find-msvc-tools" +version = "0.1.15" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "1c66915cc5391097de7a2b0b972e8505aa33c0df401fd3a6811dbdb32881ba48" + +[[package]] +name = "flate2" +version = "1.1.11" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "626d4928326b646e70f65ed36fc7cf9f206bdb68a0019ee7c6b4709da4e084c4" +dependencies = [ + "zlib-rs", +] + +[[package]] +name = "fnv" +version = "1.0.7" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "3f9eec918d3f24069decb9af1554cad7c880e2da24a9afd88aca000531ab82c1" + +[[package]] +name = "futures-core" +version = "0.3.34" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "92d699e522242e69e3003b94ecc1f960f3a5e015aa7c5d7486e65ad01dd94f5e" + +[[package]] +name = "futures-task" +version = "0.3.34" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "cd417de3d1d015fc3bfd2b1ea46dfc7bab72ef86f1cc7cc9c78e728b34a6d1fd" + +[[package]] +name = "futures-util" +version = "0.3.34" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "0d50a92467f8ba5dd6e3ee5d4bd04d73ab2e4e1c44474a0674821dfce14b79bc" +dependencies = [ + "futures-core", + "futures-task", + "pin-project-lite", + "slab", +] + +[[package]] +name = "gemm" +version = "0.19.0" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "aa0673db364b12263d103b68337a68fbecc541d6f6b61ba72fe438654709eacb" +dependencies = [ + "dyn-stack", + "gemm-c32", + "gemm-c64", + "gemm-common", + "gemm-f16", + "gemm-f32", + "gemm-f64", + "num-complex 0.4.6", + "num-traits", + "paste", + "raw-cpuid", + "seq-macro", +] + +[[package]] +name = "gemm-c32" +version = "0.19.0" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "086936dbdcb99e37aad81d320f98f670e53c1e55a98bee70573e83f95beb128c" +dependencies = [ + "dyn-stack", + "gemm-common", + "num-complex 0.4.6", + "num-traits", + "paste", + "raw-cpuid", + "seq-macro", +] + +[[package]] +name = "gemm-c64" +version = "0.19.0" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "20c8aeeeec425959bda4d9827664029ba1501a90a0d1e6228e48bef741db3a3f" +dependencies = [ + "dyn-stack", + "gemm-common", + "num-complex 0.4.6", + "num-traits", + "paste", + "raw-cpuid", + "seq-macro", +] + +[[package]] +name = "gemm-common" +version = "0.19.0" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "88027625910cc9b1085aaaa1c4bc46bb3a36aad323452b33c25b5e4e7c8e2a3e" +dependencies = [ + "bytemuck", + "dyn-stack", + "half", + "libm", + "num-complex 0.4.6", + "num-traits", + "once_cell", + "paste", + "pulp", + "raw-cpuid", + "rayon", + "seq-macro", + "sysctl", +] + +[[package]] +name = "gemm-f16" +version = "0.19.0" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "e3df7a55202e6cd6739d82ae3399c8e0c7e1402859b30e4cb780e61525d9486e" +dependencies = [ + "dyn-stack", + "gemm-common", + "gemm-f32", + "half", + "num-complex 0.4.6", + "num-traits", + "paste", + "raw-cpuid", + "rayon", + "seq-macro", +] + +[[package]] +name = "gemm-f32" +version = "0.19.0" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "02e0b8c9da1fbec6e3e3ab2ce6bc259ef18eb5f6f0d3e4edf54b75f9fd41a81c" +dependencies = [ + "dyn-stack", + "gemm-common", + "num-complex 0.4.6", + "num-traits", + "paste", + "raw-cpuid", + "seq-macro", +] + +[[package]] +name = "gemm-f64" +version = "0.19.0" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "056131e8f2a521bfab322f804ccd652520c79700d81209e9d9275bbdecaadc6a" +dependencies = [ + "dyn-stack", + "gemm-common", + "num-complex 0.4.6", + "num-traits", + "paste", + "raw-cpuid", + "seq-macro", +] + +[[package]] +name = "generativity" +version = "1.2.1" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "d2c81fb5260e37854d09d5c87183309fd8c555b75289427884b25660bc87a85e" + +[[package]] +name = "generator" +version = "0.8.11" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "1be81b31c9ce4caf7f3178eeb90662bb1864d3ad363ec6bdada3201adff19c37" +dependencies = [ + "cc", + "cfg-if", + "libc", + "log", + "rustversion", + "windows-link", + "windows-result", +] + +[[package]] +name = "getrandom" +version = "0.2.17" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "ff2abc00be7fca6ebc474524697ae276ad847ad0a6b3faa4bcb027e9a4614ad0" +dependencies = [ + "cfg-if", + "libc", + "wasi", +] + +[[package]] +name = "getrandom" +version = "0.3.4" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "899def5c37c4fd7b2664648c28120ecec138e4d395b459e5ca34f9cce2dd77fd" +dependencies = [ + "cfg-if", + "libc", + "r-efi 5.3.0", + "wasip2", +] + +[[package]] +name = "getrandom" +version = "0.4.3" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "300e883d756b2e4ec94e02791f39b04b522276138852cfc41d9fb7e904106099" +dependencies = [ + "cfg-if", + "libc", + "r-efi 6.0.0", + "rand_core 0.10.1", +] + +[[package]] +name = "half" +version = "2.7.1" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "6ea2d84b969582b4b1864a92dc5d27cd2b77b622a8d79306834f1be5ba20d84b" +dependencies = [ + "bytemuck", + "cfg-if", + "crunchy", + "num-traits", + "zerocopy", +] + +[[package]] +name = "hashbrown" +version = "0.17.1" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "ed5909b6e89a2db4456e54cd5f673791d7eca6732202bbf2a9cc504fe2f9b84a" + +[[package]] +name = "heck" +version = "0.5.0" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "2304e00983f87ffb38b55b444b5e3b60a884b5d30c0fca7d82fe33449bbe55ea" + +[[package]] +name = "hermit-abi" +version = "0.5.3" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "e17592d60ebacc7d5e169f4663c5f84f9161cc90328abcfe8456f41e4dfcb284" + +[[package]] +name = "humantime" +version = "2.4.0" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "15cdd26707701c53297e2fa6afb323d55fbc1d0810c3aec078ae3ef0424c3c15" + +[[package]] +name = "indexmap" +version = "2.14.2" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "cc4e190f5d26ca7051642629da2c52fc03bde85a03197c99408dcd291734c855" +dependencies = [ + "equivalent", + "hashbrown", +] + +[[package]] +name = "interpol" +version = "0.2.1" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "eb58032ba748f4010d15912a1855a8a0b1ba9eaad3395b0c171c09b3b356ae50" +dependencies = [ + "proc-macro2", + "quote", + "syn 1.0.109", +] + +[[package]] +name = "is-terminal" +version = "0.4.17" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "3640c1c38b8e4e43584d8df18be5fc6b0aa314ce6ebf51b53313d4306cca8e46" +dependencies = [ + "hermit-abi", + "libc", + "windows-sys 0.61.2", +] + +[[package]] +name = "itertools" +version = "0.10.5" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "b0fd2260e829bddf4cb6ea802289de2f86d6a7a690192fbe91b3f46e0f2c8473" +dependencies = [ + "either", +] + +[[package]] +name = "itoa" +version = "1.0.19" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "3bd1574e617a9a6c1f8f8181bd7e841e1f20e4277607ef28945765188d6284d4" + +[[package]] +name = "js-sys" +version = "0.3.107" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "8dc09d2154098bbf4ef54eab6b117a3c24cbbffe94046b16ee6d6d4510584d3a" +dependencies = [ + "cfg-if", + "futures-util", + "wasm-bindgen", +] + +[[package]] +name = "lazy_static" +version = "1.5.1" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "20870f649af7073d53e38067b2a84312175d56ea15217e1b15bc83506ec50afb" + +[[package]] +name = "libc" +version = "0.2.191" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "65cd87c9a6d60536580b316ad985726104730a5151c99845f2490428ef91240a" + +[[package]] +name = "libm" +version = "0.2.16" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "b6d2cec3eae94f9f509c767b45932f1ada8350c4bdb85af2fcab4a3c14807981" + +[[package]] +name = "linfa-linalg" +version = "0.2.1" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "02a834c0ec063937688a0d13573aa515ab8c425bd8de3154b908dd3b9c197dc4" +dependencies = [ + "ndarray 0.16.1", + "num-traits", + "rand 0.8.8", + "thiserror 1.0.69", +] + +[[package]] +name = "linux-raw-sys" +version = "0.12.1" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "32a66949e030da00e8c7d4434b251670a91556f4144941d37452769c25d58a53" + +[[package]] +name = "log" +version = "0.4.35" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "5d15f86d12da44cd8d4ec3c73984537eb7f4cadcb9776a575a0a8a05ca11005c" + +[[package]] +name = "loom" +version = "0.7.3" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "f1611ddbf89dc6ae42cfbd51fc207836140130257646eab8d6d2fb16577db2d2" +dependencies = [ + "cfg-if", + "generator", + "scoped-tls", + "tracing", + "tracing-subscriber", +] + +[[package]] +name = "matchers" +version = "0.2.0" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "d1525a2a28c7f4fa0fc98bb91ae755d1e2d1505079e05539e35bc876b5d65ae9" +dependencies = [ + "regex-automata", +] + +[[package]] +name = "matrixmultiply" +version = "0.3.11" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "3f607c237553f086e7043417a51df26b2eb899d3caff94e6a67592ff992fedc7" +dependencies = [ + "autocfg", + "rawpointer", +] + +[[package]] +name = "memchr" +version = "2.8.3" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "cf8baf1c55e62ffcace7a9f06f4bd9cd3f0c4beb022d3b367256b91b87513d98" + +[[package]] +name = "nano-gemm" +version = "0.2.2" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "9e04345dc84b498ff89fe0d38543d1f170da9e43a2c2bcee73a0f9069f72d081" +dependencies = [ + "equator 0.2.2", + "nano-gemm-c32", + "nano-gemm-c64", + "nano-gemm-codegen", + "nano-gemm-core", + "nano-gemm-f32", + "nano-gemm-f64", + "num-complex 0.4.6", +] + +[[package]] +name = "nano-gemm-c32" +version = "0.2.1" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "0775b1e2520e64deee8fc78b7732e3091fb7585017c0b0f9f4b451757bbbc562" +dependencies = [ + "nano-gemm-codegen", + "nano-gemm-core", + "num-complex 0.4.6", +] + +[[package]] +name = "nano-gemm-c64" +version = "0.2.1" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "9af49a20d58816e6b5ee65f64142e50edb5eba152678d4bb7377fcbf63f8437a" +dependencies = [ + "nano-gemm-codegen", + "nano-gemm-core", + "num-complex 0.4.6", +] + +[[package]] +name = "nano-gemm-codegen" +version = "0.2.1" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "6cc8d495c791627779477a2cf5df60049f5b165342610eb0d76bee5ff5c5d74c" + +[[package]] +name = "nano-gemm-core" +version = "0.2.1" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "d998dfa644de87a0f8660e5ea511d7cb5c33b5a2d9847b7af57a2565105089f0" + +[[package]] +name = "nano-gemm-f32" +version = "0.2.1" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "879d962e79bc8952e4ad21ca4845a21132540ed3f5e01184b2ff7f720e666523" +dependencies = [ + "nano-gemm-codegen", + "nano-gemm-core", +] + +[[package]] +name = "nano-gemm-f64" +version = "0.2.1" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "b9a513473dce7dc00c7e7c318481ca4494034e76997218d8dad51bd9f007a815" +dependencies = [ + "nano-gemm-codegen", + "nano-gemm-core", +] + +[[package]] +name = "ndarray" +version = "0.16.1" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "882ed72dce9365842bf196bdeedf5055305f11fc8c03dee7bb0194a6cad34841" +dependencies = [ + "approx 0.5.1", + "matrixmultiply", + "num-complex 0.4.6", + "num-integer", + "num-traits", + "portable-atomic", + "portable-atomic-util", + "rawpointer", +] + +[[package]] +name = "ndarray" +version = "0.17.2" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "520080814a7a6b4a6e9070823bb24b4531daac8c4627e08ba5de8c5ef2f2752d" +dependencies = [ + "matrixmultiply", + "num-complex 0.4.6", + "num-integer", + "num-traits", + "portable-atomic", + "portable-atomic-util", + "rawpointer", +] + +[[package]] +name = "ndarray-npy" +version = "0.10.0" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "58e8a348bca0075000d999d750420d74434fd0d3e0993b456554f885e7657a11" +dependencies = [ + "byteorder", + "ndarray 0.17.2", + "num-complex 0.4.6", + "num-traits", + "py_literal", + "zip", +] + +[[package]] +name = "npyz" +version = "0.8.4" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "9f0e759e014e630f90af745101b614f761306ddc541681e546649068e25ec1b9" +dependencies = [ + "byteorder", + "num-bigint", + "py_literal", +] + +[[package]] +name = "nu-ansi-term" +version = "0.50.3" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "7957b9740744892f114936ab4a57b3f487491bbeafaf8083688b16841a4240e5" +dependencies = [ + "windows-sys 0.61.2", +] + +[[package]] +name = "num-bigint" +version = "0.4.8" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "c89e69e7e0f03bea5ef08013795c25018e101932225a656383bd384495ecc367" +dependencies = [ + "num-integer", + "num-traits", +] + +[[package]] +name = "num-complex" +version = "0.2.4" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "b6b19411a9719e753aff12e5187b74d60d3dc449ec3f4dc21e3989c3f554bc95" +dependencies = [ + "autocfg", + "num-traits", +] + +[[package]] +name = "num-complex" +version = "0.4.6" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "73f88a1307638156682bada9d7604135552957b7818057dcef22705b4d509495" +dependencies = [ + "bytemuck", + "num-traits", + "rand 0.8.8", +] + +[[package]] +name = "num-integer" +version = "0.1.47" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "7ce2d95d4b3734dc35aa2f45e1aa22cd416814592a4f9d9205e11affd5b8e10b" +dependencies = [ + "num-traits", +] + +[[package]] +name = "num-traits" +version = "0.2.19" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "071dfc062690e90b734c0b2273ce72ad0ffa95f0c74596bc250dcfd960262841" +dependencies = [ + "autocfg", + "libm", +] + +[[package]] +name = "num_cpus" +version = "1.17.0" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "91df4bbde75afed763b708b7eee1e8e7651e02d97f6d5dd763e89367e957b23b" +dependencies = [ + "hermit-abi", + "libc", +] + +[[package]] +name = "object" +version = "0.39.1" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "2e5a6c098c7a3b6547378093f5cc30bc54fd361ce711e05293a5cc589562739b" +dependencies = [ + "memchr", +] + +[[package]] +name = "once_cell" +version = "1.21.4" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "9f7c3e4beb33f85d45ae3e3a1792185706c8e16d043238c593331cc7cd313b50" + +[[package]] +name = "oorandom" +version = "11.1.5" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "d6790f58c7ff633d8771f42965289203411a5e5c68388703c06e14f24770b41e" + +[[package]] +name = "paste" +version = "1.0.15" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "57c0d7b74b563b49d38dae00a0c37d4d6de9b432382b2892f0574ddcae73fd0a" + +[[package]] +name = "pest" +version = "2.9.6" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "5ec53fd1d256900a9a771bf2720d42cef6f8bc91b4e25065fbd291e3e7222576" +dependencies = [ + "memchr", + "pest_stack_guard", + "ucd-trie", +] + +[[package]] +name = "pest_derive" +version = "2.9.6" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "adcf794fd301ddc20818a6b4de85ed507f4b45300245cec948982e69e12e3bd7" +dependencies = [ + "pest", + "pest_generator", +] + +[[package]] +name = "pest_generator" +version = "2.9.6" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "c3073afae5db334c25dea9fc3e230a4f191e920c1df080cb9c0b37c9ce1dbb41" +dependencies = [ + "pest", + "pest_meta", + "proc-macro2", + "quote", + "syn 3.0.10", +] + +[[package]] +name = "pest_meta" +version = "2.9.6" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "7bc7f614b3742541642af1685faaa910bf6333e3cd3729c2cccd118146a57327" +dependencies = [ + "pest", +] + +[[package]] +name = "pest_stack_guard" +version = "1.0.1" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "9ac6154fd4418b8f0b82532c59c26f303f9ca59a64c883e8ce3971fd82733439" +dependencies = [ + "psm", + "stacker", +] + +[[package]] +name = "pico-args" +version = "0.5.0" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "5be167a7af36ee22fe3115051bc51f6e6c7054c9348e28deb4f49bd6f705a315" + +[[package]] +name = "pin-project-lite" +version = "0.2.17" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "a89322df9ebe1c1578d689c92318e070967d1042b512afbe49518723f4e6d5cd" + +[[package]] +name = "plotters" +version = "0.3.7" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "5aeb6f403d7a4911efb1e33402027fc44f29b5bf6def3effcc22d7bb75f2b747" +dependencies = [ + "num-traits", + "plotters-backend", + "plotters-svg", + "wasm-bindgen", + "web-sys", +] + +[[package]] +name = "plotters-backend" +version = "0.3.7" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "df42e13c12958a16b3f7f4386b9ab1f3e7933914ecea48da7139435263a4172a" + +[[package]] +name = "plotters-svg" +version = "0.3.7" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "51bae2ac328883f7acdfea3d66a7c35751187f870bc81f94563733a154d7a670" +dependencies = [ + "plotters-backend", +] + +[[package]] +name = "portable-atomic" +version = "1.15.0" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "05c8b63e8d9609db387f0324918f81d68fe27748f084ef092fb35954d0539a85" + +[[package]] +name = "portable-atomic-util" +version = "0.2.8" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "10ab3eb7f3becc3a1cbc4f2c6f20267996cfc1a6467a873763411b136a122715" +dependencies = [ + "portable-atomic", +] + +[[package]] +name = "ppv-lite86" +version = "0.2.21" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "85eae3c4ed2f50dcfe72643da4befc30deadb458a9b590d720cde2f2b1e97da9" +dependencies = [ + "zerocopy", +] + +[[package]] +name = "private-gemm-x86" +version = "0.1.22" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "bba0a7831d1297712e7e7b33759b0c837941e79196dd05df506d5f36f7f78619" +dependencies = [ + "crossbeam", + "defer", + "interpol", + "num_cpus", + "raw-cpuid", + "rayon", + "spindle", + "sysctl", +] + +[[package]] +name = "proc-macro-crate" +version = "3.5.0" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "e67ba7e9b2b56446f1d419b1d807906278ffa1a658a8a5d8a39dcb1f5a78614f" +dependencies = [ + "toml_edit", +] + +[[package]] +name = "proc-macro2" +version = "1.0.107" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "985e7ec9bb745e6ce6535b544d84d6cd6f7ad8bd711c398938ae983b91a766d9" +dependencies = [ + "unicode-ident", +] + +[[package]] +name = "proptest" +version = "1.12.0" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "b8530004ccb15eae51c7e40009fbe317f341f804db54dc033eec1c50be28cfa0" +dependencies = [ + "bit-set", + "bit-vec", + "bitflags", + "chacha20", + "core_detect", + "num-traits", + "rand 0.10.3", + "rand_xorshift", + "regex-syntax", + "rusty-fork", + "tempfile", + "unarray", +] + +[[package]] +name = "psm" +version = "0.1.32" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "4dcd034599e63b970727f70d79e02d62390a4a84f7c6b827c27c46d5ac3fa622" +dependencies = [ + "ar_archive_writer", + "cc", +] + +[[package]] +name = "pulp" +version = "0.22.3" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "046aa45b989642ec2e4717c8e72d677b13edd831a4d3b6cf37d9a3e54912496a" +dependencies = [ + "bytemuck", + "cfg-if", + "libm", + "num-complex 0.4.6", + "paste", + "pulp-wasm-simd-flag", + "raw-cpuid", + "reborrow", + "version_check", +] + +[[package]] +name = "pulp-wasm-simd-flag" +version = "0.1.1" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "1d8f70e07b9c3962945a74e59ca1c511bba65b6419468acc217c457d93f3c740" + +[[package]] +name = "py_literal" +version = "0.4.0" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "102df7a3d46db9d3891f178dcc826dc270a6746277a9ae6436f8d29fd490a8e1" +dependencies = [ + "num-bigint", + "num-complex 0.4.6", + "num-traits", + "pest", + "pest_derive", +] + +[[package]] +name = "qd" +version = "0.8.0" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "15f1304a5aecdcfe9ee72fbba90aa37b3aa067a69d14cb7f3d9deada0be7c07c" +dependencies = [ + "bytemuck", + "libm", + "num-traits", + "pulp", +] + +[[package]] +name = "quick-error" +version = "1.2.3" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "a1d01941d82fa2ab50be1e79e6714289dd7cde78eba4c074bc5a4374f650dfe0" + +[[package]] +name = "quote" +version = "1.0.47" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "1fbf4db142a473a8d80c26bbf18454ed458bf8d26c8219c331daecfdbd079001" +dependencies = [ + "proc-macro2", +] + +[[package]] +name = "r-efi" +version = "5.3.0" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "69cdb34c158ceb288df11e18b4bd39de994f6657d83847bdffdbd7f346754b0f" + +[[package]] +name = "r-efi" +version = "6.0.0" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "f8dcc9c7d52a811697d2151c701e0d08956f92b0e24136cf4cf27b57a6a0d9bf" + +[[package]] +name = "rand" +version = "0.8.8" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "e058c7de0b26af77780c769414d6257830bb240f3c38477dbc2c16e5f54d6d4c" +dependencies = [ + "libc", + "rand_chacha 0.3.1", + "rand_core 0.6.4", +] + +[[package]] +name = "rand" +version = "0.9.5" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "b9ef1d0d795eb7d84685bca4f72f3649f064e6641543d3a8c415898726a57b41" +dependencies = [ + "rand_chacha 0.9.0", + "rand_core 0.9.5", +] + +[[package]] +name = "rand" +version = "0.10.3" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "65c9fb96cbc91e3478eaae79a69fcd3f1ae4ad052e471fe6732fff548984b4af" +dependencies = [ + "getrandom 0.4.3", + "rand_core 0.10.1", +] + +[[package]] +name = "rand_chacha" +version = "0.3.1" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "e6c10a63a0fa32252be49d21e7709d4d4baf8d231c2dbce1eaa8141b9b127d88" +dependencies = [ + "ppv-lite86", + "rand_core 0.6.4", +] + +[[package]] +name = "rand_chacha" +version = "0.9.0" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "d3022b5f1df60f26e1ffddd6c66e8aa15de382ae63b3a0c1bfc0e4d3e3f325cb" +dependencies = [ + "ppv-lite86", + "rand_core 0.9.5", +] + +[[package]] +name = "rand_core" +version = "0.6.4" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "ec0be4795e2f6a28069bec0b5ff3e2ac9bafc99e6a9a7dc3547996c5c816922c" +dependencies = [ + "getrandom 0.2.17", +] + +[[package]] +name = "rand_core" +version = "0.9.5" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "76afc826de14238e6e8c374ddcc1fa19e374fd8dd986b0d2af0d02377261d83c" +dependencies = [ + "getrandom 0.3.4", +] + +[[package]] +name = "rand_core" +version = "0.10.1" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "63b8176103e19a2643978565ca18b50549f6101881c443590420e4dc998a3c69" + +[[package]] +name = "rand_distr" +version = "0.5.1" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "6a8615d50dcf34fa31f7ab52692afec947c4dd0ab803cc87cb3b0b4570ff7463" +dependencies = [ + "num-traits", + "rand 0.9.5", +] + +[[package]] +name = "rand_xorshift" +version = "0.5.0" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "60aa6af80be32871323012e02e6e65f8a7cc7890931ae421d217ad8fe0df2ccf" +dependencies = [ + "rand_core 0.10.1", +] + +[[package]] +name = "raw-cpuid" +version = "11.6.0" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "498cd0dc59d73224351ee52a95fee0f1a617a2eae0e7d9d720cc622c73a54186" +dependencies = [ + "bitflags", +] + +[[package]] +name = "rawpointer" +version = "0.2.1" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "60a357793950651c4ed0f3f52338f53b2f809f32d83a07f72909fa13e4c6c1e3" + +[[package]] +name = "rayon" +version = "1.12.0" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "fb39b166781f92d482534ef4b4b1b2568f42613b53e5b6c160e24cfbfa30926d" +dependencies = [ + "either", + "rayon-core", +] + +[[package]] +name = "rayon-core" +version = "1.13.0" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "22e18b0f0062d30d4230b2e85ff77fdfe4326feb054b9783a3460d8435c8ab91" +dependencies = [ + "crossbeam-deque", + "crossbeam-utils", +] + +[[package]] +name = "reborrow" +version = "0.5.5" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "03251193000f4bd3b042892be858ee50e8b3719f2b08e5833ac4353724632430" + +[[package]] +name = "regex" +version = "1.13.1" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "f020237b6c8eed93db2e2cb53c00c60a8e1bc73da7d073199a1180401450218d" +dependencies = [ + "aho-corasick", + "memchr", + "regex-automata", + "regex-syntax", +] + +[[package]] +name = "regex-automata" +version = "0.4.18" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "ad8553b9b26413251cbf30e620595c7a41b3887f03da04579c0e6b0d6a06b4b2" +dependencies = [ + "aho-corasick", + "memchr", + "regex-syntax", +] + +[[package]] +name = "regex-syntax" +version = "0.8.11" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "d6f6ff9a378485b298a5286656da665ba74413d36db0979633275d2e708145d4" + +[[package]] +name = "rustix" +version = "1.1.6" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "e5e76742e5294153d4dde1207dbec5bdd81eef6fabdc0d2118babadabfd858aa" +dependencies = [ + "bitflags", + "errno", + "libc", + "linux-raw-sys", + "windows-sys 0.61.2", +] + +[[package]] +name = "rustversion" +version = "1.0.23" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "cf54715a573b99ac80df0bc206da022bcd442c974952c7b9720069370852e21f" + +[[package]] +name = "rusty-fork" +version = "0.3.1" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "cc6bf79ff24e648f6da1f8d1f011e9cac26491b619e6b9280f2b47f1774e6ee2" +dependencies = [ + "fnv", + "quick-error", + "tempfile", + "wait-timeout", +] + +[[package]] +name = "same-file" +version = "1.0.6" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "93fc1dc3aaa9bfed95e02e6eadabb4baf7e3078b0bd1b4d7b6b0b68378900502" +dependencies = [ + "winapi-util", +] + +[[package]] +name = "scoped-tls" +version = "1.0.1" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "e1cf6437eb19a8f4a6cc0f7dca544973b0b78843adbfeb3683d1a94a0024a294" + +[[package]] +name = "seq-macro" +version = "0.3.6" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "1bc711410fbe7399f390ca1c3b60ad0f53f80e95c5eb935e52268a0e2cd49acc" + +[[package]] +name = "serde" +version = "1.0.229" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "4148590afebada386688f18773da617792bf2ef03ffc1e4cbd2b1d45b023e0ba" +dependencies = [ + "serde_core", + "serde_derive", +] + +[[package]] +name = "serde_core" +version = "1.0.229" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "67dca2c9c51e58a4791a4b1ed58308b39c64224d349a935ab5039aa360942a48" +dependencies = [ + "serde_derive", +] + +[[package]] +name = "serde_derive" +version = "1.0.229" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "e7a5d71263a5a7d47b41f6b3f06ba276f10cc18b0931f1799f710578e2309348" +dependencies = [ + "proc-macro2", + "quote", + "syn 3.0.10", +] + +[[package]] +name = "serde_json" +version = "1.0.154" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "e7e9cc8b1b85264074fbcc02a88680c4096b1e47df8f739dceb03bf482f04bd6" +dependencies = [ + "itoa", + "memchr", + "serde", + "serde_core", + "zmij", +] + +[[package]] +name = "sharded-slab" +version = "0.1.7" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "f40ca3c46823713e0d4209592e8d6e826aa57e928f09752619fc696c499637f6" +dependencies = [ + "lazy_static", +] + +[[package]] +name = "shlex" +version = "2.0.1" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "f8fadd59c855ef2080decdef8ff161eb6661b86933c9d82e5ba29dc602a55aba" + +[[package]] +name = "simd-adler32" +version = "0.3.10" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "3a219298ac11a56ea9a6d2120044824d6f01aeb034955e7af7bc16858527deea" + +[[package]] +name = "slab" +version = "0.4.12" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "0c790de23124f9ab44544d7ac05d60440adc586479ce501c1d6d7da3cd8c9cf5" + +[[package]] +name = "smallvec" +version = "1.16.5" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "149309498a5f7334b12ddae0cad8aba81ce785fe91755068867e017cf98fee46" + +[[package]] +name = "spectral-init" +version = "0.1.0" +dependencies = [ + "approx 0.5.1", + "criterion", + "faer", + "humantime", + "libc", + "linfa-linalg", + "log", + "ndarray 0.16.1", + "ndarray 0.17.2", + "ndarray-npy", + "pico-args", + "proptest", + "rand 0.9.5", + "rand_distr", + "rayon", + "serde", + "serde_json", + "sprs", + "thiserror 2.0.21", +] + +[[package]] +name = "spindle" +version = "0.2.6" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "673aaca3d8aa5387a6eba861fbf984af5348d9df5d940c25c6366b19556fdf64" +dependencies = [ + "atomic-wait", + "crossbeam", + "equator 0.4.2", + "loom", + "rayon", +] + +[[package]] +name = "sprs" +version = "0.11.6" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "59468ff1d42d9e2439415c7dbb6d9d965253dac6986f29dbcda72c2e36e94fb7" +dependencies = [ + "alga", + "ndarray 0.17.2", + "num-complex 0.4.6", + "num-traits", + "num_cpus", + "rayon", + "smallvec", +] + +[[package]] +name = "stacker" +version = "0.1.25" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "707f49d46706bacf8a2b00d51dace3f9de527c13eec3778f570c411f89e69967" +dependencies = [ + "cc", + "cfg-if", + "libc", + "psm", + "windows-sys 0.61.2", +] + +[[package]] +name = "syn" +version = "1.0.109" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "72b64191b275b66ffe2469e8af2c1cfe3bafa67b529ead792a6d0160888b4237" +dependencies = [ + "proc-macro2", + "quote", + "unicode-ident", +] + +[[package]] +name = "syn" +version = "2.0.119" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "872831b642d1a07999a962a351ed35b955ea2cfc8f3862091e2a240a84f17297" +dependencies = [ + "proc-macro2", + "quote", + "unicode-ident", +] + +[[package]] +name = "syn" +version = "3.0.10" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "4ae9ccbea3a7b0b09443036490c8f34a8b1b760fd345e5c0dae0aac718faea79" +dependencies = [ + "proc-macro2", + "quote", + "unicode-ident", +] + +[[package]] +name = "sysctl" +version = "0.6.0" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "01198a2debb237c62b6826ec7081082d951f46dbb64b0e8c7649a452230d1dfc" +dependencies = [ + "bitflags", + "byteorder", + "enum-as-inner", + "libc", + "thiserror 1.0.69", + "walkdir", +] + +[[package]] +name = "tempfile" +version = "3.27.0" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "32497e9a4c7b38532efcdebeef879707aa9f794296a4f0244f6f69e9bc8574bd" +dependencies = [ + "fastrand", + "getrandom 0.4.3", + "once_cell", + "rustix", + "windows-sys 0.61.2", +] + +[[package]] +name = "thiserror" +version = "1.0.69" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "b6aaf5339b578ea85b50e080feb250a3e8ae8cfcdff9a461c9ec2904bc923f52" +dependencies = [ + "thiserror-impl 1.0.69", +] + +[[package]] +name = "thiserror" +version = "2.0.21" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "09e52cb86a36cede5cb101bf8908837b3e4c6e5e59fe7fd85c23fb56200d189e" +dependencies = [ + "thiserror-impl 2.0.21", +] + +[[package]] +name = "thiserror-impl" +version = "1.0.69" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "4fee6c4efc90059e10f81e6d42c60a18f76588c3d74cb83a0b242a2b6c7504c1" +dependencies = [ + "proc-macro2", + "quote", + "syn 2.0.119", +] + +[[package]] +name = "thiserror-impl" +version = "2.0.21" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "fe5197923287db20a58125f0bc85c062f7f2c892de97b18c356f9efb14b28524" +dependencies = [ + "proc-macro2", + "quote", + "syn 3.0.10", +] + +[[package]] +name = "thread_local" +version = "1.1.10" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "1ad99c4c6d32803332c548b1af0540b357b3f5fc0be8f6c6bfe8b2e6ae784070" +dependencies = [ + "cfg-if", +] + +[[package]] +name = "tinytemplate" +version = "1.2.1" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "be4d6b5f19ff7664e8c98d03e2139cb510db9b0a60b55f8e8709b689d939b6bc" +dependencies = [ + "serde", + "serde_json", +] + +[[package]] +name = "toml_datetime" +version = "1.1.3+spec-1.1.0" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "173f25c883cd2176a2d8212155638c0a60d484a9d84546d270866f40f56b6e49" +dependencies = [ + "serde_core", +] + +[[package]] +name = "toml_edit" +version = "0.25.19+spec-1.1.0" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "dd43688c4858d7264ae1cf9a9f874a67c3feb74a883b1cd7bebd6a4ea8307218" +dependencies = [ + "indexmap", + "toml_datetime", + "toml_parser", + "winnow", +] + +[[package]] +name = "toml_parser" +version = "1.1.5+spec-1.1.0" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "baa693a8032d7e1cada7d0041e96126df243179ff061456783ac7f12bda4744c" +dependencies = [ + "winnow", +] + +[[package]] +name = "tracing" +version = "0.1.44" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "63e71662fa4b2a2c3a26f570f037eb95bb1f85397f3cd8076caed2f026a6d100" +dependencies = [ + "pin-project-lite", + "tracing-core", +] + +[[package]] +name = "tracing-core" +version = "0.1.36" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "db97caf9d906fbde555dd62fa95ddba9eecfd14cb388e4f491a66d74cd5fb79a" +dependencies = [ + "once_cell", + "valuable", +] + +[[package]] +name = "tracing-log" +version = "0.2.0" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "ee855f1f400bd0e5c02d150ae5de3840039a3f54b025156404e34c23c03f47c3" +dependencies = [ + "log", + "once_cell", + "tracing-core", +] + +[[package]] +name = "tracing-subscriber" +version = "0.3.23" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "cb7f578e5945fb242538965c2d0b04418d38ec25c79d160cd279bf0731c8d319" +dependencies = [ + "matchers", + "nu-ansi-term", + "once_cell", + "regex-automata", + "sharded-slab", + "smallvec", + "thread_local", + "tracing", + "tracing-core", + "tracing-log", +] + +[[package]] +name = "ucd-trie" +version = "0.1.7" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "2896d95c02a80c6d6a5d6e953d479f5ddf2dfdb6a244441010e373ac0fb88971" + +[[package]] +name = "unarray" +version = "0.1.4" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "eaea85b334db583fe3274d12b4cd1880032beab409c0d774be044d4480ab9a94" + +[[package]] +name = "unicode-ident" +version = "1.0.27" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "a2c754d6c33795a1c324727428e5a7dedb5b06195f9890bdbcba760d3e246563" + +[[package]] +name = "valuable" +version = "0.1.1" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "ba73ea9cf16a25df0c8caa16c51acb937d5712a8429db78a3ee29d5dcacd3a65" + +[[package]] +name = "version_check" +version = "0.9.5" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "0b928f33d975fc6ad9f86c8f283853ad26bdd5b10b7f1542aa2fa15e2289105a" + +[[package]] +name = "wait-timeout" +version = "0.2.1" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "09ac3b126d3914f9849036f826e054cbabdc8519970b8998ddaf3b5bd3c65f11" +dependencies = [ + "libc", +] + +[[package]] +name = "walkdir" +version = "2.5.0" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "29790946404f91d9c5d06f9874efddea1dc06c5efe94541a7d6863108e3a5e4b" +dependencies = [ + "same-file", + "winapi-util", +] + +[[package]] +name = "wasi" +version = "0.11.1+wasi-snapshot-preview1" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "ccf3ec651a847eb01de73ccad15eb7d99f80485de043efb2f370cd654f4ea44b" + +[[package]] +name = "wasip2" +version = "1.0.4+wasi-0.2.12" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "b67efb37e106e55ce722a510d6b5f9c17f083e5fc79afc2badeb12cc313d9487" +dependencies = [ + "wit-bindgen", +] + +[[package]] +name = "wasm-bindgen" +version = "0.2.130" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "a0181c14ddd6c7b8b0b0132a5f1ea2f32be0d893cd3ea97b6e3b28886b8a3d1c" +dependencies = [ + "cfg-if", + "rustversion", + "wasm-bindgen-macro", + "wasm-bindgen-shared", +] + +[[package]] +name = "wasm-bindgen-macro" +version = "0.2.130" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "6e931a02a39abdbf66966fc35902b5ed58344750a70885bed4ebb3d8eaf28ed9" +dependencies = [ + "quote", + "wasm-bindgen-macro-support", +] + +[[package]] +name = "wasm-bindgen-macro-support" +version = "0.2.130" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "2ca4b54280e455bd831e33a6b8e734baf432fe63fbc35c42ac14ce67a043a53a" +dependencies = [ + "bumpalo", + "proc-macro2", + "quote", + "syn 3.0.10", + "wasm-bindgen-shared", +] + +[[package]] +name = "wasm-bindgen-shared" +version = "0.2.130" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "3b1f9c3798725016c6ee5f2f57869ec0831e8bbc0ab0310a86e787e97f41389e" +dependencies = [ + "unicode-ident", +] + +[[package]] +name = "web-sys" +version = "0.3.107" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "d7d179596ff5ec0f6de4db64d54011bde6289cc49603d3a6e4ce3f329207ab88" +dependencies = [ + "js-sys", + "wasm-bindgen", +] + +[[package]] +name = "winapi-util" +version = "0.1.11" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "c2a7b1c03c876122aa43f3020e6c3c3ee5c05081c9a00739faf7503aeba10d22" +dependencies = [ + "windows-sys 0.61.2", +] + +[[package]] +name = "windows-link" +version = "0.2.1" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "f0805222e57f7521d6a62e36fa9163bc891acd422f971defe97d64e70d0a4fe5" + +[[package]] +name = "windows-result" +version = "0.4.1" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "7781fa89eaf60850ac3d2da7af8e5242a5ea78d1a11c49bf2910bb5a73853eb5" +dependencies = [ + "windows-link", +] + +[[package]] +name = "windows-sys" +version = "0.42.0" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "5a3e1820f08b8513f676f7ab6c1f99ff312fb97b553d30ff4dd86f9f15728aa7" +dependencies = [ + "windows_aarch64_gnullvm", + "windows_aarch64_msvc", + "windows_i686_gnu", + "windows_i686_msvc", + "windows_x86_64_gnu", + "windows_x86_64_gnullvm", + "windows_x86_64_msvc", +] + +[[package]] +name = "windows-sys" +version = "0.61.2" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "ae137229bcbd6cdf0f7b80a31df61766145077ddf49416a728b02cb3921ff3fc" +dependencies = [ + "windows-link", +] + +[[package]] +name = "windows_aarch64_gnullvm" +version = "0.42.2" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "597a5118570b68bc08d8d59125332c54f1ba9d9adeedeef5b99b02ba2b0698f8" + +[[package]] +name = "windows_aarch64_msvc" +version = "0.42.2" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "e08e8864a60f06ef0d0ff4ba04124db8b0fb3be5776a5cd47641e942e58c4d43" + +[[package]] +name = "windows_i686_gnu" +version = "0.42.2" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "c61d927d8da41da96a81f029489353e68739737d3beca43145c8afec9a31a84f" + +[[package]] +name = "windows_i686_msvc" +version = "0.42.2" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "44d840b6ec649f480a41c8d80f9c65108b92d89345dd94027bfe06ac444d1060" + +[[package]] +name = "windows_x86_64_gnu" +version = "0.42.2" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "8de912b8b8feb55c064867cf047dda097f92d51efad5b491dfb98f6bbb70cb36" + +[[package]] +name = "windows_x86_64_gnullvm" +version = "0.42.2" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "26d41b46a36d453748aedef1486d5c7a85db22e56aff34643984ea85514e94a3" + +[[package]] +name = "windows_x86_64_msvc" +version = "0.42.2" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "9aec5da331524158c6d1a4ac0ab1541149c0b9505fde06423b02f5ef0106b9f0" + +[[package]] +name = "winnow" +version = "1.0.5" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "8c3b93199df0ab874cdf0c6a94f0a0dc3423fe41f1cafb62b8bd7b1deb277aef" +dependencies = [ + "memchr", +] + +[[package]] +name = "wit-bindgen" +version = "0.57.1" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "1ebf944e87a7c253233ad6766e082e3cd714b5d03812acc24c318f549614536e" + +[[package]] +name = "zerocopy" +version = "0.8.63" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "e5fe1f8f1b06191a00962174c61aa5005e0bb391a6d80d07e24d115c01a92ed8" +dependencies = [ + "zerocopy-derive", +] + +[[package]] +name = "zerocopy-derive" +version = "0.8.63" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "863ad3ac83293fb4d740aedbfdc9240dd8d1a50c1099acd76ce80ce7c7230c7f" +dependencies = [ + "proc-macro2", + "quote", + "syn 2.0.119", +] + +[[package]] +name = "zip" +version = "6.0.0" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "eb2a05c7c36fde6c09b08576c9f7fb4cda705990f73b58fe011abf7dfb24168b" +dependencies = [ + "arbitrary", + "crc32fast", + "flate2", + "indexmap", + "memchr", + "zopfli", +] + +[[package]] +name = "zlib-rs" +version = "0.6.8" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "b268e58e7c693d7c271f93ffc4ba3b380412554231c85bf61ca7af91042a4112" + +[[package]] +name = "zmij" +version = "1.0.23" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "29666d0abbfad1e3dc4dcf6144730dd3a3ab225bbbdac83319345b1b44ccfc1b" + +[[package]] +name = "zopfli" +version = "0.8.4" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "aaf7fc5d30c28483d93805c4a5e12b05bbb52407fa67c5f8bd552374cd01fb11" +dependencies = [ + "bumpalo", + "crc32fast", + "log", + "simd-adler32", +] diff --git a/Cargo.toml b/Cargo.toml index 13b2a89..713095d 100644 --- a/Cargo.toml +++ b/Cargo.toml @@ -6,13 +6,12 @@ description = "Spectral initialization for UMAP embeddings" license = "MIT" repository = "https://github.com/TalonT-Org/spectral-init" readme = "README.md" -documentation = "https://docs.rs/spectral-init" -rust-version = "1.85" -keywords = ["umap", "dimensionality-reduction", "spectral", "eigenvectors", "embeddings"] +rust-version = "1.88" +keywords = ["umap", "spectral", "laplacian", "eigenvectors", "embedding"] categories = ["science", "mathematics", "algorithms"] +include = ["/src/**", "/examples/**", "/docs/katex-header.html", "/README.md", "/LICENSE"] [package.metadata.docs.rs] -all-features = true rustdoc-args = ["--html-in-header", "docs/katex-header.html"] [features] @@ -169,6 +168,15 @@ name = "test_simd_lobpcg_parity" path = "tests/integration/test_simd_lobpcg_parity.rs" required-features = ["testing"] +[[test]] +name = "test_scaling_fixtures" +path = "tests/integration/test_scaling_fixtures.rs" +required-features = ["testing"] + +[[test]] +name = "test_operator_fixtures" +path = "tests/integration/test_operator_fixtures.rs" + [[bin]] name = "trustworthiness" path = "src/bin/trustworthiness.rs" diff --git a/README.md b/README.md index 8ab7f2e..23e0514 100644 --- a/README.md +++ b/README.md @@ -6,7 +6,7 @@ [![docs.rs](https://img.shields.io/docsrs/spectral-init)](https://docs.rs/spectral-init) [![CI](https://github.com/TalonT-Org/spectral-init/actions/workflows/test.yml/badge.svg)](https://github.com/TalonT-Org/spectral-init/actions/workflows/test.yml) [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE) -[![MSRV: 1.85](https://img.shields.io/badge/MSRV-1.85-blue)](https://blog.rust-lang.org/2025/02/20/Rust-1.85.0.html) +[![MSRV: 1.88](https://img.shields.io/badge/MSRV-1.88-blue)](https://blog.rust-lang.org/2025/06/26/Rust-1.88.0/) [Docs](https://docs.rs/spectral-init) · [Crate](https://crates.io/crates/spectral-init) · [User Guide](docs/user-guide.md) @@ -137,7 +137,7 @@ for the full algorithmic design. ## Requirements -- **MSRV:** Rust 1.85 +- **MSRV:** Rust 1.88 - **No LAPACK/BLAS dependency** — pure Rust via `linfa-linalg` (LOBPCG) and `faer` (dense EVD) - **AVX2+FMA** is optional and only used when `ComputeMode::RustNative` is selected on x86\_64 - Tested on Linux x86\_64; should work on any platform supported by the above crates diff --git a/benches/dist_sq_bench.rs b/benches/dist_sq_bench.rs index 06243f0..44e6b46 100644 --- a/benches/dist_sq_bench.rs +++ b/benches/dist_sq_bench.rs @@ -5,15 +5,11 @@ use criterion::{BenchmarkId, Criterion, criterion_group, criterion_main}; use std::hint::black_box; -#[cfg(all( - target_arch = "x86_64", - target_feature = "avx2", - target_feature = "fma" -))] +#[cfg(target_arch = "x86_64")] use spectral_init::metrics::dist_sq_avx2_looped; -// Note: on non-AVX2 hosts the avx2_looped benchmark arm is omitted by cfg; only the scalar -// variant runs. CI should build with RUSTFLAGS="-C target-cpu=native" to include AVX2 coverage. +// Note: the avx2_looped benchmark arm runs only when AVX2 and FMA are detected at runtime; +// on other hosts only the scalar variant runs. fn make_vectors(d: usize, seed: u64) -> (Vec, Vec) { use std::collections::hash_map::DefaultHasher; @@ -39,14 +35,13 @@ fn bench_dist_sq_kernels(c: &mut Criterion) { for &d in &[10_usize, 50] { let (xi, xj) = make_vectors(d, 42); - #[cfg(all( - target_arch = "x86_64", - target_feature = "avx2", - target_feature = "fma" - ))] - group.bench_with_input(BenchmarkId::new("avx2_looped", d), &d, |b, _| { - b.iter(|| unsafe { dist_sq_avx2_looped(black_box(&xi), black_box(&xj)) }) - }); + #[cfg(target_arch = "x86_64")] + if is_x86_feature_detected!("avx2") && is_x86_feature_detected!("fma") { + group.bench_with_input(BenchmarkId::new("avx2_looped", d), &d, |b, _| { + // SAFETY: AVX2 and FMA were detected above; both slices have `d` elements. + b.iter(|| unsafe { dist_sq_avx2_looped(black_box(&xi), black_box(&xj)) }) + }); + } group.bench_with_input(BenchmarkId::new("scalar", d), &d, |b, _| { b.iter(|| { diff --git a/benches/lobpcg_bench.rs b/benches/lobpcg_bench.rs index 102f8b7..4462b8c 100644 --- a/benches/lobpcg_bench.rs +++ b/benches/lobpcg_bench.rs @@ -27,7 +27,7 @@ use criterion::{Criterion, criterion_group, criterion_main}; use ndarray_npy::{NpzReader, ReadNpyError, ReadNpzError}; -use spectral_init::solve_eigenproblem_pub; +use spectral_init::{ComputeMode, solve_eigenproblem_pub}; use std::hint::black_box; use std::path::Path; use std::time::Duration; @@ -118,7 +118,12 @@ fn bench_lobpcg_blobs5000(c: &mut Criterion) { // One call outside the timed loop: primes instruction caches and surfaces // the solver level via the --features testing timing lines on stderr. - let _ = solve_eigenproblem_pub(black_box(&laplacian), black_box(2), black_box(seed)); + let _ = solve_eigenproblem_pub( + black_box(&laplacian), + black_box(2), + black_box(seed), + ComputeMode::RustNative, + ); eprintln!("[lobpcg_bench] blobs_5000 ready: n={n}"); let mut group = c.benchmark_group("lobpcg_blobs5000"); @@ -132,6 +137,7 @@ fn bench_lobpcg_blobs5000(c: &mut Criterion) { black_box(&laplacian), black_box(2), black_box(seed), + ComputeMode::RustNative, )) }); }); @@ -157,7 +163,12 @@ fn bench_lobpcg_merfish_10k(c: &mut Criterion) { // One call outside the timed loop: primes instruction caches and surfaces // the solver level via the --features testing timing lines on stderr. - let _ = solve_eigenproblem_pub(black_box(&laplacian), black_box(2), black_box(seed)); + let _ = solve_eigenproblem_pub( + black_box(&laplacian), + black_box(2), + black_box(seed), + ComputeMode::RustNative, + ); eprintln!("[lobpcg_bench] merfish_10k ready: n={n}"); let mut group = c.benchmark_group("lobpcg_merfish_10k"); @@ -171,6 +182,7 @@ fn bench_lobpcg_merfish_10k(c: &mut Criterion) { black_box(&laplacian), black_box(2), black_box(seed), + ComputeMode::RustNative, )) }); }); @@ -196,7 +208,12 @@ fn bench_lobpcg_merfish_100k(c: &mut Criterion) { // One call outside the timed loop: primes instruction caches and surfaces // the solver level via the --features testing timing lines on stderr. - let _ = solve_eigenproblem_pub(black_box(&laplacian), black_box(2), black_box(seed)); + let _ = solve_eigenproblem_pub( + black_box(&laplacian), + black_box(2), + black_box(seed), + ComputeMode::RustNative, + ); eprintln!("[lobpcg_bench] merfish_100k ready: n={n}"); let mut group = c.benchmark_group("lobpcg_merfish_100k"); @@ -211,6 +228,7 @@ fn bench_lobpcg_merfish_100k(c: &mut Criterion) { black_box(&laplacian), black_box(2), black_box(seed), + ComputeMode::RustNative, )) }); }); diff --git a/benches/simd_spmv_exp.rs b/benches/simd_spmv_exp.rs index 9aed34e..9a89b6f 100644 --- a/benches/simd_spmv_exp.rs +++ b/benches/simd_spmv_exp.rs @@ -5,7 +5,7 @@ use criterion::{BenchmarkId, Criterion, criterion_group, criterion_main}; use ndarray_npy::NpzReader; use spectral_init::operator::spmv_csr; -use spectral_init::solve_eigenproblem_pub; +use spectral_init::{ComputeMode, solve_eigenproblem_pub}; use std::hint::black_box; // ─── Ring Laplacian builder ─────────────────────────────────────────────────── @@ -55,8 +55,7 @@ struct SellCsigma { chunk_len: Vec, // max NNZ per chunk col_idx: Vec, // padded column indices, interleaved row-major within chunk values: Vec, // padded values, same layout as col_idx - perm: Vec, // perm[orig_row] = sorted_pos (σ-sort permutation) - inv_perm: Vec, // inv_perm[sorted_pos] = orig_row (inverse) + inv_perm: Vec, // inv_perm[sorted_pos] = orig_row (σ-sort permutation) } impl SellCsigma { @@ -75,14 +74,8 @@ impl SellCsigma { let mut inv_perm: Vec = (0..n).collect(); inv_perm.sort_unstable_by(|&a, &b| nnz[b].cmp(&nnz[a])); - // 3. Compute forward permutation: perm[orig_row] = sorted_pos - let mut perm = vec![0usize; n]; - for (sorted_pos, &orig_row) in inv_perm.iter().enumerate() { - perm[orig_row] = sorted_pos; - } - - // 4. Partition into chunks of size c. - let n_chunks = (n + c - 1) / c; + // 3. Partition into chunks of size c. + let n_chunks = n.div_ceil(c); let mut chunk_len = Vec::with_capacity(n_chunks); let mut col_idx_buf = Vec::new(); let mut values_buf = Vec::new(); @@ -91,14 +84,14 @@ impl SellCsigma { let chunk_start = c_idx * c; let chunk_end = (chunk_start + c).min(n); - // 5. Find chunk_max_nnz over actual rows in this chunk. + // 4. Find chunk_max_nnz over actual rows in this chunk. let chunk_max = (chunk_start..chunk_end) .map(|sorted_pos| nnz[inv_perm[sorted_pos]]) .max() .unwrap_or(0); chunk_len.push(chunk_max); - // 6. Pad all c rows to chunk_max, interleaved row-major within chunk. + // 5. Pad all c rows to chunk_max, interleaved row-major within chunk. // offset = c_idx * c * chunk_max + r * chunk_max + k for r in 0..c { let sorted_pos = chunk_start + r; @@ -126,13 +119,12 @@ impl SellCsigma { chunk_len, col_idx: col_idx_buf, values: values_buf, - perm, inv_perm, } } fn spmv_scalar(&self, x: &[f64], y: &mut [f64]) { - let n_chunks = (self.num_rows + self.c - 1) / self.c; + let n_chunks = self.num_rows.div_ceil(self.c); let mut y_perm = vec![0.0_f64; self.num_rows]; for c_idx in 0..n_chunks { @@ -230,6 +222,9 @@ fn spmv_avx2_dispatch(indptr: &[usize], indices: &[usize], data: &[f64], x: &[f6 // ─── AVX-512 gather kernel ─────────────────────────────────────────────────── +// The AVX-512 intrinsics are stable from Rust 1.89, one release above the package MSRV; +// this experimental kernel exists only in this benchmark. +#[allow(clippy::incompatible_msrv)] #[cfg(any(target_arch = "x86", target_arch = "x86_64"))] #[target_feature(enable = "avx512f")] unsafe fn spmv_avx512_gather( @@ -313,7 +308,6 @@ fn spmv_avx512_dispatch( // ─── Correctness verification ───────────────────────────────────────────────── -#[cfg(test)] fn verify_sell_c(n: usize, c: usize) { let (indptr, indices, data) = make_ring_lap(n, 7); // Non-uniform x to catch permutation bugs @@ -359,7 +353,6 @@ fn verify_avx512(n: usize) { } } -#[cfg(test)] fn verify_avx2(n: usize) { let (indptr, indices, data) = make_ring_lap(n, 7); let x: Vec = (0..n).map(|i| i as f64 * 0.001).collect(); @@ -383,27 +376,6 @@ fn verify_avx2(n: usize) { } } -#[cfg(test)] -mod tests { - #[test] - fn verify_sell_c_correctness() { - verify_sell_c(200, 4); - verify_sell_c(2000, 8); - } - - #[test] - fn verify_avx2_correctness() { - verify_avx2(200); - verify_avx2(2000); - } - - #[test] - fn verify_avx512_correctness() { - verify_avx512(200); - verify_avx512(2000); - } -} - // ─── Benchmark groups ────────────────────────────────────────────────────────── fn bench_spmv_csr_scaling(c: &mut Criterion) { @@ -428,6 +400,8 @@ fn bench_spmv_csr_scaling(c: &mut Criterion) { } fn bench_spmv_sell_c(c: &mut Criterion) { + verify_sell_c(200, 4); + verify_sell_c(2000, 8); let mut group = c.benchmark_group("spmv_sell_c"); for &n in &[200_usize, 2000, 5000, 10000, 50000] { let (indptr, indices, data) = make_ring_lap(n, 7); @@ -466,6 +440,7 @@ fn bench_spmv_avx2(c: &mut Criterion) { // ISA detection: emits "[isa] avx512f=true/false" so results files can confirm // the hardware context that produced the benchmark data. eprintln!("[isa] avx512f={}", is_x86_feature_detected!("avx512f")); + verify_avx2(200); verify_avx512(200); let mut group = c.benchmark_group("spmv_avx2"); for &n in &[200_usize, 2000, 5000, 10000, 50000] { @@ -561,12 +536,24 @@ fn bench_pipeline_blobs5000(c: &mut Criterion) { let seed = 42_u64; // Warm-up: one call outside iter to prime instruction caches and BLAS state. - let _ = solve_eigenproblem_pub(black_box(&laplacian), black_box(2), black_box(seed)); + let _ = solve_eigenproblem_pub( + black_box(&laplacian), + black_box(2), + black_box(seed), + ComputeMode::RustNative, + ); let mut group = c.benchmark_group("pipeline_blobs5000"); group.sample_size(10); // Criterion minimum; eigenproblem is slow so we keep it at the floor group.bench_function("blobs5000_solver", |b| { - b.iter(|| solve_eigenproblem_pub(black_box(&laplacian), black_box(2), black_box(seed))); + b.iter(|| { + solve_eigenproblem_pub( + black_box(&laplacian), + black_box(2), + black_box(seed), + ComputeMode::RustNative, + ) + }); }); group.finish(); } diff --git a/benches/spectral_bench.rs b/benches/spectral_bench.rs index c18f468..5c6fab8 100644 --- a/benches/spectral_bench.rs +++ b/benches/spectral_bench.rs @@ -39,7 +39,7 @@ fn make_ring_graph(n: usize, half: usize) -> sprs::CsMatI { row_cols.dedup(); let nnz = row_cols.len(); indices.extend_from_slice(&row_cols); - data.extend(std::iter::repeat(1.0_f32).take(nnz)); + data.extend(std::iter::repeat_n(1.0_f32, nnz)); indptr[i + 1] = indptr[i] + nnz; } diff --git a/docs/user-guide.md b/docs/user-guide.md index afd395d..d9e1b50 100644 --- a/docs/user-guide.md +++ b/docs/user-guide.md @@ -17,7 +17,7 @@ ## Prerequisites -**Rust 1.85 or later (MSRV).** Install Rust via [rustup](https://www.rust-lang.org/tools/install). +**Rust 1.88 or later (MSRV).** Install Rust via [rustup](https://www.rust-lang.org/tools/install). **No LAPACK/BLAS required** — this crate is pure Rust. All linear algebra is handled by `linfa-linalg` (LOBPCG) and `faer` (dense EVD). diff --git a/research/2026-04-03-merfish-param-sweep-robustness/data/DATA.md b/research/2026-04-03-merfish-param-sweep-robustness/data/DATA.md new file mode 100644 index 0000000..afebda7 --- /dev/null +++ b/research/2026-04-03-merfish-param-sweep-robustness/data/DATA.md @@ -0,0 +1,23 @@ +# Data for the MERFISH parameter-sweep experiment + +The scripts in `../scripts/` (`run_param_sweep.py`, `run_tsne_sweep.py`) read +three files from this directory. They are not stored here; copy or link them +from the locations below before running the scripts. + +| File expected here | Source | Regenerate with | +|---|---|---| +| `merfish_10k_labels.npz` | `tests/visual_eval/merfish_data/merfish_10k_labels.npz` (tracked) | `python tests/visual_eval/generate_merfish_subset.py` | +| `merfish_10k_spatial.npz` | `tests/visual_eval/merfish_data/merfish_10k_spatial.npz` (tracked) | `python tests/visual_eval/generate_merfish_subset.py` | +| `merfish_10k_pca.npy` | `tests/visual_eval/output/merfish_10k_pca.npy` (untracked, generated) | `python tests/visual_eval/generate_merfish_comparisons.py` | + +From the repository root: + +```sh +cp tests/visual_eval/merfish_data/merfish_10k_labels.npz \ + tests/visual_eval/merfish_data/merfish_10k_spatial.npz \ + tests/visual_eval/output/merfish_10k_pca.npy \ + research/2026-04-03-merfish-param-sweep-robustness/data/ +``` + +The experiment scripts reproduce at the `research-baseline-pre-0.1` tag; see +`research/README.md`. diff --git a/research/2026-04-03-merfish-param-sweep-robustness/data/merfish_10k_labels.npz b/research/2026-04-03-merfish-param-sweep-robustness/data/merfish_10k_labels.npz deleted file mode 120000 index 96b3ef5..0000000 --- a/research/2026-04-03-merfish-param-sweep-robustness/data/merfish_10k_labels.npz +++ /dev/null @@ -1 +0,0 @@ -/home/talon/projects/worktrees/research-20260403-075243/tests/visual_eval/merfish_data/merfish_10k_labels.npz \ No newline at end of file diff --git a/research/2026-04-03-merfish-param-sweep-robustness/data/merfish_10k_pca.npy b/research/2026-04-03-merfish-param-sweep-robustness/data/merfish_10k_pca.npy deleted file mode 120000 index 3eabb2e..0000000 --- a/research/2026-04-03-merfish-param-sweep-robustness/data/merfish_10k_pca.npy +++ /dev/null @@ -1 +0,0 @@ -/home/talon/projects/spectral-init/tests/visual_eval/output/merfish_10k_pca.npy \ No newline at end of file diff --git a/research/2026-04-03-merfish-param-sweep-robustness/data/merfish_10k_spatial.npz b/research/2026-04-03-merfish-param-sweep-robustness/data/merfish_10k_spatial.npz deleted file mode 120000 index 12ce34b..0000000 --- a/research/2026-04-03-merfish-param-sweep-robustness/data/merfish_10k_spatial.npz +++ /dev/null @@ -1 +0,0 @@ -/home/talon/projects/worktrees/research-20260403-075243/tests/visual_eval/merfish_data/merfish_10k_spatial.npz \ No newline at end of file diff --git a/research/2026-04-09-subsampled-tw-tradeoff/data/merfish/DATA.md b/research/2026-04-09-subsampled-tw-tradeoff/data/merfish/DATA.md new file mode 100644 index 0000000..04a0d87 --- /dev/null +++ b/research/2026-04-09-subsampled-tw-tradeoff/data/merfish/DATA.md @@ -0,0 +1,30 @@ +# MERFISH data for the subsampled-trustworthiness experiment + +The scripts in `../../scripts/` (`compute_exact.py`, `run_subsampling.py`, +`verify_normalization.py`, through `utils.load_npy_pair`) load +`merfish_n{N}_x.npy` and `merfish_n{N}_y.npy` from this directory. + +`merfish_n20000_{x,y}.npy` are stored here. The 10 000- and 50 000-cell pairs +are not: they are the arrays of an earlier experiment and have to be copied or +linked from it before the scripts are run. + +| File expected here | Source (tracked) | Regenerate with | +|---|---|---| +| `merfish_n10000_x.npy` | `research/2026-04-05-tw-perf-rerun-clean/data/merfish/merfish_n10k_x.npy` | `research/2026-04-05-tw-perf-rerun-clean/scripts/prepare_merfish.py` | +| `merfish_n10000_y.npy` | `research/2026-04-05-tw-perf-rerun-clean/data/merfish/merfish_n10k_y.npy` | `research/2026-04-05-tw-perf-rerun-clean/scripts/prepare_merfish.py` | +| `merfish_n50000_x.npy` | `research/2026-04-05-tw-perf-rerun-clean/data/merfish/merfish_n50k_x.npy` | `research/2026-04-05-tw-perf-rerun-clean/scripts/prepare_merfish_50k.py` | +| `merfish_n50000_y.npy` | `research/2026-04-05-tw-perf-rerun-clean/data/merfish/merfish_n50k_y.npy` | `research/2026-04-05-tw-perf-rerun-clean/scripts/prepare_merfish_50k.py` | + +From the repository root: + +```sh +src=research/2026-04-05-tw-perf-rerun-clean/data/merfish +dst=research/2026-04-09-subsampled-tw-tradeoff/data/merfish +cp "$src/merfish_n10k_x.npy" "$dst/merfish_n10000_x.npy" +cp "$src/merfish_n10k_y.npy" "$dst/merfish_n10000_y.npy" +cp "$src/merfish_n50k_x.npy" "$dst/merfish_n50000_x.npy" +cp "$src/merfish_n50k_y.npy" "$dst/merfish_n50000_y.npy" +``` + +The experiment scripts reproduce at the `research-baseline-pre-0.1` tag; see +`research/README.md`. diff --git a/research/2026-04-09-subsampled-tw-tradeoff/data/merfish/merfish_n10000_x.npy b/research/2026-04-09-subsampled-tw-tradeoff/data/merfish/merfish_n10000_x.npy deleted file mode 120000 index 86f2eb9..0000000 --- a/research/2026-04-09-subsampled-tw-tradeoff/data/merfish/merfish_n10000_x.npy +++ /dev/null @@ -1 +0,0 @@ -/home/talon/projects/spectral-init/research/2026-04-05-tw-perf-rerun-clean/data/merfish/merfish_n10k_x.npy \ No newline at end of file diff --git a/research/2026-04-09-subsampled-tw-tradeoff/data/merfish/merfish_n10000_y.npy b/research/2026-04-09-subsampled-tw-tradeoff/data/merfish/merfish_n10000_y.npy deleted file mode 120000 index 5724caf..0000000 --- a/research/2026-04-09-subsampled-tw-tradeoff/data/merfish/merfish_n10000_y.npy +++ /dev/null @@ -1 +0,0 @@ -/home/talon/projects/spectral-init/research/2026-04-05-tw-perf-rerun-clean/data/merfish/merfish_n10k_y.npy \ No newline at end of file diff --git a/research/2026-04-09-subsampled-tw-tradeoff/data/merfish/merfish_n10k_x.npy b/research/2026-04-09-subsampled-tw-tradeoff/data/merfish/merfish_n10k_x.npy deleted file mode 120000 index 86f2eb9..0000000 --- a/research/2026-04-09-subsampled-tw-tradeoff/data/merfish/merfish_n10k_x.npy +++ /dev/null @@ -1 +0,0 @@ -/home/talon/projects/spectral-init/research/2026-04-05-tw-perf-rerun-clean/data/merfish/merfish_n10k_x.npy \ No newline at end of file diff --git a/research/2026-04-09-subsampled-tw-tradeoff/data/merfish/merfish_n10k_y.npy b/research/2026-04-09-subsampled-tw-tradeoff/data/merfish/merfish_n10k_y.npy deleted file mode 120000 index 5724caf..0000000 --- a/research/2026-04-09-subsampled-tw-tradeoff/data/merfish/merfish_n10k_y.npy +++ /dev/null @@ -1 +0,0 @@ -/home/talon/projects/spectral-init/research/2026-04-05-tw-perf-rerun-clean/data/merfish/merfish_n10k_y.npy \ No newline at end of file diff --git a/research/2026-04-09-subsampled-tw-tradeoff/data/merfish/merfish_n50000_x.npy b/research/2026-04-09-subsampled-tw-tradeoff/data/merfish/merfish_n50000_x.npy deleted file mode 120000 index 2f27404..0000000 --- a/research/2026-04-09-subsampled-tw-tradeoff/data/merfish/merfish_n50000_x.npy +++ /dev/null @@ -1 +0,0 @@ -/home/talon/projects/spectral-init/research/2026-04-05-tw-perf-rerun-clean/data/merfish/merfish_n50k_x.npy \ No newline at end of file diff --git a/research/2026-04-09-subsampled-tw-tradeoff/data/merfish/merfish_n50000_y.npy b/research/2026-04-09-subsampled-tw-tradeoff/data/merfish/merfish_n50000_y.npy deleted file mode 120000 index 0cb9a9c..0000000 --- a/research/2026-04-09-subsampled-tw-tradeoff/data/merfish/merfish_n50000_y.npy +++ /dev/null @@ -1 +0,0 @@ -/home/talon/projects/spectral-init/research/2026-04-05-tw-perf-rerun-clean/data/merfish/merfish_n50k_y.npy \ No newline at end of file diff --git a/research/2026-04-09-subsampled-tw-tradeoff/data/merfish/merfish_n50k_x.npy b/research/2026-04-09-subsampled-tw-tradeoff/data/merfish/merfish_n50k_x.npy deleted file mode 120000 index 2f27404..0000000 --- a/research/2026-04-09-subsampled-tw-tradeoff/data/merfish/merfish_n50k_x.npy +++ /dev/null @@ -1 +0,0 @@ -/home/talon/projects/spectral-init/research/2026-04-05-tw-perf-rerun-clean/data/merfish/merfish_n50k_x.npy \ No newline at end of file diff --git a/research/2026-04-09-subsampled-tw-tradeoff/data/merfish/merfish_n50k_y.npy b/research/2026-04-09-subsampled-tw-tradeoff/data/merfish/merfish_n50k_y.npy deleted file mode 120000 index 0cb9a9c..0000000 --- a/research/2026-04-09-subsampled-tw-tradeoff/data/merfish/merfish_n50k_y.npy +++ /dev/null @@ -1 +0,0 @@ -/home/talon/projects/spectral-init/research/2026-04-05-tw-perf-rerun-clean/data/merfish/merfish_n50k_y.npy \ No newline at end of file diff --git a/research/README.md b/research/README.md new file mode 100644 index 0000000..5bffcbb --- /dev/null +++ b/research/README.md @@ -0,0 +1,22 @@ +# Research artifacts + +Each dated directory holds one experiment: its plan, scripts, data and report. + +## Reproducing an experiment + +The scripts under `research/**/scripts` hard-code the Cargo features, binary +names and test names the repository had before the 0.1 release work. They +reproduce at the git tag `research-baseline-pre-0.1`: + +```sh +git checkout research-baseline-pre-0.1 +``` + +Run them from that checkout, not from `main`. + +## Data files + +Some experiments read arrays produced by another experiment or by the +visual-evaluation tooling in `tests/visual_eval/`. Where that is the case, the +experiment's data directory has a `DATA.md` naming each source file and the +script that regenerates it. diff --git a/src/components.rs b/src/components.rs index 9c2519e..82911d0 100644 --- a/src/components.rs +++ b/src/components.rs @@ -46,95 +46,6 @@ pub(crate) fn find_components(graph: &CsMatI) -> (Vec, u #[cfg(test)] mod tests { use super::*; - use std::path::{Path, PathBuf}; - - fn fixture_path(dataset: &str, filename: &str) -> PathBuf { - Path::new(env!("CARGO_MANIFEST_DIR")) - .join("tests/fixtures") - .join(dataset) - .join(filename) - } - - fn load_pruned_as_csr_f32(dataset: &str) -> CsMatI { - use ndarray::Array1; - use ndarray_npy::{NpzReader, ReadNpyError, ReadNpzError}; - - let path = fixture_path(dataset, "step5a_pruned.npz"); - let file = std::fs::File::open(&path) - .unwrap_or_else(|e| panic!("cannot open fixture {:?}: {}", path, e)); - let mut npz = NpzReader::new(file) - .unwrap_or_else(|e| panic!("cannot open NpzReader for {:?}: {}", path, e)); - - let data: Vec = match npz.by_name::, ndarray::Ix1>("data") { - Ok(arr) => arr.into_iter().collect(), - Err(ReadNpzError::Npy(ReadNpyError::WrongDescriptor(_))) => { - let arr: Array1 = npz - .by_name("data") - .unwrap_or_else(|e| panic!("data key not found in {:?}: {}", path, e)); - arr.iter().map(|&x| x as f32).collect() - } - Err(e) => panic!("error reading 'data' from {:?}: {}", path, e), - }; - - let indices: Vec = - match npz.by_name::, ndarray::Ix1>("indices") { - Ok(arr) => arr.iter().map(|&x| x as u32).collect(), - Err(ReadNpzError::Npy(ReadNpyError::WrongDescriptor(_))) => { - let arr: Array1 = npz - .by_name("indices") - .unwrap_or_else(|e| panic!("indices key not found in {:?}: {}", path, e)); - arr.iter().map(|&x| x as u32).collect() - } - Err(e) => panic!("error reading 'indices' from {:?}: {}", path, e), - }; - - let indptr: Vec = - match npz.by_name::, ndarray::Ix1>("indptr") { - Ok(arr) => arr.iter().map(|&x| x as usize).collect(), - Err(ReadNpzError::Npy(ReadNpyError::WrongDescriptor(_))) => { - let arr: Array1 = npz - .by_name("indptr") - .unwrap_or_else(|e| panic!("indptr key not found in {:?}: {}", path, e)); - arr.iter().map(|&x| x as usize).collect() - } - Err(e) => panic!("error reading 'indptr' from {:?}: {}", path, e), - }; - - let shape_arr: Vec = - match npz.by_name::, ndarray::Ix1>("shape") { - Ok(arr) => arr.iter().map(|&x| x as usize).collect(), - Err(ReadNpzError::Npy(ReadNpyError::WrongDescriptor(_))) => { - let arr: Array1 = npz - .by_name("shape") - .unwrap_or_else(|e| panic!("shape key not found in {:?}: {}", path, e)); - arr.iter().map(|&x| x as usize).collect() - } - Err(e) => panic!("error reading 'shape' from {:?}: {}", path, e), - }; - - assert!( - shape_arr.len() >= 2, - "shape key in {:?} has {} elements, expected 2", - path, - shape_arr.len() - ); - - CsMatI::try_new((shape_arr[0], shape_arr[1]), indptr, indices, data) - .unwrap_or_else(|e| panic!("fixture CSR structure invalid in {:?}: {:?}", path, e)) - } - - fn partition_of( - labels: &[usize], - ) -> std::collections::BTreeSet> { - let mut map: std::collections::BTreeMap> = - std::collections::BTreeMap::new(); - for (node, &label) in labels.iter().enumerate() { - map.entry(label).or_default().insert(node); - } - map.into_values().collect() - } - - // ── Pure unit tests ────────────────────────────────────────────────────── #[test] fn test_empty_graph() { @@ -214,101 +125,4 @@ mod tests { assert_eq!(labels[2], labels[3]); assert_ne!(labels[0], labels[2]); } - - // ── Fixture-gated tests ────────────────────────────────────────────────── - - #[test] - #[ignore = "requires generated .npz fixtures; run: python tests/generate_fixtures.py"] - fn test_components_blobs_connected_200() { - use ndarray_npy::NpzReader; - - let graph = load_pruned_as_csr_f32("blobs_connected_200"); - let (labels, n_components) = find_components(&graph); - - let path = fixture_path("blobs_connected_200", "comp_c_components.npz"); - let mut npz = NpzReader::new(std::fs::File::open(&path).unwrap()).unwrap(); - let py_n: i32 = npz - .by_name::, ndarray::Ix0>("n_components") - .unwrap() - .into_scalar(); - let py_labels_arr: ndarray::Array1 = npz.by_name("labels").unwrap(); - let py_labels: Vec = py_labels_arr.iter().map(|&x| x as usize).collect(); - - assert_eq!(n_components, py_n as usize, "n_components mismatch"); - assert_eq!(n_components, 1, "expected 1 component"); - assert_eq!(partition_of(&labels), partition_of(&py_labels)); - } - - #[test] - #[ignore = "requires generated .npz fixtures; run: python tests/generate_fixtures.py"] - fn test_components_disconnected_200() { - use ndarray_npy::NpzReader; - - let graph = load_pruned_as_csr_f32("disconnected_200"); - let (labels, n_components) = find_components(&graph); - - let path = fixture_path("disconnected_200", "comp_c_components.npz"); - let mut npz = NpzReader::new(std::fs::File::open(&path).unwrap()).unwrap(); - let py_n: i32 = npz - .by_name::, ndarray::Ix0>("n_components") - .unwrap() - .into_scalar(); - let py_labels_arr: ndarray::Array1 = npz.by_name("labels").unwrap(); - let py_labels: Vec = py_labels_arr.iter().map(|&x| x as usize).collect(); - - assert_eq!(n_components, py_n as usize, "n_components mismatch"); - assert_eq!(n_components, 4, "expected 4 components"); - assert_eq!(partition_of(&labels), partition_of(&py_labels)); - } - - #[test] - #[ignore = "requires generated .npz fixtures; run: python tests/generate_fixtures.py"] - fn test_components_all_datasets() { - use ndarray_npy::NpzReader; - - let datasets = [ - "blobs_50", - "blobs_500", - "blobs_5000", - "blobs_connected_200", - "blobs_connected_2000", - "circles_300", - "moons_200", - "near_dupes_100", - "disconnected_200", - ]; - - for dataset in &datasets { - let graph = load_pruned_as_csr_f32(dataset); - let (labels, n_components) = find_components(&graph); - - let path = fixture_path(dataset, "comp_c_components.npz"); - let mut npz = - NpzReader::new(std::fs::File::open(&path).unwrap_or_else(|e| { - panic!("dataset {}: cannot open {:?}: {}", dataset, path, e) - })) - .unwrap_or_else(|e| panic!("dataset {}: cannot parse {:?}: {}", dataset, path, e)); - - let py_n: i32 = npz - .by_name::, ndarray::Ix0>("n_components") - .unwrap_or_else(|e| panic!("dataset {}: n_components not found: {}", dataset, e)) - .into_scalar(); - let py_labels_arr: ndarray::Array1 = npz - .by_name("labels") - .unwrap_or_else(|e| panic!("dataset {}: labels not found: {}", dataset, e)); - let py_labels: Vec = py_labels_arr.iter().map(|&x| x as usize).collect(); - - assert_eq!( - n_components, py_n as usize, - "dataset {}: n_components mismatch (rust={}, python={})", - dataset, n_components, py_n - ); - assert_eq!( - partition_of(&labels), - partition_of(&py_labels), - "dataset {}: label partitioning mismatch", - dataset - ); - } - } } diff --git a/src/lib.rs b/src/lib.rs index 847df35..825ea9e 100644 --- a/src/lib.rs +++ b/src/lib.rs @@ -181,6 +181,15 @@ pub fn embed_disconnected( #[doc(hidden)] pub use crate::solvers::sinv::lobpcg_sinv_solve; +#[cfg(feature = "testing")] +#[doc(hidden)] +pub fn scale_coords( + coords: &ndarray::Array2, + max_coord: f64, +) -> Result, SpectralError> { + crate::scaling::scale_coords(coords, max_coord) +} + #[cfg(feature = "testing")] #[doc(hidden)] pub fn scale_and_add_noise_pub( @@ -464,9 +473,12 @@ mod config_tests { #[test] fn compute_mode_copy_clone_eq() { + fn clone_of(value: &T) -> T { + value.clone() + } let a = ComputeMode::PythonCompat; let b = a; // Copy - let c = a.clone(); // Clone + let c = clone_of(&a); // Clone assert_eq!(a, b); // PartialEq, Eq assert_eq!(a, c); let _ = format!("{a:?}"); // Debug diff --git a/src/metrics.rs b/src/metrics.rs index 2cd9f67..25b79aa 100644 --- a/src/metrics.rs +++ b/src/metrics.rs @@ -408,11 +408,7 @@ pub fn eigenvalue_condition_number(eigenvalues: &Array1) -> f64 { /// Both slices must have the same length and at least 10 elements (caller ensures /// `xi.len() == xj.len()` and `d_x >= 10` at the dispatch site). #[doc(hidden)] -#[cfg(all( - target_arch = "x86_64", - target_feature = "avx2", - target_feature = "fma" -))] +#[cfg(target_arch = "x86_64")] #[target_feature(enable = "avx2,fma")] pub unsafe fn dist_sq_avx2_looped(xi: &[f64], xj: &[f64]) -> f64 { debug_assert_eq!( @@ -556,22 +552,15 @@ pub(crate) fn trustworthiness_inner( #[cfg(target_arch = "x86_64")] let use_avx2 = is_x86_feature_detected!("avx2") && is_x86_feature_detected!("fma"); - #[cfg(not(target_arch = "x86_64"))] - let use_avx2 = false; + #[cfg(target_arch = "x86_64")] let d_x = x.ncols(); - let d_y = y.ncols(); #[cfg(target_arch = "x86_64")] - let use_avx2_y = { d_y == 2 && y.is_standard_layout() && is_x86_feature_detected!("avx2") }; - #[cfg(not(target_arch = "x86_64"))] - let use_avx2_y = false; + let use_avx2_y = + { y.ncols() == 2 && y.is_standard_layout() && is_x86_feature_detected!("avx2") }; // Validate contiguity once before the parallel loop: SIMD dispatch requires C-contiguous rows. - #[cfg(all( - target_arch = "x86_64", - target_feature = "avx2", - target_feature = "fma" - ))] + #[cfg(target_arch = "x86_64")] if use_avx2 && d_x >= 10 { assert!( x.is_standard_layout(), @@ -616,11 +605,7 @@ pub(crate) fn trustworthiness_inner( for j in 0..n { let xj = x.row(j); dist_x[j] = { - #[cfg(all( - target_arch = "x86_64", - target_feature = "avx2", - target_feature = "fma" - ))] + #[cfg(target_arch = "x86_64")] { if use_avx2 && d_x >= 10 { let si = xi.as_slice().expect("x row must be contiguous"); @@ -634,11 +619,7 @@ pub(crate) fn trustworthiness_inner( .sum() } } - #[cfg(not(all( - target_arch = "x86_64", - target_feature = "avx2", - target_feature = "fma" - )))] + #[cfg(not(target_arch = "x86_64"))] { xi.iter() .zip(xj.iter()) @@ -891,8 +872,8 @@ mod tests { #[test] fn t_const_02_threshold_ordering() { assert_eq!(DENSE_EVD_QUALITY_THRESHOLD, SINV_LOBPCG_QUALITY_THRESHOLD); - assert!(SINV_LOBPCG_QUALITY_THRESHOLD < LOBPCG_QUALITY_THRESHOLD); - assert!(LOBPCG_QUALITY_THRESHOLD < RSVD_QUALITY_THRESHOLD); + const { assert!(SINV_LOBPCG_QUALITY_THRESHOLD < LOBPCG_QUALITY_THRESHOLD) }; + const { assert!(LOBPCG_QUALITY_THRESHOLD < RSVD_QUALITY_THRESHOLD) }; } // ── Accuracy: eigenpair_residual ───────────────────────────────────────── @@ -1189,7 +1170,7 @@ mod tests { let x = ndarray::Array2::from_shape_fn((20, 10), |_| rng.random::()); let y = ndarray::Array2::from_shape_fn((20, 2), |_| rng.random::()); let t = trustworthiness(x.view(), y.view(), 5); - assert!(t >= 0.0 && t <= 1.0, "T out of [0,1]: {t}"); + assert!((0.0..=1.0).contains(&t), "T out of [0,1]: {t}"); } /// Hand-verifiable 4-point, k=1 example with exactly one violation of rank penalty 1. @@ -1236,7 +1217,7 @@ mod tests { let y = ndarray::Array2::from_shape_fn((n, 2), |_| rng.random::()); let t = trustworthiness(x.view(), y.view(), k); assert!(t.is_finite(), "T should be finite at k=n/2-1: {t}"); - assert!(t >= 0.0 && t <= 1.0, "T out of [0,1] at k=n/2-1: {t}"); + assert!((0.0..=1.0).contains(&t), "T out of [0,1] at k=n/2-1: {t}"); } #[test] @@ -1249,13 +1230,12 @@ mod tests { let _ = trustworthiness(x.view(), y.view(), k); } - #[cfg(all( - target_arch = "x86_64", - target_feature = "avx2", - target_feature = "fma" - ))] + #[cfg(target_arch = "x86_64")] #[test] fn t_tw_06_avx2_looped_kernel_matches_scalar() { + if !(is_x86_feature_detected!("avx2") && is_x86_feature_detected!("fma")) { + return; // skip on CPUs without AVX2+FMA + } use rand::{Rng, SeedableRng}; let mut rng = rand::rngs::SmallRng::seed_from_u64(42); for len in [10, 13, 16, 50, 100] { @@ -1266,6 +1246,7 @@ mod tests { .zip(b.iter()) .map(|(&x, &y)| (x - y) * (x - y)) .sum(); + // SAFETY: runtime check above guarantees AVX2+FMA; both slices have `len` elements. let avx2 = unsafe { super::dist_sq_avx2_looped(&a, &b) }; assert!( (avx2 - scalar).abs() < 1e-10, @@ -1400,7 +1381,7 @@ mod tests { let t = trustworthiness(x.view(), y.view(), k); let t_ref = trustworthiness_brute_force(x.view(), y.view(), k); assert!(t.is_finite(), "T(k={k}) must be finite, got {t}"); - assert!(t >= 0.0 && t <= 1.0, "T(k={k}) out of [0,1]: {t}"); + assert!((0.0..=1.0).contains(&t), "T(k={k}) out of [0,1]: {t}"); assert!( (t - t_ref).abs() < 1e-12, "T(k={k}) combined={t} diverges from brute-force reference={t_ref}" diff --git a/src/operator.rs b/src/operator.rs index e809bec..4b9130c 100644 --- a/src/operator.rs +++ b/src/operator.rs @@ -635,116 +635,4 @@ mod tests { } } } - - // ─── Fixture-gated tests ───────────────────────────────────────────────── - - /// Load the blobs_connected_200 Laplacian (f64 CSR with i32 indices) from a fixture NPZ. - fn load_fixture_laplacian() -> CsMatI { - use ndarray_npy::NpzReader; - use std::path::Path; - let path = Path::new(env!("CARGO_MANIFEST_DIR")) - .join("tests/fixtures/blobs_connected_200/comp_b_laplacian.npz"); - let file = - std::fs::File::open(&path).unwrap_or_else(|e| panic!("cannot open {:?}: {}", path, e)); - let mut npz = NpzReader::new(file) - .unwrap_or_else(|e| panic!("NpzReader error for {:?}: {}", path, e)); - let data: Vec = npz - .by_name::, ndarray::Ix1>("data") - .unwrap() - .into_iter() - .collect(); - let indices: Vec = npz - .by_name::, ndarray::Ix1>("indices") - .unwrap() - .iter() - .map(|&x| x as usize) - .collect(); - let indptr: Vec = npz - .by_name::, ndarray::Ix1>("indptr") - .unwrap() - .iter() - .map(|&x| x as usize) - .collect(); - let shape_arr: ndarray::Array1 = npz.by_name("shape").unwrap(); - assert_eq!(shape_arr.len(), 2, "shape array must have 2 elements"); - let rows = shape_arr[0] as usize; - let cols = shape_arr[1] as usize; - CsMatI::try_new((rows, cols), indptr, indices, data).expect("fixture Laplacian CSR invalid") - } - - #[test] - #[ignore = "requires fixture generation: run tests/generate_fixtures.py first"] - fn test_eigenpair_residual_from_fixture() { - use ndarray_npy::NpzReader; - use std::path::Path; - - let laplacian = load_fixture_laplacian(); - let n = laplacian.rows(); - - // Load eigenvalues and eigenvectors from comp_d_eigensolver.npz - let path = Path::new(env!("CARGO_MANIFEST_DIR")) - .join("tests/fixtures/blobs_connected_200/comp_d_eigensolver.npz"); - let file = std::fs::File::open(&path).unwrap(); - let mut npz = NpzReader::new(file).unwrap(); - let eigenvalues: ndarray::Array1 = npz.by_name("eigenvalues").unwrap(); - let eigenvectors: ndarray::Array2 = npz.by_name("eigenvectors").unwrap(); - let k = eigenvalues.len(); - assert_eq!(eigenvectors.shape()[0], n); - assert_eq!(eigenvectors.shape()[1], k); - - // For each eigenpair, assert residual ||L*v - λ*v|| / ||v|| < 1e-10. - // These are Python reference eigenvectors computed by numpy.linalg.eigh, - // so near-exact residuals are expected. - for j in 0..k { - let v = eigenvectors.column(j).to_owned(); - let lambda = eigenvalues[j]; - let residual = crate::metrics::eigenpair_residual(&laplacian, &v, lambda); - assert!( - residual < 1e-10, - "eigenpair {j}: residual={residual:.3e} >= 1e-10 (lambda={lambda:.6e})" - ); - } - } - - #[test] - #[ignore = "requires fixture generation: run tests/generate_fixtures.py first"] - fn test_multi_vector_matches_sequential_from_fixture() { - use ndarray_npy::NpzReader; - use std::path::Path; - - let mat = load_fixture_laplacian(); - let op = CsrOperator(&mat); - let n = mat.rows(); - - // Load eigenvectors as input matrix - let path = Path::new(env!("CARGO_MANIFEST_DIR")) - .join("tests/fixtures/blobs_connected_200/comp_d_eigensolver.npz"); - let file = std::fs::File::open(&path).unwrap(); - let mut npz = NpzReader::new(file).unwrap(); - let eigenvectors: ndarray::Array2 = npz.by_name("eigenvectors").unwrap(); - let k = eigenvectors.shape()[1]; - - // Apply CsrOperator to the full (n, k) matrix at once. - let mut y_block = ndarray::Array2::::zeros((n, k)); - op.apply(eigenvectors.view(), &mut y_block); - - // Apply column-by-column and compare. - for j in 0..k { - let x_col = eigenvectors - .column(j) - .to_owned() - .insert_axis(ndarray::Axis(1)); - let mut y_col = ndarray::Array2::::zeros((n, 1)); - op.apply(x_col.view(), &mut y_col); - for i in 0..n { - assert!( - (y_block[[i, j]] - y_col[[i, 0]]).abs() < 1e-14, - "block vs sequential mismatch at row={i} col={j}: \ - block={} seq={}", - y_block[[i, j]], - y_col[[i, 0]] - ); - } - } - } } diff --git a/src/scaling.rs b/src/scaling.rs index 5b2cf74..33a73c7 100644 --- a/src/scaling.rs +++ b/src/scaling.rs @@ -94,166 +94,3 @@ pub(crate) fn scale_and_add_noise( let mut rng = StdRng::seed_from_u64(seed); noisy_scale_coords(&coords, &mut rng, 10.0, 0.0001) } - -#[cfg(test)] -mod tests { - use super::*; - use ndarray_npy::{NpzReader, ReadableElement}; - use std::path::PathBuf; - - fn fixture_path(dataset: &str, file: &str) -> PathBuf { - let manifest_dir = env!("CARGO_MANIFEST_DIR"); - PathBuf::from(manifest_dir) - .join("tests") - .join("fixtures") - .join(dataset) - .join(file) - } - - fn npz_array2(path: &PathBuf, key: &str) -> Option> { - let file = std::fs::File::open(path).ok()?; - let mut reader = NpzReader::new(file).ok()?; - reader.by_name(key).ok() - } - - fn check_pre_noise_exact(dataset: &str) { - let e_path = fixture_path(dataset, "comp_e_selection.npz"); - let f_path = fixture_path(dataset, "comp_f_scaling.npz"); - - if !e_path.exists() || !f_path.exists() { - panic!("check_pre_noise_exact({dataset}): fixture files absent"); - } - - let embedding = npz_array2::(&e_path, "embedding").expect("embedding key missing"); - let expected_pre_noise = - npz_array2::(&f_path, "pre_noise").expect("pre_noise key missing"); - - let result = scale_coords(&embedding, 10.0).expect("scale_coords failed"); - - // Verify element-wise exact equality - for i in 0..result.nrows() { - for j in 0..result.ncols() { - approx::assert_abs_diff_eq!( - result[[i, j]], - expected_pre_noise[[i, j]], - epsilon = 0.0f32 - ); - } - } - - // Verify max absolute value ≈ 10.0 - let max_abs = result.iter().cloned().map(f32::abs).fold(0.0f32, f32::max); - // Tolerance is 1e-6f32: scale_coords computes expansion = 10.0 / max_abs_f64, - // then casts each element to f32. The maximum element maps to exactly 10.0 - // modulo f32 rounding (~9.5e-7, one ULP at 10.0 = 2^(3-23)); 1e-6 is just - // above that single-ULP bound. - approx::assert_abs_diff_eq!(max_abs, 10.0f32, epsilon = 1e-6f32); - } - - #[test] - #[ignore = "requires generated .npz fixtures; run: python tests/generate_fixtures.py"] - fn test_pre_noise_exact_blobs_50() { - check_pre_noise_exact("blobs_50"); - } - - #[test] - #[ignore = "requires generated .npz fixtures; run: python tests/generate_fixtures.py"] - fn test_pre_noise_exact_parametrized() { - check_pre_noise_exact("moons_200"); - check_pre_noise_exact("circles_300"); - } - - #[test] - #[ignore = "requires generated .npz fixtures; run: python tests/generate_fixtures.py"] - fn test_noise_distribution_blobs_50() { - let e_path = fixture_path("blobs_50", "comp_e_selection.npz"); - if !e_path.exists() { - panic!("test_noise_distribution_blobs_50: fixture absent"); - } - - let embedding = npz_array2::(&e_path, "embedding").expect("embedding key missing"); - let n = embedding.len(); - - let final_result = - scale_and_add_noise(embedding.clone(), 42).expect("scale_and_add_noise failed"); - let pre_noise = scale_coords(&embedding, 10.0).expect("scale_coords failed"); - - let noise: ndarray::Array2 = &final_result - &pre_noise; - let noise_flat: Vec = noise.iter().cloned().collect(); - - let mean: f32 = noise_flat.iter().sum::() / n as f32; - let variance: f32 = noise_flat.iter().map(|x| (x - mean).powi(2)).sum::() / n as f32; - let std_dev = variance.sqrt(); - - // 3-sigma test for mean ≈ 0 - let three_sigma = 3.0 * 0.0001_f32 / (n as f32).sqrt(); - assert!( - mean.abs() < three_sigma, - "noise mean {mean} exceeds 3-sigma bound {three_sigma}" - ); - - // std within 20% of 0.0001 - let relative_err = (std_dev - 0.0001f32).abs() / 0.0001f32; - assert!( - relative_err < 0.20, - "noise std {std_dev} is not within 20% of 0.0001 (relative error: {relative_err})" - ); - } - - #[test] - #[ignore = "requires generated .npz fixtures; run: python tests/generate_fixtures.py"] - fn test_max_abs_is_10() { - for dataset in &["blobs_50", "moons_200", "circles_300"] { - let e_path = fixture_path(dataset, "comp_e_selection.npz"); - if !e_path.exists() { - panic!("test_max_abs_is_10({dataset}): fixture absent"); - } - - let embedding = npz_array2::(&e_path, "embedding").expect("embedding key missing"); - let pre_noise = scale_coords(&embedding, 10.0).expect("scale_coords failed"); - let max_abs = pre_noise - .iter() - .cloned() - .map(f32::abs) - .fold(0.0f32, f32::max); - - // Tolerance is 1e-6f32: deterministic f64→f32 cast; max element rounds - // to 10.0 with at most ~9.5e-7 (f32 ULP at 10.0 = 2^(3-23)); 1e-6 gives headroom. - approx::assert_abs_diff_eq!(max_abs, 10.0f32, epsilon = 1e-6f32); - } - } - - macro_rules! make_scale_test { - ($name:ident, $dataset:literal) => { - #[test] - #[ignore = "requires generated .npz fixtures; run: python tests/generate_fixtures.py"] - fn $name() { - check_pre_noise_exact($dataset); - } - }; - } - - make_scale_test!(scale_pre_noise_matches_blobs_500, "blobs_500"); - make_scale_test!(scale_pre_noise_matches_blobs_5000, "blobs_5000"); - make_scale_test!( - scale_pre_noise_matches_blobs_connected_200, - "blobs_connected_200" - ); - make_scale_test!( - scale_pre_noise_matches_blobs_connected_2000, - "blobs_connected_2000" - ); - make_scale_test!(scale_pre_noise_matches_near_dupes_100, "near_dupes_100"); - - #[test] - #[ignore = "requires generated .npz fixtures; run: python tests/generate_fixtures.py"] - fn scale_max_abs_is_10_disconnected_200() { - let path = fixture_path("disconnected_200", "comp_f_scaling.npz"); - let pre_noise: ndarray::Array2 = - npz_array2::(&path, "pre_noise").expect("pre_noise key missing"); - assert_eq!(pre_noise.shape(), &[200, 2]); - assert!(pre_noise.iter().all(|v| v.is_finite())); - let max_abs = pre_noise.iter().copied().map(f32::abs).fold(0f32, f32::max); - assert!((max_abs - 10.0f32).abs() < 1e-6, "max_abs={max_abs}"); // f32 ULP at 10.0 ≈ 9.5e-7 - } -} diff --git a/src/solvers/dense.rs b/src/solvers/dense.rs index 166036c..6bc6cc1 100644 --- a/src/solvers/dense.rs +++ b/src/solvers/dense.rs @@ -17,7 +17,8 @@ use ndarray::{Array1, Array2}; use sprs::CsMatI; /// Dense eigendecomposition via faer for small n. -/// Returns (eigenvalues shape [k], eigenvectors shape [n, k]) sorted ascending by eigenvalue. +/// Returns (eigenvalues of shape `[k]`, eigenvectors of shape `[n, k]`) sorted ascending by +/// eigenvalue. pub fn dense_evd(laplacian: &CsMatI, k: usize) -> Result { let n = laplacian.rows(); if k > n { diff --git a/src/solvers/lobpcg.rs b/src/solvers/lobpcg.rs index c156a91..36b9a57 100644 --- a/src/solvers/lobpcg.rs +++ b/src/solvers/lobpcg.rs @@ -33,7 +33,7 @@ use rand_distr::{Distribution, StandardNormal}; // ─── ndarray 0.16 ↔ 0.17 conversion helpers ────────────────────────────────── -/// Convert an owned ndarray 0.17 Array2 to ndarray 0.16 Array2. +/// Convert an owned ndarray 0.17 `Array2` to ndarray 0.16 `Array2`. fn to_nd16_array2(a: Array2) -> nd16::Array2 { let (rows, cols) = (a.nrows(), a.ncols()); // iter() respects logical shape regardless of memory layout or slicing. @@ -42,7 +42,7 @@ fn to_nd16_array2(a: Array2) -> nd16::Array2 { .expect("shape/data mismatch converting nd17→nd16 Array2") } -/// Convert an ndarray 0.16 ArrayView2 to an owned ndarray 0.17 Array2. +/// Convert an ndarray 0.16 `ArrayView2` to an owned ndarray 0.17 `Array2`. fn from_nd16_view2(v: nd16::ArrayView2) -> Array2 { let (rows, cols) = (v.nrows(), v.ncols()); let raw: Vec = v.iter().copied().collect(); @@ -50,7 +50,7 @@ fn from_nd16_view2(v: nd16::ArrayView2) -> Array2 { .expect("shape/data mismatch converting nd16→nd17 ArrayView2") } -/// Convert an owned ndarray 0.16 Array1 to ndarray 0.17 Array1. +/// Convert an owned ndarray 0.16 `Array1` to ndarray 0.17 `Array1`. /// /// Uses `iter()` instead of `into_raw_vec()` because linfa-linalg can return sliced arrays /// whose backing Vec is longer than the logical length. `iter()` always respects logical size. @@ -58,7 +58,7 @@ fn from_nd16_array1(a: nd16::Array1) -> Array1 { Array1::from_iter(a.iter().copied()) } -/// Convert an owned ndarray 0.16 Array2 to ndarray 0.17 Array2. +/// Convert an owned ndarray 0.16 `Array2` to ndarray 0.17 `Array2`. /// /// Uses `iter()` for the same reason as `from_nd16_array1`: slice_move can leave backing /// Vecs larger than the logical extent, and `into_raw_vec()` would return all elements. diff --git a/src/solvers/mod.rs b/src/solvers/mod.rs index eea74ba..214e257 100644 --- a/src/solvers/mod.rs +++ b/src/solvers/mod.rs @@ -10,11 +10,11 @@ //! //! | Level | Condition | Solver | Quality Threshold | //! |-------|-----------|--------|-------------------| -//! | 0 | n < 2000 | Dense EVD ([`dense`]) via faer | 1e-6 | -//! | 1 | n ≥ 2000 | LOBPCG ([`lobpcg`]) without regularization | 2e-5 | -//! | 2 | Level 1 quality failed | Shift-invert LOBPCG ([`sinv`]) via faer Cholesky | 1e-6 | -//! | 3 | Level 2 quality failed | LOBPCG ([`lobpcg`]) with ε·I regularization | 2e-5 | -//! | 4 | Level 3 quality failed | Randomized SVD ([`rsvd`]) via 2I−L trick | 1e-2 | +//! | 0 | n < 2000 | Dense EVD (`dense`) via faer | 1e-6 | +//! | 1 | n ≥ 2000 | LOBPCG (`lobpcg`) without regularization | 2e-5 | +//! | 2 | Level 1 quality failed | Shift-invert LOBPCG (`sinv`) via faer Cholesky | 1e-6 | +//! | 3 | Level 2 quality failed | LOBPCG (`lobpcg`) with ε·I regularization | 2e-5 | +//! | 4 | Level 3 quality failed | Randomized SVD (`rsvd`) via 2I−L trick | 1e-2 | //! | 5 | Level 4 quality failed | Forced dense EVD — always accepted | — | //! //! A level "fails" when its residual exceeds the threshold, not when it returns an @@ -49,7 +49,7 @@ use crate::operator::CsrOperator; use ndarray::{Array1, Array2}; use sprs::CsMatI; -/// Eigendecomposition result: (eigenvalues shape [k], eigenvectors shape [n, k]). +/// Eigendecomposition result: (eigenvalues of shape `[k]`, eigenvectors of shape `[n, k]`). pub type EigenResult = (Array1, Array2); /// Graphs with n < DENSE_N_THRESHOLD use Level 0 (dense EVD) directly. @@ -436,7 +436,7 @@ mod tests { ComputeMode::PythonCompat, ); assert!( - level >= 1 && level <= 5, + (1..=5).contains(&level), "expected level in {{1,2,3,4,5}}, got {level}" ); } diff --git a/src/solvers/rsvd.rs b/src/solvers/rsvd.rs index 80b4737..3e66c09 100644 --- a/src/solvers/rsvd.rs +++ b/src/solvers/rsvd.rs @@ -396,7 +396,7 @@ mod tests { // Eigenvalue range: [0, 2] for normalized Laplacian for &lambda in eigenvalues.iter() { assert!( - lambda >= -1e-10 && lambda <= 2.0 + 1e-10, + (-1e-10..=2.0 + 1e-10).contains(&lambda), "eigenvalue {lambda:.6} out of [0, 2]" ); } @@ -444,20 +444,19 @@ mod tests { ); // Non-trivial eigenvalues of the 6-ring are 0.5 (indices 1..=n_components) - for i in 1..=n_components { - let err = (eig_slice[i] - 0.5_f64).abs(); + for (i, &lambda) in eig_slice.iter().enumerate().skip(1) { + let err = (lambda - 0.5_f64).abs(); assert!( err < 1e-4, "eigenvalue[{i}] = {:.8}, expected 0.5, err = {:.2e} (threshold 1e-4)", - eig_slice[i], + lambda, err ); } // Residual checks for non-trivial eigenpairs (index 1..=n_components) - for i in 1..=n_components { + for (i, &lambda) in eig_slice.iter().enumerate().skip(1) { let v = eigenvectors.column(i).to_owned(); - let lambda = eig_slice[i]; // L·v via SpMV let lv = &l * &v; diff --git a/src/solvers/sinv.rs b/src/solvers/sinv.rs index c6e527c..aab42c2 100644 --- a/src/solvers/sinv.rs +++ b/src/solvers/sinv.rs @@ -62,7 +62,7 @@ fn from_nd16_array2(a: nd16::Array2) -> Array2 { // ─── sprs ↔ faer sparse conversion ─────────────────────────────────────────── -/// Convert a sprs CsMat (CSR or CSC) to a faer SparseColMat, +/// Convert a sprs `CsMat` (CSR or CSC) to a faer `SparseColMat`, /// adding `diag_shift` to every diagonal entry (used to build M = L + εI). /// /// The conversion goes CSR/CSC → sprs CSC → raw arrays → faer CSC. @@ -90,20 +90,20 @@ fn sprs_csc_to_faer( // ─── ndarray 0.17 ↔ faer dense bridge helpers ──────────────────────────────── -/// Convert ndarray 0.17 ArrayView2 [n, k] to a faer Mat [n, k]. +/// Convert ndarray 0.17 `ArrayView2` `[n, k]` to a faer `Mat` `[n, k]`. /// Copies element-by-element to handle ndarray row-major vs faer column-major. fn nd17_view_to_faer(x: ArrayView2) -> faer::Mat { let (nrows, ncols) = x.dim(); faer::Mat::::from_fn(nrows, ncols, |i, j| x[[i, j]]) } -/// Convert a faer Mat [n, k] to ndarray 0.17 Array2. +/// Convert a faer `Mat` `[n, k]` to ndarray 0.17 `Array2`. fn faer_to_nd17(x: &faer::Mat) -> Array2 { let (nrows, ncols) = (x.nrows(), x.ncols()); Array2::from_shape_fn((nrows, ncols), |(i, j)| x[(i, j)]) } -/// Convert a faer Mat [n, k] to ndarray 0.16 Array2. +/// Convert a faer `Mat` `[n, k]` to ndarray 0.16 `Array2`. fn faer_to_nd17_nd16(x: &faer::Mat) -> nd16::Array2 { to_nd16_array2(faer_to_nd17(x)) } diff --git a/tests/integration/test_adversarial_graphs.rs b/tests/integration/test_adversarial_graphs.rs index 1fbb963..ba28e87 100644 --- a/tests/integration/test_adversarial_graphs.rs +++ b/tests/integration/test_adversarial_graphs.rs @@ -260,11 +260,6 @@ fn large_ring_laplacian(n: usize) -> CsMatI { CsMatI::new((n, n), indptr, indices, data) } -/// sqrt_deg vector for C_n (ring graph): all entries are sqrt(2). -fn ring_sqrt_deg(n: usize) -> Array1 { - Array1::from_elem(n, 2.0_f64.sqrt()) -} - /// Normalized Laplacian of the epsilon-bridge graph in f64. /// Two complete subgraphs of size `cluster_size` connected by a single edge /// of weight `bridge_weight`. Total n = 2 * cluster_size. @@ -299,7 +294,7 @@ fn large_epsilon_bridge_laplacian(cluster_size: usize, bridge_weight: f64) -> Cs // First clique: connect to all other first-clique nodes for j in 0..cs { if j != i { - let w_off = -1.0 * inv_sqrt_deg[i] * inv_sqrt_deg[j]; + let w_off = -inv_sqrt_deg[i] * inv_sqrt_deg[j]; row_entries.push((j, w_off)); } } @@ -312,7 +307,7 @@ fn large_epsilon_bridge_laplacian(cluster_size: usize, bridge_weight: f64) -> Cs // Second clique: connect to all other second-clique nodes for j in cs..n { if j != i { - let w_off = -1.0 * inv_sqrt_deg[i] * inv_sqrt_deg[j]; + let w_off = -inv_sqrt_deg[i] * inv_sqrt_deg[j]; row_entries.push((j, w_off)); } } @@ -332,19 +327,6 @@ fn large_epsilon_bridge_laplacian(cluster_size: usize, bridge_weight: f64) -> Cs CsMatI::new((n, n), indptr, indices, data) } -/// sqrt_deg vector for the epsilon-bridge graph. -/// Bridge nodes have degree (cluster_size - 1 + bridge_weight); others have degree cluster_size - 1. -fn epsilon_bridge_sqrt_deg(cluster_size: usize, bridge_weight: f64) -> Array1 { - let cs = cluster_size; - let n = 2 * cs; - let deg_regular = ((cs - 1) as f64).sqrt(); - let deg_bridge = ((cs - 1) as f64 + bridge_weight).sqrt(); - let mut v = vec![deg_regular; n]; - v[cs - 1] = deg_bridge; - v[cs] = deg_bridge; - Array1::from_vec(v) -} - /// 6-node unnormalized path-graph Laplacian, mirroring `path_graph_laplacian_6` in /// `src/solvers/mod.rs` unit tests. /// @@ -711,12 +693,12 @@ fn large_epsilon_bridge_laplacian_shape_and_symmetry() { let lji: Option = lap .outer_view(j) .and_then(|row| row.iter().find(|(col, _)| *col == i).map(|(_, val)| *val)); - match (lij, lji) { - (Some(a), Some(b)) => assert!( + // A non-edge (both None) is fine. + if let (Some(a), Some(b)) = (lij, lji) { + assert!( (a - b).abs() < 1e-14, "Laplacian not symmetric: L[{i},{j}]={a} != L[{j},{i}]={b}" - ), - _ => {} // non-edge: both None is fine + ); } } } diff --git a/tests/integration/test_comp_c_components.rs b/tests/integration/test_comp_c_components.rs index 4fea3f0..695ef0c 100644 --- a/tests/integration/test_comp_c_components.rs +++ b/tests/integration/test_comp_c_components.rs @@ -47,55 +47,46 @@ fn run_comp_c_test(dataset: &str, expected_n_components: usize) { // ── Per-dataset tests ───────────────────────────────────────────────────────── #[test] -#[ignore = "requires generated .npz fixtures; run: python tests/generate_fixtures.py"] fn comp_c_components_matches_python_blobs_50() { run_comp_c_test("blobs_50", 3); } #[test] -#[ignore = "requires generated .npz fixtures; run: python tests/generate_fixtures.py"] fn comp_c_components_matches_python_blobs_500() { run_comp_c_test("blobs_500", 4); } #[test] -#[ignore = "requires generated .npz fixtures; run: python tests/generate_fixtures.py"] fn comp_c_components_matches_python_blobs_5000() { run_comp_c_test("blobs_5000", 2); } #[test] -#[ignore = "requires generated .npz fixtures; run: python tests/generate_fixtures.py"] fn comp_c_components_matches_python_blobs_connected_200() { run_comp_c_test("blobs_connected_200", 1); } #[test] -#[ignore = "requires generated .npz fixtures; run: python tests/generate_fixtures.py"] fn comp_c_components_matches_python_blobs_connected_2000() { run_comp_c_test("blobs_connected_2000", 1); } #[test] -#[ignore = "requires generated .npz fixtures; run: python tests/generate_fixtures.py"] fn comp_c_components_matches_python_circles_300() { run_comp_c_test("circles_300", 1); } #[test] -#[ignore = "requires generated .npz fixtures; run: python tests/generate_fixtures.py"] fn comp_c_components_matches_python_moons_200() { run_comp_c_test("moons_200", 1); } #[test] -#[ignore = "requires generated .npz fixtures; run: python tests/generate_fixtures.py"] fn comp_c_components_matches_python_near_dupes_100() { run_comp_c_test("near_dupes_100", 1); } #[test] -#[ignore = "requires generated .npz fixtures; run: python tests/generate_fixtures.py"] fn comp_c_components_matches_python_disconnected_200() { run_comp_c_test("disconnected_200", 4); } @@ -103,7 +94,6 @@ fn comp_c_components_matches_python_disconnected_200() { // ── All-datasets sweep ──────────────────────────────────────────────────────── #[test] -#[ignore = "requires generated .npz fixtures; run: python tests/generate_fixtures.py"] fn comp_c_components_matches_python_all_datasets() { let datasets: &[(&str, usize)] = &[ ("blobs_50", 3), diff --git a/tests/integration/test_metrics_assess.rs b/tests/integration/test_metrics_assess.rs index e709fbd..2113d66 100644 --- a/tests/integration/test_metrics_assess.rs +++ b/tests/integration/test_metrics_assess.rs @@ -51,7 +51,7 @@ fn datasets_to_run() -> Vec<(&'static str, usize, bool, usize)> { let filter = std::env::var("SPECTRAL_DATASET").ok(); DATASETS .iter() - .filter(|(name, ..)| filter.as_deref().map_or(true, |f| *name == f)) + .filter(|(name, ..)| filter.as_deref().is_none_or(|f| *name == f)) .copied() .collect() } @@ -232,7 +232,6 @@ fn parity_to_markdown(experiment: &ExperimentMetrics, solver_levels: &[Option = Vec::new(); @@ -421,7 +420,6 @@ fn assess_accuracy() { } #[test] -#[ignore = "requires generated .npz fixtures; run: python tests/generate_fixtures.py"] fn assess_parity() { let run_set = datasets_to_run(); let mut all_reports: Vec = Vec::new(); diff --git a/tests/integration/test_operator_fixtures.rs b/tests/integration/test_operator_fixtures.rs new file mode 100644 index 0000000..eed4fec --- /dev/null +++ b/tests/integration/test_operator_fixtures.rs @@ -0,0 +1,69 @@ +#[path = "../common/mod.rs"] +mod common; + +use ndarray::{Array1, Array2}; +use spectral_init::operator::{CsrOperator, LinearOperator}; + +const DATASET: &str = "blobs_connected_200"; + +#[test] +fn test_eigenpair_residual_from_fixture() { + let laplacian = common::load_sparse_csr(&common::fixture_path(DATASET, "comp_b_laplacian.npz")); + let n = laplacian.rows(); + + let eigen_path = common::fixture_path(DATASET, "comp_d_eigensolver.npz"); + let eigenvalues: Array1 = common::load_dense(&eigen_path, "eigenvalues"); + let eigenvectors: Array2 = common::load_dense(&eigen_path, "eigenvectors"); + let k = eigenvalues.len(); + assert_eq!(eigenvectors.shape()[0], n); + assert_eq!(eigenvectors.shape()[1], k); + + // For each eigenpair, assert residual ||L*v - λ*v|| / ||v|| < 1e-10. + // These are Python reference eigenvectors computed by numpy.linalg.eigh, + // so near-exact residuals are expected. + for j in 0..k { + let lambda = eigenvalues[j]; + let residual = common::residual_spmv(&laplacian, eigenvectors.column(j), lambda); + assert!( + residual < 1e-10, + "eigenpair {j}: residual={residual:.3e} >= 1e-10 (lambda={lambda:.6e})" + ); + } +} + +#[test] +fn test_multi_vector_matches_sequential_from_fixture() { + let mat = common::load_sparse_csr(&common::fixture_path(DATASET, "comp_b_laplacian.npz")); + let op = CsrOperator(&mat); + let n = mat.rows(); + + // Load eigenvectors as input matrix + let eigenvectors: Array2 = common::load_dense( + &common::fixture_path(DATASET, "comp_d_eigensolver.npz"), + "eigenvectors", + ); + let k = eigenvectors.shape()[1]; + + // Apply CsrOperator to the full (n, k) matrix at once. + let mut y_block = Array2::::zeros((n, k)); + op.apply(eigenvectors.view(), &mut y_block); + + // Apply column-by-column and compare. + for j in 0..k { + let x_col = eigenvectors + .column(j) + .to_owned() + .insert_axis(ndarray::Axis(1)); + let mut y_col = Array2::::zeros((n, 1)); + op.apply(x_col.view(), &mut y_col); + for i in 0..n { + assert!( + (y_block[[i, j]] - y_col[[i, 0]]).abs() < 1e-14, + "block vs sequential mismatch at row={i} col={j}: \ + block={} seq={}", + y_block[[i, j]], + y_col[[i, 0]] + ); + } + } +} diff --git a/tests/integration/test_pipeline.rs b/tests/integration/test_pipeline.rs index cdb729d..3225d9e 100644 --- a/tests/integration/test_pipeline.rs +++ b/tests/integration/test_pipeline.rs @@ -5,7 +5,6 @@ use spectral_init::{SpectralInitConfig, spectral_init}; use sprs::CsMatI; #[test] -#[ignore = "requires generated .npz fixtures; run: python tests/generate_fixtures.py"] fn spectral_init_output_shape_all_connected_datasets() { let datasets = [ ("blobs_50", 50usize), @@ -35,7 +34,6 @@ fn spectral_init_output_shape_all_connected_datasets() { } #[test] -#[ignore = "requires generated .npz fixtures; run: python tests/generate_fixtures.py"] fn spectral_init_output_close_to_pre_noise_blobs_connected_200() { // spectral_init() returns the post-noise output (scale_and_add_noise is its final step, // adding Gaussian noise with sigma=0.0001 on coordinates scaled to max 10.0). @@ -187,7 +185,6 @@ fn spectral_init_synthetic_disconnected_preserves_component_structure() { // ── fixture-gated tests (require generated .npz files) ─────────────────────── #[test] -#[ignore = "requires generated .npz fixtures; run: python tests/generate_fixtures.py"] fn spectral_init_disconnected_200_shape_and_finite() { let path = common::fixture_path("disconnected_200", "step5a_pruned.npz"); let graph = common::load_sparse_csr_f32_u32(&path); @@ -201,7 +198,6 @@ fn spectral_init_disconnected_200_shape_and_finite() { } #[test] -#[ignore = "requires generated .npz fixtures; run: python tests/generate_fixtures.py"] fn spectral_init_blobs_50_produces_valid_embedding() { // blobs_50 has 3 tight clusters that may be disconnected in the k-NN graph let path = common::fixture_path("blobs_50", "step5a_pruned.npz"); diff --git a/tests/integration/test_scaling_fixtures.rs b/tests/integration/test_scaling_fixtures.rs new file mode 100644 index 0000000..cfec59f --- /dev/null +++ b/tests/integration/test_scaling_fixtures.rs @@ -0,0 +1,134 @@ +#[path = "../common/mod.rs"] +mod common; + +use ndarray::Array2; +use spectral_init::{scale_and_add_noise_pub, scale_coords}; + +fn load_embedding(dataset: &str) -> Array2 { + common::load_dense( + &common::fixture_path(dataset, "comp_e_selection.npz"), + "embedding", + ) +} + +fn load_pre_noise(dataset: &str) -> Array2 { + common::load_dense( + &common::fixture_path(dataset, "comp_f_scaling.npz"), + "pre_noise", + ) +} + +fn check_pre_noise_exact(dataset: &str) { + let embedding = load_embedding(dataset); + let expected_pre_noise = load_pre_noise(dataset); + + let result = scale_coords(&embedding, 10.0).expect("scale_coords failed"); + + // Verify element-wise exact equality + for i in 0..result.nrows() { + for j in 0..result.ncols() { + approx::assert_abs_diff_eq!( + result[[i, j]], + expected_pre_noise[[i, j]], + epsilon = 0.0f32 + ); + } + } + + // Verify max absolute value ≈ 10.0 + let max_abs = result.iter().cloned().map(f32::abs).fold(0.0f32, f32::max); + // Tolerance is 1e-6f32: scale_coords computes expansion = 10.0 / max_abs_f64, + // then casts each element to f32. The maximum element maps to exactly 10.0 + // modulo f32 rounding (~9.5e-7, one ULP at 10.0 = 2^(3-23)); 1e-6 is just + // above that single-ULP bound. + approx::assert_abs_diff_eq!(max_abs, 10.0f32, epsilon = 1e-6f32); +} + +#[test] +fn test_pre_noise_exact_blobs_50() { + check_pre_noise_exact("blobs_50"); +} + +#[test] +fn test_pre_noise_exact_parametrized() { + check_pre_noise_exact("moons_200"); + check_pre_noise_exact("circles_300"); +} + +#[test] +fn test_noise_distribution_blobs_50() { + let embedding = load_embedding("blobs_50"); + let n = embedding.len(); + + let final_result = + scale_and_add_noise_pub(embedding.clone(), 42).expect("scale_and_add_noise failed"); + let pre_noise = scale_coords(&embedding, 10.0).expect("scale_coords failed"); + + let noise: Array2 = &final_result - &pre_noise; + let noise_flat: Vec = noise.iter().cloned().collect(); + + let mean: f32 = noise_flat.iter().sum::() / n as f32; + let variance: f32 = noise_flat.iter().map(|x| (x - mean).powi(2)).sum::() / n as f32; + let std_dev = variance.sqrt(); + + // 3-sigma test for mean ≈ 0 + let three_sigma = 3.0 * 0.0001_f32 / (n as f32).sqrt(); + assert!( + mean.abs() < three_sigma, + "noise mean {mean} exceeds 3-sigma bound {three_sigma}" + ); + + // std within 20% of 0.0001 + let relative_err = (std_dev - 0.0001f32).abs() / 0.0001f32; + assert!( + relative_err < 0.20, + "noise std {std_dev} is not within 20% of 0.0001 (relative error: {relative_err})" + ); +} + +#[test] +fn test_max_abs_is_10() { + for dataset in &["blobs_50", "moons_200", "circles_300"] { + let embedding = load_embedding(dataset); + let pre_noise = scale_coords(&embedding, 10.0).expect("scale_coords failed"); + let max_abs = pre_noise + .iter() + .cloned() + .map(f32::abs) + .fold(0.0f32, f32::max); + + // Tolerance is 1e-6f32: deterministic f64→f32 cast; max element rounds + // to 10.0 with at most ~9.5e-7 (f32 ULP at 10.0 = 2^(3-23)); 1e-6 gives headroom. + approx::assert_abs_diff_eq!(max_abs, 10.0f32, epsilon = 1e-6f32); + } +} + +macro_rules! make_scale_test { + ($name:ident, $dataset:literal) => { + #[test] + fn $name() { + check_pre_noise_exact($dataset); + } + }; +} + +make_scale_test!(scale_pre_noise_matches_blobs_500, "blobs_500"); +make_scale_test!(scale_pre_noise_matches_blobs_5000, "blobs_5000"); +make_scale_test!( + scale_pre_noise_matches_blobs_connected_200, + "blobs_connected_200" +); +make_scale_test!( + scale_pre_noise_matches_blobs_connected_2000, + "blobs_connected_2000" +); +make_scale_test!(scale_pre_noise_matches_near_dupes_100, "near_dupes_100"); + +#[test] +fn scale_max_abs_is_10_disconnected_200() { + let pre_noise = load_pre_noise("disconnected_200"); + assert_eq!(pre_noise.shape(), &[200, 2]); + assert!(pre_noise.iter().all(|v| v.is_finite())); + let max_abs = pre_noise.iter().copied().map(f32::abs).fold(0f32, f32::max); + assert!((max_abs - 10.0f32).abs() < 1e-6, "max_abs={max_abs}"); // f32 ULP at 10.0 ≈ 9.5e-7 +} diff --git a/tests/integration/test_simd_lobpcg_parity.rs b/tests/integration/test_simd_lobpcg_parity.rs index 1171bdc..d8be53d 100644 --- a/tests/integration/test_simd_lobpcg_parity.rs +++ b/tests/integration/test_simd_lobpcg_parity.rs @@ -1,7 +1,7 @@ #[path = "../common/mod.rs"] mod common; -use ndarray::{Array1, Array2}; +use ndarray::Array2; use serde_json::json; use spectral_init::metrics::{ max_eigenpair_residual, sign_agnostic_max_error, subspace_gram_det_kd, @@ -10,11 +10,8 @@ use spectral_init::{ ComputeMode, DEGENERATE_GAP_THRESHOLD, normalize_signs_pub, solve_eigenproblem_pub, }; use sprs::CsMatI; -use std::fs; -const SIMD_PARITY_F32_THRESHOLD: f64 = 4.0 * f32::EPSILON as f64; const SUBSPACE_ANGLE_SENSITIVITY_RAD: f64 = 1e-6; -const SUBSPACE_ANGLE_FAILURE_RAD: f64 = 0.01; const BRIDGE_WEIGHTS: [f64; 7] = [1e-2, 1e-3, 1e-4, 1e-5, 1e-6, 1e-7, 1e-8]; const DISCRETE_WEIGHTS: [f64; 3] = [0.25, 2.5e-4, 2.5e-7]; const SEEDS: [u64; 5] = [42, 123, 777, 1337, 9999]; @@ -64,7 +61,7 @@ fn large_epsilon_bridge_laplacian(cluster_size: usize, bridge_weight: f64) -> Cs // First clique: connect to all other first-clique nodes for j in 0..cs { if j != i { - let w_off = -1.0 * inv_sqrt_deg[i] * inv_sqrt_deg[j]; + let w_off = -inv_sqrt_deg[i] * inv_sqrt_deg[j]; row_entries.push((j, w_off)); } } @@ -77,7 +74,7 @@ fn large_epsilon_bridge_laplacian(cluster_size: usize, bridge_weight: f64) -> Cs // Second clique: connect to all other second-clique nodes for j in cs..n { if j != i { - let w_off = -1.0 * inv_sqrt_deg[i] * inv_sqrt_deg[j]; + let w_off = -inv_sqrt_deg[i] * inv_sqrt_deg[j]; row_entries.push((j, w_off)); } } @@ -97,17 +94,6 @@ fn large_epsilon_bridge_laplacian(cluster_size: usize, bridge_weight: f64) -> Cs CsMatI::new((n, n), indptr, indices, data) } -fn epsilon_bridge_sqrt_deg(cluster_size: usize, bridge_weight: f64) -> Array1 { - let cs = cluster_size; - let n = 2 * cs; - let deg_regular = ((cs - 1) as f64).sqrt(); - let deg_bridge = ((cs - 1) as f64 + bridge_weight).sqrt(); - let mut v = vec![deg_regular; n]; - v[cs - 1] = deg_bridge; - v[cs] = deg_bridge; - Array1::from_vec(v) -} - /// Compute the maximum principal angle between two column subspaces. /// Returns arccos(min singular value of A^T * B) in radians. fn max_subspace_angle(a: &Array2, b: &Array2) -> f64 { diff --git a/tests/integration/test_trustworthiness.rs b/tests/integration/test_trustworthiness.rs index 091ddde..879c513 100644 --- a/tests/integration/test_trustworthiness.rs +++ b/tests/integration/test_trustworthiness.rs @@ -3,7 +3,6 @@ use spectral_init::trustworthiness; /// Sklearn parity: load fixture and assert |rust − sklearn| < 1e-6. /// Requires: python tests/visual_eval/generate_tw_fixture.py #[test] -#[ignore = "requires fixture; run: python tests/visual_eval/generate_tw_fixture.py"] fn sklearn_parity_synthetic() { use ndarray_npy::NpzReader; use std::fs::File; diff --git a/tests/integration/test_warm_restart_benefit.rs b/tests/integration/test_warm_restart_benefit.rs index 852766d..63fb6bd 100644 --- a/tests/integration/test_warm_restart_benefit.rs +++ b/tests/integration/test_warm_restart_benefit.rs @@ -119,7 +119,7 @@ fn epsilon_bridge_laplacian(cluster_size: usize, bridge_weight: f64) -> CsMatI CsMatI Date: Wed, 11 Nov 2026 15:41:25 -0800 Subject: [PATCH 002/113] =?UTF-8?q?Phase=201:=20crate=20boundary=20?= =?UTF-8?q?=E2=80=94=20lean=20library,=20standalone=20tools=20as=20workspa?= =?UTF-8?q?ce=20packages?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Workspace - The root manifest becomes a workspace with two unpublished members: `trustworthiness/` (metric, AVX2 kernels, `trustworthiness` and `tw_profiler` binaries, `cli`/`profiling` features; no dependency on spectral-init) and `eval/` -> `spectral-init-eval` (solver benches, sweeps, exporters, report structs). - The root package drops its binaries, benches, the `testing`, `cli` and `profiling` features and the dependencies only they needed. Library - `src/metrics.rs` is split: solver thresholds and residual checks move to `src/solvers/quality.rs`; diagnostics move to test support; the trustworthiness code and the report structs move to their packages. - All modules are private. A hidden `__internal` feature exposes `spectral_init::__internal` for the crate's own tests and `eval`. - `SolverParams`, `QualityGates`, `SolverLevel` and `SolveReport` replace the SPECTRAL_* environment knobs and the stderr timing lines; `solve_eigenproblem` returns `Result<(EigenResult, SolveReport), _>` and each solver call site logs its report through `log::debug!`. Tests - Integration tests become two auto-discovered binaries: `public_api` (default features) and `internals` (`__internal`). `tests/common` is split into `fixtures.rs`, `internals.rs` and `diagnostics.rs`, shared with `eval` by path-include. - Measurement-style tests move to `eval/tests`; their real assertions (SIMD/scalar parity, warm-restart behaviour) stay with the library in `tests/internals`. Tests that mutated the environment now pass `SolverParams`. - `eval` writes to `temp/eval/` unless RESULTS_DIR is set. Readers - CI workflows, the merge-gate test command, nextest profiles, experiment skills, visual-eval scripts and docs follow the new package, feature and binary names. Add `.github/scripts/check-purity.sh`. `eval` declares rust-version 1.89: its `simd_spmv_exp` bench uses AVX-512 intrinsics that are stable from that release. Co-Authored-By: Claude --- .autoskillit/config.yaml | 5 +- .claude/skills/plan-experiment/SKILL.md | 19 +- .claude/skills/run-experiment/SKILL.md | 13 +- .claude/skills/scope/SKILL.md | 12 +- .config/nextest.toml | 5 - .github/package-allowlist.txt | 4 +- .github/scripts/check-purity.sh | 49 + .github/workflows/slow-tests.yml | 2 +- .github/workflows/test.yml | 14 +- Cargo.lock | 38 +- Cargo.toml | 193 +- README.md | 23 +- docs/user-guide.md | 13 +- eval/Cargo.toml | 38 + {benches => eval/benches}/README.md | 18 +- {benches => eval/benches}/lobpcg_bench.rs | 72 +- {benches => eval/benches}/simd_spmv_exp.rs | 25 +- {benches => eval/benches}/spectral_bench.rs | 20 +- eval/src/lib.rs | 109 ++ .../tests}/export_merfish_init.rs | 68 +- .../tests}/export_rust_init.rs | 8 +- .../tests}/test_exp_rsvd_nbiter_sweep.rs | 43 +- .../tests}/test_exp_rsvd_sweep.rs | 36 +- .../tests}/test_metrics_assess.rs | 134 +- .../tests}/test_rq3_threshold.rs | 48 +- .../tests}/test_simd_lobpcg_parity.rs | 47 +- .../tests}/test_simd_parity.rs | 87 +- .../tests}/test_warm_restart_benefit.rs | 199 +- src/components.rs | 2 +- src/lib.rs | 198 +- src/metrics.rs | 1711 ----------------- src/multi_component.rs | 61 +- src/operator.rs | 67 +- src/scaling.rs | 6 +- src/solvers/dense.rs | 2 +- src/solvers/lobpcg.rs | 2 +- src/solvers/mod.rs | 401 ++-- src/solvers/quality.rs | 145 ++ src/solvers/rsvd.rs | 176 +- src/solvers/sinv.rs | 9 +- tests/common/diagnostics.rs | 313 +++ tests/common/{mod.rs => fixtures.rs} | 205 +- tests/common/internals.rs | 70 + .../accuracy_report.rs} | 106 +- .../adversarial_graphs.rs} | 34 +- .../comp_a_degrees.rs} | 15 +- .../comp_b_laplacian.rs} | 14 +- .../comp_c_components.rs} | 14 +- .../comp_d_dense_evd.rs} | 18 +- .../comp_d_rsvd.rs} | 17 +- .../comp_e_selection.rs} | 16 +- .../comp_f_lobpcg.rs} | 27 +- .../comp_g_sinv.rs} | 18 +- tests/internals/diagnostic_metrics.rs | 238 +++ tests/internals/e2e_residual.rs | 88 + tests/internals/main.rs | 30 + .../operator_fixtures.rs} | 23 +- .../property_tests.proptest-regressions} | 0 .../property_tests.rs} | 57 +- .../psd_contract.rs} | 20 +- .../scaling_fixtures.rs} | 16 +- tests/internals/simd.rs | 64 + .../solver_invariants.rs} | 79 +- tests/internals/warm_restart.rs | 113 ++ .../e2e_validation.rs} | 126 +- tests/public_api/main.rs | 8 + tests/{ => public_api}/npz_loading.rs | 8 +- .../pipeline.rs} | 24 +- tests/visual_eval/README.md | 2 +- .../visual_eval/generate_umap_comparisons.py | 4 +- tests/visual_eval/run_eval.sh | 2 +- tests/visual_eval/run_merfish_eval.sh | 2 +- .../test_generate_umap_comparisons.py | 2 +- trustworthiness/Cargo.toml | 52 + .../benches}/dist_sq_bench.rs | 4 +- .../benches}/trustworthiness_bench.rs | 4 +- .../src}/bin/trustworthiness.rs | 2 +- .../src}/bin/tw_profiler.rs | 4 +- trustworthiness/src/kernels.rs | 146 ++ trustworthiness/src/lib.rs | 789 ++++++++ .../tests}/test_trustworthiness.rs | 15 +- .../tests}/test_tw_profiler.rs | 0 82 files changed, 3552 insertions(+), 3359 deletions(-) create mode 100755 .github/scripts/check-purity.sh create mode 100644 eval/Cargo.toml rename {benches => eval/benches}/README.md (85%) rename {benches => eval/benches}/lobpcg_bench.rs (81%) rename {benches => eval/benches}/simd_spmv_exp.rs (97%) rename {benches => eval/benches}/spectral_bench.rs (92%) create mode 100644 eval/src/lib.rs rename {tests/visual_eval => eval/tests}/export_merfish_init.rs (85%) rename {tests/visual_eval => eval/tests}/export_rust_init.rs (93%) rename {tests/integration => eval/tests}/test_exp_rsvd_nbiter_sweep.rs (82%) rename {tests/integration => eval/tests}/test_exp_rsvd_sweep.rs (67%) rename {tests/integration => eval/tests}/test_metrics_assess.rs (83%) rename {tests/integration => eval/tests}/test_rq3_threshold.rs (77%) rename {tests/integration => eval/tests}/test_simd_lobpcg_parity.rs (89%) rename {tests/integration => eval/tests}/test_simd_parity.rs (73%) rename {tests/integration => eval/tests}/test_warm_restart_benefit.rs (58%) delete mode 100644 src/metrics.rs create mode 100644 src/solvers/quality.rs create mode 100644 tests/common/diagnostics.rs rename tests/common/{mod.rs => fixtures.rs} (83%) create mode 100644 tests/common/internals.rs rename tests/{integration/test_accuracy_report.rs => internals/accuracy_report.rs} (91%) rename tests/{integration/test_adversarial_graphs.rs => internals/adversarial_graphs.rs} (96%) rename tests/{integration/test_comp_a_degrees.rs => internals/comp_a_degrees.rs} (89%) rename tests/{integration/test_comp_b_laplacian.rs => internals/comp_b_laplacian.rs} (86%) rename tests/{integration/test_comp_c_components.rs => internals/comp_c_components.rs} (92%) rename tests/{integration/test_comp_d_dense_evd.rs => internals/comp_d_dense_evd.rs} (79%) rename tests/{integration/test_comp_d_rsvd.rs => internals/comp_d_rsvd.rs} (86%) rename tests/{integration/test_comp_e_selection.rs => internals/comp_e_selection.rs} (85%) rename tests/{integration/test_comp_f_lobpcg.rs => internals/comp_f_lobpcg.rs} (78%) rename tests/{integration/test_comp_g_sinv.rs => internals/comp_g_sinv.rs} (89%) create mode 100644 tests/internals/diagnostic_metrics.rs create mode 100644 tests/internals/e2e_residual.rs create mode 100644 tests/internals/main.rs rename tests/{integration/test_operator_fixtures.rs => internals/operator_fixtures.rs} (68%) rename tests/{integration/test_rq4_property_tests.proptest-regressions => internals/property_tests.proptest-regressions} (100%) rename tests/{integration/test_rq4_property_tests.rs => internals/property_tests.rs} (69%) rename tests/{integration/test_psd_contract_enforced.rs => internals/psd_contract.rs} (68%) rename tests/{integration/test_scaling_fixtures.rs => internals/scaling_fixtures.rs} (91%) create mode 100644 tests/internals/simd.rs rename tests/{integration/test_solver_invariants.rs => internals/solver_invariants.rs} (83%) create mode 100644 tests/internals/warm_restart.rs rename tests/{integration/test_e2e_validation.rs => public_api/e2e_validation.rs} (63%) create mode 100644 tests/public_api/main.rs rename tests/{ => public_api}/npz_loading.rs (72%) rename tests/{integration/test_pipeline.rs => public_api/pipeline.rs} (94%) create mode 100644 trustworthiness/Cargo.toml rename {benches => trustworthiness/benches}/dist_sq_bench.rs (94%) rename {benches => trustworthiness/benches}/trustworthiness_bench.rs (90%) rename {src => trustworthiness/src}/bin/trustworthiness.rs (93%) rename {src => trustworthiness/src}/bin/tw_profiler.rs (96%) create mode 100644 trustworthiness/src/kernels.rs create mode 100644 trustworthiness/src/lib.rs rename {tests/integration => trustworthiness/tests}/test_trustworthiness.rs (83%) rename {tests/integration => trustworthiness/tests}/test_tw_profiler.rs (100%) diff --git a/.autoskillit/config.yaml b/.autoskillit/config.yaml index 806d174..f48fb6f 100644 --- a/.autoskillit/config.yaml +++ b/.autoskillit/config.yaml @@ -13,7 +13,8 @@ test_check: - cargo - nextest - run + - --locked + - --workspace + - --all-features - --profile - ci - - --features - - testing diff --git a/.claude/skills/plan-experiment/SKILL.md b/.claude/skills/plan-experiment/SKILL.md index 84b0930..c0baa76 100644 --- a/.claude/skills/plan-experiment/SKILL.md +++ b/.claude/skills/plan-experiment/SKILL.md @@ -74,15 +74,19 @@ information gaps and produce the best possible experiment plan. **Minimum subagents:** **Subagent A — Measurement Feasibility:** -> Read `src/metrics.rs` to inventory all canonical metric names, quality -> dimensions (Accuracy, Parity, Performance), and threshold constants. -> If `src/metrics.rs` does not exist or is unreadable, treat all dependent -> variables as "NEW" and flag the missing file in your report. +> Read the metric sources to inventory all canonical metric names, quality +> dimensions (Accuracy, Parity, Performance), and threshold constants: +> `src/solvers/quality.rs` (solver residual thresholds and residual checks), +> `tests/common/diagnostics.rs` (accuracy, parity and conditioning metrics), +> `eval/src/` (assessment report structures) and `trustworthiness/src/` (the +> trustworthiness metric). +> If a source does not exist or is unreadable, treat the dependent variables it +> would define as "NEW" and flag the missing file in your report. > Cross-reference against the scope report's Metric Context section if present; > if the scope report lacks a Metric Context section (e.g., scope ran before > this tooling was added), proceed without it and note the gap. > For each dependent variable in the research question: verify it has a -> canonical name in `src/metrics.rs`, or flag it as "NEW" requiring formula, +> canonical name in those sources, or flag it as "NEW" requiring formula, > unit, and threshold definition. Report what measurement infrastructure > already exists vs. what needs to be built. @@ -139,9 +143,10 @@ measurable outcome} | Metric | Unit | Collection Method | Canonical Name | |--------|------|-------------------|----------------| -| {metric1} | {unit} | {how collected} | {name in src/metrics.rs, or "NEW"} | +| {metric1} | {unit} | {how collected} | {name in the metric sources, or "NEW"} | -Canonical names must match entries in `src/metrics.rs`. For any metric marked +Canonical names must match entries in `src/solvers/quality.rs`, +`tests/common/diagnostics.rs` or `trustworthiness/src/`. For any metric marked "NEW", include: formula, unit, threshold value, and a note that it must be added to the catalog before the experiment is finalized. diff --git a/.claude/skills/run-experiment/SKILL.md b/.claude/skills/run-experiment/SKILL.md index a5db8f6..a999d19 100644 --- a/.claude/skills/run-experiment/SKILL.md +++ b/.claude/skills/run-experiment/SKILL.md @@ -125,14 +125,14 @@ the final conclusions.} After collecting experiment-specific results, run the canonical metrics assessment CLI to produce standardized JSON and markdown artifacts: -> **Prerequisite:** If `.npz` fixture files have not been generated yet, run `python tests/generate_fixtures.py` first (matching the `#[ignore]` annotation on fixture-dependent tests). - ```bash cd "$WORKTREE_PATH" -cargo test --features testing --test test_metrics_assess -- assess_accuracy --include-ignored --no-capture +RESULTS_DIR="$WORKTREE_PATH/.autoskillit/temp/run-experiment" \ + cargo test -p spectral-init-eval --test test_metrics_assess -- assess_accuracy --no-capture ``` -This writes two files to `.autoskillit/temp/run-experiment/` (relative to the worktree): +`RESULTS_DIR` must be an absolute path: the test runs with `eval/` as its working +directory. This writes two files to `.autoskillit/temp/run-experiment/` (relative to the worktree): - `accuracy_metrics.json` — machine-readable metrics with per-metric pass/fail status - `accuracy_metrics.md` — human-readable summary table @@ -140,7 +140,8 @@ This writes two files to `.autoskillit/temp/run-experiment/` (relative to the wo scaling behavior, or eigenvector sign normalization), also run: ```bash -cargo test --features testing --test test_metrics_assess -- assess_parity --include-ignored --no-capture +RESULTS_DIR="$WORKTREE_PATH/.autoskillit/temp/run-experiment" \ + cargo test -p spectral-init-eval --test test_metrics_assess -- assess_parity --no-capture ``` This writes: @@ -159,7 +160,7 @@ Accuracy assessment: see `accuracy_metrics.md` {Inline the summary table from the .md file, or note any failed metrics here.} ``` -If `cargo test` fails (e.g., fixtures not generated), note the failure in the +If `cargo test` fails (e.g., a metric misses its threshold), note the failure in the `## Standardized Metrics` section and continue — a metrics CLI failure does not block result collection. diff --git a/.claude/skills/scope/SKILL.md b/.claude/skills/scope/SKILL.md index 73bbade..5f9a47b 100644 --- a/.claude/skills/scope/SKILL.md +++ b/.claude/skills/scope/SKILL.md @@ -85,11 +85,14 @@ additional exploration is necessary for the specific research question. > community discussion of the topic. Report findings with source links. **Subagent D — Metric Context:** -> Read `src/metrics.rs` to identify which quality dimensions (Accuracy, Parity, -> Performance) the research question touches. If `src/metrics.rs` is absent or +> Read the metric sources to identify which quality dimensions (Accuracy, Parity, +> Performance) the research question touches: `src/solvers/quality.rs` (solver +> residual thresholds and residual checks), `tests/common/diagnostics.rs` (accuracy, +> parity and conditioning metrics), `eval/src/` (assessment report structures) and +> `trustworthiness/src/` (the trustworthiness metric). If any of these is absent or > empty, flag it explicitly in the output (do not silently emit an empty section). > Report the current threshold values for relevant metrics and any existing test -> coverage in `tests/integration/test_metrics_assess.rs`. If that test file does +> coverage in `eval/tests/test_metrics_assess.rs`. If that test file does > not exist, note it as missing rather than omitting coverage information. > Output a "Metric Context" section listing which canonical metrics apply to this > research question and their current thresholds. @@ -140,7 +143,8 @@ must contain these sections: {What would constitute a conclusive answer to the research question} ## Metric Context -{Which canonical metrics from src/metrics.rs apply to this research question. +{Which canonical metrics (from `src/solvers/quality.rs`, `tests/common/diagnostics.rs` +and `trustworthiness/src/`) apply to this research question. List each metric name, quality dimension (Accuracy/Parity/Performance), and current threshold value. Note any gaps where no canonical metric exists.} ``` diff --git a/.config/nextest.toml b/.config/nextest.toml index c2c1fd8..d57f1f2 100644 --- a/.config/nextest.toml +++ b/.config/nextest.toml @@ -24,11 +24,6 @@ status-level = "all" final-status-level = "all" default-filter = 'test(comp_d_rsvd_blobs_connected_2000) or test(test_level_3_rsvd_valid_on_large_path)' -[profile.with-fixtures] -retries = 0 -slow-timeout = { period = "120s" } -# Runs ignored tests too (fixture-dependent) - [profile.quiet] retries = 0 slow-timeout = { period = "120s" } diff --git a/.github/package-allowlist.txt b/.github/package-allowlist.txt index 00428cc..f628915 100644 --- a/.github/package-allowlist.txt +++ b/.github/package-allowlist.txt @@ -8,13 +8,10 @@ docs/katex-header.html examples/basic.rs examples/compute_modes.rs examples/from_adjacency_list.rs -src/bin/trustworthiness.rs -src/bin/tw_profiler.rs src/components.rs src/config.rs src/laplacian.rs src/lib.rs -src/metrics.rs src/multi_component.rs src/operator.rs src/scaling.rs @@ -22,5 +19,6 @@ src/selection.rs src/solvers/dense.rs src/solvers/lobpcg.rs src/solvers/mod.rs +src/solvers/quality.rs src/solvers/rsvd.rs src/solvers/sinv.rs diff --git a/.github/scripts/check-purity.sh b/.github/scripts/check-purity.sh new file mode 100755 index 0000000..90d5b87 --- /dev/null +++ b/.github/scripts/check-purity.sh @@ -0,0 +1,49 @@ +#!/usr/bin/env bash +# Purity gate. +# +# The published library stays silent and independent of its environment, and Cargo +# features that belong to other workspace packages stay out of it. +# +# Usage: .github/scripts/check-purity.sh +set -euo pipefail + +repo_root="$(cd "$(dirname "${BASH_SOURCE[0]}")/../.." && pwd)" +cd "$repo_root" + +status=0 + +# forbid ... +# Fails the gate when the pattern occurs in any Rust source under the given paths. +forbid() { + local description="$1" pattern="$2" + shift 2 + local path hits + for path in "$@"; do + if [ ! -e "$path" ]; then + echo "error: ${path} does not exist" >&2 + exit 2 + fi + done + if hits="$(grep -rnE --include='*.rs' -e "$pattern" "$@")"; then + echo "error: ${description}" >&2 + echo "$hits" >&2 + status=1 + fi +} + +forbid "the library must not print or read the environment (src/)" \ + 'println!|eprintln!|dbg!|env::var|SPECTRAL_' \ + src + +forbid "no package has a 'testing' feature" \ + 'feature *= *"testing"' \ + src tests examples eval trustworthiness + +forbid "the 'cli' and 'profiling' features belong to the trustworthiness package" \ + 'feature *= *"(cli|profiling)"' \ + src tests examples + +if [ "$status" -eq 0 ]; then + echo "purity gate passed" +fi +exit "$status" diff --git a/.github/workflows/slow-tests.yml b/.github/workflows/slow-tests.yml index 6e1ebf4..9beb277 100644 --- a/.github/workflows/slow-tests.yml +++ b/.github/workflows/slow-tests.yml @@ -30,4 +30,4 @@ jobs: tool: cargo-nextest - name: Run slow tests - run: cargo nextest run --profile slow --features testing + run: cargo nextest run --locked --workspace --all-features --profile slow diff --git a/.github/workflows/test.yml b/.github/workflows/test.yml index c4b8bf3..3ce4969 100644 --- a/.github/workflows/test.yml +++ b/.github/workflows/test.yml @@ -32,7 +32,7 @@ jobs: tool: cargo-nextest - name: Run tests (CI profile) - run: cargo nextest run --locked --profile ci --features testing + run: cargo nextest run --locked --workspace --all-features --profile ci - name: Upload JUnit XML uses: actions/upload-artifact@v4 @@ -68,8 +68,14 @@ jobs: - name: Check formatting run: cargo fmt --all --check - - name: Clippy - run: cargo clippy --locked --all-targets --all-features -- -D warnings + - name: Clippy (the build users compile) + run: cargo clippy --locked -p spectral-init --all-targets -- -D warnings + + - name: Clippy (workspace, all features) + run: cargo clippy --locked --workspace --all-targets --all-features -- -D warnings + + - name: Purity gate + run: .github/scripts/check-purity.sh docs: name: docs @@ -90,7 +96,7 @@ jobs: RUSTDOCFLAGS: "-D warnings" - name: Run doctests - run: cargo test --locked --doc + run: cargo test --locked --workspace --doc msrv: name: msrv diff --git a/Cargo.lock b/Cargo.lock index 2b07456..67c9640 100644 --- a/Cargo.lock +++ b/Cargo.lock @@ -1727,26 +1727,40 @@ name = "spectral-init" version = "0.1.0" dependencies = [ "approx 0.5.1", - "criterion", "faer", "humantime", - "libc", "linfa-linalg", "log", "ndarray 0.16.1", "ndarray 0.17.2", "ndarray-npy", - "pico-args", "proptest", "rand 0.9.5", "rand_distr", - "rayon", - "serde", "serde_json", "sprs", "thiserror 2.0.21", ] +[[package]] +name = "spectral-init-eval" +version = "0.1.0" +dependencies = [ + "criterion", + "faer", + "humantime", + "linfa-linalg", + "ndarray 0.16.1", + "ndarray 0.17.2", + "ndarray-npy", + "rand 0.9.5", + "rand_distr", + "serde", + "serde_json", + "spectral-init", + "sprs", +] + [[package]] name = "spindle" version = "0.2.6" @@ -1986,6 +2000,20 @@ dependencies = [ "tracing-log", ] +[[package]] +name = "trustworthiness" +version = "0.1.0" +dependencies = [ + "criterion", + "libc", + "ndarray 0.17.2", + "ndarray-npy", + "pico-args", + "rand 0.9.5", + "rayon", + "serde_json", +] + [[package]] name = "ucd-trie" version = "0.1.7" diff --git a/Cargo.toml b/Cargo.toml index 713095d..707b5a1 100644 --- a/Cargo.toml +++ b/Cargo.toml @@ -14,212 +14,51 @@ include = ["/src/**", "/examples/**", "/docs/katex-header.html", "/README.md", " [package.metadata.docs.rs] rustdoc-args = ["--html-in-header", "docs/katex-header.html"] +[workspace] +members = ["trustworthiness", "eval"] + [features] -# Expose internal solver functions for integration tests. -# Not part of the stable public API. -testing = ["dep:serde"] -profiling = [] -# Enable CLI binary (trustworthiness) and .npy I/O support. -cli = ["dep:ndarray-npy", "dep:pico-args", "dep:serde_json", "dep:libc"] +# Exposes `spectral_init::__internal` to this crate's own integration tests and to +# the `eval` research harness. Exempt from semver; not for downstream use. +__internal = [] [dependencies] -serde = { version = "1", features = ["derive"], optional = true } -ndarray-npy = { version = "0.10", optional = true } -pico-args = { version = "0.5", optional = true } sprs = "0.11" ndarray = "0.17" faer = "0.24" rand = "0.9" rand_distr = "0.5" -rayon = "1" thiserror = "2" linfa-linalg = "0.2" # pure-Rust LOBPCG; no LAPACK backend required log = "0.4" # logging facade for library diagnostics ndarray16 = { package = "ndarray", version = "0.16" } # linfa-linalg uses ndarray 0.16; alias for bridging -serde_json = { version = "1", optional = true } -libc = { version = "0.2", optional = true } [dev-dependencies] ndarray-npy = "0.10" approx = "0.5" serde_json = "1" humantime = "2" -criterion = { version = "0.5", features = ["html_reports"] } proptest = "1" [profile.dev.package."*"] opt-level = 2 +[profile.dev.package.trustworthiness] +opt-level = 2 + +[profile.dev.package.spectral-init-eval] +opt-level = 2 + [profile.test.package.spectral-init] opt-level = 2 debug-assertions = true overflow-checks = true -[[test]] -name = "test_comp_e_selection" -path = "tests/integration/test_comp_e_selection.rs" - -[[test]] -name = "test_comp_a_degrees" -path = "tests/integration/test_comp_a_degrees.rs" - -[[test]] -name = "test_comp_b_laplacian" -path = "tests/integration/test_comp_b_laplacian.rs" - -[[test]] -name = "test_comp_c_components" -path = "tests/integration/test_comp_c_components.rs" -required-features = ["testing"] - -[[test]] -name = "test_comp_d_dense_evd" -path = "tests/integration/test_comp_d_dense_evd.rs" - -[[test]] -name = "test_comp_f_lobpcg" -path = "tests/integration/test_comp_f_lobpcg.rs" - -[[test]] -name = "test_comp_d_rsvd" -path = "tests/integration/test_comp_d_rsvd.rs" -required-features = ["testing"] - -[[test]] -name = "test_pipeline" -path = "tests/integration/test_pipeline.rs" - -[[test]] -name = "test_e2e_validation" -path = "tests/integration/test_e2e_validation.rs" - -[[test]] -name = "test_adversarial_graphs" -path = "tests/integration/test_adversarial_graphs.rs" -required-features = ["testing"] - -[[test]] -name = "test_accuracy_report" -path = "tests/integration/test_accuracy_report.rs" -required-features = ["testing"] - -[[test]] -name = "test_comp_g_sinv" -path = "tests/integration/test_comp_g_sinv.rs" -required-features = ["testing"] - -[[test]] -name = "test_warm_restart_benefit" -path = "tests/integration/test_warm_restart_benefit.rs" -required-features = ["testing"] - -[[test]] -name = "test_rq3_threshold" -path = "tests/integration/test_rq3_threshold.rs" -required-features = ["testing"] - -[[test]] -name = "test_rq4_property_tests" -path = "tests/integration/test_rq4_property_tests.rs" -required-features = ["testing"] - -[[test]] -name = "test_exp_rsvd_sweep" -path = "tests/integration/test_exp_rsvd_sweep.rs" -required-features = ["testing"] - -[[test]] -name = "test_exp_rsvd_nbiter_sweep" -path = "tests/integration/test_exp_rsvd_nbiter_sweep.rs" -required-features = ["testing"] - -[[test]] -name = "test_solver_invariants" -path = "tests/integration/test_solver_invariants.rs" -required-features = ["testing"] - -[[test]] -name = "export_rust_init" -path = "tests/visual_eval/export_rust_init.rs" -required-features = ["testing"] - -[[test]] -name = "export_merfish_init" -path = "tests/visual_eval/export_merfish_init.rs" -required-features = ["testing"] - -[[test]] -name = "test_simd_parity" -path = "tests/integration/test_simd_parity.rs" -required-features = ["testing"] - -[[test]] -name = "test_metrics_assess" -path = "tests/integration/test_metrics_assess.rs" -required-features = ["testing"] - -[[test]] -name = "test_psd_contract_enforced" -path = "tests/integration/test_psd_contract_enforced.rs" -required-features = ["testing"] - -[[test]] -name = "test_simd_lobpcg_parity" -path = "tests/integration/test_simd_lobpcg_parity.rs" -required-features = ["testing"] - -[[test]] -name = "test_scaling_fixtures" -path = "tests/integration/test_scaling_fixtures.rs" -required-features = ["testing"] - -[[test]] -name = "test_operator_fixtures" -path = "tests/integration/test_operator_fixtures.rs" - -[[bin]] -name = "trustworthiness" -path = "src/bin/trustworthiness.rs" -required-features = ["cli"] - -[[bin]] -name = "tw_profiler" -path = "src/bin/tw_profiler.rs" -required-features = ["cli"] - -[[test]] -name = "test_trustworthiness" -path = "tests/integration/test_trustworthiness.rs" -required-features = ["testing"] - -[[test]] -name = "test_tw_profiler" -path = "tests/integration/test_tw_profiler.rs" -required-features = ["cli"] - -[[bench]] -name = "spectral_bench" -harness = false -required-features = ["testing"] - -[[bench]] -name = "simd_spmv_exp" -harness = false -required-features = ["testing"] - -[[bench]] -name = "lobpcg_bench" -harness = false -required-features = ["testing"] - -[[bench]] -name = "trustworthiness_bench" -harness = false -required-features = ["testing"] +[profile.test.package.trustworthiness] +opt-level = 2 -[[bench]] -name = "dist_sq_bench" -harness = false +[profile.test.package.spectral-init-eval] +opt-level = 2 [[example]] name = "basic" diff --git a/README.md b/README.md index 23e0514..1fe365f 100644 --- a/README.md +++ b/README.md @@ -102,11 +102,9 @@ See [`examples/compute_modes.rs`](examples/compute_modes.rs) for a side-by-side ## Feature Flags -| Feature | Description | -|---------|-------------| -| `testing` | Exposes internal solver functions for integration tests. **Not stable API.** | -| `cli` | Builds `trustworthiness` and `tw_profiler` binaries for embedding quality assessment. | -| `profiling` | Enables timing instrumentation in the solver escalation chain. | +The crate has no public Cargo features. The `trustworthiness` and `tw_profiler` +embedding-quality tools are a separate workspace package, [`trustworthiness/`](trustworthiness/) +(`cargo build --release -p trustworthiness --features cli`). ## Performance @@ -121,7 +119,7 @@ Benchmarks run on a 2000-node ring graph (4 neighbours per node): > These are pre-optimization baselines on a regular ring graph. Real k-NN graphs > have non-uniform degree distributions; expect 2–4× slower SpMV in practice. -> See [`benches/README.md`](benches/README.md) for methodology and inputs. +> See [`eval/benches/README.md`](eval/benches/README.md) for methodology and inputs. ## Correctness @@ -150,24 +148,19 @@ Install [`cargo-nextest`](https://nexte.st/) if not already present: cargo install cargo-nextest ``` -Run the test suite (synthetic tests only — no fixture generation required): +Run the whole workspace (the reference fixtures are committed; no generation step is needed): ```sh -cargo nextest run --features testing +cargo nextest run --workspace --all-features ``` Run with CI profile: ```sh -cargo nextest run --profile ci --features testing +cargo nextest run --workspace --all-features --profile ci ``` -Run fixture-dependent tests (requires Python fixture generation first): - -```sh -python tests/generate_fixtures.py -cargo nextest run --profile with-fixtures --run-ignored all --features testing -``` +`cargo test` on its own runs only the published crate's default-feature tests. ## License diff --git a/docs/user-guide.md b/docs/user-guide.md index d9e1b50..33989b4 100644 --- a/docs/user-guide.md +++ b/docs/user-guide.md @@ -58,13 +58,7 @@ sprs = "0.11" ### Feature Flags -| Flag | Purpose | -|------|---------| -| `testing` | Exposes internal solver functions. **Not stable API.** Only for integration testing. | -| `cli` | Builds the `trustworthiness` and `tw_profiler` quality-assessment binaries. | -| `profiling` | Enables timing instrumentation in the solver escalation chain. | - -Normal users only need the default features (none enabled). +The crate has no public Cargo features. --- @@ -428,7 +422,4 @@ This is especially effective when `ComputeMode::RustNative` is selected. The eigensolver escalates through up to six levels automatically; you do not need to tune it. For graphs with `n < 2 000`, dense EVD is used directly (fast and exact). -For larger graphs, LOBPCG iterative solvers are used. The dense EVD threshold can be -overridden via the `SPECTRAL_DENSE_N_THRESHOLD` environment variable, but this is -only available in test builds (`--features testing`) and is intended for integration -tests — not for production or general benchmarking use. +For larger graphs, LOBPCG iterative solvers are used. diff --git a/eval/Cargo.toml b/eval/Cargo.toml new file mode 100644 index 0000000..764a361 --- /dev/null +++ b/eval/Cargo.toml @@ -0,0 +1,38 @@ +[package] +name = "spectral-init-eval" +version = "0.1.0" +edition = "2024" +description = "Research harness for spectral-init: solver benchmarks, sweeps and exporters" +license = "MIT" +repository = "https://github.com/TalonT-Org/spectral-init" +# One release above the library's MSRV: `simd_spmv_exp` benchmarks an AVX-512 kernel +# whose intrinsics are stable from Rust 1.89. +rust-version = "1.89" +publish = false + +[dependencies] +spectral-init = { path = "..", features = ["__internal"] } +ndarray = "0.17" +sprs = "0.11" +faer = "0.24" +rand = "0.9" +rand_distr = "0.5" +serde = { version = "1", features = ["derive"] } +serde_json = "1" +ndarray-npy = "0.10" +criterion = { version = "0.5", features = ["html_reports"] } +humantime = "2" +linfa-linalg = "0.2" +ndarray16 = { package = "ndarray", version = "0.16" } + +[[bench]] +name = "spectral_bench" +harness = false + +[[bench]] +name = "lobpcg_bench" +harness = false + +[[bench]] +name = "simd_spmv_exp" +harness = false diff --git a/benches/README.md b/eval/benches/README.md similarity index 85% rename from benches/README.md rename to eval/benches/README.md index bc36e44..a46b49d 100644 --- a/benches/README.md +++ b/eval/benches/README.md @@ -6,7 +6,7 @@ Use them to measure improvement after optimizations land. ## Running ```sh -cargo bench --features testing +cargo bench -p spectral-init-eval ``` HTML reports are written to `target/criterion/`. @@ -24,9 +24,9 @@ HTML reports are written to `target/criterion/`. | `components_bfs_2000` | 2000-node ring graph | BFS connected components | 7.24 µs | | `full_pipeline/200` | 200-node ring graph | End-to-end spectral_init | 14.2 ms | | `full_pipeline/2000` | 2000-node ring graph | End-to-end at medium scale | 223 ms | -| `lobpcg_blobs5000/solve_eigenproblem` | 5,000-node blobs Laplacian | `solve_eigenproblem_pub()` full escalation chain | (TBD) | -| `lobpcg_merfish_10k/solve_eigenproblem` | MERFISH 10K Laplacian | `solve_eigenproblem_pub()` full escalation chain | (optional fixture) | -| `lobpcg_merfish_100k/solve_eigenproblem` | MERFISH 100K Laplacian | `solve_eigenproblem_pub()` full escalation chain | (optional fixture) | +| `lobpcg_blobs5000/solve_eigenproblem` | 5,000-node blobs Laplacian | `solve_eigenproblem()` full escalation chain | (TBD) | +| `lobpcg_merfish_10k/solve_eigenproblem` | MERFISH 10K Laplacian | `solve_eigenproblem()` full escalation chain | (optional fixture) | +| `lobpcg_merfish_100k/solve_eigenproblem` | MERFISH 100K Laplacian | `solve_eigenproblem()` full escalation chain | (optional fixture) | ## Input Graphs @@ -45,19 +45,19 @@ All benchmarks use deterministic synthetic ring graphs (`make_ring_graph(n, 2)`) ## LOBPCG Microbenchmark -`lobpcg_bench` provides algorithm-level timing for `solve_eigenproblem_pub()`, +`lobpcg_bench` provides algorithm-level timing for `solve_eigenproblem()`, bypassing the `cargo nextest` process-spawn overhead that dominated the 100K MERFISH wall-time measurement in the H4 benchmark (PR #216). ### Run (mandatory fixture only) ```sh -cargo bench --bench lobpcg_bench --features testing +cargo bench -p spectral-init-eval --bench lobpcg_bench ``` ### Run (with optional large fixtures) -Generate the Laplacian NPZ files first (see `benches/lobpcg_bench.rs` doc +Generate the Laplacian NPZ files first (see `eval/benches/lobpcg_bench.rs` doc comment for the Python export snippet), then: ```sh @@ -68,12 +68,12 @@ import scipy.sparse as sp sp.save_npz("temp/lobpcg_bench/merfish_10k_laplacian.npz", lap) EOF -cargo bench --bench lobpcg_bench --features testing +cargo bench -p spectral-init-eval --bench lobpcg_bench ``` ### Comparing with Python eigsh -The `solve_eigenproblem_pub()` timing from this benchmark is directly comparable +The `solve_eigenproblem()` timing from this benchmark is directly comparable to the Python `eigsh()` call timing reported in the MERFISH benchmark reports under `research/`. Both measure only the iterative eigensolver, not graph construction or process startup. diff --git a/benches/lobpcg_bench.rs b/eval/benches/lobpcg_bench.rs similarity index 81% rename from benches/lobpcg_bench.rs rename to eval/benches/lobpcg_bench.rs index 4462b8c..2cd9ded 100644 --- a/benches/lobpcg_bench.rs +++ b/eval/benches/lobpcg_bench.rs @@ -1,12 +1,12 @@ //! LOBPCG eigensolver microbenchmark — Criterion harness. //! -//! Benchmarks `solve_eigenproblem_pub()` on pre-loaded CSR Laplacians, bypassing +//! Benchmarks `solve_eigenproblem()` on pre-loaded CSR Laplacians, bypassing //! `cargo nextest` overhead (process spawn ~50 s measured on the 100K MERFISH run). //! This produces valid algorithm-level timing comparable to Python `eigsh`. //! //! # Run //! ```sh -//! cargo bench --bench lobpcg_bench --features testing +//! cargo bench -p spectral-init-eval --bench lobpcg_bench //! ``` //! //! HTML reports are written to `target/criterion/`. @@ -25,9 +25,15 @@ //! If absent, those groups emit `[lobpcg_bench] SKIP ...` to stderr and return //! immediately; the run still exits 0. +#[path = "../../tests/common/internals.rs"] +mod internals; + use criterion::{Criterion, criterion_group, criterion_main}; +use internals::solve_with_unit_hint; use ndarray_npy::{NpzReader, ReadNpyError, ReadNpzError}; -use spectral_init::{ComputeMode, solve_eigenproblem_pub}; +use spectral_init::__internal::SolverParams; +use spectral_init::ComputeMode; +use spectral_init_eval::WORKSPACE_ROOT; use std::hint::black_box; use std::path::Path; use std::time::Duration; @@ -107,24 +113,29 @@ fn load_laplacian(path: &Path) -> Option> { // ─── blobs_5000 — 5,000 nodes, mandatory ───────────────────────────────────── fn bench_lobpcg_blobs5000(c: &mut Criterion) { - let path = Path::new(env!("CARGO_MANIFEST_DIR")) - .join("tests/fixtures/blobs_5000/comp_b_laplacian.npz"); + let path = Path::new(WORKSPACE_ROOT).join("tests/fixtures/blobs_5000/comp_b_laplacian.npz"); let laplacian = load_laplacian(&path) .unwrap_or_else(|| panic!("mandatory fixture not found: {}", path.display())); let n = laplacian.rows(); let seed = 42_u64; + let params = SolverParams::default(); - // One call outside the timed loop: primes instruction caches and surfaces - // the solver level via the --features testing timing lines on stderr. - let _ = solve_eigenproblem_pub( + // One call outside the timed loop: primes instruction caches and reports + // which solver level the chain settles on. + let (_, report) = solve_with_unit_hint( black_box(&laplacian), black_box(2), black_box(seed), ComputeMode::RustNative, + ¶ms, + ); + eprintln!( + "[lobpcg_bench] blobs_5000 ready: n={n}, solver level {} ({})", + report.level as u8, + report.level.name() ); - eprintln!("[lobpcg_bench] blobs_5000 ready: n={n}"); let mut group = c.benchmark_group("lobpcg_blobs5000"); group.sample_size(10); // Criterion minimum; solver takes ~300 ms @@ -133,11 +144,12 @@ fn bench_lobpcg_blobs5000(c: &mut Criterion) { group.bench_function("solve_eigenproblem", |b| { b.iter(|| { - black_box(solve_eigenproblem_pub( + black_box(solve_with_unit_hint( black_box(&laplacian), black_box(2), black_box(seed), ComputeMode::RustNative, + ¶ms, )) }); }); @@ -147,8 +159,7 @@ fn bench_lobpcg_blobs5000(c: &mut Criterion) { // ─── merfish_10k — 10,000 nodes, optional ──────────────────────────────────── fn bench_lobpcg_merfish_10k(c: &mut Criterion) { - let path = - Path::new(env!("CARGO_MANIFEST_DIR")).join("temp/lobpcg_bench/merfish_10k_laplacian.npz"); + let path = Path::new(WORKSPACE_ROOT).join("temp/lobpcg_bench/merfish_10k_laplacian.npz"); let Some(laplacian) = load_laplacian(&path) else { eprintln!( @@ -160,16 +171,22 @@ fn bench_lobpcg_merfish_10k(c: &mut Criterion) { let n = laplacian.rows(); let seed = 42_u64; + let params = SolverParams::default(); - // One call outside the timed loop: primes instruction caches and surfaces - // the solver level via the --features testing timing lines on stderr. - let _ = solve_eigenproblem_pub( + // One call outside the timed loop: primes instruction caches and reports + // which solver level the chain settles on. + let (_, report) = solve_with_unit_hint( black_box(&laplacian), black_box(2), black_box(seed), ComputeMode::RustNative, + ¶ms, + ); + eprintln!( + "[lobpcg_bench] merfish_10k ready: n={n}, solver level {} ({})", + report.level as u8, + report.level.name() ); - eprintln!("[lobpcg_bench] merfish_10k ready: n={n}"); let mut group = c.benchmark_group("lobpcg_merfish_10k"); group.sample_size(10); @@ -178,11 +195,12 @@ fn bench_lobpcg_merfish_10k(c: &mut Criterion) { group.bench_function("solve_eigenproblem", |b| { b.iter(|| { - black_box(solve_eigenproblem_pub( + black_box(solve_with_unit_hint( black_box(&laplacian), black_box(2), black_box(seed), ComputeMode::RustNative, + ¶ms, )) }); }); @@ -192,8 +210,7 @@ fn bench_lobpcg_merfish_10k(c: &mut Criterion) { // ─── merfish_100k — 100,000 nodes, optional ────────────────────────────────── fn bench_lobpcg_merfish_100k(c: &mut Criterion) { - let path = - Path::new(env!("CARGO_MANIFEST_DIR")).join("temp/lobpcg_bench/merfish_100k_laplacian.npz"); + let path = Path::new(WORKSPACE_ROOT).join("temp/lobpcg_bench/merfish_100k_laplacian.npz"); let Some(laplacian) = load_laplacian(&path) else { eprintln!( @@ -205,16 +222,22 @@ fn bench_lobpcg_merfish_100k(c: &mut Criterion) { let n = laplacian.rows(); let seed = 42_u64; + let params = SolverParams::default(); - // One call outside the timed loop: primes instruction caches and surfaces - // the solver level via the --features testing timing lines on stderr. - let _ = solve_eigenproblem_pub( + // One call outside the timed loop: primes instruction caches and reports + // which solver level the chain settles on. + let (_, report) = solve_with_unit_hint( black_box(&laplacian), black_box(2), black_box(seed), ComputeMode::RustNative, + ¶ms, + ); + eprintln!( + "[lobpcg_bench] merfish_100k ready: n={n}, solver level {} ({})", + report.level as u8, + report.level.name() ); - eprintln!("[lobpcg_bench] merfish_100k ready: n={n}"); let mut group = c.benchmark_group("lobpcg_merfish_100k"); group.sample_size(10); @@ -224,11 +247,12 @@ fn bench_lobpcg_merfish_100k(c: &mut Criterion) { group.bench_function("solve_eigenproblem", |b| { b.iter(|| { - black_box(solve_eigenproblem_pub( + black_box(solve_with_unit_hint( black_box(&laplacian), black_box(2), black_box(seed), ComputeMode::RustNative, + ¶ms, )) }); }); diff --git a/benches/simd_spmv_exp.rs b/eval/benches/simd_spmv_exp.rs similarity index 97% rename from benches/simd_spmv_exp.rs rename to eval/benches/simd_spmv_exp.rs index 9a89b6f..8d3d663 100644 --- a/benches/simd_spmv_exp.rs +++ b/eval/benches/simd_spmv_exp.rs @@ -1,11 +1,16 @@ //! SIMD SpMV ISA baseline — Criterion benchmark harness (groupB: CSR scaling, groupC: SELL-C-σ). //! -//! Run with: cargo bench --features testing --bench simd_spmv_exp +//! Run with: cargo bench -p spectral-init-eval --bench simd_spmv_exp + +#[path = "../../tests/common/internals.rs"] +mod internals; use criterion::{BenchmarkId, Criterion, criterion_group, criterion_main}; +use internals::solve_with_unit_hint; use ndarray_npy::NpzReader; -use spectral_init::operator::spmv_csr; -use spectral_init::{ComputeMode, solve_eigenproblem_pub}; +use spectral_init::__internal::{SolverParams, spmv_csr}; +use spectral_init::ComputeMode; +use spectral_init_eval::WORKSPACE_ROOT; use std::hint::black_box; // ─── Ring Laplacian builder ─────────────────────────────────────────────────── @@ -222,9 +227,6 @@ fn spmv_avx2_dispatch(indptr: &[usize], indices: &[usize], data: &[f64], x: &[f6 // ─── AVX-512 gather kernel ─────────────────────────────────────────────────── -// The AVX-512 intrinsics are stable from Rust 1.89, one release above the package MSRV; -// this experimental kernel exists only in this benchmark. -#[allow(clippy::incompatible_msrv)] #[cfg(any(target_arch = "x86", target_arch = "x86_64"))] #[target_feature(enable = "avx512f")] unsafe fn spmv_avx512_gather( @@ -494,8 +496,8 @@ fn bench_spmv_avx2(c: &mut Criterion) { // ─── blobs_5000 fixture loader ───────────────────────────────────────────────── fn load_blobs5000_laplacian() -> sprs::CsMatI { - let path = std::path::Path::new(env!("CARGO_MANIFEST_DIR")) - .join("tests/fixtures/blobs_5000/comp_b_laplacian.npz"); + let path = + std::path::Path::new(WORKSPACE_ROOT).join("tests/fixtures/blobs_5000/comp_b_laplacian.npz"); let file = std::fs::File::open(&path) .unwrap_or_else(|e| panic!("cannot open blobs_5000 fixture {:?}: {}", path, e)); let mut npz = NpzReader::new(file).expect("NpzReader failed on blobs_5000"); @@ -534,24 +536,27 @@ fn load_blobs5000_laplacian() -> sprs::CsMatI { fn bench_pipeline_blobs5000(c: &mut Criterion) { let laplacian = load_blobs5000_laplacian(); let seed = 42_u64; + let params = SolverParams::default(); // Warm-up: one call outside iter to prime instruction caches and BLAS state. - let _ = solve_eigenproblem_pub( + let _ = solve_with_unit_hint( black_box(&laplacian), black_box(2), black_box(seed), ComputeMode::RustNative, + ¶ms, ); let mut group = c.benchmark_group("pipeline_blobs5000"); group.sample_size(10); // Criterion minimum; eigenproblem is slow so we keep it at the floor group.bench_function("blobs5000_solver", |b| { b.iter(|| { - solve_eigenproblem_pub( + solve_with_unit_hint( black_box(&laplacian), black_box(2), black_box(seed), ComputeMode::RustNative, + ¶ms, ) }); }); diff --git a/benches/spectral_bench.rs b/eval/benches/spectral_bench.rs similarity index 92% rename from benches/spectral_bench.rs rename to eval/benches/spectral_bench.rs index 5c6fab8..092c724 100644 --- a/benches/spectral_bench.rs +++ b/eval/benches/spectral_bench.rs @@ -1,16 +1,16 @@ //! Criterion benchmark baselines for spectral-init pipeline components. //! -//! Run with: cargo bench --features testing +//! Run with: cargo bench -p spectral-init-eval --bench spectral_bench //! //! Inputs: deterministic synthetic ring graphs — no fixture files required. //! Each benchmark uses `black_box` to prevent dead-code elimination. use criterion::{BenchmarkId, Criterion, criterion_group, criterion_main}; -use spectral_init::operator::{CsrOperator, spmv_csr}; -use spectral_init::{ - ComputeMode, SpectralInitConfig, build_normalized_laplacian, compute_degrees, dense_evd, - find_components, lobpcg_solve, rsvd_solve, spectral_init, +use spectral_init::__internal::{ + CsrOperator, SolverParams, build_normalized_laplacian, compute_degrees, dense_evd, + find_components, lobpcg_solve, rsvd_solve, spmv_csr, }; +use spectral_init::{ComputeMode, SpectralInitConfig, spectral_init}; use std::hint::black_box; // ─── Synthetic Graph Helpers ────────────────────────────────────────────────── @@ -119,8 +119,16 @@ fn bench_lobpcg(c: &mut Criterion) { /// Randomized SVD: 2I-L trick solver. Production Level 3. fn bench_rsvd(c: &mut Criterion) { let lap = make_laplacian(2000, 2); + let params = SolverParams::default(); c.bench_function("rsvd_2000", |b| { - b.iter(|| black_box(rsvd_solve(black_box(&lap), black_box(3), black_box(42_u64)))) + b.iter(|| { + black_box(rsvd_solve( + black_box(&lap), + black_box(3), + black_box(42_u64), + black_box(¶ms), + )) + }) }); } diff --git a/eval/src/lib.rs b/eval/src/lib.rs new file mode 100644 index 0000000..185d040 --- /dev/null +++ b/eval/src/lib.rs @@ -0,0 +1,109 @@ +//! Research harness for `spectral-init`. +//! +//! Holds the report structures shared by the assessment tests in `tests/` and by +//! the tooling that reads their JSON output, and the locations the harness reads +//! from and writes to. + +use serde::{Deserialize, Serialize}; +use std::path::{Path, PathBuf}; + +/// Root of the workspace this package belongs to. Reference fixtures and the +/// visual-evaluation data live under it. +pub const WORKSPACE_ROOT: &str = concat!(env!("CARGO_MANIFEST_DIR"), "/.."); + +/// Directory the harness writes its results to: `$RESULTS_DIR` when that variable is +/// set, otherwise `temp/eval/` under the workspace root. +pub fn results_dir() -> PathBuf { + match std::env::var_os("RESULTS_DIR") { + Some(dir) => PathBuf::from(dir), + None => Path::new(WORKSPACE_ROOT).join("temp").join("eval"), + } +} + +/// One measured quantity with the threshold it was judged against. +#[derive(Debug, Clone, Serialize, Deserialize)] +pub struct MetricResult { + pub name: String, + pub dimension: usize, + pub value: f64, + pub threshold: f64, + pub passed: bool, +} + +/// All metrics measured on one dataset. +#[derive(Debug, Clone, Serialize, Deserialize)] +pub struct AssessmentReport { + pub dataset: String, + pub n: usize, + pub metrics: Vec, +} + +/// One assessment run across datasets. +#[derive(Debug, Clone, Serialize, Deserialize)] +pub struct ExperimentMetrics { + pub generated_at: String, + pub datasets: Vec, +} + +#[cfg(test)] +mod tests { + use super::*; + + #[test] + fn t_serde_01_round_trip_metric_result() { + let m = MetricResult { + name: "test_metric".to_string(), + dimension: 2, + value: 0.001, + threshold: 0.01, + passed: true, + }; + let json = serde_json::to_string(&m).expect("serialize MetricResult"); + let m2: MetricResult = serde_json::from_str(&json).expect("deserialize MetricResult"); + assert_eq!(m2.name, m.name); + assert_eq!(m2.dimension, m.dimension); + assert_eq!(m2.value, m.value); + assert_eq!(m2.threshold, m.threshold); + assert_eq!(m2.passed, m.passed); + } + + #[test] + fn t_serde_02_round_trip_assessment_report() { + let r = AssessmentReport { + dataset: "test_dataset".to_string(), + n: 100, + metrics: vec![MetricResult { + name: "residual".to_string(), + dimension: 2, + value: 1e-7, + threshold: 1e-6, + passed: true, + }], + }; + let json = serde_json::to_string(&r).expect("serialize AssessmentReport"); + let r2: AssessmentReport = + serde_json::from_str(&json).expect("deserialize AssessmentReport"); + assert_eq!(r2.dataset, r.dataset); + assert_eq!(r2.n, r.n); + assert_eq!(r2.metrics.len(), 1); + assert_eq!(r2.metrics[0].name, "residual"); + } + + #[test] + fn t_serde_03_round_trip_experiment_metrics() { + let e = ExperimentMetrics { + generated_at: "2026-01-01T00:00:00Z".to_string(), + datasets: vec![AssessmentReport { + dataset: "iris".to_string(), + n: 150, + metrics: vec![], + }], + }; + let json = serde_json::to_string(&e).expect("serialize ExperimentMetrics"); + let e2: ExperimentMetrics = + serde_json::from_str(&json).expect("deserialize ExperimentMetrics"); + assert_eq!(e2.generated_at, e.generated_at); + assert_eq!(e2.datasets.len(), 1); + assert_eq!(e2.datasets[0].dataset, "iris"); + } +} diff --git a/tests/visual_eval/export_merfish_init.rs b/eval/tests/export_merfish_init.rs similarity index 85% rename from tests/visual_eval/export_merfish_init.rs rename to eval/tests/export_merfish_init.rs index d0cfc89..da5804e 100644 --- a/tests/visual_eval/export_merfish_init.rs +++ b/eval/tests/export_merfish_init.rs @@ -1,19 +1,21 @@ -#[path = "../common/mod.rs"] -mod common; +#[path = "../../tests/common/fixtures.rs"] +mod fixtures; +#[path = "../../tests/common/internals.rs"] +mod internals; -use common::load_sparse_csr_f32_u32; +use fixtures::load_sparse_csr_f32_u32; +use internals::solve_with_unit_hint; use ndarray_npy::write_npy; -use spectral_init::{ - ComputeMode, build_normalized_laplacian, compute_degrees, solve_eigenproblem_pub, -}; -use spectral_init::{SpectralInitConfig, spectral_init}; +use spectral_init::__internal::{SolverParams, build_normalized_laplacian, compute_degrees}; +use spectral_init::{ComputeMode, SpectralInitConfig, spectral_init}; +use spectral_init_eval::WORKSPACE_ROOT; use std::path::Path; use std::time::Instant; #[test] #[ignore = "requires MERFISH 10K subset data"] fn export_merfish_init_10k() { - let output_dir = Path::new(env!("CARGO_MANIFEST_DIR")).join("tests/visual_eval/output"); + let output_dir = Path::new(WORKSPACE_ROOT).join("tests/visual_eval/output"); if !output_dir.exists() { panic!( @@ -37,7 +39,7 @@ fn export_merfish_init_10k() { println!("====================================="); println!("Graph: {} nodes", n); - // Emit solver level via the testing seam so the Python sweep harness can parse it. + // Emit solver level via the internal seam so the Python sweep harness can parse it. // Builds the Laplacian independently of spectral_init(); the actual embedding below // still uses spectral_init() as the authoritative pipeline path. let (_degrees, sqrt_deg) = compute_degrees(&graph, ComputeMode::PythonCompat); @@ -46,8 +48,14 @@ fn export_merfish_init_10k() { .map(|&s| if s > 0.0 { 1.0 / s } else { 0.0 }) .collect(); let lap = build_normalized_laplacian(&graph, &inv_sqrt_deg); - let (_, solver_level) = solve_eigenproblem_pub(&lap, 2, 42, ComputeMode::PythonCompat); - println!("SOLVER_LEVEL={}", solver_level); + let (_, report) = solve_with_unit_hint( + &lap, + 2, + 42, + ComputeMode::PythonCompat, + &SolverParams::default(), + ); + println!("SOLVER_LEVEL={}", report.level as u8); let start = Instant::now(); let coords = spectral_init(&graph, 2, 42, None, SpectralInitConfig::default()) @@ -84,7 +92,7 @@ fn export_merfish_init_10k() { #[test] #[ignore = "requires MERFISH 20K subset data in temp/merfish_20k/"] fn export_merfish_init_20k() { - let output_dir = Path::new(env!("CARGO_MANIFEST_DIR")).join("temp/merfish_20k/output"); + let output_dir = Path::new(WORKSPACE_ROOT).join("temp/merfish_20k/output"); if !output_dir.exists() { panic!( @@ -114,8 +122,14 @@ fn export_merfish_init_20k() { .map(|&s| if s > 0.0 { 1.0 / s } else { 0.0 }) .collect(); let lap = build_normalized_laplacian(&graph, &inv_sqrt_deg); - let (_, solver_level) = solve_eigenproblem_pub(&lap, 2, 42, ComputeMode::PythonCompat); - println!("SOLVER_LEVEL={}", solver_level); + let (_, report) = solve_with_unit_hint( + &lap, + 2, + 42, + ComputeMode::PythonCompat, + &SolverParams::default(), + ); + println!("SOLVER_LEVEL={}", report.level as u8); let start = Instant::now(); let coords = spectral_init(&graph, 2, 42, None, SpectralInitConfig::default()) @@ -172,7 +186,7 @@ fn export_merfish_init_20k() { #[test] #[ignore = "requires MERFISH 100K subset data"] fn export_merfish_init_100k() { - let output_dir = Path::new(env!("CARGO_MANIFEST_DIR")).join("tests/visual_eval/output"); + let output_dir = Path::new(WORKSPACE_ROOT).join("tests/visual_eval/output"); if !output_dir.exists() { panic!( @@ -196,7 +210,7 @@ fn export_merfish_init_100k() { println!("======================================"); println!("Graph: {} nodes", n); - // Emit solver level via the testing seam so the Python sweep harness can parse it. + // Emit solver level via the internal seam so the Python sweep harness can parse it. // Builds the Laplacian independently of spectral_init(); the actual embedding below // still uses spectral_init() as the authoritative pipeline path. let (_degrees, sqrt_deg) = compute_degrees(&graph, ComputeMode::PythonCompat); @@ -205,8 +219,14 @@ fn export_merfish_init_100k() { .map(|&s| if s > 0.0 { 1.0 / s } else { 0.0 }) .collect(); let lap = build_normalized_laplacian(&graph, &inv_sqrt_deg); - let (_, solver_level) = solve_eigenproblem_pub(&lap, 2, 42, ComputeMode::PythonCompat); - println!("SOLVER_LEVEL={}", solver_level); + let (_, report) = solve_with_unit_hint( + &lap, + 2, + 42, + ComputeMode::PythonCompat, + &SolverParams::default(), + ); + println!("SOLVER_LEVEL={}", report.level as u8); let start = Instant::now(); let coords = spectral_init(&graph, 2, 42, None, SpectralInitConfig::default()) @@ -261,7 +281,7 @@ fn export_merfish_init_100k() { #[test] #[ignore = "requires MERFISH 250K subset data"] fn export_merfish_init_250k() { - let output_dir = Path::new(env!("CARGO_MANIFEST_DIR")).join("tests/visual_eval/output"); + let output_dir = Path::new(WORKSPACE_ROOT).join("tests/visual_eval/output"); if !output_dir.exists() { panic!( @@ -291,8 +311,14 @@ fn export_merfish_init_250k() { .map(|&s| if s > 0.0 { 1.0 / s } else { 0.0 }) .collect(); let lap = build_normalized_laplacian(&graph, &inv_sqrt_deg); - let (_, solver_level) = solve_eigenproblem_pub(&lap, 2, 42, ComputeMode::PythonCompat); - println!("SOLVER_LEVEL={}", solver_level); + let (_, report) = solve_with_unit_hint( + &lap, + 2, + 42, + ComputeMode::PythonCompat, + &SolverParams::default(), + ); + println!("SOLVER_LEVEL={}", report.level as u8); let start = Instant::now(); let coords = spectral_init(&graph, 2, 42, None, SpectralInitConfig::default()) diff --git a/tests/visual_eval/export_rust_init.rs b/eval/tests/export_rust_init.rs similarity index 93% rename from tests/visual_eval/export_rust_init.rs rename to eval/tests/export_rust_init.rs index b82fbf0..68e3bc3 100644 --- a/tests/visual_eval/export_rust_init.rs +++ b/eval/tests/export_rust_init.rs @@ -1,7 +1,7 @@ -#[path = "../common/mod.rs"] -mod common; +#[path = "../../tests/common/fixtures.rs"] +mod fixtures; -use common::load_sparse_csr_f32_u32; +use fixtures::load_sparse_csr_f32_u32; use ndarray_npy::write_npy; use spectral_init::{SpectralInitConfig, spectral_init}; use std::path::Path; @@ -10,7 +10,7 @@ use std::time::Instant; #[test] #[ignore = "requires Phase 1 visual eval data"] fn export_all_rust_inits() { - let output_dir = Path::new(env!("CARGO_MANIFEST_DIR")).join("tests/visual_eval/output"); + let output_dir = Path::new(spectral_init_eval::WORKSPACE_ROOT).join("tests/visual_eval/output"); if !output_dir.exists() { panic!( diff --git a/tests/integration/test_exp_rsvd_nbiter_sweep.rs b/eval/tests/test_exp_rsvd_nbiter_sweep.rs similarity index 82% rename from tests/integration/test_exp_rsvd_nbiter_sweep.rs rename to eval/tests/test_exp_rsvd_nbiter_sweep.rs index 8aa275c..d738e2a 100644 --- a/tests/integration/test_exp_rsvd_nbiter_sweep.rs +++ b/eval/tests/test_exp_rsvd_nbiter_sweep.rs @@ -12,16 +12,19 @@ //! the direction_b grid; reference is rsvd_solve_accurate at nbiter=10, p=100. //! Emits `QUALITY_ROW_C,{fixture},{method},{nbiter},{p},{gram_det},{sign_error}`. //! -//! Run with --test-threads=1 for reproducible wall-time measurements and safe env-var -//! manipulation in the 2il dispatch path. +//! Run with --test-threads=1 for reproducible wall-time measurements. -#[path = "../common/mod.rs"] -mod common; +#[path = "../../tests/common/diagnostics.rs"] +mod diagnostics; +#[path = "../../tests/common/fixtures.rs"] +mod fixtures; +use diagnostics::{ + orthogonality_error, sign_agnostic_max_error, spectral_gap, subspace_gram_det_kd, +}; use ndarray::s; -use spectral_init::metrics::{ - RSVD_QUALITY_THRESHOLD, max_eigenpair_residual, orthogonality_error, sign_agnostic_max_error, - spectral_gap, subspace_gram_det_kd, +use spectral_init::__internal::{ + RSVD_QUALITY_THRESHOLD, SolverParams, max_eigenpair_residual, rsvd_solve, rsvd_solve_accurate, }; const SEED: u64 = 42; @@ -31,9 +34,10 @@ const NBITER_B: &[usize] = &[2, 3, 4, 5, 6, 8, 10]; const P_B: &[usize] = &[20, 30, 50, 100]; fn load_fixture(fixture: &str) -> (sprs::CsMat, usize, usize) { - let laplacian = common::load_sparse_csr(&common::fixture_path(fixture, "comp_b_laplacian.npz")); + let laplacian = + fixtures::load_sparse_csr(&fixtures::fixture_path(fixture, "comp_b_laplacian.npz")); let n = laplacian.rows(); - let ev_path = common::fixture_path(fixture, "comp_d_eigensolver.npz"); + let ev_path = fixtures::fixture_path(fixture, "comp_d_eigensolver.npz"); let mut npz = ndarray_npy::NpzReader::new( std::fs::File::open(&ev_path) .unwrap_or_else(|e| panic!("cannot open {:?}: {}", ev_path, e)), @@ -58,19 +62,14 @@ fn run_solver( let k_sub = (nc + 1 + p).min(n); match method { "2il" => { - // SAFETY: all callers run with --test-threads=1; no concurrent env readers. - unsafe { - std::env::set_var("SPECTRAL_RSVD_NBITER", nbiter.to_string()); - std::env::set_var("SPECTRAL_RSVD_OVERSAMPLING", p.to_string()); - } - let result = spectral_init::rsvd_solve(lap, nc, SEED); - unsafe { - std::env::remove_var("SPECTRAL_RSVD_NBITER"); - std::env::remove_var("SPECTRAL_RSVD_OVERSAMPLING"); - } - result + let params = SolverParams { + rsvd_oversampling: Some(p), + rsvd_nbiter: nbiter, + ..SolverParams::default() + }; + rsvd_solve(lap, nc, SEED, ¶ms) } - "direct_l" => spectral_init::rsvd_solve_accurate(lap, nc, SEED, k_sub, nbiter), + "direct_l" => rsvd_solve_accurate(lap, nc, SEED, k_sub, nbiter), _ => panic!("unknown method: {method}"), } } @@ -135,7 +134,7 @@ fn direction_c_subspace() { for (fixture, (lap, n, nc)) in &fixture_data { // Reference: high-accuracy solve at nbiter=10, p=100. let k_sub_ref = (nc + 1 + 100).min(*n); - let (_, ref_vecs) = spectral_init::rsvd_solve_accurate(lap, *nc, SEED, k_sub_ref, 10); + let (_, ref_vecs) = rsvd_solve_accurate(lap, *nc, SEED, k_sub_ref, 10); let ref_nt_vecs = ref_vecs.slice(s![.., 1..]).to_owned(); let ref_f32: ndarray::Array2 = ref_nt_vecs.mapv(|x| x as f32); diff --git a/tests/integration/test_exp_rsvd_sweep.rs b/eval/tests/test_exp_rsvd_sweep.rs similarity index 67% rename from tests/integration/test_exp_rsvd_sweep.rs rename to eval/tests/test_exp_rsvd_sweep.rs index 2e62612..26bd365 100644 --- a/tests/integration/test_exp_rsvd_sweep.rs +++ b/eval/tests/test_exp_rsvd_sweep.rs @@ -2,13 +2,17 @@ //! //! `accurate_sweep` — loops over p values using the high-accuracy rSVD variant (nbiter=6). //! `production_sweep` — runs a single p value (set via SPECTRAL_RSVD_OVERSAMPLING) using -//! the production rSVD variant (nbiter=2, reads env-var seam internally). +//! the production rSVD variant (nbiter=2). //! //! Both tests emit `SWEEP_ROW,,,

,,,,` //! lines to stdout for collection by the outer shell scripts. -#[path = "../common/mod.rs"] -mod common; +#[path = "../../tests/common/fixtures.rs"] +mod fixtures; +#[path = "../../tests/common/internals.rs"] +mod internals; + +use spectral_init::__internal::{SolverParams, rsvd_solve, rsvd_solve_accurate}; const FIXTURES: &[&str] = &[ "near_dupes_100", @@ -26,20 +30,19 @@ const P_VALUES_ACCURATE: &[usize] = &[5, 10, 15, 20, 25, 30, 50, 100]; #[test] fn accurate_sweep() { for &fixture in FIXTURES { - let path = common::fixture_path(fixture, "comp_b_laplacian.npz"); - let laplacian = common::load_sparse_csr(&path); + let path = fixtures::fixture_path(fixture, "comp_b_laplacian.npz"); + let laplacian = fixtures::load_sparse_csr(&path); let n = laplacian.rows(); for &p in P_VALUES_ACCURATE { let k_sub = N_COMPONENTS + 1 + p; // rank=3, so k_sub = 3 + p let t0 = std::time::Instant::now(); - let (eigs, vecs) = - spectral_init::rsvd_solve_accurate(&laplacian, N_COMPONENTS, SEED, k_sub, 6); + let (eigs, vecs) = rsvd_solve_accurate(&laplacian, N_COMPONENTS, SEED, k_sub, 6); let wall_time = t0.elapsed().as_secs_f64(); // max residual over non-trivial pairs (indices 1..=n_components) let max_res = (1..=N_COMPONENTS) - .map(|i| common::residual_spmv(&laplacian, vecs.column(i), eigs[i])) + .map(|i| internals::residual_spmv(&laplacian, vecs.column(i), eigs[i])) .fold(0.0_f64, f64::max); let passes = max_res < 1e-2; @@ -51,18 +54,22 @@ fn accurate_sweep() { #[test] fn production_sweep() { - // Read p from env-var once for CSV reporting; rsvd_solve reads it internally. + // The outer shell scripts choose the oversampling count through the environment. let env_p: Option = std::env::var("SPECTRAL_RSVD_OVERSAMPLING") .ok() .and_then(|s| s.parse::().ok()); + let params = SolverParams { + rsvd_oversampling: env_p, + ..SolverParams::default() + }; for &fixture in FIXTURES { - let path = common::fixture_path(fixture, "comp_b_laplacian.npz"); - let laplacian = common::load_sparse_csr(&path); + let path = fixtures::fixture_path(fixture, "comp_b_laplacian.npz"); + let laplacian = fixtures::load_sparse_csr(&path); let n = laplacian.rows(); let rank = N_COMPONENTS + 1; // 3 - // Mirror rsvd_k_sub_effective logic for CSV reporting. + // Mirror the solver's subspace-size rule for CSV reporting. let (p, k) = if let Some(p_override) = env_p { let k = (rank + p_override).min(n); (p_override, k) @@ -73,12 +80,11 @@ fn production_sweep() { }; let t0 = std::time::Instant::now(); - // rsvd_solve (production path: nbiter=2) reads SPECTRAL_RSVD_OVERSAMPLING internally. - let (eigs, vecs) = spectral_init::rsvd_solve(&laplacian, N_COMPONENTS, SEED); + let (eigs, vecs) = rsvd_solve(&laplacian, N_COMPONENTS, SEED, ¶ms); let wall_time = t0.elapsed().as_secs_f64(); let max_res = (1..=N_COMPONENTS) - .map(|i| common::residual_spmv(&laplacian, vecs.column(i), eigs[i])) + .map(|i| internals::residual_spmv(&laplacian, vecs.column(i), eigs[i])) .fold(0.0_f64, f64::max); let passes = max_res < 1e-2; diff --git a/tests/integration/test_metrics_assess.rs b/eval/tests/test_metrics_assess.rs similarity index 83% rename from tests/integration/test_metrics_assess.rs rename to eval/tests/test_metrics_assess.rs index 2113d66..271d220 100644 --- a/tests/integration/test_metrics_assess.rs +++ b/eval/tests/test_metrics_assess.rs @@ -1,18 +1,26 @@ -#[path = "../common/mod.rs"] -mod common; - +#[path = "../../tests/common/diagnostics.rs"] +mod diagnostics; +#[path = "../../tests/common/fixtures.rs"] +mod fixtures; +#[path = "../../tests/common/internals.rs"] +mod internals; + +use diagnostics::{ + DEGENERATE_GAP_THRESHOLD, SUBSPACE_GRAM_DET_THRESHOLD, check_eigenvalue_bounds, + eigenvalue_abs_errors, eigenvalue_condition_number, orthogonality_error, separation_ratio, + sign_agnostic_max_error, spectral_gap, subspace_gram_det_kd, tolerance_margin, +}; +use internals::solve_with_unit_hint; use ndarray::s; use ndarray::{Array1, Array2}; use serde_json::json; -use spectral_init::{ - AssessmentReport, ComputeMode, DEGENERATE_GAP_THRESHOLD, DENSE_EVD_QUALITY_THRESHOLD, - ExperimentMetrics, LOBPCG_QUALITY_THRESHOLD, MetricResult, RSVD_QUALITY_THRESHOLD, - SINV_LOBPCG_QUALITY_THRESHOLD, SUBSPACE_GRAM_DET_THRESHOLD, check_eigenvalue_bounds, - eigenvalue_abs_errors, eigenvalue_condition_number, embed_disconnected, find_components, - max_eigenpair_residual, orthogonality_error, select_eigenvectors, separation_ratio, - sign_agnostic_max_error, solve_eigenproblem_pub, spectral_gap, subspace_gram_det_kd, - tolerance_margin, +use spectral_init::__internal::{ + DENSE_EVD_QUALITY_THRESHOLD, LOBPCG_QUALITY_THRESHOLD, RSVD_QUALITY_THRESHOLD, + SINV_LOBPCG_QUALITY_THRESHOLD, SolverLevel, SolverParams, embed_disconnected, find_components, + max_eigenpair_residual, select_eigenvectors, }; +use spectral_init::ComputeMode; +use spectral_init_eval::{AssessmentReport, ExperimentMetrics, MetricResult, results_dir}; /// (name, n, is_connected, expected_n_components) const DATASETS: &[(&str, usize, bool, usize)] = &[ @@ -37,15 +45,6 @@ const BOUNDS_TOL: f64 = f64::EPSILON * 4.0; // ~8.88e-16 /// Sign-agnostic max error threshold for parity assessment. const SIGN_ERROR_THRESHOLD: f64 = 5e-3; -/// Output directory: RESULTS_DIR env var or default. -fn results_dir() -> std::path::PathBuf { - match std::env::var("RESULTS_DIR") { - Ok(d) => std::path::PathBuf::from(d), - Err(_) => std::path::PathBuf::from(env!("CARGO_MANIFEST_DIR")) - .join(".autoskillit/temp/run-experiment"), - } -} - /// Dataset filter: SPECTRAL_DATASET env var narrows to a single fixture. fn datasets_to_run() -> Vec<(&'static str, usize, bool, usize)> { let filter = std::env::var("SPECTRAL_DATASET").ok(); @@ -56,26 +55,13 @@ fn datasets_to_run() -> Vec<(&'static str, usize, bool, usize)> { .collect() } -/// Canonical solver name from level byte. -fn solver_name(level: u8) -> &'static str { - match level { - 0 => "Dense EVD", - 1 => "LOBPCG", - 2 => "SINV LOBPCG", - 3 => "LOBPCG+reg", - 4 => "rSVD", - 5 => "Forced Dense EVD", - _ => "Unknown", - } -} - /// Per-solver residual threshold. -fn residual_threshold(level: u8) -> f64 { +fn residual_threshold(level: SolverLevel) -> f64 { match level { - 0 | 5 => DENSE_EVD_QUALITY_THRESHOLD, - 1 | 3 => LOBPCG_QUALITY_THRESHOLD, - 2 => SINV_LOBPCG_QUALITY_THRESHOLD, - _ => RSVD_QUALITY_THRESHOLD, + SolverLevel::DenseEvd | SolverLevel::ForcedDense => DENSE_EVD_QUALITY_THRESHOLD, + SolverLevel::Lobpcg | SolverLevel::LobpcgRegularized => LOBPCG_QUALITY_THRESHOLD, + SolverLevel::SinvLobpcg => SINV_LOBPCG_QUALITY_THRESHOLD, + SolverLevel::Rsvd => RSVD_QUALITY_THRESHOLD, } } @@ -106,7 +92,7 @@ fn diag_entry(value: f64) -> serde_json::Value { /// Serialize an ExperimentMetrics to Section 4.5 JSON for the given dimension string. fn experiment_to_json( experiment: &ExperimentMetrics, - solver_levels: &[Option], + solver_levels: &[Option], dimension: &str, ) -> String { let datasets: Vec = experiment @@ -130,8 +116,8 @@ fn experiment_to_json( "dimension": dimension, "dataset": report.dataset, "n": report.n, - "solver_level": solver_level, - "solver_name": solver_level.map(solver_name), + "solver_level": solver_level.map(|level| level as u8), + "solver_name": solver_level.map(SolverLevel::name), "metrics": metrics_obj, }) }) @@ -144,16 +130,22 @@ fn experiment_to_json( .expect("JSON serialization failed") } -fn accuracy_to_json(experiment: &ExperimentMetrics, solver_levels: &[Option]) -> String { +fn accuracy_to_json( + experiment: &ExperimentMetrics, + solver_levels: &[Option], +) -> String { experiment_to_json(experiment, solver_levels, "accuracy") } -fn parity_to_json(experiment: &ExperimentMetrics, solver_levels: &[Option]) -> String { +fn parity_to_json(experiment: &ExperimentMetrics, solver_levels: &[Option]) -> String { experiment_to_json(experiment, solver_levels, "parity") } /// Markdown table for accuracy assessment. -fn accuracy_to_markdown(experiment: &ExperimentMetrics, solver_levels: &[Option]) -> String { +fn accuracy_to_markdown( + experiment: &ExperimentMetrics, + solver_levels: &[Option], +) -> String { let mut out = String::new(); out.push_str("# Metrics Assessment: Accuracy\n"); out.push_str(&format!("Generated: {}\n\n", experiment.generated_at)); @@ -183,7 +175,7 @@ fn accuracy_to_markdown(experiment: &ExperimentMetrics, solver_levels: &[Option< "| {} | {} | {} | {} | {} | {} | {} | {} | {} |\n", report.dataset, report.n, - solver_level.map(solver_name).unwrap_or("N/A"), + solver_level.map(SolverLevel::name).unwrap_or("N/A"), fmt_val("max_eigenpair_residual"), fmt_val("orthogonality_error"), fmt_bool("eigenvalue_bounds_in_range"), @@ -196,7 +188,10 @@ fn accuracy_to_markdown(experiment: &ExperimentMetrics, solver_levels: &[Option< } /// Markdown table for parity assessment. -fn parity_to_markdown(experiment: &ExperimentMetrics, solver_levels: &[Option]) -> String { +fn parity_to_markdown( + experiment: &ExperimentMetrics, + solver_levels: &[Option], +) -> String { let mut out = String::new(); out.push_str("# Metrics Assessment: Parity\n"); out.push_str(&format!("Generated: {}\n\n", experiment.generated_at)); @@ -221,7 +216,7 @@ fn parity_to_markdown(experiment: &ExperimentMetrics, solver_levels: &[Option = Vec::new(); - let mut solver_levels: Vec> = Vec::new(); + let mut solver_levels: Vec> = Vec::new(); for (dataset, n, is_connected, expected_n_components) in &run_set { - let base = common::fixture_path(dataset, ""); + let base = fixtures::fixture_path(dataset, ""); let ref_eigenvalues: Array1 = - common::load_dense(&base.join("comp_d_eigensolver.npz"), "eigenvalues"); + fixtures::load_dense(&base.join("comp_d_eigensolver.npz"), "eigenvalues"); assert!( !ref_eigenvalues.is_empty(), "{dataset}: ref eigenvalues array is empty — fixture may be corrupt" @@ -249,7 +244,7 @@ fn assess_accuracy() { let n_components_dim = ref_eigenvalues.len() - 1; if !is_connected { - let graph = common::load_sparse_csr_f32_u32(&base.join("step5a_pruned.npz")); + let graph = fixtures::load_sparse_csr_f32_u32(&base.join("step5a_pruned.npz")); let (rust_labels, rust_n_components) = find_components(&graph); let embedding = embed_disconnected( @@ -260,11 +255,12 @@ fn assess_accuracy() { 42, None, ComputeMode::PythonCompat, + &SolverParams::default(), ) .unwrap_or_else(|e| panic!("{dataset}: embed_disconnected failed: {e}")); let py_labels_i32: Array1 = - common::load_dense(&base.join("comp_c_components.npz"), "labels"); + fixtures::load_dense(&base.join("comp_c_components.npz"), "labels"); let labels: Vec = py_labels_i32.iter().map(|&x| x as usize).collect(); let sep = separation_ratio(embedding.view(), &labels); @@ -296,9 +292,15 @@ fn assess_accuracy() { } // Connected dataset path - let laplacian = common::load_sparse_csr(&base.join("comp_b_laplacian.npz")); - let ((eigenvalues, eigenvectors), solver_level) = - solve_eigenproblem_pub(&laplacian, n_components_dim, 42, ComputeMode::PythonCompat); + let laplacian = fixtures::load_sparse_csr(&base.join("comp_b_laplacian.npz")); + let ((eigenvalues, eigenvectors), solve_report) = solve_with_unit_hint( + &laplacian, + n_components_dim, + 42, + ComputeMode::PythonCompat, + &SolverParams::default(), + ); + let solver_level = solve_report.level; let residual = max_eigenpair_residual(&laplacian, &eigenvalues, &eigenvectors); let ortho = orthogonality_error(&eigenvectors); @@ -423,18 +425,18 @@ fn assess_accuracy() { fn assess_parity() { let run_set = datasets_to_run(); let mut all_reports: Vec = Vec::new(); - let mut solver_levels: Vec> = Vec::new(); + let mut solver_levels: Vec> = Vec::new(); for (dataset, n, _, _) in run_set.iter().filter(|(_, _, is_conn, _)| *is_conn) { - let base = common::fixture_path(dataset, ""); + let base = fixtures::fixture_path(dataset, ""); - let laplacian = common::load_sparse_csr(&base.join("comp_b_laplacian.npz")); + let laplacian = fixtures::load_sparse_csr(&base.join("comp_b_laplacian.npz")); let ref_eigenvalues: Array1 = - common::load_dense(&base.join("comp_d_eigensolver.npz"), "eigenvalues"); + fixtures::load_dense(&base.join("comp_d_eigensolver.npz"), "eigenvalues"); let ref_eigenvectors: Array2 = - common::load_dense(&base.join("comp_d_eigensolver.npz"), "eigenvectors"); + fixtures::load_dense(&base.join("comp_d_eigensolver.npz"), "eigenvectors"); let ref_pre_noise: Array2 = - common::load_dense(&base.join("comp_f_scaling.npz"), "pre_noise"); + fixtures::load_dense(&base.join("comp_f_scaling.npz"), "pre_noise"); assert!( !ref_eigenvalues.is_empty(), @@ -442,8 +444,14 @@ fn assess_parity() { ); let n_components_dim = ref_eigenvalues.len() - 1; - let ((eigenvalues, eigenvectors), solver_level) = - solve_eigenproblem_pub(&laplacian, n_components_dim, 42, ComputeMode::PythonCompat); + let ((eigenvalues, eigenvectors), solve_report) = solve_with_unit_hint( + &laplacian, + n_components_dim, + 42, + ComputeMode::PythonCompat, + &SolverParams::default(), + ); + let solver_level = solve_report.level; let abs_errors: Array1 = eigenvalue_abs_errors(&eigenvalues, &ref_eigenvalues); let max_abs_err = abs_errors.iter().cloned().fold(0.0f64, f64::max); diff --git a/tests/integration/test_rq3_threshold.rs b/eval/tests/test_rq3_threshold.rs similarity index 77% rename from tests/integration/test_rq3_threshold.rs rename to eval/tests/test_rq3_threshold.rs index 800f747..0ffe469 100644 --- a/tests/integration/test_rq3_threshold.rs +++ b/eval/tests/test_rq3_threshold.rs @@ -1,13 +1,14 @@ //! RQ3: Threshold override validation — dense EVD vs LOBPCG subspace agreement. -//! -//! This test requires `--features testing` and `--test-threads=1` (env var mutation). -#[path = "../common/mod.rs"] -mod common; +#[path = "../../tests/common/fixtures.rs"] +mod fixtures; +#[path = "../../tests/common/internals.rs"] +mod internals; use ndarray::Array2; use ndarray_npy::write_npy; -use std::path::Path; +use spectral_init::__internal::SolverParams; +use spectral_init::ComputeMode; /// Compute the maximum principal angle between two column subspaces. /// Returns arccos(min singular value of A^T * B) in radians. @@ -43,47 +44,46 @@ fn rq3_threshold_override_subspace_agreement() { let n_components = 2; // solve_eigenproblem returns n_components+1 = 3 eigenpairs // Build 200-node ring Laplacian - let laplacian = common::ring_laplacian(n); + let laplacian = fixtures::ring_laplacian(n); // ── Run 1: Force dense EVD (threshold=2000, n=200 < 2000 → Level 0) ── - // SAFETY: single-threaded test (--test-threads=1), no concurrent env readers - unsafe { - std::env::set_var("SPECTRAL_DENSE_N_THRESHOLD", "2000"); - } - let ((eigs_dense, vecs_dense), level_dense) = spectral_init::solve_eigenproblem_pub( + let dense_params = SolverParams { + dense_n_threshold: 2000, + ..SolverParams::default() + }; + let ((eigs_dense, vecs_dense), report_dense) = internals::solve_with_unit_hint( &laplacian, n_components, 42, - spectral_init::ComputeMode::PythonCompat, + ComputeMode::PythonCompat, + &dense_params, ); + let level_dense = report_dense.level as u8; assert_eq!( level_dense, 0, "expected Level 0 (dense EVD) with threshold=2000" ); // ── Run 2: Force LOBPCG (threshold=50, n=200 >= 50 → Level 1+) ── - unsafe { - std::env::set_var("SPECTRAL_DENSE_N_THRESHOLD", "50"); - } - let ((eigs_lobpcg, vecs_lobpcg), level_lobpcg) = spectral_init::solve_eigenproblem_pub( + let lobpcg_params = SolverParams { + dense_n_threshold: 50, + ..SolverParams::default() + }; + let ((eigs_lobpcg, vecs_lobpcg), report_lobpcg) = internals::solve_with_unit_hint( &laplacian, n_components, 42, - spectral_init::ComputeMode::PythonCompat, + ComputeMode::PythonCompat, + &lobpcg_params, ); + let level_lobpcg = report_lobpcg.level as u8; assert!( level_lobpcg >= 1, "expected Level >= 1 (LOBPCG path) with threshold=50, got {level_lobpcg}" ); - // ── Cleanup env var ── - unsafe { - std::env::remove_var("SPECTRAL_DENSE_N_THRESHOLD"); - } - // ── Save eigenvector matrices to .npy ── - let results_dir = Path::new(env!("CARGO_MANIFEST_DIR")) - .join("research/2026-03-25-ci-test-optimization/results/rq3_threshold"); + let results_dir = spectral_init_eval::results_dir().join("rq3_threshold"); std::fs::create_dir_all(&results_dir).expect("create results dir"); write_npy(results_dir.join("dense_n200_eigvecs.npy"), &vecs_dense) diff --git a/tests/integration/test_simd_lobpcg_parity.rs b/eval/tests/test_simd_lobpcg_parity.rs similarity index 89% rename from tests/integration/test_simd_lobpcg_parity.rs rename to eval/tests/test_simd_lobpcg_parity.rs index d8be53d..587a842 100644 --- a/tests/integration/test_simd_lobpcg_parity.rs +++ b/eval/tests/test_simd_lobpcg_parity.rs @@ -1,14 +1,14 @@ -#[path = "../common/mod.rs"] -mod common; +#[path = "../../tests/common/diagnostics.rs"] +mod diagnostics; +#[path = "../../tests/common/internals.rs"] +mod internals; +use diagnostics::{DEGENERATE_GAP_THRESHOLD, sign_agnostic_max_error, subspace_gram_det_kd}; +use internals::solve_with_unit_hint; use ndarray::Array2; use serde_json::json; -use spectral_init::metrics::{ - max_eigenpair_residual, sign_agnostic_max_error, subspace_gram_det_kd, -}; -use spectral_init::{ - ComputeMode, DEGENERATE_GAP_THRESHOLD, normalize_signs_pub, solve_eigenproblem_pub, -}; +use spectral_init::__internal::{SolverParams, max_eigenpair_residual, normalize_signs}; +use spectral_init::ComputeMode; use sprs::CsMatI; const SUBSPACE_ANGLE_SENSITIVITY_RAD: f64 = 1e-6; @@ -27,11 +27,7 @@ fn cluster_size() -> usize { } fn results_dir() -> std::path::PathBuf { - let p = match std::env::var("RESULTS_DIR") { - Ok(d) => std::path::PathBuf::from(d), - Err(_) => std::path::PathBuf::from(env!("CARGO_MANIFEST_DIR")) - .join("research/2026-03-28-simd-lobpcg-near-degenerate/results"), - }; + let p = spectral_init_eval::results_dir(); std::fs::create_dir_all(&p).expect("results dir"); p } @@ -144,10 +140,13 @@ fn measure_solver_pair( const N_LOBPCG_ITER: u32 = 300; // --- Solver invocations --- - let ((eigenvalues_s, eigvecs_s_raw), level_s) = - solve_eigenproblem_pub(laplacian, 2, seed, ComputeMode::PythonCompat); - let ((eigenvalues_x, eigvecs_x_raw), level_x) = - solve_eigenproblem_pub(laplacian, 2, seed, ComputeMode::RustNative); + let params = SolverParams::default(); + let ((eigenvalues_s, eigvecs_s_raw), report_s) = + solve_with_unit_hint(laplacian, 2, seed, ComputeMode::PythonCompat, ¶ms); + let ((eigenvalues_x, eigvecs_x_raw), report_x) = + solve_with_unit_hint(laplacian, 2, seed, ComputeMode::RustNative, ¶ms); + let level_s = report_s.level as u8; + let level_x = report_x.level as u8; // --- Residuals (pre-normalization, per Davis-Kahan definition) --- let residual_scalar = max_eigenpair_residual(laplacian, &eigenvalues_s, &eigvecs_s_raw); @@ -155,9 +154,9 @@ fn measure_solver_pair( // --- Sign normalization --- let mut eigvecs_s = eigvecs_s_raw; - normalize_signs_pub(&mut eigvecs_s); + normalize_signs(&mut eigvecs_s); let mut eigvecs_x = eigvecs_x_raw; - normalize_signs_pub(&mut eigvecs_x); + normalize_signs(&mut eigvecs_x); // --- Subspace comparison --- let max_subspace_angle_rad = max_subspace_angle(&eigvecs_s, &eigvecs_x); @@ -281,9 +280,13 @@ fn test_solver_level_parity() { let n = cluster_size(); for &w in BRIDGE_WEIGHTS.iter() { let laplacian = large_epsilon_bridge_laplacian(n, w); - let ((eigenvalues_s, _), level_s) = - solve_eigenproblem_pub(&laplacian, 2, 42, ComputeMode::PythonCompat); - let (_, level_x) = solve_eigenproblem_pub(&laplacian, 2, 42, ComputeMode::RustNative); + let params = SolverParams::default(); + let ((eigenvalues_s, _), report_s) = + solve_with_unit_hint(&laplacian, 2, 42, ComputeMode::PythonCompat, ¶ms); + let (_, report_x) = + solve_with_unit_hint(&laplacian, 2, 42, ComputeMode::RustNative, ¶ms); + let level_s = report_s.level as u8; + let level_x = report_x.level as u8; let approx_gap = (eigenvalues_s[1] - eigenvalues_s[0]).max(0.0); let is_degenerate = approx_gap < DEGENERATE_GAP_THRESHOLD; diff --git a/tests/integration/test_simd_parity.rs b/eval/tests/test_simd_parity.rs similarity index 73% rename from tests/integration/test_simd_parity.rs rename to eval/tests/test_simd_parity.rs index 52e39da..e3eb3c9 100644 --- a/tests/integration/test_simd_parity.rs +++ b/eval/tests/test_simd_parity.rs @@ -1,19 +1,21 @@ -#[path = "../common/mod.rs"] -mod common; +#[path = "../../tests/common/fixtures.rs"] +mod fixtures; +#[path = "../../tests/common/internals.rs"] +mod internals; +use internals::solve_with_unit_hint; use ndarray::Ix1; use rand::SeedableRng; use rand::rngs::StdRng; use rand_distr::{Distribution, StandardNormal}; use serde_json::json; -use spectral_init::{ - ComputeMode, normalize_signs_pub, scale_and_add_noise_pub, solve_eigenproblem_pub, -}; - -#[cfg(any(target_arch = "x86", target_arch = "x86_64"))] -use spectral_init::operator::spmv_avx2_gather_pub; - -use spectral_init::operator::spmv_csr; +#[cfg(target_arch = "x86_64")] +use spectral_init::__internal::spmv_avx2_gather; +use spectral_init::__internal::{SolverParams, spmv_csr}; +#[cfg(target_arch = "x86_64")] +use spectral_init::__internal::{normalize_signs, scale_and_add_noise}; +use spectral_init::ComputeMode; +use spectral_init_eval::results_dir; const FIXTURES: &[&str] = &[ "blobs_50", @@ -27,14 +29,6 @@ const FIXTURES: &[&str] = &[ "blobs_5000", ]; -fn results_dir() -> std::path::PathBuf { - match std::env::var("RESULTS_DIR") { - Ok(d) => std::path::PathBuf::from(d), - Err(_) => std::path::PathBuf::from(env!("CARGO_MANIFEST_DIR")) - .join("research/2026-03-27-computemode-simd-spmv-parity/results"), - } -} - fn ulp_distance(a: f64, b: f64) -> u64 { // Both exactly zero: 0 ULPs by definition. if a == 0.0 && b == 0.0 { @@ -61,8 +55,8 @@ fn test_spmv_divergence() { let mut records: Vec = Vec::new(); for (fixture_idx, &fixture) in FIXTURES.iter().enumerate() { - let lap_path = common::fixture_path(fixture, "comp_b_laplacian.npz"); - let laplacian = common::load_sparse_csr(&lap_path); + let lap_path = fixtures::fixture_path(fixture, "comp_b_laplacian.npz"); + let laplacian = fixtures::load_sparse_csr(&lap_path); let n = laplacian.rows(); let nnz = laplacian.nnz(); let indptr = laplacian.indptr().raw_storage().to_vec(); @@ -77,10 +71,10 @@ fn test_spmv_divergence() { let mut y_scalar = vec![0.0_f64; n]; spmv_csr(&indptr, &indices, &data, &x, &mut y_scalar); - #[cfg(any(target_arch = "x86", target_arch = "x86_64"))] + #[cfg(target_arch = "x86_64")] let (max_abs_diff, rms_diff, max_ulp) = { let mut y_avx2 = vec![0.0_f64; n]; - spmv_avx2_gather_pub(&indptr, &indices, &data, &x, &mut y_avx2); + spmv_avx2_gather(&indptr, &indices, &data, &x, &mut y_avx2); let mut max_abs: f64 = 0.0; let mut sum_sq: f64 = 0.0; @@ -101,7 +95,7 @@ fn test_spmv_divergence() { }; // On non-x86_64: scalar-only, divergence is zero by definition. - #[cfg(not(any(target_arch = "x86", target_arch = "x86_64")))] + #[cfg(not(target_arch = "x86_64"))] let (max_abs_diff, rms_diff, max_ulp): (f64, f64, u64) = (0.0, 0.0, 0); records.push(json!({ @@ -123,7 +117,7 @@ fn test_spmv_divergence() { #[test] fn test_solver_divergence() { - #[cfg(any(target_arch = "x86", target_arch = "x86_64"))] + #[cfg(target_arch = "x86_64")] if !is_x86_feature_detected!("avx2") || !is_x86_feature_detected!("fma") { eprintln!( "test_solver_divergence: skipping — AVX2/FMA not available; \ @@ -139,27 +133,30 @@ fn test_solver_divergence() { let mut records: Vec = Vec::new(); for &fixture in FIXTURES.iter() { - let lap_path = common::fixture_path(fixture, "comp_b_laplacian.npz"); - let laplacian = common::load_sparse_csr(&lap_path); + let lap_path = fixtures::fixture_path(fixture, "comp_b_laplacian.npz"); + let laplacian = fixtures::load_sparse_csr(&lap_path); let n = laplacian.rows(); - let ((_, eigvec_scalar), solver_level_scalar) = - solve_eigenproblem_pub(&laplacian, 2, 42, ComputeMode::PythonCompat); + let params = SolverParams::default(); + let ((_, eigvec_scalar), report_scalar) = + solve_with_unit_hint(&laplacian, 2, 42, ComputeMode::PythonCompat, ¶ms); + let solver_level_scalar = report_scalar.level as u8; // x86_64 path: run SIMD solver and compare. - #[cfg(any(target_arch = "x86", target_arch = "x86_64"))] + #[cfg(target_arch = "x86_64")] let record = { - let mut eigvec_scalar = eigvec_scalar; // rebind as mut — normalize_signs_pub needs &mut - let ((_, mut eigvec_avx2), solver_level_avx2) = - solve_eigenproblem_pub(&laplacian, 2, 42, ComputeMode::RustNative); + let mut eigvec_scalar = eigvec_scalar; // rebind as mut — normalize_signs needs &mut + let ((_, mut eigvec_avx2), report_avx2) = + solve_with_unit_hint(&laplacian, 2, 42, ComputeMode::RustNative, ¶ms); + let solver_level_avx2 = report_avx2.level as u8; - normalize_signs_pub(&mut eigvec_scalar); // match production E.5 - normalize_signs_pub(&mut eigvec_avx2); // match production E.5 + normalize_signs(&mut eigvec_scalar); // match production E.5 + normalize_signs(&mut eigvec_avx2); // match production E.5 let scaled_scalar = - scale_and_add_noise_pub(eigvec_scalar, 42).expect("scale_and_add_noise_pub failed"); + scale_and_add_noise(eigvec_scalar, 42).expect("scale_and_add_noise failed"); let scaled_avx2 = - scale_and_add_noise_pub(eigvec_avx2, 42).expect("scale_and_add_noise_pub failed"); + scale_and_add_noise(eigvec_avx2, 42).expect("scale_and_add_noise failed"); let f32_total = scaled_scalar.len(); let f32_bitwise_identical = scaled_scalar @@ -173,14 +170,6 @@ fn test_solver_divergence() { .map(|(a, b)| (a - b).abs()) .fold(0.0f32, f32::max); - // 4 * f32::EPSILON ≈ 4.77e-7; allows one rounding-budget above zero for - // any residual scalar/SIMD divergence that survives normalize_signs. - assert!( - f32_max_abs_diff <= 4.77e-7, - "fixture {fixture}: max_abs_diff={f32_max_abs_diff:.3e} > 4.77e-7 after normalize_signs — \ - sign flip not resolved; SIMD kernel must be gated behind ComputeMode::RustNative" - ); - let eigenvectors_saved = if solver_level_scalar >= 1 { let scalar_path = results_dir .join("eigenvectors") @@ -209,7 +198,7 @@ fn test_solver_divergence() { }; // Non-x86_64 path: record scalar result only; SIMD path does not exist. - #[cfg(not(any(target_arch = "x86", target_arch = "x86_64")))] + #[cfg(not(target_arch = "x86_64"))] let record = { // Suppress unused variable: eigvec_scalar consumed but comparison skipped. let _ = eigvec_scalar; @@ -241,13 +230,13 @@ fn test_spectral_gaps() { let mut records: Vec = Vec::new(); for &fixture in FIXTURES.iter() { - let lap_path = common::fixture_path(fixture, "comp_b_laplacian.npz"); - let laplacian = common::load_sparse_csr(&lap_path); + let lap_path = fixtures::fixture_path(fixture, "comp_b_laplacian.npz"); + let laplacian = fixtures::load_sparse_csr(&lap_path); let n = laplacian.rows(); - let ev_path = common::fixture_path(fixture, "comp_d_eigensolver.npz"); + let ev_path = fixtures::fixture_path(fixture, "comp_d_eigensolver.npz"); let gaps: ndarray::Array1 = - common::load_dense::(&ev_path, "eigenvalue_gaps"); + fixtures::load_dense::(&ev_path, "eigenvalue_gaps"); let gaps_vec: Vec = gaps.iter().copied().collect(); let min_gap = gaps_vec.iter().copied().fold(f64::MAX, f64::min); diff --git a/tests/integration/test_warm_restart_benefit.rs b/eval/tests/test_warm_restart_benefit.rs similarity index 58% rename from tests/integration/test_warm_restart_benefit.rs rename to eval/tests/test_warm_restart_benefit.rs index 63fb6bd..cb64787 100644 --- a/tests/integration/test_warm_restart_benefit.rs +++ b/eval/tests/test_warm_restart_benefit.rs @@ -1,23 +1,26 @@ -// NOTE: compile only with --features testing -// Run with: cargo test --features testing --release warm_restart -- --nocapture +// Run with: +// cargo test -p spectral-init-eval --release --test test_warm_restart_benefit -- --nocapture // // This test file measures warm-restart count and eigenvector residuals on adversarial // graph types to determine whether the warm-restart loop in lobpcg_solve is reachable // and beneficial for UMAP-style Laplacians. -#[path = "../common/mod.rs"] -mod common; +#[path = "../../tests/common/fixtures.rs"] +mod fixtures; +#[path = "../../tests/common/internals.rs"] +mod internals; extern crate ndarray16; use ndarray16 as nd16; +use fixtures::{path_laplacian, path_sqrt_deg, ring_laplacian, ring_sqrt_deg}; +use internals::max_operator_residual; use linfa_linalg::lobpcg::{Order, lobpcg}; use ndarray::{Array1, Array2}; use rand::SeedableRng; use rand::rngs::StdRng; use rand_distr::{Distribution, StandardNormal}; -use spectral_init::operator::{CsrOperator, LinearOperator}; -use spectral_init::solvers::lobpcg::lobpcg_solve; +use spectral_init::__internal::{CsrOperator, LinearOperator, lobpcg_solve}; use sprs::CsMatI; // ─── ndarray 0.16 ↔ 0.17 conversion helpers ────────────────────────────────── @@ -46,62 +49,6 @@ fn from_nd16_array2(a: nd16::Array2) -> Array2 { // ─── Graph builder helpers ──────────────────────────────────────────────────── -/// Normalized Laplacian of P_n (path graph) in f64. Replicates large_path_laplacian. -fn path_laplacian(n: usize) -> CsMatI { - let inv_sqrt2 = 1.0_f64 / 2.0_f64.sqrt(); - let mut indptr = vec![0usize; n + 1]; - let mut indices: Vec = Vec::new(); - let mut data: Vec = Vec::new(); - for i in 0..n { - if i > 0 { - let w = if i == n - 1 { -inv_sqrt2 } else { -0.5 }; - indices.push(i - 1); - data.push(w); - } - indices.push(i); - data.push(1.0); - if i + 1 < n { - let w = if i == 0 { -inv_sqrt2 } else { -0.5 }; - indices.push(i + 1); - data.push(w); - } - indptr[i + 1] = indices.len(); - } - CsMatI::new((n, n), indptr, indices, data) -} - -/// sqrt_deg for P_n: endpoints = 1.0, interior = sqrt(2). -fn path_sqrt_deg(n: usize) -> Array1 { - let mut v = vec![2.0_f64.sqrt(); n]; - v[0] = 1.0; - v[n - 1] = 1.0; - Array1::from_vec(v) -} - -/// Normalized Laplacian of C_n (ring graph) in f64. -fn ring_laplacian(n: usize) -> CsMatI { - let mut indptr = vec![0usize; n + 1]; - let mut indices: Vec = Vec::new(); - let mut data: Vec = Vec::new(); - for i in 0..n { - let left = if i == 0 { n - 1 } else { i - 1 }; - let right = if i + 1 == n { 0 } else { i + 1 }; - let mut entries = [(left, -0.5_f64), (i, 1.0_f64), (right, -0.5_f64)]; - entries.sort_unstable_by_key(|&(col, _)| col); - for (col, val) in entries { - indices.push(col); - data.push(val); - } - indptr[i + 1] = indices.len(); - } - CsMatI::new((n, n), indptr, indices, data) -} - -/// sqrt_deg for C_n: all sqrt(2). -fn ring_sqrt_deg(n: usize) -> Array1 { - Array1::from_elem(n, 2.0_f64.sqrt()) -} - /// Normalized Laplacian of epsilon-bridge graph (two K_{cs} cliques with bridge weight bw). fn epsilon_bridge_laplacian(cluster_size: usize, bridge_weight: f64) -> CsMatI { let cs = cluster_size; @@ -264,17 +211,6 @@ fn single_pass_lobpcg( // ─── Core measurement function ──────────────────────────────────────────────── -/// Compute max per-vector residual over all n_components+1 eigenpairs. -fn max_residual( - op: &O, - eigenvalues: &Array1, - eigenvectors: &Array2, -) -> f64 { - (0..eigenvalues.len()) - .map(|i| common::eigenpair_residual(op, eigenvectors.column(i), eigenvalues[i])) - .fold(0.0_f64, f64::max) -} - /// Run a warm-restart-benefit measurement on one graph configuration. /// /// For each seed in [42, 43, 44], records: @@ -282,7 +218,7 @@ fn max_residual( /// - max_residual_with_restart from lobpcg_solve result /// - max_residual_no_restart from single-pass linfa_linalg::lobpcg /// -/// Prints METRIC lines for result collection and asserts final residuals < LOBPCG_ACCEPT_TOL. +/// Prints METRIC lines for result collection. fn run_warm_restart_test( op: &O, sqrt_deg: &Array1, @@ -296,11 +232,11 @@ fn run_warm_restart_test( lobpcg_solve(op, n_components, seed, false, sqrt_deg) .unwrap_or_else(|| panic!("lobpcg_solve returned None for {label} seed={seed}")); - let max_res_wr = max_residual(op, &eigenvalues, &eigenvectors); + let max_res_wr = max_operator_residual(op, &eigenvalues, &eigenvectors); // ── Single-pass baseline (no warm restart) ── let max_res_nr = match single_pass_lobpcg(op, n_components, seed, sqrt_deg) { - Some((eigvals_sp, eigvecs_sp)) => max_residual(op, &eigvals_sp, &eigvecs_sp), + Some((eigvals_sp, eigvecs_sp)) => max_operator_residual(op, &eigvals_sp, &eigvecs_sp), None => f64::NAN, }; @@ -329,33 +265,6 @@ fn test_path_2000_warm_restart() { run_warm_restart_test(&op, &sqrt_deg, 2, "path_2000"); } -#[test] -#[ignore = "requires --release; LOBPCG convergence behaviour differs in debug mode and the test times out (>1200s) without optimisation"] -fn test_path_2000_warm_restart_majority_converged() { - // Issue #123: with LOBPCG_RESTART_MAXITER_CAP = 1000, path_2000 should converge - // on a majority of seeds. Currently fails because 300-iter cap is insufficient. - let lap = path_laplacian(2000); - let sqrt_deg = path_sqrt_deg(2000); - let op = CsrOperator(&lap); - let n_components = 2; - - let mut n_converged = 0usize; - for seed in [42u64, 43, 44] { - if let Some(((eigs, vecs), _)) = lobpcg_solve(&op, n_components, seed, false, &sqrt_deg) { - let residuals = (0..eigs.len()) - .map(|i| common::eigenpair_residual(&op, vecs.column(i), eigs[i])) - .collect::>(); - if residuals.iter().all(|&r| r < 1e-5) { - n_converged += 1; - } - } - } - assert!( - n_converged >= 2, - "path_2000 should converge on >= 2/3 seeds with raised restart cap; got {n_converged}/3" - ); -} - #[test] fn test_path_3000_warm_restart() { let lap = path_laplacian(3000); @@ -382,40 +291,6 @@ fn test_ring_2000_warm_restart() { run_warm_restart_test(&op, &sqrt_deg, 2, "ring_2000"); } -#[test] -fn test_ring_2000_warm_restart_converges() { - // ring_2000 seed=42: single reproducible case from the research experiment - // where warm restart achieves full convergence (residual < 1e-5). - // Research evidence: restart_count=3, improvement_ratio=33.4x - // (residual drops from 3.25e-4 to 9.74e-6). - // Only meaningful under --release; skip in debug builds where LOBPCG - // convergence behaviour differs due to reduced optimisation. - if cfg!(debug_assertions) { - return; - } - let lap = ring_laplacian(2000); - let sqrt_deg = ring_sqrt_deg(2000); - let op = CsrOperator(&lap); - - let result = lobpcg_solve(&op, 2, 42, false, &sqrt_deg); - assert!( - result.is_some(), - "lobpcg_solve returned None for ring_2000 seed=42" - ); - - let ((eigs, vecs), restart_count) = result.unwrap(); - assert!( - restart_count >= 3, - "warm restart should fire 3 times on ring_2000 seed=42 (research: restart_count=3); got restart_count={restart_count}" - ); - - let max_res = max_residual(&op, &eigs, &vecs); - assert!( - max_res < 1e-5, - "ring_2000 seed=42 should converge to max_residual < 1e-5; got {max_res:.2e}" - ); -} - #[test] fn test_ring_3000_warm_restart() { let lap = ring_laplacian(3000); @@ -424,56 +299,6 @@ fn test_ring_3000_warm_restart() { run_warm_restart_test(&op, &sqrt_deg, 2, "ring_3000"); } -// ─── Warm-restart fires assertions (B6 detection) ──────────────────────────── - -#[test] -fn test_ring_2000_warm_restart_fires() { - // ring_2000 seed=42: research shows restart_count=3 at opt-level=2. - // At opt-level=2 the solver completes 300 iters/pass quickly; warm restart fires - // because 300 iters yields residual 3.25e-4 >> 1e-5 threshold. - // With B6 applied (for restart in 0..=0), restart_count=0 → assertion fails. - // NOTE: This assertion is FP-sensitive — LLVM FP reassociation at opt-level=2 can - // change Gram matrix conditioning, affecting whether Cholesky triggers a restart. - // Uses restart_count > 0 (weaker than >= 3) to reduce toolchain-version fragility. - let lap = ring_laplacian(2000); - let sqrt_deg = ring_sqrt_deg(2000); - let op = CsrOperator(&lap); - let result = lobpcg_solve(&op, 2, 42, false, &sqrt_deg); - let (_, restart_count) = result.expect("lobpcg_solve returned None for ring_2000 seed=42"); - assert!( - restart_count > 0, - "ring_2000 seed=42 must trigger at least one warm restart at opt-level=2; \ - got restart_count={restart_count}" - ); -} - -#[test] -fn test_path_2000_warm_restart_fires() { - // path_2000 is a known hard input: high condition number, small spectral gap. - // At opt-level=2, at least one of seeds 42/43/44 will trigger warm restart. - // With B6 applied (for restart in 0..=0), restart_count=0 for ALL seeds → fails. - // NOTE: This assertion is FP-sensitive — same LLVM reassociation concern as above. - // Uses total_restarts > 0 across 3 seeds to reduce single-seed fragility. - // ⚠️ Historical note: test_path_2000_warm_restart_majority_converged was marked - // #[ignore] in de36131 due to ~20 min CI timing at opt-level=0 on path_2000. - // This test requires Step 1 (opt-level=2) to be implemented first; at opt-level=0 - // the 3-seed run will be extremely slow. - let lap = path_laplacian(2000); - let sqrt_deg = path_sqrt_deg(2000); - let op = CsrOperator(&lap); - let mut total_restarts = 0usize; - for seed in [42u64, 43, 44] { - if let Some((_, rc)) = lobpcg_solve(&op, 2, seed, false, &sqrt_deg) { - total_restarts += rc; - } - } - assert!( - total_restarts > 0, - "path_2000: expected warm restart to fire on at least one of seeds 42/43/44 \ - at opt-level=2; got total_restarts={total_restarts}" - ); -} - // ─── Epsilon-bridge sweep ───────────────────────────────────────────────────── #[test] diff --git a/src/components.rs b/src/components.rs index 82911d0..78b355c 100644 --- a/src/components.rs +++ b/src/components.rs @@ -4,7 +4,7 @@ use std::collections::VecDeque; /// BFS connected-component labelling on a sparse graph. /// Returns a Vec of length n where `result[i]` is the component index for node i, /// and the number of distinct components. -pub(crate) fn find_components(graph: &CsMatI) -> (Vec, usize) { +pub fn find_components(graph: &CsMatI) -> (Vec, usize) { debug_assert!( graph.is_csr(), "find_components requires CSR storage; a CSC matrix would silently traverse \ diff --git a/src/lib.rs b/src/lib.rs index 825ea9e..3155a72 100644 --- a/src/lib.rs +++ b/src/lib.rs @@ -41,7 +41,7 @@ //! //! The eigensolver uses a 6-level escalation chain (dense EVD → LOBPCG → //! shift-invert LOBPCG → LOBPCG+regularization → randomized SVD → forced dense EVD) -//! to guarantee convergence on any valid graph. See [`solvers`] for details. +//! to guarantee convergence on any valid graph. //! //! # Compute Mode //! @@ -53,11 +53,7 @@ //! //! # Feature Flags //! -//! | Flag | Purpose | -//! |------|---------| -//! | `testing` | Exposes internal solver functions for integration tests. Not part of the stable public API. | -//! | `cli` | Builds the `trustworthiness` and `tw_profiler` binaries for embedding quality evaluation. | -//! | `profiling` | Enables timing instrumentation in the solver escalation chain. | +//! The crate has no public Cargo features. //! //! # Integration with umap-rs //! @@ -81,147 +77,51 @@ mod components; mod config; mod laplacian; -#[doc(hidden)] -pub mod metrics; mod multi_component; -#[doc(hidden)] -pub mod operator; +mod operator; mod scaling; mod selection; -#[doc(hidden)] -pub mod solvers; +mod solvers; pub use config::{ComputeMode, SpectralInitConfig}; -// Re-exported for component-level integration tests. These are internal pipeline -// functions, not part of the stable public API. -pub use crate::laplacian::build_normalized_laplacian; -pub use crate::laplacian::compute_degrees; -pub use crate::selection::select_eigenvectors; -/// Dense EVD solver. Exposed for component-level integration tests; not part of the -/// stable public API and may change without notice. -pub use crate::solvers::dense_evd; - -#[cfg(feature = "testing")] -#[doc(hidden)] -pub fn find_components(graph: &sprs::CsMatI) -> (Vec, usize) { - components::find_components(graph) -} - -#[cfg(feature = "testing")] -#[doc(hidden)] -pub fn rsvd_solve( - laplacian: &sprs::CsMatI, - n_components: usize, - seed: u64, -) -> (ndarray::Array1, ndarray::Array2) { - crate::solvers::rsvd::rsvd_solve(laplacian, n_components, seed) -} - -#[cfg(feature = "testing")] -#[doc(hidden)] -pub fn rsvd_solve_accurate( - laplacian: &sprs::CsMatI, - n_components: usize, - seed: u64, - k_sub: usize, - nbiter: usize, -) -> (ndarray::Array1, ndarray::Array2) { - crate::solvers::rsvd::rsvd_solve_accurate(laplacian, n_components, seed, k_sub, nbiter) -} - -#[cfg(feature = "testing")] -#[doc(hidden)] -/// Exposes `solve_eigenproblem` for integration tests that need to assert which -/// solver level was reached. +/// Internal pipeline pieces for this crate's own integration tests and research harness. /// -/// **Test-only seam — not part of the stable public API.** The returned `u8` -/// encodes the solver level (0 = dense EVD, 1 = LOBPCG, 2 = sinv LOBPCG, -/// 3 = LOBPCG+reg, 4 = rSVD, 5 = forced dense EVD) and may change if the -/// escalation chain is reordered or extended. Test code that asserts on this -/// value is intentionally coupled to the current chain ordering. -pub fn solve_eigenproblem_pub( - laplacian: &sprs::CsMatI, - n_components: usize, - seed: u64, - compute_mode: ComputeMode, -) -> ((ndarray::Array1, ndarray::Array2), u8) { - let n = laplacian.rows(); - let sqrt_deg = ndarray::Array1::ones(n); - crate::solvers::solve_eigenproblem(laplacian, n_components, seed, &sqrt_deg, compute_mode) -} - -#[cfg(feature = "testing")] -#[doc(hidden)] -pub use crate::solvers::lobpcg::lobpcg_solve; - -#[cfg(feature = "testing")] +/// Exempt from semver: anything in this module may change or disappear in any release. +#[cfg(feature = "__internal")] #[doc(hidden)] -pub fn embed_disconnected( - graph: &sprs::CsMatI, - component_labels: &[usize], - n_conn_components: usize, - n_embedding_dims: usize, - seed: u64, - data: Option>, - compute_mode: ComputeMode, -) -> Result, SpectralError> { - crate::multi_component::embed_disconnected( - graph, - component_labels, - n_conn_components, - n_embedding_dims, - seed, - data, - compute_mode, - ) -} - -#[cfg(feature = "testing")] -#[doc(hidden)] -pub use crate::solvers::sinv::lobpcg_sinv_solve; - -#[cfg(feature = "testing")] -#[doc(hidden)] -pub fn scale_coords( - coords: &ndarray::Array2, - max_coord: f64, -) -> Result, SpectralError> { - crate::scaling::scale_coords(coords, max_coord) -} - -#[cfg(feature = "testing")] -#[doc(hidden)] -pub fn scale_and_add_noise_pub( - coords: ndarray::Array2, - seed: u64, -) -> Result, SpectralError> { - crate::scaling::scale_and_add_noise(coords, seed) -} - -#[cfg(feature = "testing")] -#[doc(hidden)] -pub fn normalize_signs_pub(coords: &mut ndarray::Array2) { - crate::scaling::normalize_signs(coords) +pub mod __internal { + #[doc(hidden)] + pub use crate::components::find_components; + #[doc(hidden)] + pub use crate::laplacian::{build_normalized_laplacian, compute_degrees}; + #[doc(hidden)] + pub use crate::multi_component::embed_disconnected; + #[doc(hidden)] + pub use crate::operator::{CsrOperator, LinearOperator, spmv_csr}; + #[cfg(target_arch = "x86_64")] + #[doc(hidden)] + pub use crate::operator::{CsrOperatorSimd, spmv_avx2_gather}; + #[doc(hidden)] + pub use crate::scaling::{normalize_signs, scale_and_add_noise, scale_coords}; + #[doc(hidden)] + pub use crate::selection::select_eigenvectors; + #[doc(hidden)] + pub use crate::solvers::dense_evd; + #[doc(hidden)] + pub use crate::solvers::lobpcg::lobpcg_solve; + #[doc(hidden)] + pub use crate::solvers::quality::*; + #[doc(hidden)] + pub use crate::solvers::rsvd::{rsvd_solve, rsvd_solve_accurate}; + #[doc(hidden)] + pub use crate::solvers::sinv::lobpcg_sinv_solve; + #[doc(hidden)] + pub use crate::solvers::{ + EigenResult, QualityGates, SolveReport, SolverLevel, SolverParams, solve_eigenproblem, + }; } -#[cfg(feature = "testing")] -#[doc(hidden)] -pub use crate::metrics::{ - AssessmentReport, DEGENERATE_GAP_THRESHOLD, DENSE_EVD_QUALITY_THRESHOLD, ExperimentMetrics, - LOBPCG_QUALITY_THRESHOLD, MetricResult, RSVD_QUALITY_THRESHOLD, SINV_LOBPCG_QUALITY_THRESHOLD, - SUBSPACE_GRAM_DET_THRESHOLD, check_eigenvalue_bounds, eigenpair_residual, - eigenvalue_abs_errors, eigenvalue_condition_number, max_eigenpair_residual, - orthogonality_error, separation_ratio, sign_agnostic_max_error, spectral_gap, - subspace_gram_det_kd, tolerance_margin, trustworthiness, trustworthiness_subsampled, -}; - -// Re-export trustworthiness for the CLI binary when built with the `cli` feature. -// The `testing` block above already covers test builds; this separate cfg avoids -// double-export when both features are active. -#[cfg(all(feature = "cli", not(feature = "testing")))] -pub use crate::metrics::{trustworthiness, trustworthiness_subsampled}; - use ndarray::{Array2, ArrayView2}; use sprs::CsMatI; @@ -308,6 +208,8 @@ pub fn spectral_init( }); } + let solver_params = solvers::SolverParams::default(); + // ── Component A: connectivity check ─────────────────────────────────── let (labels, n_conn_components) = components::find_components(graph); if n_conn_components > 1 { @@ -319,6 +221,7 @@ pub fn spectral_init( seed, data, config.compute_mode, + &solver_params, )?; return scaling::scale_and_add_noise(coords, seed); } @@ -334,8 +237,15 @@ pub fn spectral_init( let lap = laplacian::build_normalized_laplacian(graph, &inv_sqrt_deg); // ── Component D: eigensolver escalation chain ───────────────────────── - let ((eigenvalues, eigenvectors), _) = - solvers::solve_eigenproblem(&lap, n_components, seed, &sqrt_deg, config.compute_mode); + let ((eigenvalues, eigenvectors), report) = solvers::solve_eigenproblem( + &lap, + n_components, + seed, + &sqrt_deg, + config.compute_mode, + &solver_params, + )?; + report.log("connected graph", n); // ── Component E: eigenvector selection ──────────────────────────────── let mut selected = selection::select_eigenvectors( @@ -359,16 +269,6 @@ pub fn spectral_init( mod tests { use super::*; - #[cfg(all(feature = "testing", test))] - #[test] - fn scale_and_add_noise_pub_is_accessible() { - let coords = - ndarray::Array2::::from_shape_vec((2, 2), vec![1.0, 2.0, 3.0, 4.0]).unwrap(); - let result = scale_and_add_noise_pub(coords, 42); - assert!(result.is_ok()); - assert_eq!(result.unwrap().shape(), &[2, 2]); - } - #[test] fn spectral_error_is_std_error() { let e: &dyn std::error::Error = &SpectralError::ConvergenceFailure; diff --git a/src/metrics.rs b/src/metrics.rs deleted file mode 100644 index 25b79aa..0000000 --- a/src/metrics.rs +++ /dev/null @@ -1,1711 +0,0 @@ -//! Quality metrics, threshold constants, and assessment data structures. -//! -//! This module is the single canonical home for: -//! - Eigensolver quality thresholds (used in the solver escalation chain) -//! - Accuracy metric functions (residual, orthogonality, eigenvalue bounds) -//! - Parity metric functions (comparing Rust vs Python reference outputs) -//! - Diagnostic functions (spectral gap, condition number, tolerance margin) -//! - Data structures for structured metric reporting (behind `#[cfg(feature = "testing")]`) - -use faer::linalg::solvers::SelfAdjointEigen; -use faer::{Mat as FaerMat, Side}; -use ndarray::{Array1, Array2, ArrayView1, ArrayView2}; -use rayon::prelude::*; -use sprs::CsMatI; -use std::collections::HashSet; - -// ─── Threshold constants ────────────────────────────────────────────────────── - -/// Maximum acceptable max-residual from rSVD before falling to Level 5. -/// rSVD with 2 power iterations typically achieves 1e-4 to 1e-6 on well-conditioned -/// graphs; 1e-2 accepts all such results while correctly escalating pathological cases. -pub const RSVD_QUALITY_THRESHOLD: f64 = 1e-2; - -/// Maximum acceptable max-residual from dense EVD (Levels 0 and 5). -/// Dense EVD via faer is numerically exact (machine precision); 1e-6 leaves -/// a generous margin while catching any pathological faer regression. -pub const DENSE_EVD_QUALITY_THRESHOLD: f64 = 1e-6; - -/// Maximum acceptable max-residual from LOBPCG (Levels 1 and 3). -/// Set to 2e-5: provides ≥2× safety margin for the tightest observed fixture -/// (blobs_connected_2000 at 9.097e-6, margin = 2.20×). Tighter than rSVD (1e-2). -pub const LOBPCG_QUALITY_THRESHOLD: f64 = 2e-5; - -/// Maximum acceptable max-residual from shift-and-invert LOBPCG (Level 2). -/// Sinv achieves near-exact results (like dense EVD); 1e-6 accepts all -/// well-converged results while correctly escalating pathological graphs. -pub const SINV_LOBPCG_QUALITY_THRESHOLD: f64 = 1e-6; - -/// LOBPCG internal per-vector convergence tolerance (linfa-linalg `tol` argument). -/// Remains at 1e-5 — this is independent of `LOBPCG_QUALITY_THRESHOLD`: the former -/// controls the iterative solver's per-step stopping criterion; the latter is the -/// post-solve acceptance gate applied to the returned residuals. -pub const LOBPCG_ACCEPT_TOL: f64 = 1e-5; - -/// Linfa-linalg internal convergence tolerance for shift-invert LOBPCG. -/// Tighter than SINV_LOBPCG_QUALITY_THRESHOLD (1e-6) because this controls the iterative -/// solver's per-step residual; the outer acceptance guard (SINV_LOBPCG_QUALITY_THRESHOLD) -/// then decides whether the converged result is good enough to use. -pub const SINV_LINFA_TOL: f64 = 1e-8; - -/// Minimum eigenvalue gap to treat eigenpairs as distinct; below this use subspace comparison. -pub const DEGENERATE_GAP_THRESHOLD: f64 = 1e-6; - -/// Minimum acceptable subspace Gram determinant for quality assessment. -pub const SUBSPACE_GRAM_DET_THRESHOLD: f64 = 0.95; - -/// Empirical noise floor for eigenvalue deviation below 0.0 in faer dense EVD -/// (the tightest solver; rSVD 2-λ cancellation can reach ~1e-8, which exceeds this constant). -/// -/// After `enforce_psd_contract` is applied at the solver chain boundary, callers of -/// `solve_eigenproblem` receive eigenvalues already clamped to [0, 2] and do not need -/// to account for this floor. This constant is retained for internal diagnostic use only. -pub const PSD_NOISE_FLOOR: f64 = 1e-9; - -// ─── Accuracy metric functions ──────────────────────────────────────────────── - -/// Computes the relative residual `‖L·v − λ·v‖₂ / max(‖v‖₂, ε)` for a single eigenpair. -pub fn eigenpair_residual( - laplacian: &CsMatI, - eigenvector: &Array1, - eigenvalue: f64, -) -> f64 { - let lv = laplacian * eigenvector; - let lambda_v = eigenvector.mapv(|x| eigenvalue * x); - let diff = &lv - &lambda_v; - let v_norm = eigenvector.dot(eigenvector).sqrt().max(1e-300); - diff.dot(&diff).sqrt() / v_norm -} - -/// Returns the maximum relative residual `‖L·v − λ·v‖₂ / ‖v‖₂` over all eigenpairs. -/// -/// Delegates per-pair computation to [`eigenpair_residual`]. Returns `NaN` if any -/// individual residual is `NaN`. -pub fn max_eigenpair_residual( - laplacian: &CsMatI, - eigenvalues: &Array1, - eigenvectors: &Array2, -) -> f64 { - eigenvalues - .iter() - .enumerate() - .map(|(i, &lambda)| { - let v = eigenvectors.column(i).to_owned(); - eigenpair_residual(laplacian, &v, lambda) - }) - .fold(0.0_f64, |a, b| { - if a.is_nan() || b.is_nan() { - f64::NAN - } else { - a.max(b) - } - }) -} - -/// Computes `‖VᵀV − I‖_F` where `V` has columns `eigenvectors`. -/// -/// Returns 0.0 for a perfectly orthonormal set of columns. -pub fn orthogonality_error(eigenvectors: &Array2) -> f64 { - let k = eigenvectors.ncols(); - let vtv = eigenvectors.t().dot(eigenvectors); - let mut diff = vtv; - for i in 0..k { - diff[[i, i]] -= 1.0; - } - diff.iter().map(|x| x * x).sum::().sqrt() -} - -/// Checks whether eigenvalues are in range and sorted ascending. -/// -/// Returns `(in_range, sorted_ascending)` where: -/// - `in_range`: all `λ ∈ [−tol, 2+tol]` -/// - `sorted_ascending`: `λ[i] ≤ λ[i+1] + tol` for all `i` -pub fn check_eigenvalue_bounds(eigenvalues: &Array1, tol: f64) -> (bool, bool) { - assert!( - tol >= 0.0, - "check_eigenvalue_bounds: tol must be non-negative, got {}", - tol - ); - let in_range = eigenvalues.iter().all(|&v| v >= -tol && v <= 2.0 + tol); - let sorted = eigenvalues - .windows(2) - .into_iter() - .all(|w| w[0] <= w[1] + tol); - (in_range, sorted) -} - -/// Computes the separation ratio `min_inter_centroid_distance / max_intra_component_spread` -/// for a disconnected-graph embedding. -/// -/// `labels` assigns each row of `embedding` to a component index in `0..n_components`. -/// Returns `f64::INFINITY` when `max_intra == 0.0` (all points collapse to centroids). -pub fn separation_ratio(embedding: ArrayView2, labels: &[usize]) -> f64 { - let n = labels.len(); - assert_eq!( - embedding.nrows(), - n, - "embedding rows must match labels length" - ); - let n_dims = embedding.ncols(); - - let n_components = labels.iter().copied().max().map(|m| m + 1).unwrap_or(0); - if n_components < 2 { - return f64::INFINITY; - } - - let mut component_members: Vec> = vec![Vec::new(); n_components]; - for (i, &label) in labels.iter().enumerate() { - component_members[label].push(i); - } - - let centroids: Vec> = component_members - .iter() - .map(|members| { - let n_c = members.len() as f64; - let mut c = vec![0.0f64; n_dims]; - for &orig_i in members { - for d in 0..n_dims { - c[d] += embedding[[orig_i, d]]; - } - } - c.iter_mut().for_each(|x| *x /= n_c); - c - }) - .collect(); - - let min_inter = (0..n_components) - .flat_map(|i| ((i + 1)..n_components).map(move |j| (i, j))) - .map(|(i, j)| { - (0..n_dims) - .map(|d| (centroids[i][d] - centroids[j][d]).powi(2)) - .sum::() - .sqrt() - }) - .fold(f64::INFINITY, f64::min); - - let max_intra = component_members - .iter() - .enumerate() - .map(|(c_idx, members)| { - members - .iter() - .map(|&orig_i| { - (0..n_dims) - .map(|d| (embedding[[orig_i, d]] - centroids[c_idx][d]).powi(2)) - .sum::() - .sqrt() - }) - .fold(0.0f64, f64::max) - }) - .fold(0.0f64, f64::max); - - if max_intra > 0.0 { - min_inter / max_intra - } else { - f64::INFINITY - } -} - -// ─── Parity metric functions ────────────────────────────────────────────────── - -/// Element-wise `|computed[i] − reference[i]|`. -/// -/// # Panics -/// Panics if `computed` and `reference` have different lengths. -pub fn eigenvalue_abs_errors(computed: &Array1, reference: &Array1) -> Array1 { - assert_eq!( - computed.len(), - reference.len(), - "eigenvalue_abs_errors: lengths must match ({} vs {})", - computed.len(), - reference.len() - ); - (computed - reference).mapv(f64::abs) -} - -/// Computes `|det(G)|` for the 2×2 cross-Gram matrix of two n×2 subspaces. -/// -/// Each column is normalized by its L2 norm before building the cross-Gram matrix: -/// `G[i,j] = dot(r_i / ‖r_i‖, u_j / ‖u_j‖)`. -/// Returns `|a·d − b·c|` where `[[a,b],[c,d]]` is the normalized 2×2 Gram matrix. -pub fn subspace_gram_det(u: ArrayView2, r: ArrayView2) -> f64 { - assert_eq!( - u.ncols(), - 2, - "subspace_gram_det: u must have exactly 2 columns" - ); - assert_eq!( - r.ncols(), - 2, - "subspace_gram_det: r must have exactly 2 columns" - ); - assert_eq!( - u.nrows(), - r.nrows(), - "subspace_gram_det: u and r must have the same number of rows" - ); - - let norm = |v: ArrayView1| v.iter().map(|x| x * x).sum::().sqrt().max(1e-300); - let dot = |a: ArrayView1, b: ArrayView1| -> f64 { - a.iter().zip(b.iter()).map(|(x, y)| x * y).sum() - }; - - let v1 = u.column(0); - let v2 = u.column(1); - let r1 = r.column(0); - let r2 = r.column(1); - - let n1 = norm(v1); - let n2 = norm(v2); - let nr1 = norm(r1); - let nr2 = norm(r2); - - let a = dot(r1, v1) / (nr1 * n1); - let b = dot(r1, v2) / (nr1 * n2); - let c = dot(r2, v1) / (nr2 * n1); - let d = dot(r2, v2) / (nr2 * n2); - - (a * d - b * c).abs() -} - -/// k-dimensional generalization of [`subspace_gram_det`]. -/// -/// Steps: -/// 1. Normalize each column of both inputs by its L2 norm. -/// 2. Compute the k×k cross-Gram matrix `G = reference_norm^T · computed_norm`. -/// 3. Compute the SVD of `G` via the eigendecomposition of `GᵀG` (using faer). -/// 4. Return the product of singular values, which equals `|det(G)|` for square `G`. -pub fn subspace_gram_det_kd(computed: ArrayView2, reference: ArrayView2) -> f64 { - let k = computed.ncols(); - assert_eq!( - reference.ncols(), - k, - "subspace_gram_det_kd: computed and reference must have the same number of columns" - ); - assert_eq!( - computed.nrows(), - reference.nrows(), - "subspace_gram_det_kd: computed and reference must have the same number of rows" - ); - - // Normalize each column - let normalize = |mat: ArrayView2| -> Array2 { - let mut norm_mat = Array2::::zeros(mat.dim()); - for (j, col) in mat.columns().into_iter().enumerate() { - let norm = col.dot(&col).sqrt().max(f64::EPSILON); - for (i, &v) in col.iter().enumerate() { - norm_mat[[i, j]] = v / norm; - } - } - norm_mat - }; - - let cn = normalize(computed); - let rn = normalize(reference); - - // G = rn^T · cn (k × k cross-Gram matrix) - let g = rn.t().dot(&cn); - - // G^T G is symmetric PSD; its eigenvalues are the squares of the singular values of G. - let gtg = g.t().dot(&g); - let gtg_faer = FaerMat::from_fn(k, k, |i, j| gtg[[i, j]]); - let eigen = SelfAdjointEigen::new(gtg_faer.as_ref(), Side::Lower) - .expect("subspace_gram_det_kd: SelfAdjointEigen failed on G^T G"); - - // sqrt(product of eigenvalues of G^T G) = product of singular values = |det(G)| - let mut det_sq = 1.0f64; - eigen.S().for_each(|&x| det_sq *= x.max(0.0)); - det_sq.sqrt() -} - -/// Sign-agnostic maximum column-wise error between `computed` and `reference`. -/// -/// For each column, computes `min(‖col_rust − col_ref‖∞, ‖col_rust + col_ref‖∞)`. -/// Returns the maximum such value across all columns. -/// -/// Inputs are `f32`; internal arithmetic is in `f64` for precision. -pub fn sign_agnostic_max_error(computed: &Array2, reference: &Array2) -> f64 { - assert_eq!( - computed.ncols(), - reference.ncols(), - "sign_agnostic_max_error: column count mismatch" - ); - assert_eq!( - computed.nrows(), - reference.nrows(), - "sign_agnostic_max_error: row count mismatch" - ); - - let mut worst = 0.0f64; - for col in 0..computed.ncols() { - let r = computed.column(col); - let rf = reference.column(col); - let err_pos: f64 = r - .iter() - .zip(rf.iter()) - .map(|(&a, &b)| (a as f64 - b as f64).abs()) - .fold(0.0f64, f64::max); - let err_neg: f64 = r - .iter() - .zip(rf.iter()) - .map(|(&a, &b)| (a as f64 + b as f64).abs()) - .fold(0.0f64, f64::max); - worst = worst.max(err_pos.min(err_neg)); - } - worst -} - -// ─── Diagnostic functions ───────────────────────────────────────────────────── - -/// Returns `threshold / worst_value`. -/// -/// Returns `f64::INFINITY` if `worst_value == 0.0`. -pub fn tolerance_margin(threshold: f64, worst_value: f64) -> f64 { - if worst_value == 0.0 { - f64::INFINITY - } else { - threshold / worst_value - } -} - -/// Returns `eigenvalues[1] − eigenvalues[0]` (λ₂ − λ₁). -/// -/// # Panics -/// Panics if `eigenvalues` has fewer than 2 elements. -pub fn spectral_gap(eigenvalues: &Array1) -> f64 { - assert!( - eigenvalues.len() >= 2, - "spectral_gap: need at least 2 eigenvalues" - ); - eigenvalues[1] - eigenvalues[0] -} - -/// Returns `eigenvalues[last] / eigenvalues[1]` (λ_last / λ₂). -/// -/// Returns `f64::INFINITY` if `eigenvalues[1] == 0.0`. -/// -/// # Panics -/// Panics if `eigenvalues` has fewer than 2 elements. -pub fn eigenvalue_condition_number(eigenvalues: &Array1) -> f64 { - assert!( - eigenvalues.len() >= 2, - "eigenvalue_condition_number: need at least 2 eigenvalues" - ); - if eigenvalues[1] == 0.0 { - f64::INFINITY - } else { - eigenvalues[eigenvalues.len() - 1] / eigenvalues[1] - } -} - -// ─── AVX2+FMA squared-distance kernel ──────────────────────────────────────── - -/// Squared Euclidean distance using AVX2+FMA intrinsics, looped over all elements. -/// -/// 4-wide YMM loop with FMA accumulation, horizontal reduce, scalar tail 0-3. -/// -/// # Safety -/// Both slices must have the same length and at least 10 elements (caller ensures -/// `xi.len() == xj.len()` and `d_x >= 10` at the dispatch site). -#[doc(hidden)] -#[cfg(target_arch = "x86_64")] -#[target_feature(enable = "avx2,fma")] -pub unsafe fn dist_sq_avx2_looped(xi: &[f64], xj: &[f64]) -> f64 { - debug_assert_eq!( - xi.len(), - xj.len(), - "dist_sq_avx2_looped: slices must have equal length" - ); - use std::arch::x86_64::*; - let n = xi.len().min(xj.len()); - unsafe { - let mut acc = _mm256_setzero_pd(); - let mut k = 0usize; - while k + 4 <= n { - let a = _mm256_loadu_pd(xi.as_ptr().add(k)); - let b = _mm256_loadu_pd(xj.as_ptr().add(k)); - let d = _mm256_sub_pd(a, b); - acc = _mm256_fmadd_pd(d, d, acc); - k += 4; - } - // Horizontal reduce: sum 4 lanes - let lo = _mm256_castpd256_pd128(acc); - let hi = _mm256_extractf128_pd(acc, 1); - let sum128 = _mm_add_pd(lo, hi); - let halved = _mm_hadd_pd(sum128, sum128); - let mut result = _mm_cvtsd_f64(halved); - // Scalar tail (0–3 remaining elements) - while k < n { - let d = xi[k] - xj[k]; - result += d * d; - k += 1; - } - result - } -} - -/// Batch squared Euclidean distances from a 2D query point to `n` target points -/// stored in row-major layout (`y_flat`, stride 2). Processes two target points per -/// SIMD iteration using `_mm256_hadd_pd` for horizontal reduction. -/// -/// # Safety -/// - `yi` must have exactly 2 elements. -/// - `y_flat` must have at least `n * 2` elements (row-major, d_y = 2). -/// - `out` must have at least `n` elements. -/// -/// Called only when `d_y == 2`, `y.is_standard_layout()`, and `avx2` is detected at runtime. -#[cfg(target_arch = "x86_64")] -#[target_feature(enable = "avx2")] -unsafe fn dist_sq_2d_avx2_batch(yi: &[f64], y_flat: &[f64], n: usize, out: &mut [f64]) { - use std::arch::x86_64::*; - debug_assert!(yi.len() >= 2, "yi must have at least 2 elements"); - debug_assert!( - y_flat.len() >= n * 2, - "y_flat must have at least n*2 elements" - ); - debug_assert!(out.len() >= n, "out must have at least n elements"); - unsafe { - // Broadcast query: [yi[1], yi[0], yi[1], yi[0]] — _mm256_set_pd args are (e3,e2,e1,e0) - let yi_bc = _mm256_set_pd(yi[1], yi[0], yi[1], yi[0]); - let mut j = 0usize; - while j + 1 < n { - // Load two target points: [yj[0], yj[1], yj+1[0], yj+1[1]] - debug_assert!(j * 2 + 3 < y_flat.len(), "y_flat bounds exceeded at j={j}"); - let yj_pair = _mm256_loadu_pd(y_flat.as_ptr().add(j * 2)); - let diff = _mm256_sub_pd(yi_bc, yj_pair); - let sq = _mm256_mul_pd(diff, diff); - // hadd: lower 128-bit → sq[0]+sq[1] = dist_j; upper 128-bit → sq[2]+sq[3] = dist_{j+1} - let hadd = _mm256_hadd_pd(sq, sq); - out[j] = _mm_cvtsd_f64(_mm256_castpd256_pd128(hadd)); - out[j + 1] = _mm_cvtsd_f64(_mm256_extractf128_pd(hadd, 1)); - j += 2; - } - // Scalar tail for odd n - if j < n { - let base = j * 2; - let d0 = yi[0] - y_flat[base]; - let d1 = yi[1] - y_flat[base + 1]; - out[j] = d0 * d0 + d1 * d1; - } - } -} - -// ─── Trustworthiness metric ─────────────────────────────────────────────────── - -/// Computes the trustworthiness metric T(k) — a measure of how well the k-nearest-neighbor -/// structure of X (high-dimensional) is preserved in Y (embedding). -/// -/// Uses partial rank (introselect) for O(n)-average X-NN detection, thread-local -/// scratch buffers to eliminate per-row allocations, and AVX2+FMA SIMD dispatch -/// for X-distance computation when dimensionality >= 10. -/// -/// # Formula -/// `T(k) = 1 − (2 / (n·k·(2n−3k−1))) · Σᵢ Σ_{j ∈ U_i(k)} (r(i,j) − k)` -/// -/// where `r(i,j)` is the 0-indexed rank of j in the distance ordering from i in X -/// (self = rank 0), and `U_i(k)` is the set of j in k-NN(i, Y) but NOT in k-NN(i, X). -/// -/// # Panics -/// Panics if `k == 0`, `k >= n / 2`, or if `x` and `y` have different row counts. -/// The `k < n/2` restriction is required by the normalization denominator -/// `G_k = n·k·(2n−3k−1)`: when `k ≥ n/2` this denominator produces T > 1. -/// The guard uses integer floor division (`n / 2`), matching sklearn's exact boundary -/// condition (`n_neighbors >= n // 2` raises `ValueError` in sklearn). -/// Shared inner kernel for [`trustworthiness`] and [`trustworthiness_subsampled`]. -/// -/// `query_indices` selects which rows participate as outer "query" points; values -/// must lie in `[0, n)` and should be unique (duplicates would double-count their -/// penalty contribution). The per-row computation always runs against the full -/// `n`-point population. Only the leading factor of the normalization denominator -/// uses `m = query_indices.len()` — the `(2n − 3k − 1)` factor still uses the -/// full population `n`. -pub(crate) fn trustworthiness_inner( - x: ArrayView2, - y: ArrayView2, - k: usize, - query_indices: Option<&[usize]>, -) -> f64 { - use std::cell::RefCell; - let n = x.nrows(); - assert_eq!( - y.nrows(), - n, - "trustworthiness: x and y must have the same number of rows" - ); - assert!(k > 0, "trustworthiness: k must be > 0"); - assert!( - k < n / 2, - "trustworthiness: k must be < n/2 (got k={k}, n={n}, n/2={}); \ - this constraint is required by the normalization denominator and matches sklearn's ValueError", - n / 2 - ); - let m_query = query_indices.map_or(n, |q| q.len()); - - #[cfg(feature = "profiling")] - { - use std::sync::atomic::Ordering; - X_DIST_NS.store(0, Ordering::Relaxed); - X_SORT_NS.store(0, Ordering::Relaxed); - Y_DIST_NS.store(0, Ordering::Relaxed); - PENALTY_NS.store(0, Ordering::Relaxed); - } - - #[cfg(target_arch = "x86_64")] - let use_avx2 = is_x86_feature_detected!("avx2") && is_x86_feature_detected!("fma"); - #[cfg(target_arch = "x86_64")] - let d_x = x.ncols(); - - #[cfg(target_arch = "x86_64")] - let use_avx2_y = - { y.ncols() == 2 && y.is_standard_layout() && is_x86_feature_detected!("avx2") }; - - // Validate contiguity once before the parallel loop: SIMD dispatch requires C-contiguous rows. - #[cfg(target_arch = "x86_64")] - if use_avx2 && d_x >= 10 { - assert!( - x.is_standard_layout(), - "trustworthiness: x must be in C-contiguous (standard) layout for SIMD dispatch" - ); - } - - thread_local! { - static COMB_DIST_X: RefCell> = const { RefCell::new(Vec::new()) }; - static COMB_INDICES: RefCell> = const { RefCell::new(Vec::new()) }; - } - - thread_local! { - static COMB_DIST_Y: RefCell> = const { RefCell::new(Vec::new()) }; - static COMB_INDICES_Y: RefCell> = const { RefCell::new(Vec::new()) }; - } - - #[cfg(feature = "profiling")] - static X_DIST_NS: std::sync::atomic::AtomicU64 = std::sync::atomic::AtomicU64::new(0); - #[cfg(feature = "profiling")] - static X_SORT_NS: std::sync::atomic::AtomicU64 = std::sync::atomic::AtomicU64::new(0); - #[cfg(feature = "profiling")] - static Y_DIST_NS: std::sync::atomic::AtomicU64 = std::sync::atomic::AtomicU64::new(0); - #[cfg(feature = "profiling")] - static PENALTY_NS: std::sync::atomic::AtomicU64 = std::sync::atomic::AtomicU64::new(0); - - let process_row = |i: usize| -> f64 { - let xi = x.row(i); - let yi = y.row(i); - - COMB_DIST_X.with(|dist_x_cell| { - COMB_INDICES.with(|indices_cell| { - let mut dist_x = dist_x_cell.borrow_mut(); - let mut indices = indices_cell.borrow_mut(); - - // ── x_dist step ────────────────────────────────────────────── - #[cfg(feature = "profiling")] - let t_x_dist = std::time::Instant::now(); - - dist_x.clear(); - dist_x.resize(n, 0.0f64); - for j in 0..n { - let xj = x.row(j); - dist_x[j] = { - #[cfg(target_arch = "x86_64")] - { - if use_avx2 && d_x >= 10 { - let si = xi.as_slice().expect("x row must be contiguous"); - let sj = xj.as_slice().expect("x row must be contiguous"); - // SAFETY: runtime + d_x check guarantees AVX2+FMA and >= 10 elements. - unsafe { dist_sq_avx2_looped(si, sj) } - } else { - xi.iter() - .zip(xj.iter()) - .map(|(&a, &b)| (a - b) * (a - b)) - .sum() - } - } - #[cfg(not(target_arch = "x86_64"))] - { - xi.iter() - .zip(xj.iter()) - .map(|(&a, &b)| (a - b) * (a - b)) - .sum() - } - }; - } - - #[cfg(feature = "profiling")] - X_DIST_NS.fetch_add( - t_x_dist.elapsed().as_nanos() as u64, - std::sync::atomic::Ordering::Relaxed, - ); - - // ── x_sort step ────────────────────────────────────────────── - #[cfg(feature = "profiling")] - let t_x_sort = std::time::Instant::now(); - - indices.clear(); - indices.extend(0..n); - indices.select_nth_unstable_by(k, |&a, &b| { - dist_x[a].total_cmp(&dist_x[b]).then(a.cmp(&b)) - }); - - let knn_x_set: HashSet = - indices[..=k].iter().filter(|&&m| m != i).copied().collect(); - - #[cfg(feature = "profiling")] - X_SORT_NS.fetch_add( - t_x_sort.elapsed().as_nanos() as u64, - std::sync::atomic::Ordering::Relaxed, - ); - - // ── y_dist step (flat_simd, replaces BinaryHeap) ───────────── - #[cfg(feature = "profiling")] - let t_y_dist = std::time::Instant::now(); - - COMB_DIST_Y.with(|dy_cell| { - COMB_INDICES_Y.with(|iy_cell| { - let mut dist_y = dy_cell.borrow_mut(); - let mut indices_y = iy_cell.borrow_mut(); - - dist_y.clear(); - dist_y.resize(n, 0.0f64); - - // Fill Y distances: AVX2 2D batch or scalar fallback. - #[cfg(target_arch = "x86_64")] - if use_avx2_y { - let y_flat = y - .as_slice() - .expect("y must be standard layout for AVX2 dispatch"); - let yi_slice = &y_flat[i * 2..(i + 1) * 2]; - // SAFETY: y_flat has n*d_y elements; yi_slice has 2 elements; - // dist_y has n elements; use_avx2_y guarantees d_y==2, - // standard_layout, and runtime AVX2. - unsafe { - dist_sq_2d_avx2_batch(yi_slice, y_flat, n, &mut dist_y); - } - } else { - for j in 0..n { - let yj = y.row(j); - dist_y[j] = yi - .iter() - .zip(yj.iter()) - .map(|(&a, &b)| (a - b) * (a - b)) - .sum(); - } - } - #[cfg(not(target_arch = "x86_64"))] - { - for j in 0..n { - let yj = y.row(j); - dist_y[j] = yi - .iter() - .zip(yj.iter()) - .map(|(&a, &b)| (a - b) * (a - b)) - .sum(); - } - } - - dist_y[i] = f64::INFINITY; // self-exclusion - - indices_y.clear(); - indices_y.extend(0..n); - indices_y.select_nth_unstable_by(k, |&a, &b| { - dist_y[a].total_cmp(&dist_y[b]).then(a.cmp(&b)) - }); - - #[cfg(feature = "profiling")] - Y_DIST_NS.fetch_add( - t_y_dist.elapsed().as_nanos() as u64, - std::sync::atomic::Ordering::Relaxed, - ); - - // ── penalty step ────────────────────────────────────── - #[cfg(feature = "profiling")] - let t_penalty = std::time::Instant::now(); - - let mut row_penalty = 0u64; - for &j in &indices_y[..k] { - if !knn_x_set.contains(&j) { - let dj = dist_x[j]; - let rank: usize = (0..n) - .filter(|&m| dist_x[m] < dj || (dist_x[m] == dj && m < j)) - .count(); - row_penalty += (rank - k) as u64; - } - } - - #[cfg(feature = "profiling")] - PENALTY_NS.fetch_add( - t_penalty.elapsed().as_nanos() as u64, - std::sync::atomic::Ordering::Relaxed, - ); - - row_penalty as f64 - }) - }) - }) - }) - }; - - let penalty_sum: f64 = match query_indices { - None => (0..n).into_par_iter().map(&process_row).sum(), - Some(qi) => qi.par_iter().copied().map(&process_row).sum(), - }; - - #[cfg(feature = "profiling")] - { - use std::sync::atomic::Ordering; - eprintln!("[timing:x_dist] {}", X_DIST_NS.load(Ordering::Relaxed)); - eprintln!("[timing:x_sort] {}", X_SORT_NS.load(Ordering::Relaxed)); - eprintln!("[timing:y_dist] {}", Y_DIST_NS.load(Ordering::Relaxed)); - eprintln!("[timing:penalty] {}", PENALTY_NS.load(Ordering::Relaxed)); - } - - let denom = m_query as f64 * k as f64 * (2 * n).saturating_sub(3 * k + 1) as f64; - 1.0 - penalty_sum * 2.0 / denom -} - -pub fn trustworthiness(x: ArrayView2, y: ArrayView2, k: usize) -> f64 { - trustworthiness_inner(x, y, k, None) -} - -/// Sub-sampled trustworthiness: evaluates only `m` randomly chosen query rows -/// against the full `n`-point population. -/// -/// Identical to [`trustworthiness`] except that the outer iteration is restricted -/// to `m` query rows sampled uniformly without replacement using `seed`. The -/// per-row computation (full pairwise X-distances, full Y k-NN, rank penalty -/// scan) still runs against all `n` points — only the outer iterator and the -/// leading denominator factor change. -/// -/// # Formula -/// `T(k, m) = 1 − (2 / (m·k·(2n−3k−1))) · Σ_{i ∈ Q} Σ_{j ∈ U_i(k)} (r(i,j) − k)` -/// -/// where `Q ⊂ [0, n)` is the set of `m` sampled query rows. The -/// `(2n − 3k − 1)` factor uses the full population `n`, so when `m == n` the -/// result is identical to `trustworthiness(x, y, k)`. -/// -/// # Determinism -/// The sample is reproducible: equal `seed` values produce equal row sets. -/// When `m == n`, the function bypasses sampling entirely and uses the full -/// `0..n` range, guaranteeing parity with `trustworthiness`. -/// -/// # Panics -/// Panics if `k == 0`, `k >= n / 2`, `m == 0`, `m > n`, or if `x` and `y` have -/// different row counts. -pub fn trustworthiness_subsampled( - x: ArrayView2, - y: ArrayView2, - k: usize, - m: usize, - seed: u64, -) -> f64 { - let n = x.nrows(); - assert!(m > 0, "trustworthiness_subsampled: m must be > 0"); - assert!( - m <= n, - "trustworthiness_subsampled: m must be <= n (got m={m}, n={n})" - ); - - if m == n { - return trustworthiness_inner(x, y, k, None); - } - - use rand::SeedableRng; - let mut rng = rand::rngs::SmallRng::seed_from_u64(seed); - let query_indices = rand::seq::index::sample(&mut rng, n, m).into_vec(); - trustworthiness_inner(x, y, k, Some(&query_indices)) -} - -// ─── Data structures (testing feature only) ────────────────────────────────── - -#[cfg(feature = "testing")] -#[derive(Debug, Clone, serde::Serialize, serde::Deserialize)] -pub struct MetricResult { - pub name: String, - pub dimension: usize, - pub value: f64, - pub threshold: f64, - pub passed: bool, -} - -#[cfg(feature = "testing")] -#[derive(Debug, Clone, serde::Serialize, serde::Deserialize)] -pub struct AssessmentReport { - pub dataset: String, - pub n: usize, - pub metrics: Vec, -} - -#[cfg(feature = "testing")] -#[derive(Debug, Clone, serde::Serialize, serde::Deserialize)] -pub struct ExperimentMetrics { - pub generated_at: String, - pub datasets: Vec, -} - -// ─── Unit Tests ─────────────────────────────────────────────────────────────── - -#[cfg(test)] -mod tests { - use super::*; - - /// 3-node path Laplacian: [[1,-1,0],[-1,2,-1],[0,-1,1]] - fn path_laplacian_3() -> CsMatI { - CsMatI::new( - (3, 3), - vec![0usize, 2, 5, 7], - vec![0usize, 1, 0, 1, 2, 1, 2], - vec![1.0_f64, -1.0, -1.0, 2.0, -1.0, -1.0, 1.0], - ) - } - - // ── Threshold constants ─────────────────────────────────────────────────── - - #[test] - fn t_const_01_all_7_constants_have_required_values() { - assert_eq!(DENSE_EVD_QUALITY_THRESHOLD, 1e-6_f64); - assert_eq!(LOBPCG_QUALITY_THRESHOLD, 2e-5_f64); - assert_eq!(SINV_LOBPCG_QUALITY_THRESHOLD, 1e-6_f64); - assert_eq!(RSVD_QUALITY_THRESHOLD, 1e-2_f64); - assert_eq!(LOBPCG_ACCEPT_TOL, 1e-5_f64); - assert_eq!(DEGENERATE_GAP_THRESHOLD, 1e-6_f64); - assert_eq!(SUBSPACE_GRAM_DET_THRESHOLD, 0.95_f64); - } - - #[test] - fn t_const_02_threshold_ordering() { - assert_eq!(DENSE_EVD_QUALITY_THRESHOLD, SINV_LOBPCG_QUALITY_THRESHOLD); - const { assert!(SINV_LOBPCG_QUALITY_THRESHOLD < LOBPCG_QUALITY_THRESHOLD) }; - const { assert!(LOBPCG_QUALITY_THRESHOLD < RSVD_QUALITY_THRESHOLD) }; - } - - // ── Accuracy: eigenpair_residual ───────────────────────────────────────── - - #[test] - fn t_eresid_01_trivial_eigenvector_near_zero() { - let laplacian = path_laplacian_3(); - let s = 1.0_f64 / 3.0_f64.sqrt(); - let v = Array1::from_vec(vec![s, s, s]); - let residual = eigenpair_residual(&laplacian, &v, 0.0); - assert!( - residual < 1e-10, - "trivial eigenvector residual={residual:.2e}, expected < 1e-10" - ); - } - - #[test] - fn t_eresid_02_non_eigenvector_large_residual() { - let laplacian = path_laplacian_3(); - let v = Array1::from_vec(vec![1.0_f64, 0.0, 0.0]); - let residual = eigenpair_residual(&laplacian, &v, 0.0); - assert!( - residual >= RSVD_QUALITY_THRESHOLD, - "non-eigenvector residual={residual:.2e}, expected >= RSVD_QUALITY_THRESHOLD={RSVD_QUALITY_THRESHOLD:.2e}" - ); - } - - // ── Accuracy: max_eigenpair_residual ───────────────────────────────────── - - #[test] - fn t_maxresid_01_returns_worst_across_two_eigenpairs() { - let laplacian = path_laplacian_3(); - // Trivial eigenvector at λ=0: small residual - let s = 1.0_f64 / 3.0_f64.sqrt(); - // Non-eigenvector at λ=0: large residual - let eigenvalues = Array1::from_vec(vec![0.0_f64, 0.0_f64]); - let eigenvectors = - Array2::from_shape_vec((3, 2), vec![s, 1.0_f64, s, 0.0_f64, s, 0.0_f64]).unwrap(); - let max_res = max_eigenpair_residual(&laplacian, &eigenvalues, &eigenvectors); - // The second column [1,0,0] has a large residual; max must reflect that. - assert!( - max_res >= RSVD_QUALITY_THRESHOLD, - "max_residual={max_res:.2e}, expected >= RSVD_QUALITY_THRESHOLD" - ); - } - - // ── Accuracy: orthogonality_error ──────────────────────────────────────── - - #[test] - fn t_ortho_01_identity_columns_zero_error() { - let v = Array2::::eye(3); - let err = orthogonality_error(&v); - assert!( - err < 1e-14, - "identity orthogonality_error={err:.2e}, expected ≈ 0" - ); - } - - #[test] - fn t_ortho_02_non_orthogonal_positive_error() { - let v = Array2::from_shape_vec( - (3, 2), - vec![1.0_f64, 1.0_f64, 0.0_f64, 1.0_f64, 0.0_f64, 0.0_f64], - ) - .unwrap(); - let err = orthogonality_error(&v); - assert!( - err > 0.0, - "non-orthogonal matrix should have positive error, got {err:.2e}" - ); - } - - // ── Accuracy: check_eigenvalue_bounds ──────────────────────────────────── - - #[test] - fn t_bounds_01_valid_range_and_sorted() { - let eigs = Array1::from_vec(vec![0.0_f64, 0.5, 1.0]); - assert_eq!(check_eigenvalue_bounds(&eigs, 1e-8), (true, true)); - } - - #[test] - fn t_bounds_02_negative_eigenvalue_out_of_range() { - let eigs = Array1::from_vec(vec![-0.1_f64, 0.5]); - assert_eq!(check_eigenvalue_bounds(&eigs, 1e-8), (false, true)); - } - - #[test] - fn t_bounds_03_unsorted_eigenvalues() { - let eigs = Array1::from_vec(vec![0.5_f64, 0.1]); - assert_eq!(check_eigenvalue_bounds(&eigs, 1e-8), (true, false)); - } - - // ── Accuracy: separation_ratio ─────────────────────────────────────────── - - #[test] - fn t_sep_01_well_separated_clusters() { - // 4 points: cluster 0 near [0,0], cluster 1 near [10,0] - let data = vec![0.0_f64, 0.0, 0.1, 0.0, 10.0, 0.0, 10.1, 0.0]; - let embedding = Array2::from_shape_vec((4, 2), data).unwrap(); - let labels = vec![0usize, 0, 1, 1]; - let ratio = separation_ratio(embedding.view(), &labels); - assert!( - ratio > 1.0, - "well-separated clusters should have ratio > 1.0, got {ratio:.4}" - ); - } - - #[test] - fn t_sep_02_overlapping_clusters() { - // 4 points where intra-cluster spread > inter-centroid distance - let data = vec![0.0_f64, 0.0, 3.0, 0.0, 1.0, 0.0, 4.0, 0.0]; - let embedding = Array2::from_shape_vec((4, 2), data).unwrap(); - let labels = vec![0usize, 0, 1, 1]; - let ratio = separation_ratio(embedding.view(), &labels); - // Centroids [1.5,0] and [2.5,0]: inter=1.0, max_intra=1.5. ratio=0.667 - assert!( - ratio <= 1.0, - "overlapping clusters should have ratio <= 1.0, got {ratio:.4}" - ); - } - - // ── Parity: eigenvalue_abs_errors ──────────────────────────────────────── - - #[test] - fn t_abserr_01_basic_errors() { - let computed = Array1::from_vec(vec![1.0_f64, 2.0]); - let reference = Array1::from_vec(vec![1.1_f64, 2.2]); - let errors = eigenvalue_abs_errors(&computed, &reference); - assert!( - (errors[0] - 0.1).abs() < 1e-14, - "errors[0]={:.6e}, expected 0.1", - errors[0] - ); - assert!( - (errors[1] - 0.2).abs() < 1e-14, - "errors[1]={:.6e}, expected 0.2", - errors[1] - ); - } - - // ── Parity: subspace_gram_det ──────────────────────────────────────────── - - #[test] - fn t_gram2d_01_parallel_subspace_near_one() { - // u = r = [[1,0],[0,1],[0,0]] (orthonormal columns) - let data = vec![1.0_f64, 0.0, 0.0, 1.0, 0.0, 0.0]; - let u = Array2::from_shape_vec((3, 2), data.clone()).unwrap(); - let r = Array2::from_shape_vec((3, 2), data).unwrap(); - let det = subspace_gram_det(u.view(), r.view()); - assert!( - (det - 1.0).abs() < 1e-12, - "parallel orthonormal subspace: det={det:.6e}, expected ≈ 1.0" - ); - } - - #[test] - fn t_gram2d_02_orthogonal_subspace_near_zero() { - // u spans {e1, e2}, r spans {e3, e4} - let u_data = vec![1.0_f64, 0.0, 0.0, 1.0, 0.0, 0.0, 0.0, 0.0]; - let r_data = vec![0.0_f64, 0.0, 0.0, 0.0, 1.0, 0.0, 0.0, 1.0]; - let u = Array2::from_shape_vec((4, 2), u_data).unwrap(); - let r = Array2::from_shape_vec((4, 2), r_data).unwrap(); - let det = subspace_gram_det(u.view(), r.view()); - assert!( - det < 1e-12, - "orthogonal subspaces: det={det:.6e}, expected ≈ 0.0" - ); - } - - // ── Parity: subspace_gram_det_kd ───────────────────────────────────────── - - #[test] - fn t_gramkd_01_same_subspace_near_one() { - // k=3 identity columns in R^3 - let eye = Array2::::eye(3); - let det = subspace_gram_det_kd(eye.view(), eye.view()); - assert!( - (det - 1.0).abs() < 1e-10, - "same subspace: det={det:.6e}, expected ≈ 1.0" - ); - } - - #[test] - fn t_gramkd_02_orthogonal_subspaces_near_zero() { - // computed spans {e1,e2}, reference spans {e3,e4} in R^4 - let comp_data = vec![1.0_f64, 0.0, 0.0, 0.0, 0.0, 1.0, 0.0, 0.0]; - let ref_data = vec![0.0_f64, 0.0, 1.0, 0.0, 0.0, 0.0, 0.0, 1.0]; - let comp = Array2::from_shape_vec((4, 2), comp_data).unwrap(); - let reff = Array2::from_shape_vec((4, 2), ref_data).unwrap(); - let det = subspace_gram_det_kd(comp.view(), reff.view()); - assert!( - det < 1e-10, - "orthogonal subspaces: det={det:.6e}, expected ≈ 0.0" - ); - } - - // ── Parity: sign_agnostic_max_error ────────────────────────────────────── - - #[test] - fn t_signerr_01_identical_arrays_zero_error() { - let data = vec![1.0_f32, 2.0, 3.0, 4.0]; - let arr = Array2::from_shape_vec((4, 1), data).unwrap(); - let err = sign_agnostic_max_error(&arr, &arr); - assert_eq!(err, 0.0, "identical arrays: error={err:.2e}, expected 0.0"); - } - - #[test] - fn t_signerr_02_negated_columns_zero_error() { - let computed_data = vec![1.0_f32, -2.0, 3.0, -4.0]; - let reference_data = vec![-1.0_f32, 2.0, -3.0, 4.0]; - let computed = Array2::from_shape_vec((4, 1), computed_data).unwrap(); - let reference = Array2::from_shape_vec((4, 1), reference_data).unwrap(); - let err = sign_agnostic_max_error(&computed, &reference); - assert_eq!( - err, 0.0, - "fully negated column: error={err:.2e}, expected 0.0" - ); - } - - #[test] - fn t_signerr_03_small_perturbation_small_error() { - let reference_data = vec![1.0_f32, 2.0, 3.0, 4.0]; - let computed_data = vec![1.01_f32, 2.01, 3.01, 4.01]; - let reference = Array2::from_shape_vec((4, 1), reference_data).unwrap(); - let computed = Array2::from_shape_vec((4, 1), computed_data).unwrap(); - let err = sign_agnostic_max_error(&computed, &reference); - assert!( - err > 0.0 && err < 0.1, - "small perturbation: error={err:.4e}, expected small positive" - ); - } - - // ── Diagnostic: tolerance_margin ───────────────────────────────────────── - - #[test] - fn t_tolmargin_01_basic() { - let margin = tolerance_margin(1e-5, 5e-6); - assert!( - (margin - 2.0).abs() < 1e-12, - "tolerance_margin={margin:.6e}, expected 2.0" - ); - } - - #[test] - fn t_tolmargin_02_zero_worst_value_returns_infinity() { - let margin = tolerance_margin(1e-5, 0.0); - assert!( - margin.is_infinite() && margin > 0.0, - "tolerance_margin with worst_value=0.0 should be +∞, got {margin:.6e}" - ); - } - - // ── Diagnostic: spectral_gap ────────────────────────────────────────────── - - #[test] - fn t_specgap_01_basic() { - let eigs = Array1::from_vec(vec![0.0_f64, 0.5, 1.0]); - let gap = spectral_gap(&eigs); - assert!( - (gap - 0.5).abs() < 1e-14, - "spectral_gap={gap:.6e}, expected 0.5" - ); - } - - // ── Diagnostic: eigenvalue_condition_number ─────────────────────────────── - - #[test] - fn t_condnum_01_basic() { - let eigs = Array1::from_vec(vec![0.0_f64, 0.5, 1.0]); - let cn = eigenvalue_condition_number(&eigs); - assert!( - (cn - 2.0).abs() < 1e-14, - "eigenvalue_condition_number={cn:.6e}, expected 2.0" - ); - } - - // ── Data structures: serde round-trip ──────────────────────────────────── - - // ── Trustworthiness metric ──────────────────────────────────────────────── - - #[test] - fn t_tw_01_perfect_preservation() { - // 20-point grid; each point embedded to its own location - let x = ndarray::Array2::from_shape_fn((20, 4), |(i, d)| (i * 4 + d) as f64); - let y = x.slice(ndarray::s![.., ..2]).to_owned(); - let t = trustworthiness(x.view(), y.view(), 5); - assert!((t - 1.0).abs() < 1e-10, "perfect preservation: T={t}"); - } - - #[test] - fn t_tw_02_result_in_unit_interval() { - use rand::{Rng, SeedableRng}; - let mut rng = rand::rngs::SmallRng::seed_from_u64(99); - let x = ndarray::Array2::from_shape_fn((20, 10), |_| rng.random::()); - let y = ndarray::Array2::from_shape_fn((20, 2), |_| rng.random::()); - let t = trustworthiness(x.view(), y.view(), 5); - assert!((0.0..=1.0).contains(&t), "T out of [0,1]: {t}"); - } - - /// Hand-verifiable 4-point, k=1 example with exactly one violation of rank penalty 1. - /// - /// n=4, k=1: denominator = 4·1·(8−3−1) = 16. - /// - /// X = [[0,0],[1,0],[0,1.5],[0,100]]: - /// KNN(0,X,1)={1} (rank_x[2]=2), KNN(1,X,1)={0}, KNN(2,X,1)={0}, KNN(3,X,1)={2} - /// - /// Y = [[0,0],[1,0],[0,0.5],[0,100]] (point 2 moved closer to 0): - /// KNN(0,Y,1)={2} → violation: rank_x[2]=2, penalty = 2−1 = 1 - /// KNN(1,Y,1)={0} → 0 ∈ KNN(1,X,1): no penalty - /// KNN(2,Y,1)={0} → 0 ∈ KNN(2,X,1): no penalty - /// KNN(3,Y,1)={2} → 2 ∈ KNN(3,X,1): no penalty - /// - /// T = 1 − 2·1/16 = 7/8 = 0.875 - #[test] - fn t_tw_03_formula_hand_check() { - let x = ndarray::Array2::from_shape_vec( - (4, 2), - vec![0.0f64, 0.0, 1.0, 0.0, 0.0, 1.5, 0.0, 100.0], - ) - .unwrap(); - let y = ndarray::Array2::from_shape_vec( - (4, 2), - vec![0.0f64, 0.0, 1.0, 0.0, 0.0, 0.5, 0.0, 100.0], - ) - .unwrap(); - let t = trustworthiness(x.view(), y.view(), 1); - let expected = 7.0 / 8.0; - assert!( - (t - expected).abs() < 1e-10, - "hand-check: T={t:.10}, expected {expected:.10} (7/8)" - ); - } - - #[test] - fn t_tw_04_k_less_than_half_n() { - use rand::{Rng, SeedableRng}; - let mut rng = rand::rngs::SmallRng::seed_from_u64(7); - let n = 20usize; - let k = n / 2 - 1; // 9, just below the boundary - let x = ndarray::Array2::from_shape_fn((n, 4), |_| rng.random::()); - let y = ndarray::Array2::from_shape_fn((n, 2), |_| rng.random::()); - let t = trustworthiness(x.view(), y.view(), k); - assert!(t.is_finite(), "T should be finite at k=n/2-1: {t}"); - assert!((0.0..=1.0).contains(&t), "T out of [0,1] at k=n/2-1: {t}"); - } - - #[test] - #[should_panic(expected = "k must be < n/2")] - fn t_tw_05_panics_on_k_gte_half_n() { - let n = 20usize; - let k = n / 2; // exactly n/2 — must panic - let x = ndarray::Array2::zeros((n, 4)); - let y = ndarray::Array2::zeros((n, 2)); - let _ = trustworthiness(x.view(), y.view(), k); - } - - #[cfg(target_arch = "x86_64")] - #[test] - fn t_tw_06_avx2_looped_kernel_matches_scalar() { - if !(is_x86_feature_detected!("avx2") && is_x86_feature_detected!("fma")) { - return; // skip on CPUs without AVX2+FMA - } - use rand::{Rng, SeedableRng}; - let mut rng = rand::rngs::SmallRng::seed_from_u64(42); - for len in [10, 13, 16, 50, 100] { - let a: Vec = (0..len).map(|_| rng.random::()).collect(); - let b: Vec = (0..len).map(|_| rng.random::()).collect(); - let scalar: f64 = a - .iter() - .zip(b.iter()) - .map(|(&x, &y)| (x - y) * (x - y)) - .sum(); - // SAFETY: runtime check above guarantees AVX2+FMA; both slices have `len` elements. - let avx2 = unsafe { super::dist_sq_avx2_looped(&a, &b) }; - assert!( - (avx2 - scalar).abs() < 1e-10, - "dist_sq_avx2_looped mismatch at len={len}: avx2={avx2}, scalar={scalar}" - ); - } - } - - #[test] - fn t_tw_07_partial_rank_matches_full_sort() { - use rand::{Rng, SeedableRng}; - use std::collections::HashSet; - let mut rng = rand::rngs::SmallRng::seed_from_u64(77); - let n = 30; - let k = 5; - let x = ndarray::Array2::from_shape_fn((n, 4), |_| rng.random::()); - - for i in 0..n { - let xi = x.row(i); - let dist_x: Vec = (0..n) - .map(|j| { - xi.iter() - .zip(x.row(j).iter()) - .map(|(&a, &b)| (a - b) * (a - b)) - .sum() - }) - .collect(); - - // Full-sort baseline: knn_x_set via sort + rank scatter - let mut sorted: Vec<(f64, usize)> = dist_x.iter().copied().zip(0..n).collect(); - sorted.sort_unstable_by(|a, b| a.0.total_cmp(&b.0).then(a.1.cmp(&b.1))); - let knn_baseline: HashSet = sorted[1..=k].iter().map(|&(_, j)| j).collect(); - - // Partial-rank approach: select_nth_unstable_by - let mut indices: Vec = (0..n).collect(); - indices.select_nth_unstable_by(k, |&a, &b| { - dist_x[a].total_cmp(&dist_x[b]).then(a.cmp(&b)) - }); - let knn_partial: HashSet = - indices[..=k].iter().filter(|&&m| m != i).copied().collect(); - - assert_eq!(knn_baseline, knn_partial, "knn_x_set mismatch at row {i}"); - - // Verify rank values for all non-knn points - let mut rank_x = vec![0usize; n]; - for (rank, &(_, j)) in sorted.iter().enumerate() { - rank_x[j] = rank; - } - for j in 0..n { - if j == i || knn_baseline.contains(&j) { - continue; - } - let dj = dist_x[j]; - let scan_rank: usize = (0..n) - .filter(|&m| dist_x[m] < dj || (dist_x[m] == dj && m < j)) - .count(); - assert_eq!( - rank_x[j], scan_rank, - "rank mismatch for point {j} from row {i}: sort={}, scan={scan_rank}", - rank_x[j] - ); - } - } - } - - /// Brute-force O(n²) reference: full-sort X distances, sort-based Y-kNN. - fn trustworthiness_brute_force( - x: ndarray::ArrayView2, - y: ndarray::ArrayView2, - k: usize, - ) -> f64 { - use std::collections::HashSet; - let n = x.nrows(); - let penalty_sum: f64 = (0..n) - .map(|i| { - let xi = x.row(i); - let yi = y.row(i); - - let mut dist_x: Vec<(f64, usize)> = (0..n) - .map(|j| { - let d: f64 = xi - .iter() - .zip(x.row(j).iter()) - .map(|(&a, &b)| (a - b) * (a - b)) - .sum(); - (d, j) - }) - .collect(); - dist_x.sort_unstable_by(|a, b| a.0.total_cmp(&b.0).then(a.1.cmp(&b.1))); - let knn_x: HashSet = dist_x[1..=k].iter().map(|&(_, j)| j).collect(); - let mut rank_x = vec![0usize; n]; - for (rank, &(_, j)) in dist_x.iter().enumerate() { - rank_x[j] = rank; - } - - let mut dist_y: Vec<(f64, usize)> = (0..n) - .filter(|&j| j != i) - .map(|j| { - let d: f64 = yi - .iter() - .zip(y.row(j).iter()) - .map(|(&a, &b)| (a - b) * (a - b)) - .sum(); - (d, j) - }) - .collect(); - dist_y.sort_unstable_by(|a, b| a.0.total_cmp(&b.0).then(a.1.cmp(&b.1))); - let knn_y: HashSet = dist_y[..k].iter().map(|&(_, j)| j).collect(); - - let mut row_penalty = 0u64; - for j in &knn_y { - if !knn_x.contains(j) { - row_penalty += (rank_x[*j] - k) as u64; - } - } - row_penalty as f64 - }) - .sum(); - let denom = n as f64 * k as f64 * (2 * n).saturating_sub(3 * k + 1) as f64; - 1.0 - penalty_sum * 2.0 / denom - } - - #[test] - fn t_tw_08_combined_matches_baseline() { - use rand::{Rng, SeedableRng}; - let mut rng = rand::rngs::SmallRng::seed_from_u64(123); - let n = 50; - let x = ndarray::Array2::from_shape_fn((n, 6), |_| rng.random::()); - let y = ndarray::Array2::from_shape_fn((n, 2), |_| rng.random::()); - - for k in [3, 7] { - let t = trustworthiness(x.view(), y.view(), k); - let t_ref = trustworthiness_brute_force(x.view(), y.view(), k); - assert!(t.is_finite(), "T(k={k}) must be finite, got {t}"); - assert!((0.0..=1.0).contains(&t), "T(k={k}) out of [0,1]: {t}"); - assert!( - (t - t_ref).abs() < 1e-12, - "T(k={k}) combined={t} diverges from brute-force reference={t_ref}" - ); - } - } - - #[cfg(target_arch = "x86_64")] - #[test] - fn t_tw_09_avx2_2d_kernel_matches_scalar() { - if !is_x86_feature_detected!("avx2") { - return; // skip on CPUs without AVX2 - } - use rand::{Rng, SeedableRng}; - let mut rng = rand::rngs::SmallRng::seed_from_u64(55); - for n in [0usize, 1, 2, 3, 10, 20, 51] { - let y_flat: Vec = (0..n * 2).map(|_| rng.random::()).collect(); - let yi: Vec = (0..2).map(|_| rng.random::()).collect(); - let mut out_avx2 = vec![0.0f64; n]; - // SAFETY: runtime check above guarantees AVX2; y_flat has n*2, yi has 2, out has n. - unsafe { - super::dist_sq_2d_avx2_batch(&yi, &y_flat, n, &mut out_avx2); - } - for j in 0..n { - let scalar: f64 = yi - .iter() - .zip(y_flat[j * 2..j * 2 + 2].iter()) - .map(|(&a, &b)| (a - b) * (a - b)) - .sum(); - assert!( - (out_avx2[j] - scalar).abs() < 1e-10, - "dist_sq_2d_avx2_batch mismatch at n={n}, j={j}: avx2={}, scalar={scalar}", - out_avx2[j] - ); - } - } - } - - #[test] - fn t_tw_10_self_exclusion_never_in_knn() { - // Verify that the self-exclusion (dist_y[i] = INFINITY) prevents point i - // from appearing in its own k-NN result. Catching a regression where the - // INFINITY assignment is accidentally dropped. - use rand::{Rng, SeedableRng}; - let mut rng = rand::rngs::SmallRng::seed_from_u64(77); - let n = 20; - let k = 3; - let x = ndarray::Array2::from_shape_fn((n, 4), |_| rng.random::()); - let y = ndarray::Array2::from_shape_fn((n, 2), |_| rng.random::()); - // Run trustworthiness — internally computes k-NN of Y for each row. - // We verify correctness by comparing against brute-force which also applies self-exclusion. - let t = trustworthiness(x.view(), y.view(), k); - let t_ref = trustworthiness_brute_force(x.view(), y.view(), k); - assert!( - (t - t_ref).abs() < 1e-12, - "self-exclusion regression: combined={t} diverges from brute-force={t_ref}" - ); - // Additionally, verify directly via brute-force that no point is its own neighbor. - for i in 0..n { - let yi = y.row(i); - let mut dists: Vec<(f64, usize)> = (0..n) - .filter(|&j| j != i) - .map(|j| { - let d: f64 = yi - .iter() - .zip(y.row(j).iter()) - .map(|(&a, &b)| (a - b) * (a - b)) - .sum(); - (d, j) - }) - .collect(); - dists.sort_by(|a, b| a.0.total_cmp(&b.0)); - let knn: Vec = dists[..k].iter().map(|&(_, j)| j).collect(); - assert!(!knn.contains(&i), "point {i} appeared in its own k-NN"); - } - } - - fn trustworthiness_brute_force_subsampled( - x: ndarray::ArrayView2, - y: ndarray::ArrayView2, - k: usize, - query_indices: &[usize], - ) -> f64 { - use std::collections::HashSet; - let n = x.nrows(); - let m = query_indices.len(); - let penalty_sum: f64 = query_indices - .iter() - .map(|&i| { - let xi = x.row(i); - let yi = y.row(i); - let mut dist_x: Vec<(f64, usize)> = (0..n) - .map(|j| { - let d: f64 = xi - .iter() - .zip(x.row(j).iter()) - .map(|(&a, &b)| (a - b) * (a - b)) - .sum(); - (d, j) - }) - .collect(); - dist_x.sort_unstable_by(|a, b| a.0.total_cmp(&b.0).then(a.1.cmp(&b.1))); - let knn_x: HashSet = dist_x[1..=k].iter().map(|&(_, j)| j).collect(); - let mut rank_x = vec![0usize; n]; - for (rank, &(_, j)) in dist_x.iter().enumerate() { - rank_x[j] = rank; - } - let mut dist_y: Vec<(f64, usize)> = (0..n) - .filter(|&j| j != i) - .map(|j| { - let d: f64 = yi - .iter() - .zip(y.row(j).iter()) - .map(|(&a, &b)| (a - b) * (a - b)) - .sum(); - (d, j) - }) - .collect(); - dist_y.sort_unstable_by(|a, b| a.0.total_cmp(&b.0).then(a.1.cmp(&b.1))); - let knn_y: HashSet = dist_y[..k].iter().map(|&(_, j)| j).collect(); - let mut row_penalty = 0u64; - for j in &knn_y { - if !knn_x.contains(j) { - row_penalty += (rank_x[*j] - k) as u64; - } - } - row_penalty as f64 - }) - .sum(); - let denom = m as f64 * k as f64 * (2 * n).saturating_sub(3 * k + 1) as f64; - 1.0 - penalty_sum * 2.0 / denom - } - - #[test] - fn t_tws_01_m_equals_n_matches_full_trustworthiness() { - use rand::{Rng, SeedableRng}; - let mut rng = rand::rngs::SmallRng::seed_from_u64(2026); - let n = 60; - let k = 5; - let x = ndarray::Array2::from_shape_fn((n, 8), |_| rng.random::()); - let y = ndarray::Array2::from_shape_fn((n, 2), |_| rng.random::()); - let t_full = trustworthiness(x.view(), y.view(), k); - let t_sub = trustworthiness_subsampled(x.view(), y.view(), k, n, 0); - assert!( - (t_full - t_sub).abs() < 1e-10, - "m==n parity: full={t_full}, subsampled={t_sub}" - ); - } - - #[test] - fn t_tws_02_m_less_than_n_in_unit_interval() { - use rand::{Rng, SeedableRng}; - let mut rng = rand::rngs::SmallRng::seed_from_u64(33); - let n = 200; - let k = 5; - let x = ndarray::Array2::from_shape_fn((n, 10), |_| rng.random::()); - let y = ndarray::Array2::from_shape_fn((n, 2), |_| rng.random::()); - - // Hard-coded query indices cross-checked against brute force: guards - // against constant-output regressions and is independent of the - // production sampling implementation. - let query_indices: Vec = vec![3, 17, 29, 42, 58, 71, 89, 104, 127, 145, 161, 188]; - let t = trustworthiness_inner(x.view(), y.view(), k, Some(&query_indices)); - let t_ref = trustworthiness_brute_force_subsampled(x.view(), y.view(), k, &query_indices); - assert!( - (t - t_ref).abs() < 1e-12, - "subsampled kernel vs brute force mismatch: inner={t}, brute={t_ref}" - ); - assert!(t.is_finite(), "T must be finite, got {t}"); - assert!(t > 0.0 && t <= 1.0, "T out of (0,1]: {t}"); - } - - #[test] - fn t_tws_03_same_seed_is_deterministic() { - use rand::{Rng, SeedableRng}; - let mut rng = rand::rngs::SmallRng::seed_from_u64(11); - let n = 100; - let k = 4; - let m = 30; - let x = ndarray::Array2::from_shape_fn((n, 6), |_| rng.random::()); - let y = ndarray::Array2::from_shape_fn((n, 2), |_| rng.random::()); - let a = trustworthiness_subsampled(x.view(), y.view(), k, m, 12345); - let b = trustworthiness_subsampled(x.view(), y.view(), k, m, 12345); - assert_eq!(a, b, "same seed must produce identical result"); - } - - #[test] - fn t_tws_04_different_seeds_produce_different_results() { - use rand::{Rng, SeedableRng}; - let mut rng = rand::rngs::SmallRng::seed_from_u64(99); - let n = 100; - let k = 4; - let m = 20; - let x = ndarray::Array2::from_shape_fn((n, 6), |_| rng.random::()); - let y = ndarray::Array2::from_shape_fn((n, 2), |_| rng.random::()); - - // First verify the sampling layer is seed-dependent, independent of - // the metric computation. - let mut rng_a = rand::rngs::SmallRng::seed_from_u64(1); - let indices_a = rand::seq::index::sample(&mut rng_a, n, m).into_vec(); - let mut rng_b = rand::rngs::SmallRng::seed_from_u64(2); - let indices_b = rand::seq::index::sample(&mut rng_b, n, m).into_vec(); - assert_ne!( - indices_a, indices_b, - "different seeds must produce different sampled index sets" - ); - - // Then verify that the metric values computed on different samples differ. - let a = trustworthiness_subsampled(x.view(), y.view(), k, m, 1); - let b = trustworthiness_subsampled(x.view(), y.view(), k, m, 2); - assert_ne!(a, b, "different seeds must produce different metric values"); - } - - #[test] - #[should_panic(expected = "m must be <= n")] - fn t_tws_05_panics_when_m_exceeds_n() { - let n = 20usize; - let x = ndarray::Array2::zeros((n, 4)); - let y = ndarray::Array2::zeros((n, 2)); - let _ = trustworthiness_subsampled(x.view(), y.view(), 3, n + 1, 0); - } - - #[test] - #[should_panic(expected = "m must be > 0")] - fn t_tws_06_panics_when_m_zero() { - let n = 20usize; - let x = ndarray::Array2::zeros((n, 4)); - let y = ndarray::Array2::zeros((n, 2)); - let _ = trustworthiness_subsampled(x.view(), y.view(), 3, 0, 0); - } - - #[test] - fn t_tws_07_perfect_preservation_subsampled() { - let n = 40; - let x = ndarray::Array2::from_shape_fn((n, 4), |(i, d)| (i * 4 + d) as f64); - let y = x.slice(ndarray::s![.., ..2]).to_owned(); - let t = trustworthiness_subsampled(x.view(), y.view(), 5, 10, 0); - assert!( - (t - 1.0).abs() < 1e-12, - "perfect preservation: T={t}, expected 1.0" - ); - } - - #[test] - fn t_tws_08_brute_force_reference_matches() { - use rand::{Rng, SeedableRng}; - let mut rng = rand::rngs::SmallRng::seed_from_u64(7777); - let n = 80; - let k = 4; - let x = ndarray::Array2::from_shape_fn((n, 6), |_| rng.random::()); - let y = ndarray::Array2::from_shape_fn((n, 2), |_| rng.random::()); - - // Hard-coded query indices decouple this correctness test from the - // production sampling implementation (RNG choice, call order). - let query_indices: Vec = vec![ - 2, 7, 13, 19, 23, 28, 34, 41, 46, 52, 55, 58, 61, 64, 67, 70, 73, 75, 77, 79, - ]; - - let t_kernel = trustworthiness_inner(x.view(), y.view(), k, Some(&query_indices)); - let t_ref = trustworthiness_brute_force_subsampled(x.view(), y.view(), k, &query_indices); - assert!( - (t_kernel - t_ref).abs() < 1e-12, - "subsampled brute-force mismatch: kernel={t_kernel}, ref={t_ref}" - ); - } - - #[cfg(feature = "testing")] - #[test] - fn t_serde_01_round_trip_metric_result() { - let m = MetricResult { - name: "test_metric".to_string(), - dimension: 2, - value: 0.001, - threshold: 0.01, - passed: true, - }; - let json = serde_json::to_string(&m).expect("serialize MetricResult"); - let m2: MetricResult = serde_json::from_str(&json).expect("deserialize MetricResult"); - assert_eq!(m2.name, m.name); - assert_eq!(m2.dimension, m.dimension); - assert_eq!(m2.value, m.value); - assert_eq!(m2.threshold, m.threshold); - assert_eq!(m2.passed, m.passed); - } - - #[cfg(feature = "testing")] - #[test] - fn t_serde_02_round_trip_assessment_report() { - let r = AssessmentReport { - dataset: "test_dataset".to_string(), - n: 100, - metrics: vec![MetricResult { - name: "residual".to_string(), - dimension: 2, - value: 1e-7, - threshold: 1e-6, - passed: true, - }], - }; - let json = serde_json::to_string(&r).expect("serialize AssessmentReport"); - let r2: AssessmentReport = - serde_json::from_str(&json).expect("deserialize AssessmentReport"); - assert_eq!(r2.dataset, r.dataset); - assert_eq!(r2.n, r.n); - assert_eq!(r2.metrics.len(), 1); - assert_eq!(r2.metrics[0].name, "residual"); - } - - #[cfg(feature = "testing")] - #[test] - fn t_serde_03_round_trip_experiment_metrics() { - let e = ExperimentMetrics { - generated_at: "2026-01-01T00:00:00Z".to_string(), - datasets: vec![AssessmentReport { - dataset: "iris".to_string(), - n: 150, - metrics: vec![], - }], - }; - let json = serde_json::to_string(&e).expect("serialize ExperimentMetrics"); - let e2: ExperimentMetrics = - serde_json::from_str(&json).expect("deserialize ExperimentMetrics"); - assert_eq!(e2.generated_at, e.generated_at); - assert_eq!(e2.datasets.len(), 1); - assert_eq!(e2.datasets[0].dataset, "iris"); - } -} diff --git a/src/multi_component.rs b/src/multi_component.rs index 1c48e31..ba7a4cf 100644 --- a/src/multi_component.rs +++ b/src/multi_component.rs @@ -6,13 +6,14 @@ use crate::{ laplacian::{build_normalized_laplacian, compute_degrees}, scaling, selection::select_eigenvectors, - solvers::solve_eigenproblem, + solvers::{SolverParams, solve_eigenproblem}, }; /// Computes spectral embedding for disconnected graphs. /// Each component is embedded independently; component embeddings are aligned /// into a common coordinate frame via centroid meta-embedding. -pub(crate) fn embed_disconnected( +#[allow(clippy::too_many_arguments)] +pub fn embed_disconnected( graph: &CsMatI, component_labels: &[usize], n_conn_components: usize, @@ -20,6 +21,7 @@ pub(crate) fn embed_disconnected( seed: u64, data: Option>, compute_mode: ComputeMode, + params: &SolverParams, ) -> Result, SpectralError> { let n = graph.rows(); @@ -36,6 +38,7 @@ pub(crate) fn embed_disconnected( n_embedding_dims, seed, compute_mode, + params, )?, None => { return Err(SpectralError::InvalidGraph( @@ -63,6 +66,7 @@ pub(crate) fn embed_disconnected( &meta_pos, seed, compute_mode, + params, )?; for (local_i, &orig_i) in members.iter().enumerate() { result.row_mut(orig_i).assign(&comp_coords.row(local_i)); @@ -149,6 +153,7 @@ fn spectral_meta_embedding( n_embedding_dims: usize, seed: u64, compute_mode: ComputeMode, + params: &SolverParams, ) -> Result, SpectralError> { let n_features = data.ncols(); @@ -206,13 +211,15 @@ fn spectral_meta_embedding( let centroid_laplacian = tri.to_csr(); let sqrt_deg_meta = ndarray::Array1::from_iter(degrees.iter().map(|&d| d.sqrt())); - let ((evals, evecs), _) = solve_eigenproblem( + let ((evals, evecs), report) = solve_eigenproblem( ¢roid_laplacian, n_embedding_dims, seed, &sqrt_deg_meta, compute_mode, - ); + params, + )?; + report.log("component meta-embedding", n_comp); let evals_slice = evals .as_slice_memory_order() .ok_or(SpectralError::ConvergenceFailure)?; @@ -266,6 +273,7 @@ fn compute_data_range(meta_embedding: &Array2) -> Vec { /// translated to its position in meta-embedding space. /// /// Tiny components (`size < 2 * n_embedding_dims`) are placed directly at `meta_pos`. +#[allow(clippy::too_many_arguments)] fn embed_single_component( graph: &CsMatI, members: &[usize], @@ -274,6 +282,7 @@ fn embed_single_component( meta_pos: &ArrayView1, seed: u64, compute_mode: ComputeMode, + params: &SolverParams, ) -> Result, SpectralError> { let size = members.len(); @@ -296,8 +305,15 @@ fn embed_single_component( .map(|&s| if s > 0.0 { 1.0 / s } else { 0.0 }) .collect(); let laplacian = build_normalized_laplacian(&sub_graph, &inv_sqrt_deg); - let ((evals, evecs), _) = - solve_eigenproblem(&laplacian, n_embedding_dims, seed, &sqrt_deg, compute_mode); + let ((evals, evecs), report) = solve_eigenproblem( + &laplacian, + n_embedding_dims, + seed, + &sqrt_deg, + compute_mode, + params, + )?; + report.log("component", size); let evals_slice = evals .as_slice_memory_order() .ok_or(SpectralError::ConvergenceFailure)?; @@ -435,7 +451,16 @@ mod tests { fn test_embed_disconnected_two_pairs_shape_and_finite() { let g = make_two_pair_graph(); let labels = vec![0usize, 0, 1, 1]; - let result = embed_disconnected(&g, &labels, 2, 2, 42, None, ComputeMode::PythonCompat); + let result = embed_disconnected( + &g, + &labels, + 2, + 2, + 42, + None, + ComputeMode::PythonCompat, + &SolverParams::default(), + ); let arr = result.expect("embed_disconnected should succeed"); assert_eq!(arr.shape(), &[4, 2]); for &v in arr.iter() { @@ -450,7 +475,16 @@ mod tests { // Both size=1 < 2*dim=4 → placed at meta centroid let g = make_empty_pair_graph(); let labels = vec![0usize, 1]; - let result = embed_disconnected(&g, &labels, 2, 2, 42, None, ComputeMode::PythonCompat); + let result = embed_disconnected( + &g, + &labels, + 2, + 2, + 42, + None, + ComputeMode::PythonCompat, + &SolverParams::default(), + ); let arr = result.expect("embed_disconnected should succeed for tiny components"); assert_eq!(arr.shape(), &[2, 2]); let eps = 1e-10; @@ -485,7 +519,16 @@ mod tests { // strictly greater than the max intra-component spread (≤ data_range = sqrt(2)/2). let g = make_3_clique_graph(); let labels: Vec = (0..12).map(|i| i / 4).collect(); - let result = embed_disconnected(&g, &labels, 3, 2, 42, None, ComputeMode::PythonCompat); + let result = embed_disconnected( + &g, + &labels, + 3, + 2, + 42, + None, + ComputeMode::PythonCompat, + &SolverParams::default(), + ); let arr = result.expect("embed_disconnected on 3-clique graph should succeed"); assert_eq!(arr.shape(), &[12, 2]); diff --git a/src/operator.rs b/src/operator.rs index 4b9130c..120a976 100644 --- a/src/operator.rs +++ b/src/operator.rs @@ -3,6 +3,7 @@ use sprs::CsMatI; // ─── Trait ─────────────────────────────────────────────────────────────────── +/// A square linear operator applied to blocks of column vectors. #[doc(hidden)] pub trait LinearOperator { /// Apply operator: y = self * x. Both arrays have shape [n, k]. @@ -15,50 +16,13 @@ pub trait LinearOperator { /// CSR sparse-matrix × dense-vector product: y = A * x. /// -/// This is the Phase 3 SIMD replacement point. The raw-slice signature exposes -/// the memory layout that AVX-512 / SELL-C-sigma intrinsics require. Do not -/// change the signature; replace the body in Phase 3. -/// -/// `pub` under the `testing` feature (bench/test access) with always-on -/// precondition assertions; `pub(crate)` otherwise with `debug_assert!` guards. -#[cfg(feature = "testing")] +/// The raw-slice signature exposes the CSR memory layout directly, so scalar and +/// SIMD kernels share one calling convention. The CSR invariants (`indptr.len() == +/// y.len() + 1`, every column index below `x.len()`, `data` at least `nnz` long) are +/// checked with `debug_assert!`; violating them in a release build panics on the +/// out-of-bounds index. #[doc(hidden)] pub fn spmv_csr(indptr: &[usize], indices: &[usize], data: &[f64], x: &[f64], y: &mut [f64]) { - assert!( - indptr.len() == y.len() + 1, - "CSR invariant violated: indptr.len()={} != y.len()+1={}", - indptr.len(), - y.len() + 1 - ); - assert!( - indices.iter().all(|&j| j < x.len()), - "CSR invariant violated: column index out of bounds (x.len()={})", - x.len() - ); - assert!( - data.len() >= indptr.last().copied().unwrap_or(0), - "CSR invariant violated: data.len()={} < nnz={}", - data.len(), - indptr.last().copied().unwrap_or(0) - ); - for i in 0..y.len() { - let mut acc = 0.0_f64; - for k in indptr[i]..indptr[i + 1] { - acc += data[k] * x[indices[k]]; - } - y[i] = acc; - } -} - -#[cfg(not(feature = "testing"))] -#[allow(dead_code)] // only used in #[cfg(test)] unit tests -pub(crate) fn spmv_csr( - indptr: &[usize], - indices: &[usize], - data: &[f64], - x: &[f64], - y: &mut [f64], -) { debug_assert!( indptr.len() == y.len() + 1, "CSR invariant violated: indptr.len()={} != y.len()+1={}", @@ -138,14 +102,15 @@ unsafe fn spmv_avx2_gather_inner( } } -/// Safe public wrapper around the AVX2+FMA gather SpMV kernel. +/// Safe wrapper around the AVX2+FMA gather SpMV kernel, for tests. /// /// Panics if AVX2 or FMA is not available on the current CPU. -/// Under `#[cfg(all(feature = "testing", any(target_arch = "x86", target_arch = "x86_64")))]` -/// only — not part of the stable public API. -#[cfg(all(feature = "testing", any(target_arch = "x86", target_arch = "x86_64")))] +#[cfg(all( + any(test, feature = "__internal"), + any(target_arch = "x86", target_arch = "x86_64") +))] #[doc(hidden)] -pub fn spmv_avx2_gather_pub( +pub fn spmv_avx2_gather( indptr: &[usize], indices: &[usize], data: &[f64], @@ -154,7 +119,7 @@ pub fn spmv_avx2_gather_pub( ) { assert!( is_x86_feature_detected!("avx2") && is_x86_feature_detected!("fma"), - "spmv_avx2_gather_pub: AVX2+FMA not available on this CPU" + "spmv_avx2_gather: AVX2+FMA not available on this CPU" ); // SAFETY: feature detection above guarantees avx2+fma are present. unsafe { spmv_avx2_gather_inner(indptr, indices, data, x, y) } @@ -563,9 +528,9 @@ mod tests { // ─── AVX2/SIMD operator tests ──────────────────────────────────────────── - #[cfg(all(feature = "testing", any(target_arch = "x86", target_arch = "x86_64")))] + #[cfg(any(target_arch = "x86", target_arch = "x86_64"))] #[test] - fn test_spmv_avx2_gather_pub_matches_scalar() { + fn test_spmv_avx2_gather_matches_scalar() { if !is_x86_feature_detected!("avx2") || !is_x86_feature_detected!("fma") { return; // skip on non-AVX2 machines } @@ -576,7 +541,7 @@ mod tests { let mut y_scalar = vec![0.0_f64; 3]; let mut y_avx2 = vec![0.0_f64; 3]; spmv_csr(&indptr, &indices, &data, &x, &mut y_scalar); - spmv_avx2_gather_pub(&indptr, &indices, &data, &x, &mut y_avx2); + spmv_avx2_gather(&indptr, &indices, &data, &x, &mut y_avx2); for i in 0..3 { assert!( (y_avx2[i] - y_scalar[i]).abs() < 1e-13, diff --git a/src/scaling.rs b/src/scaling.rs index 33a73c7..0bc7dc4 100644 --- a/src/scaling.rs +++ b/src/scaling.rs @@ -6,7 +6,7 @@ use rand_distr::{Distribution, Normal}; /// Internal helper: deterministic scaling only (no noise). /// Scales `coords` so the global max absolute value equals `max_coord`, then /// casts to f32. -pub(crate) fn scale_coords( +pub fn scale_coords( coords: &Array2, max_coord: f64, ) -> Result, crate::SpectralError> { @@ -59,7 +59,7 @@ pub(crate) fn noisy_scale_coords( /// /// Must be called on f64 eigenvectors after `select_eigenvectors` and before /// `scale_and_add_noise`. -pub(crate) fn normalize_signs(coords: &mut Array2) { +pub fn normalize_signs(coords: &mut Array2) { for col in 0..coords.ncols() { let sign = coords .column(col) @@ -82,7 +82,7 @@ pub(crate) fn normalize_signs(coords: &mut Array2) { /// Scales columns so max absolute value is 10.0, then adds Gaussian noise /// with scale=0.0001. Downcasts to f32. -pub(crate) fn scale_and_add_noise( +pub fn scale_and_add_noise( coords: Array2, seed: u64, ) -> Result, crate::SpectralError> { diff --git a/src/solvers/dense.rs b/src/solvers/dense.rs index 6bc6cc1..96e8f3a 100644 --- a/src/solvers/dense.rs +++ b/src/solvers/dense.rs @@ -31,7 +31,7 @@ pub fn dense_evd(laplacian: &CsMatI, k: usize) -> Result, Array2); @@ -55,23 +49,109 @@ pub type EigenResult = (Array1, Array2); /// Graphs with n < DENSE_N_THRESHOLD use Level 0 (dense EVD) directly. const DENSE_N_THRESHOLD: usize = 2000; -/// Returns the effective dense-EVD size threshold. -/// -/// In test builds (`--features testing`), reads the `SPECTRAL_DENSE_N_THRESHOLD` -/// environment variable, falling back to `DENSE_N_THRESHOLD` on absence or -/// parse error. In release builds the function is a trivial constant return -/// that the compiler inlines away entirely. -#[cfg(feature = "testing")] -fn dense_n_threshold() -> usize { - std::env::var("SPECTRAL_DENSE_N_THRESHOLD") - .ok() - .and_then(|s| s.parse::().ok()) - .unwrap_or(DENSE_N_THRESHOLD) +/// Level of the solver escalation chain. +#[repr(u8)] +#[derive(Debug, Clone, Copy, PartialEq, Eq, PartialOrd, Ord, Hash)] +pub enum SolverLevel { + /// Level 0: dense EVD, tried first for small problems. + DenseEvd = 0, + /// Level 1: LOBPCG without regularization. + Lobpcg = 1, + /// Level 2: shift-and-invert LOBPCG. + SinvLobpcg = 2, + /// Level 3: LOBPCG with ε·I regularization. + LobpcgRegularized = 3, + /// Level 4: randomized SVD. + Rsvd = 4, + /// Level 5: forced dense EVD. + ForcedDense = 5, +} + +impl SolverLevel { + /// Human-readable solver name. + pub fn name(self) -> &'static str { + match self { + SolverLevel::DenseEvd => "Dense EVD", + SolverLevel::Lobpcg => "LOBPCG", + SolverLevel::SinvLobpcg => "SINV LOBPCG", + SolverLevel::LobpcgRegularized => "LOBPCG+reg", + SolverLevel::Rsvd => "rSVD", + SolverLevel::ForcedDense => "Forced Dense EVD", + } + } +} + +/// Residual thresholds of the escalation chain. A level's result is accepted when its +/// max eigenpair residual is strictly below the level's gate. +#[derive(Debug, Clone, Copy, PartialEq)] +pub struct QualityGates { + /// Gate for Level 0 (dense EVD). + pub dense: f64, + /// Gate for Levels 1 and 3 (LOBPCG, plain and regularized). + pub lobpcg: f64, + /// Gate for Level 2 (shift-and-invert LOBPCG). + pub sinv: f64, + /// Gate for Level 4 (randomized SVD). + pub rsvd: f64, +} + +impl Default for QualityGates { + fn default() -> Self { + Self { + dense: DENSE_EVD_QUALITY_THRESHOLD, + lobpcg: LOBPCG_QUALITY_THRESHOLD, + sinv: SINV_LOBPCG_QUALITY_THRESHOLD, + rsvd: RSVD_QUALITY_THRESHOLD, + } + } } -#[cfg(not(feature = "testing"))] -fn dense_n_threshold() -> usize { - DENSE_N_THRESHOLD +/// Tunable parameters of the solver escalation chain. +#[derive(Debug, Clone, PartialEq)] +pub struct SolverParams { + /// Problems with `n < dense_n_threshold` start at Level 0 (dense EVD). + pub dense_n_threshold: usize, + /// Oversampling of the randomized SVD subspace; `None` selects the n-dependent default. + pub rsvd_oversampling: Option, + /// Number of power-iteration passes of the randomized SVD. + pub rsvd_nbiter: usize, + /// Per-level residual acceptance thresholds. + pub gates: QualityGates, +} + +impl Default for SolverParams { + fn default() -> Self { + Self { + dense_n_threshold: DENSE_N_THRESHOLD, + rsvd_oversampling: None, + rsvd_nbiter: rsvd::DEFAULT_NBITER, + gates: QualityGates::default(), + } + } +} + +/// What the escalation chain did to produce a result. +#[derive(Debug, Clone, PartialEq)] +pub struct SolveReport { + /// Level whose result was returned. + pub level: SolverLevel, + /// Max eigenpair residual of the returned result. + pub residual: f64, + /// Wall-clock time spent in each level that ran, indexed by level number. + pub level_elapsed: [Option; 6], +} + +impl SolveReport { + /// Emits one `log::debug!` line describing the solve of a problem of size `n`. + pub(crate) fn log(&self, context: &str, n: usize) { + log::debug!( + "[spectral] {context}: n={n}, level {} ({}), max_residual={:.2e}, elapsed per level={:?}", + self.level as u8, + self.level.name(), + self.residual, + self.level_elapsed + ); + } } /// Enforce the mathematical PSD contract on solver output. @@ -91,12 +171,29 @@ fn enforce_psd_contract(result: EigenResult) -> EigenResult { (clamped, eigenvectors) } +/// Packages an accepted eigenpair set with the report describing how it was obtained. +fn accepted( + result: EigenResult, + level: SolverLevel, + residual: f64, + level_elapsed: [Option; 6], +) -> (EigenResult, SolveReport) { + ( + enforce_psd_contract(result), + SolveReport { + level, + residual, + level_elapsed, + }, + ) +} + /// Core solver escalation chain, parameterized over the `LinearOperator` used for LOBPCG. /// /// Returns `n_components+1` eigenpairs (including the trivial λ≈0 vector at index 0) /// so that the caller can apply `select_eigenvectors` uniformly across all solver paths. /// -/// Level 0: Dense EVD (n < 2000, O(n³)). +/// Level 0: Dense EVD (n < `params.dense_n_threshold`, O(n³)). /// Level 1: LOBPCG without regularization. /// Level 2: Shift-and-invert LOBPCG via sparse Cholesky. /// Level 3: LOBPCG with ε·I regularization. @@ -113,29 +210,30 @@ fn solve_eigenproblem_with_op( n_components: usize, seed: u64, sqrt_deg: &ndarray::Array1, -) -> (EigenResult, u8) { - #[cfg(feature = "testing")] - let _t_solve = std::time::Instant::now(); - + params: &SolverParams, +) -> Result<(EigenResult, SolveReport), SpectralError> { let n = laplacian.rows(); + let gates = ¶ms.gates; + let mut level_elapsed: [Option; 6] = [None; 6]; // Level 0: Dense EVD — exact, used for small n where O(n³) is acceptable. - if n < dense_n_threshold() { - #[cfg(feature = "testing")] - let _t0 = std::time::Instant::now(); - let _l0_result = dense_evd(laplacian, n_components + 1); - #[cfg(feature = "testing")] - eprintln!("[timing:level_0] {}µs", _t0.elapsed().as_micros()); - match _l0_result { + if n < params.dense_n_threshold { + let started = Instant::now(); + let l0_result = dense_evd(laplacian, n_components + 1); + level_elapsed[SolverLevel::DenseEvd as usize] = Some(started.elapsed()); + match l0_result { Ok((eigs, vecs)) => { let quality = max_eigenpair_residual(laplacian, &eigs, &vecs); - if quality < DENSE_EVD_QUALITY_THRESHOLD { + if quality < gates.dense { log::debug!( "[spectral] Level 0 (dense EVD) succeeded (n={n}, max_residual={quality:.2e})" ); - #[cfg(feature = "testing")] - eprintln!("[timing:level_total] {}µs", _t_solve.elapsed().as_micros()); - return (enforce_psd_contract((eigs, vecs)), 0); + return Ok(accepted( + (eigs, vecs), + SolverLevel::DenseEvd, + quality, + level_elapsed, + )); } log::debug!( "[spectral] Level 0 (dense EVD) poor quality \ @@ -149,20 +247,21 @@ fn solve_eigenproblem_with_op( } // Level 1: LOBPCG without regularization. - #[cfg(feature = "testing")] - let _t1 = std::time::Instant::now(); - let _l1 = lobpcg::lobpcg_solve(&op, n_components, seed, false, sqrt_deg); - #[cfg(feature = "testing")] - eprintln!("[timing:level_1] {}µs", _t1.elapsed().as_micros()); - if let Some(((eigs, vecs), _restarts)) = _l1 { + let started = Instant::now(); + let l1 = lobpcg::lobpcg_solve(&op, n_components, seed, false, sqrt_deg); + level_elapsed[SolverLevel::Lobpcg as usize] = Some(started.elapsed()); + if let Some(((eigs, vecs), _restarts)) = l1 { let quality = max_eigenpair_residual(laplacian, &eigs, &vecs); - if quality < LOBPCG_QUALITY_THRESHOLD { + if quality < gates.lobpcg { log::debug!( "[spectral] Level 1 (LOBPCG) succeeded (n={n}, max_residual={quality:.2e})" ); - #[cfg(feature = "testing")] - eprintln!("[timing:level_total] {}µs", _t_solve.elapsed().as_micros()); - return (enforce_psd_contract((eigs, vecs)), 1); + return Ok(accepted( + (eigs, vecs), + SolverLevel::Lobpcg, + quality, + level_elapsed, + )); } log::debug!( "[spectral] Level 1 (LOBPCG) poor quality \ @@ -174,20 +273,21 @@ fn solve_eigenproblem_with_op( // sprs_csc_to_faer converts the Laplacian to faer CSC and adds SINV_SHIFT to the // diagonal, producing M = L + εI. sp_cholesky factorizes M; if it fails (e.g. M // is not SPD due to numerical degenerate edges) we skip silently to Level 3. - #[cfg(feature = "testing")] - let _t2 = std::time::Instant::now(); - let _l2 = sinv::lobpcg_sinv_solve(laplacian, n_components, seed, sqrt_deg); - #[cfg(feature = "testing")] - eprintln!("[timing:level_2] {}µs", _t2.elapsed().as_micros()); - if let Some((eigs, vecs)) = _l2 { + let started = Instant::now(); + let l2 = sinv::lobpcg_sinv_solve(laplacian, n_components, seed, sqrt_deg); + level_elapsed[SolverLevel::SinvLobpcg as usize] = Some(started.elapsed()); + if let Some((eigs, vecs)) = l2 { let quality = max_eigenpair_residual(laplacian, &eigs, &vecs); - if quality < SINV_LOBPCG_QUALITY_THRESHOLD { + if quality < gates.sinv { log::debug!( "[spectral] Level 2 (sinv LOBPCG) succeeded (n={n}, max_residual={quality:.2e})" ); - #[cfg(feature = "testing")] - eprintln!("[timing:level_total] {}µs", _t_solve.elapsed().as_micros()); - return (enforce_psd_contract((eigs, vecs)), 2); + return Ok(accepted( + (eigs, vecs), + SolverLevel::SinvLobpcg, + quality, + level_elapsed, + )); } log::debug!( "[spectral] Level 2 (sinv LOBPCG) poor quality \ @@ -199,20 +299,21 @@ fn solve_eigenproblem_with_op( // lobpcg_solve(regularize=true) applies Rayleigh-Ritz refinement internally // (G = X^T L X against the true Laplacian), so eigs are exact Rayleigh quotients // and can be passed directly to the residual check. - #[cfg(feature = "testing")] - let _t3 = std::time::Instant::now(); - let _l3 = lobpcg::lobpcg_solve(&op, n_components, seed, true, sqrt_deg); - #[cfg(feature = "testing")] - eprintln!("[timing:level_3] {}µs", _t3.elapsed().as_micros()); - if let Some(((eigs, vecs), _restarts)) = _l3 { + let started = Instant::now(); + let l3 = lobpcg::lobpcg_solve(&op, n_components, seed, true, sqrt_deg); + level_elapsed[SolverLevel::LobpcgRegularized as usize] = Some(started.elapsed()); + if let Some(((eigs, vecs), _restarts)) = l3 { let quality = max_eigenpair_residual(laplacian, &eigs, &vecs); - if quality < LOBPCG_QUALITY_THRESHOLD { + if quality < gates.lobpcg { log::debug!( "[spectral] Level 3 (LOBPCG+reg) succeeded (n={n}, max_residual={quality:.2e})" ); - #[cfg(feature = "testing")] - eprintln!("[timing:level_total] {}µs", _t_solve.elapsed().as_micros()); - return (enforce_psd_contract((eigs, vecs)), 3); + return Ok(accepted( + (eigs, vecs), + SolverLevel::LobpcgRegularized, + quality, + level_elapsed, + )); } log::debug!( "[spectral] Level 3 (LOBPCG+reg) poor quality \ @@ -223,17 +324,18 @@ fn solve_eigenproblem_with_op( // Level 4: Randomized SVD via 2I-L trick. // rsvd_solve is infallible; gate on output quality via residual check. { - #[cfg(feature = "testing")] - let _t4 = std::time::Instant::now(); - let (eigs, vecs) = rsvd::rsvd_solve(laplacian, n_components, seed); - #[cfg(feature = "testing")] - eprintln!("[timing:level_4] {}µs", _t4.elapsed().as_micros()); + let started = Instant::now(); + let (eigs, vecs) = rsvd::rsvd_solve(laplacian, n_components, seed, params); + level_elapsed[SolverLevel::Rsvd as usize] = Some(started.elapsed()); let quality = max_eigenpair_residual(laplacian, &eigs, &vecs); - if quality < RSVD_QUALITY_THRESHOLD { + if quality < gates.rsvd { log::debug!("[spectral] Level 4 (rSVD) succeeded (n={n}, max_residual={quality:.2e})"); - #[cfg(feature = "testing")] - eprintln!("[timing:level_total] {}µs", _t_solve.elapsed().as_micros()); - return (enforce_psd_contract((eigs, vecs)), 4); + return Ok(accepted( + (eigs, vecs), + SolverLevel::Rsvd, + quality, + level_elapsed, + )); } log::debug!( "[spectral] Level 4 (rSVD) poor quality (max_residual={quality:.2e}), \ @@ -247,18 +349,20 @@ fn solve_eigenproblem_with_op( // unrecoverable and should surface as an assertion failure, not a silent // ConvergenceFailure that would produce a garbage embedding. log::debug!("[spectral] Level 5 (forced dense EVD) (n={n})"); - #[cfg(feature = "testing")] - let _t5 = std::time::Instant::now(); - let result = dense_evd(laplacian, n_components + 1).expect( + let started = Instant::now(); + let (eigs, vecs) = dense_evd(laplacian, n_components + 1).expect( "solve_eigenproblem: Level 5 forced dense EVD failed — \ this is a bug; the spectral theorem guarantees eigenvectors \ exist for any symmetric positive semidefinite matrix", ); - #[cfg(feature = "testing")] - eprintln!("[timing:level_5] {}µs", _t5.elapsed().as_micros()); - #[cfg(feature = "testing")] - eprintln!("[timing:level_total] {}µs", _t_solve.elapsed().as_micros()); - (enforce_psd_contract(result), 5) + level_elapsed[SolverLevel::ForcedDense as usize] = Some(started.elapsed()); + let quality = max_eigenpair_residual(laplacian, &eigs, &vecs); + Ok(accepted( + (eigs, vecs), + SolverLevel::ForcedDense, + quality, + level_elapsed, + )) } /// Solver escalation chain with runtime operator dispatch. @@ -267,16 +371,19 @@ fn solve_eigenproblem_with_op( /// levels through `CsrOperatorSimd`; all other configurations use scalar `CsrOperator`. /// `ComputeMode::PythonCompat` always uses the scalar path regardless of CPU features. /// +/// Returns the `n_components + 1` smallest eigenpairs together with a [`SolveReport`]. +/// /// # Panics /// /// Panics at Level 5 exhaustion — this represents a bug, not a user error. -pub(crate) fn solve_eigenproblem( +pub fn solve_eigenproblem( laplacian: &CsMatI, n_components: usize, seed: u64, sqrt_deg: &ndarray::Array1, compute_mode: ComputeMode, -) -> (EigenResult, u8) { + params: &SolverParams, +) -> Result<(EigenResult, SolveReport), SpectralError> { #[cfg(any(target_arch = "x86", target_arch = "x86_64"))] if matches!(compute_mode, ComputeMode::RustNative) && is_x86_feature_detected!("avx2") @@ -284,10 +391,10 @@ pub(crate) fn solve_eigenproblem( { use crate::operator::CsrOperatorSimd; let op = CsrOperatorSimd::new(laplacian); - return solve_eigenproblem_with_op(laplacian, op, n_components, seed, sqrt_deg); + return solve_eigenproblem_with_op(laplacian, op, n_components, seed, sqrt_deg, params); } let op = CsrOperator(laplacian); - solve_eigenproblem_with_op(laplacian, op, n_components, seed, sqrt_deg) + solve_eigenproblem_with_op(laplacian, op, n_components, seed, sqrt_deg, params) } // ─── Unit Tests ────────────────────────────────────────────────────────────── @@ -295,9 +402,6 @@ pub(crate) fn solve_eigenproblem( #[cfg(test)] mod tests { use super::*; - use crate::metrics::{ - DENSE_EVD_QUALITY_THRESHOLD, LOBPCG_QUALITY_THRESHOLD, max_eigenpair_residual, - }; /// Build a 6-node path-graph Laplacian in CSR format. /// @@ -340,7 +444,9 @@ mod tests { 42, &ndarray::Array1::ones(6), ComputeMode::PythonCompat, - ); + &SolverParams::default(), + ) + .expect("solve_eigenproblem failed"); // All eigenvalues must be non-negative for &v in eigvals.iter() { @@ -369,7 +475,9 @@ mod tests { 42, &ndarray::Array1::ones(6), ComputeMode::PythonCompat, - ); + &SolverParams::default(), + ) + .expect("solve_eigenproblem failed"); assert_eq!(eigs.len(), 3, "expected n_components+1=3 eigenvalues"); assert_eq!( vecs.shape(), @@ -403,7 +511,9 @@ mod tests { 42, &ndarray::Array1::ones(n), ComputeMode::PythonCompat, - ); + &SolverParams::default(), + ) + .expect("solve_eigenproblem failed"); assert_eq!( eigvals.len(), @@ -428,17 +538,28 @@ mod tests { // For a well-conditioned diagonal Laplacian, Level 1 (plain LOBPCG) succeeds. let n = 2001; let laplacian = diagonal_laplacian(n); - let (_, level) = solve_eigenproblem( + let (_, report) = solve_eigenproblem( &laplacian, 2, 42, &ndarray::Array1::ones(n), ComputeMode::PythonCompat, - ); + &SolverParams::default(), + ) + .expect("solve_eigenproblem failed"); + let level = report.level as u8; assert!( (1..=5).contains(&level), "expected level in {{1,2,3,4,5}}, got {level}" ); + assert!( + report.level_elapsed[SolverLevel::DenseEvd as usize].is_none(), + "Level 0 must not run above the dense threshold" + ); + assert!( + report.level_elapsed[level as usize].is_some(), + "the accepted level must have a recorded duration" + ); } #[test] @@ -504,13 +625,16 @@ mod tests { fn level0_result_passes_dense_evd_quality_gate() { // 6-node path graph, n=6 < 2000 → Level 0 dense EVD. let laplacian = path_graph_laplacian_6(); - let ((eigs, vecs), _) = solve_eigenproblem( + let ((eigs, vecs), report) = solve_eigenproblem( &laplacian, 2, 42, &ndarray::Array1::ones(6), ComputeMode::PythonCompat, - ); + &SolverParams::default(), + ) + .expect("solve_eigenproblem failed"); + assert_eq!(report.level, SolverLevel::DenseEvd); let residual = max_eigenpair_residual(&laplacian, &eigs, &vecs); assert!( residual < DENSE_EVD_QUALITY_THRESHOLD, @@ -519,37 +643,56 @@ mod tests { } #[test] - fn dense_n_threshold_returns_default_when_env_unset() { - // SAFETY: single-threaded test (--test-threads=1), no concurrent env readers - unsafe { - std::env::remove_var("SPECTRAL_DENSE_N_THRESHOLD"); - } - assert_eq!(dense_n_threshold(), DENSE_N_THRESHOLD); + fn default_params_match_the_documented_chain() { + let params = SolverParams::default(); + assert_eq!(params.dense_n_threshold, DENSE_N_THRESHOLD); + assert_eq!(params.rsvd_oversampling, None); + assert_eq!(params.rsvd_nbiter, 2); + assert_eq!(params.gates.dense, DENSE_EVD_QUALITY_THRESHOLD); + assert_eq!(params.gates.lobpcg, LOBPCG_QUALITY_THRESHOLD); + assert_eq!(params.gates.sinv, SINV_LOBPCG_QUALITY_THRESHOLD); + assert_eq!(params.gates.rsvd, RSVD_QUALITY_THRESHOLD); } - #[cfg(feature = "testing")] #[test] - fn dense_n_threshold_reads_env_override() { - // SAFETY: single-threaded test (--test-threads=1), no concurrent env readers - unsafe { - std::env::set_var("SPECTRAL_DENSE_N_THRESHOLD", "50"); - } - assert_eq!(dense_n_threshold(), 50); - unsafe { - std::env::remove_var("SPECTRAL_DENSE_N_THRESHOLD"); - } + fn dense_n_threshold_zero_skips_level_0() { + // n=6 would use Level 0 by default; a zero threshold must route it to Level 1+. + let params = SolverParams { + dense_n_threshold: 0, + ..SolverParams::default() + }; + let (_, report) = solve_eigenproblem( + &path_graph_laplacian_6(), + 2, + 42, + &ndarray::Array1::ones(6), + ComputeMode::PythonCompat, + ¶ms, + ) + .expect("solve_eigenproblem failed"); + assert!( + report.level >= SolverLevel::Lobpcg, + "expected Level 1 or later, got {:?}", + report.level + ); + assert!(report.level_elapsed[SolverLevel::DenseEvd as usize].is_none()); } #[test] - fn dense_n_threshold_falls_back_on_parse_error() { - // SAFETY: single-threaded test (--test-threads=1), no concurrent env readers - unsafe { - std::env::set_var("SPECTRAL_DENSE_N_THRESHOLD", "not_a_number"); - } - assert_eq!(dense_n_threshold(), DENSE_N_THRESHOLD); - unsafe { - std::env::remove_var("SPECTRAL_DENSE_N_THRESHOLD"); + fn solver_level_discriminants_and_names() { + let levels = [ + SolverLevel::DenseEvd, + SolverLevel::Lobpcg, + SolverLevel::SinvLobpcg, + SolverLevel::LobpcgRegularized, + SolverLevel::Rsvd, + SolverLevel::ForcedDense, + ]; + for (expected, level) in levels.iter().enumerate() { + assert_eq!(*level as usize, expected); + assert!(!level.name().is_empty()); } + assert!(SolverLevel::DenseEvd < SolverLevel::ForcedDense); } #[test] diff --git a/src/solvers/quality.rs b/src/solvers/quality.rs new file mode 100644 index 0000000..fac4196 --- /dev/null +++ b/src/solvers/quality.rs @@ -0,0 +1,145 @@ +//! Residual-quality thresholds and checks for the solver escalation chain. + +use ndarray::{Array1, Array2}; +use sprs::CsMatI; + +/// Maximum acceptable max-residual from rSVD before falling to Level 5. +/// rSVD with 2 power iterations typically achieves 1e-4 to 1e-6 on well-conditioned +/// graphs; 1e-2 accepts all such results while correctly escalating pathological cases. +pub const RSVD_QUALITY_THRESHOLD: f64 = 1e-2; + +/// Maximum acceptable max-residual from dense EVD (Levels 0 and 5). +/// Dense EVD via faer is numerically exact (machine precision); 1e-6 leaves +/// a generous margin while catching any pathological faer regression. +pub const DENSE_EVD_QUALITY_THRESHOLD: f64 = 1e-6; + +/// Maximum acceptable max-residual from LOBPCG (Levels 1 and 3). +/// Set to 2e-5: provides ≥2× safety margin for the tightest observed fixture +/// (blobs_connected_2000 at 9.097e-6, margin = 2.20×). Tighter than rSVD (1e-2). +pub const LOBPCG_QUALITY_THRESHOLD: f64 = 2e-5; + +/// Maximum acceptable max-residual from shift-and-invert LOBPCG (Level 2). +/// Sinv achieves near-exact results (like dense EVD); 1e-6 accepts all +/// well-converged results while correctly escalating pathological graphs. +pub const SINV_LOBPCG_QUALITY_THRESHOLD: f64 = 1e-6; + +/// LOBPCG internal per-vector convergence tolerance (linfa-linalg `tol` argument). +/// Remains at 1e-5 — this is independent of `LOBPCG_QUALITY_THRESHOLD`: the former +/// controls the iterative solver's per-step stopping criterion; the latter is the +/// post-solve acceptance gate applied to the returned residuals. +pub const LOBPCG_ACCEPT_TOL: f64 = 1e-5; + +/// Linfa-linalg internal convergence tolerance for shift-invert LOBPCG. +/// Tighter than SINV_LOBPCG_QUALITY_THRESHOLD (1e-6) because this controls the iterative +/// solver's per-step residual; the outer acceptance guard (SINV_LOBPCG_QUALITY_THRESHOLD) +/// then decides whether the converged result is good enough to use. +pub const SINV_LINFA_TOL: f64 = 1e-8; + +/// Computes the relative residual `‖L·v − λ·v‖₂ / max(‖v‖₂, ε)` for a single eigenpair. +pub fn eigenpair_residual( + laplacian: &CsMatI, + eigenvector: &Array1, + eigenvalue: f64, +) -> f64 { + let lv = laplacian * eigenvector; + let lambda_v = eigenvector.mapv(|x| eigenvalue * x); + let diff = &lv - &lambda_v; + let v_norm = eigenvector.dot(eigenvector).sqrt().max(1e-300); + diff.dot(&diff).sqrt() / v_norm +} + +/// Returns the maximum relative residual `‖L·v − λ·v‖₂ / ‖v‖₂` over all eigenpairs. +/// +/// Delegates per-pair computation to [`eigenpair_residual`]. Returns `NaN` if any +/// individual residual is `NaN`. +pub fn max_eigenpair_residual( + laplacian: &CsMatI, + eigenvalues: &Array1, + eigenvectors: &Array2, +) -> f64 { + eigenvalues + .iter() + .enumerate() + .map(|(i, &lambda)| { + let v = eigenvectors.column(i).to_owned(); + eigenpair_residual(laplacian, &v, lambda) + }) + .fold(0.0_f64, |a, b| { + if a.is_nan() || b.is_nan() { + f64::NAN + } else { + a.max(b) + } + }) +} + +#[cfg(test)] +mod tests { + use super::*; + + /// 3-node path Laplacian: [[1,-1,0],[-1,2,-1],[0,-1,1]] + fn path_laplacian_3() -> CsMatI { + CsMatI::new( + (3, 3), + vec![0usize, 2, 5, 7], + vec![0usize, 1, 0, 1, 2, 1, 2], + vec![1.0_f64, -1.0, -1.0, 2.0, -1.0, -1.0, 1.0], + ) + } + + #[test] + fn t_const_01_solver_thresholds_have_required_values() { + assert_eq!(DENSE_EVD_QUALITY_THRESHOLD, 1e-6_f64); + assert_eq!(LOBPCG_QUALITY_THRESHOLD, 2e-5_f64); + assert_eq!(SINV_LOBPCG_QUALITY_THRESHOLD, 1e-6_f64); + assert_eq!(RSVD_QUALITY_THRESHOLD, 1e-2_f64); + assert_eq!(LOBPCG_ACCEPT_TOL, 1e-5_f64); + } + + #[test] + fn t_const_02_threshold_ordering() { + assert_eq!(DENSE_EVD_QUALITY_THRESHOLD, SINV_LOBPCG_QUALITY_THRESHOLD); + const { assert!(SINV_LOBPCG_QUALITY_THRESHOLD < LOBPCG_QUALITY_THRESHOLD) }; + const { assert!(LOBPCG_QUALITY_THRESHOLD < RSVD_QUALITY_THRESHOLD) }; + } + + #[test] + fn t_eresid_01_trivial_eigenvector_near_zero() { + let laplacian = path_laplacian_3(); + let s = 1.0_f64 / 3.0_f64.sqrt(); + let v = Array1::from_vec(vec![s, s, s]); + let residual = eigenpair_residual(&laplacian, &v, 0.0); + assert!( + residual < 1e-10, + "trivial eigenvector residual={residual:.2e}, expected < 1e-10" + ); + } + + #[test] + fn t_eresid_02_non_eigenvector_large_residual() { + let laplacian = path_laplacian_3(); + let v = Array1::from_vec(vec![1.0_f64, 0.0, 0.0]); + let residual = eigenpair_residual(&laplacian, &v, 0.0); + assert!( + residual >= RSVD_QUALITY_THRESHOLD, + "non-eigenvector residual={residual:.2e}, expected >= RSVD_QUALITY_THRESHOLD={RSVD_QUALITY_THRESHOLD:.2e}" + ); + } + + #[test] + fn t_maxresid_01_returns_worst_across_two_eigenpairs() { + let laplacian = path_laplacian_3(); + // Trivial eigenvector at λ=0: small residual + let s = 1.0_f64 / 3.0_f64.sqrt(); + // Non-eigenvector at λ=0: large residual + let eigenvalues = Array1::from_vec(vec![0.0_f64, 0.0_f64]); + let eigenvectors = + Array2::from_shape_vec((3, 2), vec![s, 1.0_f64, s, 0.0_f64, s, 0.0_f64]).unwrap(); + let max_res = max_eigenpair_residual(&laplacian, &eigenvalues, &eigenvectors); + // The second column [1,0,0] has a large residual; max must reflect that. + assert!( + max_res >= RSVD_QUALITY_THRESHOLD, + "max_residual={max_res:.2e}, expected >= RSVD_QUALITY_THRESHOLD" + ); + } +} diff --git a/src/solvers/rsvd.rs b/src/solvers/rsvd.rs index 3e66c09..322b2d5 100644 --- a/src/solvers/rsvd.rs +++ b/src/solvers/rsvd.rs @@ -12,7 +12,7 @@ //! residual threshold (1e-2) means Level 4 rarely fails its quality gate. If it does, //! Level 5 (forced dense EVD) is the final fallback. -use super::EigenResult; +use super::{EigenResult, SolverParams}; use faer::linalg::solvers::{Qr, SelfAdjointEigen}; use faer::{Mat as FaerMat, Side}; use ndarray::{Array1, Array2}; @@ -93,55 +93,21 @@ fn sym_eig(b: &Array2) -> (Vec, Array2) { (eigenvalues, eigenvectors) } +/// Default number of QR-stabilized power-iteration passes. +pub(crate) const DEFAULT_NBITER: usize = 2; + /// Returns the subspace size k for randomized SVD. /// -/// Oversampling scales with n/10 so large graphs get a subspace large enough to -/// produce residuals below `RSVD_QUALITY_THRESHOLD`, avoiding fallthrough to the -/// O(n³) Level 5 dense EVD. -fn rsvd_k_sub(n: usize, rank: usize) -> usize { - let oversampling = (n / 10).max(rank.max(5)).min(n.saturating_sub(rank)); +/// With `oversampling = None` the oversampling scales with n/10 so large graphs get a +/// subspace large enough to produce residuals below `RSVD_QUALITY_THRESHOLD`, avoiding +/// fallthrough to the O(n³) Level 5 dense EVD. An explicit oversampling count is used +/// as given. The result never exceeds `n`. +fn rsvd_k_sub(n: usize, rank: usize, oversampling: Option) -> usize { + let oversampling = + oversampling.unwrap_or_else(|| (n / 10).max(rank.max(5)).min(n.saturating_sub(rank))); (rank + oversampling).min(n) } -/// Returns the effective subspace size k for randomized SVD. -/// -/// In test builds (`--features testing`), reads the `SPECTRAL_RSVD_OVERSAMPLING` -/// environment variable as the oversampling count, falling back to `rsvd_k_sub` -/// on absence or parse error. In release builds the function is a trivial delegate -/// that the compiler inlines away entirely. -#[cfg(feature = "testing")] -fn rsvd_k_sub_effective(n: usize, rank: usize) -> usize { - std::env::var("SPECTRAL_RSVD_OVERSAMPLING") - .ok() - .and_then(|s| s.parse::().ok()) - .map(|oversampling| (rank + oversampling).min(n)) - .unwrap_or_else(|| rsvd_k_sub(n, rank)) -} - -#[cfg(not(feature = "testing"))] -fn rsvd_k_sub_effective(n: usize, rank: usize) -> usize { - rsvd_k_sub(n, rank) -} - -/// Returns the effective number of power-iteration passes for randomized SVD. -/// -/// In test builds (`--features testing`), reads the `SPECTRAL_RSVD_NBITER` -/// environment variable as the iteration count, falling back to `2` on absence -/// or parse error. In release builds the function always returns `2` and the -/// compiler inlines it away entirely. -#[cfg(feature = "testing")] -fn rsvd_nbiter_effective() -> usize { - std::env::var("SPECTRAL_RSVD_NBITER") - .ok() - .and_then(|s| s.parse::().ok()) - .unwrap_or(2) -} - -#[cfg(not(feature = "testing"))] -fn rsvd_nbiter_effective() -> usize { - 2 -} - /// Randomized SVD eigensolver via the 2I − L trick (Level 3). /// /// Implements Algorithm 5.1 (Halko-Tropp) with power iteration: @@ -149,10 +115,11 @@ fn rsvd_nbiter_effective() -> usize { /// - Computes the top-(n_components+1) eigenvalues/vectors of M via randomized SVD /// - Discards the trivial eigenvector (column 0, corresponding to λ_L ≈ 0) /// - Maps eigenvalues back to L eigenvalues via λ_L = 2 − σ_M -pub(crate) fn rsvd_solve( +pub fn rsvd_solve( laplacian: &CsMatI, n_components: usize, seed: u64, + params: &SolverParams, ) -> EigenResult { let n = laplacian.rows(); assert!( @@ -166,8 +133,8 @@ pub(crate) fn rsvd_solve( // rank = n_components + 1: request one extra so we can discard the trivial vector let rank = n_components + 1; // k = total random vectors; see rsvd_k_sub for the oversampling formula. - let k = rsvd_k_sub_effective(n, rank); - let nbiter = rsvd_nbiter_effective(); // QR-stabilized subspace iterations (Halko-Tropp Algorithm 4.4) + let k = rsvd_k_sub(n, rank, params.rsvd_oversampling); + let nbiter = params.rsvd_nbiter; // QR-stabilized subspace iterations (Halko-Tropp Algorithm 4.4) // ── Step A: Form M = 2I - L ────────────────────────────────────────────── let m = two_i_minus_laplacian(laplacian); @@ -246,8 +213,8 @@ pub(crate) fn rsvd_solve( /// /// `k_sub` controls the subspace size; larger values give higher accuracy at /// higher cost. Must satisfy `k_sub > n_components + 1`. -#[cfg(feature = "testing")] -pub(crate) fn rsvd_solve_accurate( +#[cfg(feature = "__internal")] +pub fn rsvd_solve_accurate( laplacian: &CsMatI, n_components: usize, seed: u64, @@ -380,7 +347,8 @@ mod tests { let l = build_normalized_laplacian(&graph, inv_sqrt_deg.as_slice().unwrap()); let n_components = 2; - let (eigenvalues, eigenvectors) = rsvd_solve(&l, n_components, 42); + let (eigenvalues, eigenvectors) = + rsvd_solve(&l, n_components, 42, &SolverParams::default()); assert_eq!( eigenvalues.shape(), @@ -432,7 +400,7 @@ mod tests { let l = build_normalized_laplacian(&graph, inv_sqrt_deg.as_slice().unwrap()); let n_components = 2; - let (eigenvalues, eigenvectors) = rsvd_solve(&l, n_components, 0); + let (eigenvalues, eigenvectors) = rsvd_solve(&l, n_components, 0, &SolverParams::default()); let eig_slice = eigenvalues.as_slice().unwrap(); @@ -472,87 +440,43 @@ mod tests { } } - // T1 — formula preserved when env var is absent - #[test] - fn rsvd_k_sub_returns_default_when_env_unset() { - // SAFETY: single-threaded test (--test-threads=1), no concurrent env readers - unsafe { - std::env::remove_var("SPECTRAL_RSVD_OVERSAMPLING"); - } - let n = 200_usize; - let rank = 3_usize; - let oversampling = (n / 10).max(rank.max(5)).min(n.saturating_sub(rank)); - let expected = (rank + oversampling).min(n); - assert_eq!(rsvd_k_sub_effective(n, rank), expected); - } - - // T2 — env override is respected - #[cfg(feature = "testing")] - #[test] - fn rsvd_k_sub_reads_env_override() { - // SAFETY: single-threaded test (--test-threads=1), no concurrent env readers - unsafe { - std::env::set_var("SPECTRAL_RSVD_OVERSAMPLING", "10"); - } - let n = 200_usize; - let rank = 3_usize; - assert_eq!(rsvd_k_sub_effective(n, rank), rank + 10); - unsafe { - std::env::remove_var("SPECTRAL_RSVD_OVERSAMPLING"); - } - } - - // T3 — unparseable value falls back to formula #[test] - fn rsvd_k_sub_falls_back_on_parse_error() { - // SAFETY: single-threaded test (--test-threads=1), no concurrent env readers - unsafe { - std::env::set_var("SPECTRAL_RSVD_OVERSAMPLING", "abc"); - } - let n = 200_usize; - let rank = 3_usize; - let oversampling = (n / 10).max(rank.max(5)).min(n.saturating_sub(rank)); - let expected = (rank + oversampling).min(n); - assert_eq!(rsvd_k_sub_effective(n, rank), expected); - unsafe { - std::env::remove_var("SPECTRAL_RSVD_OVERSAMPLING"); - } + fn rsvd_k_sub_default_oversampling_scales_with_n() { + // n/10 dominates for large n; the floor of 5 applies for small n. + assert_eq!(rsvd_k_sub(200, 3, None), 3 + 20); + assert_eq!(rsvd_k_sub(20, 3, None), 3 + 5); + // Never larger than n. + assert_eq!(rsvd_k_sub(6, 3, None), 6); } - // T-NBE-1 — rsvd_nbiter_effective returns 2 when env var is absent #[test] - fn rsvd_nbiter_returns_default_when_env_unset() { - // SAFETY: single-threaded test (--test-threads=1), no concurrent env readers - unsafe { - std::env::remove_var("SPECTRAL_RSVD_NBITER"); - } - assert_eq!(rsvd_nbiter_effective(), 2); + fn rsvd_k_sub_uses_explicit_oversampling() { + assert_eq!(rsvd_k_sub(200, 3, Some(10)), 13); + assert_eq!(rsvd_k_sub(200, 3, Some(0)), 3); + // Clamped to n. + assert_eq!(rsvd_k_sub(8, 3, Some(100)), 8); } - // T-NBE-2 — rsvd_nbiter_effective reads SPECTRAL_RSVD_NBITER env var (testing only) - #[cfg(feature = "testing")] #[test] - fn rsvd_nbiter_reads_env_override() { - // SAFETY: single-threaded test (--test-threads=1), no concurrent env readers - unsafe { - std::env::set_var("SPECTRAL_RSVD_NBITER", "4"); - } - assert_eq!(rsvd_nbiter_effective(), 4); - unsafe { - std::env::remove_var("SPECTRAL_RSVD_NBITER"); - } - } + fn rsvd_solve_honours_params() { + // A larger explicit subspace and more power iterations must still produce the + // analytical 6-ring eigenvalues (0, 0.5, 0.5). + let n = 6; + let edges: Vec<(usize, usize, f32)> = (0..n).map(|i| (i, (i + 1) % n, 1.0f32)).collect(); + let graph = make_graph(n, &edges); + let (_, sqrt_deg) = crate::laplacian::compute_degrees(&graph, ComputeMode::PythonCompat); + let inv_sqrt_deg = sqrt_deg.mapv(|x| if x == 0.0 { 0.0 } else { 1.0 / x }); + let l = build_normalized_laplacian(&graph, inv_sqrt_deg.as_slice().unwrap()); - // T-NBE-3 — rsvd_nbiter_effective falls back to 2 on parse error - #[test] - fn rsvd_nbiter_falls_back_on_parse_error() { - // SAFETY: single-threaded test (--test-threads=1), no concurrent env readers - unsafe { - std::env::set_var("SPECTRAL_RSVD_NBITER", "xyz"); - } - assert_eq!(rsvd_nbiter_effective(), 2); - unsafe { - std::env::remove_var("SPECTRAL_RSVD_NBITER"); - } + let params = SolverParams { + rsvd_oversampling: Some(2), + rsvd_nbiter: 4, + ..SolverParams::default() + }; + let (eigenvalues, eigenvectors) = rsvd_solve(&l, 2, 0, ¶ms); + assert_eq!(eigenvectors.shape(), &[n, 3]); + assert!(eigenvalues[0].abs() < 1e-3); + assert!((eigenvalues[1] - 0.5).abs() < 1e-4); + assert!((eigenvalues[2] - 0.5).abs() < 1e-4); } } diff --git a/src/solvers/sinv.rs b/src/solvers/sinv.rs index aab42c2..cf06655 100644 --- a/src/solvers/sinv.rs +++ b/src/solvers/sinv.rs @@ -28,7 +28,7 @@ use rand_distr::{Distribution, StandardNormal}; use sprs::CsMatI; use super::EigenResult; -use crate::metrics::{SINV_LINFA_TOL, SINV_LOBPCG_QUALITY_THRESHOLD}; +use super::quality::{SINV_LINFA_TOL, SINV_LOBPCG_QUALITY_THRESHOLD}; /// Diagonal shift ε making M = L + εI strictly SPD (REQ-SINV-002). pub(crate) const SINV_SHIFT: f64 = 1e-4; @@ -281,8 +281,11 @@ mod tests { // All residuals < 1e-8. for i in 0..eigvals.len() { - let r = - crate::metrics::eigenpair_residual(&mat, &eigvecs.column(i).to_owned(), eigvals[i]); + let r = crate::solvers::quality::eigenpair_residual( + &mat, + &eigvecs.column(i).to_owned(), + eigvals[i], + ); assert!(r < 1e-8, "residual for eigenpair {i}: {r} >= 1e-8"); } } diff --git a/tests/common/diagnostics.rs b/tests/common/diagnostics.rs new file mode 100644 index 0000000..994bce2 --- /dev/null +++ b/tests/common/diagnostics.rs @@ -0,0 +1,313 @@ +//! Diagnostic metrics for judging eigensolver output: accuracy checks, parity against a +//! reference, and conditioning figures. Shared by the integration tests and the research +//! harness. + +#![allow(dead_code)] + +use faer::linalg::solvers::SelfAdjointEigen; +use faer::{Mat as FaerMat, Side}; +use ndarray::{Array1, Array2, ArrayView1, ArrayView2}; + +/// Minimum eigenvalue gap to treat eigenpairs as distinct; below this use subspace comparison. +pub const DEGENERATE_GAP_THRESHOLD: f64 = 1e-6; + +/// Minimum acceptable subspace Gram determinant for quality assessment. +pub const SUBSPACE_GRAM_DET_THRESHOLD: f64 = 0.95; + +// ─── Accuracy metric functions ──────────────────────────────────────────────── + +/// Computes `‖VᵀV − I‖_F` where `V` has columns `eigenvectors`. +/// +/// Returns 0.0 for a perfectly orthonormal set of columns. +pub fn orthogonality_error(eigenvectors: &Array2) -> f64 { + let k = eigenvectors.ncols(); + let vtv = eigenvectors.t().dot(eigenvectors); + let mut diff = vtv; + for i in 0..k { + diff[[i, i]] -= 1.0; + } + diff.iter().map(|x| x * x).sum::().sqrt() +} + +/// Checks whether eigenvalues are in range and sorted ascending. +/// +/// Returns `(in_range, sorted_ascending)` where: +/// - `in_range`: all `λ ∈ [−tol, 2+tol]` +/// - `sorted_ascending`: `λ[i] ≤ λ[i+1] + tol` for all `i` +pub fn check_eigenvalue_bounds(eigenvalues: &Array1, tol: f64) -> (bool, bool) { + assert!( + tol >= 0.0, + "check_eigenvalue_bounds: tol must be non-negative, got {}", + tol + ); + let in_range = eigenvalues.iter().all(|&v| v >= -tol && v <= 2.0 + tol); + let sorted = eigenvalues + .windows(2) + .into_iter() + .all(|w| w[0] <= w[1] + tol); + (in_range, sorted) +} + +/// Computes the separation ratio `min_inter_centroid_distance / max_intra_component_spread` +/// for a disconnected-graph embedding. +/// +/// `labels` assigns each row of `embedding` to a component index in `0..n_components`. +/// Returns `f64::INFINITY` when `max_intra == 0.0` (all points collapse to centroids). +pub fn separation_ratio(embedding: ArrayView2, labels: &[usize]) -> f64 { + let n = labels.len(); + assert_eq!( + embedding.nrows(), + n, + "embedding rows must match labels length" + ); + let n_dims = embedding.ncols(); + + let n_components = labels.iter().copied().max().map(|m| m + 1).unwrap_or(0); + if n_components < 2 { + return f64::INFINITY; + } + + let mut component_members: Vec> = vec![Vec::new(); n_components]; + for (i, &label) in labels.iter().enumerate() { + component_members[label].push(i); + } + + let centroids: Vec> = component_members + .iter() + .map(|members| { + let n_c = members.len() as f64; + let mut c = vec![0.0f64; n_dims]; + for &orig_i in members { + for d in 0..n_dims { + c[d] += embedding[[orig_i, d]]; + } + } + c.iter_mut().for_each(|x| *x /= n_c); + c + }) + .collect(); + + let min_inter = (0..n_components) + .flat_map(|i| ((i + 1)..n_components).map(move |j| (i, j))) + .map(|(i, j)| { + (0..n_dims) + .map(|d| (centroids[i][d] - centroids[j][d]).powi(2)) + .sum::() + .sqrt() + }) + .fold(f64::INFINITY, f64::min); + + let max_intra = component_members + .iter() + .enumerate() + .map(|(c_idx, members)| { + members + .iter() + .map(|&orig_i| { + (0..n_dims) + .map(|d| (embedding[[orig_i, d]] - centroids[c_idx][d]).powi(2)) + .sum::() + .sqrt() + }) + .fold(0.0f64, f64::max) + }) + .fold(0.0f64, f64::max); + + if max_intra > 0.0 { + min_inter / max_intra + } else { + f64::INFINITY + } +} + +// ─── Parity metric functions ────────────────────────────────────────────────── + +/// Element-wise `|computed[i] − reference[i]|`. +/// +/// # Panics +/// Panics if `computed` and `reference` have different lengths. +pub fn eigenvalue_abs_errors(computed: &Array1, reference: &Array1) -> Array1 { + assert_eq!( + computed.len(), + reference.len(), + "eigenvalue_abs_errors: lengths must match ({} vs {})", + computed.len(), + reference.len() + ); + (computed - reference).mapv(f64::abs) +} + +/// Computes `|det(G)|` for the 2×2 cross-Gram matrix of two n×2 subspaces. +/// +/// Each column is normalized by its L2 norm before building the cross-Gram matrix: +/// `G[i,j] = dot(r_i / ‖r_i‖, u_j / ‖u_j‖)`. +/// Returns `|a·d − b·c|` where `[[a,b],[c,d]]` is the normalized 2×2 Gram matrix. +pub fn subspace_gram_det(u: ArrayView2, r: ArrayView2) -> f64 { + assert_eq!( + u.ncols(), + 2, + "subspace_gram_det: u must have exactly 2 columns" + ); + assert_eq!( + r.ncols(), + 2, + "subspace_gram_det: r must have exactly 2 columns" + ); + assert_eq!( + u.nrows(), + r.nrows(), + "subspace_gram_det: u and r must have the same number of rows" + ); + + let norm = |v: ArrayView1| v.iter().map(|x| x * x).sum::().sqrt().max(1e-300); + let dot = |a: ArrayView1, b: ArrayView1| -> f64 { + a.iter().zip(b.iter()).map(|(x, y)| x * y).sum() + }; + + let v1 = u.column(0); + let v2 = u.column(1); + let r1 = r.column(0); + let r2 = r.column(1); + + let n1 = norm(v1); + let n2 = norm(v2); + let nr1 = norm(r1); + let nr2 = norm(r2); + + let a = dot(r1, v1) / (nr1 * n1); + let b = dot(r1, v2) / (nr1 * n2); + let c = dot(r2, v1) / (nr2 * n1); + let d = dot(r2, v2) / (nr2 * n2); + + (a * d - b * c).abs() +} + +/// k-dimensional generalization of [`subspace_gram_det`]. +/// +/// Steps: +/// 1. Normalize each column of both inputs by its L2 norm. +/// 2. Compute the k×k cross-Gram matrix `G = reference_norm^T · computed_norm`. +/// 3. Compute the SVD of `G` via the eigendecomposition of `GᵀG` (using faer). +/// 4. Return the product of singular values, which equals `|det(G)|` for square `G`. +pub fn subspace_gram_det_kd(computed: ArrayView2, reference: ArrayView2) -> f64 { + let k = computed.ncols(); + assert_eq!( + reference.ncols(), + k, + "subspace_gram_det_kd: computed and reference must have the same number of columns" + ); + assert_eq!( + computed.nrows(), + reference.nrows(), + "subspace_gram_det_kd: computed and reference must have the same number of rows" + ); + + // Normalize each column + let normalize = |mat: ArrayView2| -> Array2 { + let mut norm_mat = Array2::::zeros(mat.dim()); + for (j, col) in mat.columns().into_iter().enumerate() { + let norm = col.dot(&col).sqrt().max(f64::EPSILON); + for (i, &v) in col.iter().enumerate() { + norm_mat[[i, j]] = v / norm; + } + } + norm_mat + }; + + let cn = normalize(computed); + let rn = normalize(reference); + + // G = rn^T · cn (k × k cross-Gram matrix) + let g = rn.t().dot(&cn); + + // G^T G is symmetric PSD; its eigenvalues are the squares of the singular values of G. + let gtg = g.t().dot(&g); + let gtg_faer = FaerMat::from_fn(k, k, |i, j| gtg[[i, j]]); + let eigen = SelfAdjointEigen::new(gtg_faer.as_ref(), Side::Lower) + .expect("subspace_gram_det_kd: SelfAdjointEigen failed on G^T G"); + + // sqrt(product of eigenvalues of G^T G) = product of singular values = |det(G)| + let mut det_sq = 1.0f64; + eigen.S().for_each(|&x| det_sq *= x.max(0.0)); + det_sq.sqrt() +} + +/// Sign-agnostic maximum column-wise error between `computed` and `reference`. +/// +/// For each column, computes `min(‖col_rust − col_ref‖∞, ‖col_rust + col_ref‖∞)`. +/// Returns the maximum such value across all columns. +/// +/// Inputs are `f32`; internal arithmetic is in `f64` for precision. +pub fn sign_agnostic_max_error(computed: &Array2, reference: &Array2) -> f64 { + assert_eq!( + computed.ncols(), + reference.ncols(), + "sign_agnostic_max_error: column count mismatch" + ); + assert_eq!( + computed.nrows(), + reference.nrows(), + "sign_agnostic_max_error: row count mismatch" + ); + + let mut worst = 0.0f64; + for col in 0..computed.ncols() { + let r = computed.column(col); + let rf = reference.column(col); + let err_pos: f64 = r + .iter() + .zip(rf.iter()) + .map(|(&a, &b)| (a as f64 - b as f64).abs()) + .fold(0.0f64, f64::max); + let err_neg: f64 = r + .iter() + .zip(rf.iter()) + .map(|(&a, &b)| (a as f64 + b as f64).abs()) + .fold(0.0f64, f64::max); + worst = worst.max(err_pos.min(err_neg)); + } + worst +} + +// ─── Diagnostic functions ───────────────────────────────────────────────────── + +/// Returns `threshold / worst_value`. +/// +/// Returns `f64::INFINITY` if `worst_value == 0.0`. +pub fn tolerance_margin(threshold: f64, worst_value: f64) -> f64 { + if worst_value == 0.0 { + f64::INFINITY + } else { + threshold / worst_value + } +} + +/// Returns `eigenvalues[1] − eigenvalues[0]` (λ₂ − λ₁). +/// +/// # Panics +/// Panics if `eigenvalues` has fewer than 2 elements. +pub fn spectral_gap(eigenvalues: &Array1) -> f64 { + assert!( + eigenvalues.len() >= 2, + "spectral_gap: need at least 2 eigenvalues" + ); + eigenvalues[1] - eigenvalues[0] +} + +/// Returns `eigenvalues[last] / eigenvalues[1]` (λ_last / λ₂). +/// +/// Returns `f64::INFINITY` if `eigenvalues[1] == 0.0`. +/// +/// # Panics +/// Panics if `eigenvalues` has fewer than 2 elements. +pub fn eigenvalue_condition_number(eigenvalues: &Array1) -> f64 { + assert!( + eigenvalues.len() >= 2, + "eigenvalue_condition_number: need at least 2 eigenvalues" + ); + if eigenvalues[1] == 0.0 { + f64::INFINITY + } else { + eigenvalues[eigenvalues.len() - 1] / eigenvalues[1] + } +} diff --git a/tests/common/mod.rs b/tests/common/fixtures.rs similarity index 83% rename from tests/common/mod.rs rename to tests/common/fixtures.rs index 613f3bd..70f17bb 100644 --- a/tests/common/mod.rs +++ b/tests/common/fixtures.rs @@ -1,16 +1,28 @@ +//! Fixture loaders and synthetic graph builders shared by the test binaries. + #![allow(dead_code)] +use ndarray::{Array, Array1, Dimension}; +use ndarray_npy::{NpzReader, ReadNpyError, ReadNpzError, ReadableElement}; +use sprs::{CsMat, CsMatI}; use std::path::{Path, PathBuf}; -pub fn fixture_path(dataset: &str, filename: &str) -> PathBuf { - Path::new(env!("CARGO_MANIFEST_DIR")) - .join("tests/fixtures") - .join(dataset) - .join(filename) +/// Directory holding the Python-generated reference fixtures. +/// +/// Located by walking up from the including package's manifest directory to the first +/// ancestor that contains `tests/fixtures`, so every workspace member finds the same data. +pub fn fixtures_dir() -> PathBuf { + let manifest_dir = Path::new(env!("CARGO_MANIFEST_DIR")); + manifest_dir + .ancestors() + .map(|dir| dir.join("tests").join("fixtures")) + .find(|candidate| candidate.is_dir()) + .unwrap_or_else(|| panic!("no tests/fixtures directory at or above {manifest_dir:?}")) } -use ndarray::{Array, Array1, Dimension}; -use ndarray_npy::{NpzReader, ReadNpyError, ReadNpzError, ReadableElement}; +pub fn fixture_path(dataset: &str, filename: &str) -> PathBuf { + fixtures_dir().join(dataset).join(filename) +} pub fn load_dense(path: &Path, key: &str) -> Array where @@ -25,8 +37,7 @@ where .unwrap_or_else(|e| panic!("key {:?} not found in {:?}: {}", key, path, e)) } -use sprs::CsMat; - +/// Load a scipy-saved CSR matrix as f64 data with usize indices. pub fn load_sparse_csr(path: &Path) -> CsMat { let file = std::fs::File::open(path) .unwrap_or_else(|e| panic!("cannot open fixture {:?}: {}", path, e)); @@ -99,54 +110,63 @@ pub fn load_sparse_csr(path: &Path) -> CsMat { .unwrap_or_else(|e| panic!("fixture CSR structure invalid in {:?}: {:?}", path, e)) } -/// Compute the relative residual ||L·v - λ·v|| / ||v|| for an eigenpair. -/// -/// Delegates to `spectral_init::metrics::eigenpair_residual`. -pub fn residual_spmv( - laplacian: &sprs::CsMat, - eigvec: ndarray::ArrayView1, - eigval: f64, -) -> f64 { - spectral_init::metrics::eigenpair_residual(laplacian, &eigvec.to_owned(), eigval) -} +/// Load a scipy-saved CSR matrix with f32 data and u32 column indices. +/// Python scipy typically stores indices as int32 (i32), which are cast to u32 here. +pub fn load_sparse_csr_f32_u32(path: &Path) -> CsMatI { + let file = std::fs::File::open(path) + .unwrap_or_else(|e| panic!("cannot open fixture {:?}: {}", path, e)); + let mut npz = NpzReader::new(file) + .unwrap_or_else(|e| panic!("cannot open NpzReader for {:?}: {}", path, e)); -/// Compute the residual norm ||A*v - λ*v|| / ||v|| for one eigenpair. -/// -/// # Justified Exception -/// This function operates over the [`spectral_init::operator::LinearOperator`] trait rather -/// than a concrete sparse matrix. It is needed by operator-generic tests -/// (e.g., warm-restart and SIMD-operator tests) that exercise `CsrOperatorSimd` and other -/// `LinearOperator` implementations. No equivalent exists in `src/metrics.rs`, which takes -/// a concrete `CsMatI`. This variant is retained here intentionally. -pub fn eigenpair_residual( - op: &O, - eigvec: ndarray::ArrayView1, - eigval: f64, -) -> f64 { - let n = eigvec.len(); - let col: ndarray::Array2 = eigvec.to_owned().insert_axis(ndarray::Axis(1)); - let mut av = ndarray::Array2::zeros((n, 1)); - op.apply(col.view(), &mut av); - let mut sq = 0.0_f64; - let mut norm_sq = 0.0_f64; - for r in 0..n { - let diff = av[[r, 0]] - eigval * col[[r, 0]]; - sq += diff * diff; - norm_sq += col[[r, 0]] * col[[r, 0]]; - } - sq.sqrt() / norm_sq.sqrt().max(1e-300) -} + // data: f32 + let data: Vec = npz + .by_name::, ndarray::Ix1>("data") + .unwrap_or_else(|e| panic!("data key not found in {:?}: {}", path, e)) + .into_iter() + .collect(); -pub fn load_metadata(path: &Path) -> serde_json::Value { - let content = std::fs::read_to_string(path) - .unwrap_or_else(|e| panic!("cannot read metadata {:?}: {}", path, e)); - serde_json::from_str(&content).unwrap_or_else(|e| panic!("invalid JSON in {:?}: {}", path, e)) -} + // indices: i32 → u32 + let indices: Vec = match npz.by_name::, ndarray::Ix1>("indices") { + Ok(arr) => arr.iter().map(|&x| x as u32).collect(), + Err(ReadNpzError::Npy(ReadNpyError::WrongDescriptor(_))) => { + let arr: Array1 = npz + .by_name("indices") + .unwrap_or_else(|e| panic!("indices key not found in {:?}: {}", path, e)); + arr.iter().map(|&x| x as u32).collect() + } + Err(e) => panic!("error reading 'indices' from {:?}: {}", path, e), + }; -use sprs::CsMatI; + // indptr: i32 → usize + let indptr: Vec = match npz.by_name::, ndarray::Ix1>("indptr") { + Ok(arr) => arr.iter().map(|&x| x as usize).collect(), + Err(ReadNpzError::Npy(ReadNpyError::WrongDescriptor(_))) => { + let arr: Array1 = npz + .by_name("indptr") + .unwrap_or_else(|e| panic!("indptr key not found in {:?}: {}", path, e)); + arr.iter().map(|&x| x as usize).collect() + } + Err(e) => panic!("error reading 'indptr' from {:?}: {}", path, e), + }; + + // shape: i32 → usize + let shape_arr: Vec = match npz.by_name::, ndarray::Ix1>("shape") + { + Ok(arr) => arr.iter().map(|&x| x as usize).collect(), + Err(ReadNpzError::Npy(ReadNpyError::WrongDescriptor(_))) => { + let arr: Array1 = npz + .by_name("shape") + .unwrap_or_else(|e| panic!("shape key not found in {:?}: {}", path, e)); + arr.iter().map(|&x| x as usize).collect() + } + Err(e) => panic!("error reading 'shape' from {:?}: {}", path, e), + }; + + let (rows, cols) = (shape_arr[0], shape_arr[1]); + CsMatI::try_new((rows, cols), indptr, indices, data) + .unwrap_or_else(|e| panic!("fixture CSR structure invalid in {:?}: {:?}", path, e)) +} -/// Load a scipy-saved CSR matrix with f32 data and u32 column indices. -/// Python scipy typically stores indices as int32 (i32), which are cast to u32 here. /// Convert a label vector to a set-of-sets, permitting label-invariant comparison. /// Two label assignments are equivalent iff they produce the same partition. pub fn partition_of( @@ -231,57 +251,36 @@ pub fn make_path(n: u32) -> CsMatI { CsMatI::::new((n_usize, n_usize), indptr, indices, data) } -pub fn load_sparse_csr_f32_u32(path: &Path) -> CsMatI { - let file = std::fs::File::open(path) - .unwrap_or_else(|e| panic!("cannot open fixture {:?}: {}", path, e)); - let mut npz = NpzReader::new(file) - .unwrap_or_else(|e| panic!("cannot open NpzReader for {:?}: {}", path, e)); - - // data: f32 - let data: Vec = npz - .by_name::, ndarray::Ix1>("data") - .unwrap_or_else(|e| panic!("data key not found in {:?}: {}", path, e)) - .into_iter() - .collect(); - - // indices: i32 → u32 - let indices: Vec = match npz.by_name::, ndarray::Ix1>("indices") { - Ok(arr) => arr.iter().map(|&x| x as u32).collect(), - Err(ReadNpzError::Npy(ReadNpyError::WrongDescriptor(_))) => { - let arr: Array1 = npz - .by_name("indices") - .unwrap_or_else(|e| panic!("indices key not found in {:?}: {}", path, e)); - arr.iter().map(|&x| x as u32).collect() - } - Err(e) => panic!("error reading 'indices' from {:?}: {}", path, e), - }; - - // indptr: i32 → usize - let indptr: Vec = match npz.by_name::, ndarray::Ix1>("indptr") { - Ok(arr) => arr.iter().map(|&x| x as usize).collect(), - Err(ReadNpzError::Npy(ReadNpyError::WrongDescriptor(_))) => { - let arr: Array1 = npz - .by_name("indptr") - .unwrap_or_else(|e| panic!("indptr key not found in {:?}: {}", path, e)); - arr.iter().map(|&x| x as usize).collect() +/// Normalized Laplacian of P_n (path graph) in f64. +/// L = D^{-1/2}(D - A)D^{-1/2}. Tridiagonal with known closed-form entries: +/// diagonal = 1.0, endpoint off-diagonals = -1/sqrt(2), interior off-diagonals = -0.5. +pub fn path_laplacian(n: usize) -> CsMatI { + let inv_sqrt2 = 1.0_f64 / 2.0_f64.sqrt(); + let mut indptr = vec![0usize; n + 1]; + let mut indices: Vec = Vec::new(); + let mut data: Vec = Vec::new(); + for i in 0..n { + if i > 0 { + let w = if i == n - 1 { -inv_sqrt2 } else { -0.5 }; + indices.push(i - 1); + data.push(w); } - Err(e) => panic!("error reading 'indptr' from {:?}: {}", path, e), - }; - - // shape: i32 → usize - let shape_arr: Vec = match npz.by_name::, ndarray::Ix1>("shape") - { - Ok(arr) => arr.iter().map(|&x| x as usize).collect(), - Err(ReadNpzError::Npy(ReadNpyError::WrongDescriptor(_))) => { - let arr: Array1 = npz - .by_name("shape") - .unwrap_or_else(|e| panic!("shape key not found in {:?}: {}", path, e)); - arr.iter().map(|&x| x as usize).collect() + indices.push(i); + data.push(1.0); + if i + 1 < n { + let w = if i == 0 { -inv_sqrt2 } else { -0.5 }; + indices.push(i + 1); + data.push(w); } - Err(e) => panic!("error reading 'shape' from {:?}: {}", path, e), - }; + indptr[i + 1] = indices.len(); + } + CsMatI::new((n, n), indptr, indices, data) +} - let (rows, cols) = (shape_arr[0], shape_arr[1]); - CsMatI::try_new((rows, cols), indptr, indices, data) - .unwrap_or_else(|e| panic!("fixture CSR structure invalid in {:?}: {:?}", path, e)) +/// sqrt_deg vector for P_n (path graph): endpoints = 1.0, interior = sqrt(2). +pub fn path_sqrt_deg(n: usize) -> Array1 { + let mut v = vec![2.0_f64.sqrt(); n]; + v[0] = 1.0; + v[n - 1] = 1.0; + Array1::from_vec(v) } diff --git a/tests/common/internals.rs b/tests/common/internals.rs new file mode 100644 index 0000000..b57ee08 --- /dev/null +++ b/tests/common/internals.rs @@ -0,0 +1,70 @@ +//! Test support built on `spectral_init::__internal`. + +#![allow(dead_code)] + +use ndarray::{Array1, Array2, ArrayView1}; +use spectral_init::__internal::{ + EigenResult, LinearOperator, SolveReport, SolverParams, solve_eigenproblem, +}; +use spectral_init::ComputeMode; +use sprs::CsMatI; + +/// Compute the relative residual ||L·v - λ·v|| / ||v|| for an eigenpair. +/// +/// Delegates to the library's `eigenpair_residual`. +pub fn residual_spmv(laplacian: &CsMatI, eigvec: ArrayView1, eigval: f64) -> f64 { + spectral_init::__internal::eigenpair_residual(laplacian, &eigvec.to_owned(), eigval) +} + +/// Compute the residual norm ||A*v - λ*v|| / ||v|| for one eigenpair of a [`LinearOperator`]. +/// +/// Unlike [`residual_spmv`], which takes a concrete sparse matrix, this works with any +/// operator, so it can check results produced through the SIMD operator. +pub fn eigenpair_residual(op: &O, eigvec: ArrayView1, eigval: f64) -> f64 { + let n = eigvec.len(); + let col: Array2 = eigvec.to_owned().insert_axis(ndarray::Axis(1)); + let mut av = Array2::zeros((n, 1)); + op.apply(col.view(), &mut av); + let mut sq = 0.0_f64; + let mut norm_sq = 0.0_f64; + for r in 0..n { + let diff = av[[r, 0]] - eigval * col[[r, 0]]; + sq += diff * diff; + norm_sq += col[[r, 0]] * col[[r, 0]]; + } + sq.sqrt() / norm_sq.sqrt().max(1e-300) +} + +/// Maximum of [`eigenpair_residual`] over every eigenpair. +pub fn max_operator_residual( + op: &O, + eigenvalues: &Array1, + eigenvectors: &Array2, +) -> f64 { + (0..eigenvalues.len()) + .map(|i| eigenpair_residual(op, eigenvectors.column(i), eigenvalues[i])) + .fold(0.0_f64, f64::max) +} + +/// Run the solver escalation chain on a bare Laplacian. +/// +/// The trivial-eigenvector hint is the all-ones vector (`sqrt_deg = ones(n)`), which is +/// what a Laplacian loaded without its degree vector calls for. +pub fn solve_with_unit_hint( + laplacian: &CsMatI, + n_components: usize, + seed: u64, + compute_mode: ComputeMode, + params: &SolverParams, +) -> (EigenResult, SolveReport) { + let sqrt_deg = Array1::ones(laplacian.rows()); + solve_eigenproblem( + laplacian, + n_components, + seed, + &sqrt_deg, + compute_mode, + params, + ) + .expect("solve_eigenproblem failed") +} diff --git a/tests/integration/test_accuracy_report.rs b/tests/internals/accuracy_report.rs similarity index 91% rename from tests/integration/test_accuracy_report.rs rename to tests/internals/accuracy_report.rs index 636814f..53e4864 100644 --- a/tests/integration/test_accuracy_report.rs +++ b/tests/internals/accuracy_report.rs @@ -1,12 +1,10 @@ -#[path = "../common/mod.rs"] -mod common; - +use crate::{diagnostics, fixtures, internals}; use ndarray::{Array1, Array2, s}; -use spectral_init::{ - ComputeMode, SpectralInitConfig, build_normalized_laplacian, compute_degrees, - embed_disconnected, find_components, select_eigenvectors, solve_eigenproblem_pub, - spectral_init, +use spectral_init::__internal::{ + SolverParams, build_normalized_laplacian, compute_degrees, embed_disconnected, find_components, + select_eigenvectors, }; +use spectral_init::{ComputeMode, SpectralInitConfig, spectral_init}; use std::path::Path; /// (name, n, is_connected, expected_n_components) @@ -75,17 +73,6 @@ fn compute_rust_pre_noise(selected: &Array2) -> Array2 { selected.mapv(|v| (v * expansion) as f32) } -fn solver_name(level: u8) -> &'static str { - match level { - 0 => "Dense EVD", - 1 => "LOBPCG", - 2 => "LOBPCG+reg", - 3 => "rSVD", - 4 => "Forced Dense EVD", - _ => "Unknown", - } -} - fn extract_subgraph_local( graph: &sprs::CsMatI, node_indices: &[usize], @@ -115,12 +102,12 @@ fn extract_subgraph_local( } fn process_disconnected_path(dataset: &str, n_embedding_dims: usize) -> DisconnectedPathMetrics { - let base = common::fixture_path(dataset, ""); + let base = fixtures::fixture_path(dataset, ""); - let graph = common::load_sparse_csr_f32_u32(&base.join("step5a_pruned.npz")); + let graph = fixtures::load_sparse_csr_f32_u32(&base.join("step5a_pruned.npz")); let raw_data: ndarray::Array2 = { let f64_data: ndarray::Array2 = - common::load_dense(&base.join("step0_raw_data.npz"), "X"); + fixtures::load_dense(&base.join("step0_raw_data.npz"), "X"); f64_data.mapv(|x| x as f32) }; @@ -139,6 +126,7 @@ fn process_disconnected_path(dataset: &str, n_embedding_dims: usize) -> Disconne 42, Some(raw_data.view()), ComputeMode::PythonCompat, + &SolverParams::default(), ) .unwrap_or_else(|e| panic!("{dataset}: embed_disconnected failed: {e}")); @@ -161,15 +149,20 @@ fn process_disconnected_path(dataset: &str, n_embedding_dims: usize) -> Disconne .collect(); let lap_c = build_normalized_laplacian(&sub_graph, &inv_sqrt_c); - let ((evals, evecs), _) = - solve_eigenproblem_pub(&lap_c, n_embedding_dims, 42, ComputeMode::PythonCompat); + let ((evals, evecs), _) = internals::solve_with_unit_hint( + &lap_c, + n_embedding_dims, + 42, + ComputeMode::PythonCompat, + &SolverParams::default(), + ); (0..evecs.ncols()) - .map(|d| common::residual_spmv(&lap_c, evecs.column(d), evals[d])) + .map(|d| internals::residual_spmv(&lap_c, evecs.column(d), evals[d])) .fold(0.0f64, f64::max) }) .collect(); - let separation_ratio = spectral_init::metrics::separation_ratio(embedding.view(), &labels); + let separation_ratio = diagnostics::separation_ratio(embedding.view(), &labels); let e2e_result = spectral_init( &graph, @@ -196,20 +189,20 @@ fn process_dataset( is_connected: bool, expected_n_components: usize, ) -> DatasetMetrics { - let base = common::fixture_path(dataset, ""); + let base = fixtures::fixture_path(dataset, ""); - let graph = common::load_sparse_csr_f32_u32(&base.join("step5a_pruned.npz")); - let laplacian = common::load_sparse_csr(&base.join("comp_b_laplacian.npz")); + let graph = fixtures::load_sparse_csr_f32_u32(&base.join("step5a_pruned.npz")); + let laplacian = fixtures::load_sparse_csr(&base.join("comp_b_laplacian.npz")); let ref_eigenvalues: Array1 = - common::load_dense(&base.join("comp_d_eigensolver.npz"), "eigenvalues"); + fixtures::load_dense(&base.join("comp_d_eigensolver.npz"), "eigenvalues"); let ref_eigenvectors: Array2 = - common::load_dense(&base.join("comp_d_eigensolver.npz"), "eigenvectors"); + fixtures::load_dense(&base.join("comp_d_eigensolver.npz"), "eigenvectors"); let ref_pre_noise: Array2 = - common::load_dense(&base.join("comp_f_scaling.npz"), "pre_noise"); + fixtures::load_dense(&base.join("comp_f_scaling.npz"), "pre_noise"); let expansion_arr: ndarray::Array0 = - common::load_dense(&base.join("comp_f_scaling.npz"), "expansion"); + fixtures::load_dense(&base.join("comp_f_scaling.npz"), "expansion"); let expansion_val = expansion_arr.into_scalar(); let k = ref_eigenvalues.len(); @@ -241,9 +234,14 @@ fn process_dataset( }; } - // NOTE: solve_eigenproblem_pub uses sqrt_deg = ones(n) internally. - let ((eigenvalues, eigenvectors), solver_level) = - solve_eigenproblem_pub(&laplacian, n_components_dim, 42, ComputeMode::PythonCompat); + // NOTE: solve_with_unit_hint uses sqrt_deg = ones(n). + let ((eigenvalues, eigenvectors), solve_report) = internals::solve_with_unit_hint( + &laplacian, + n_components_dim, + 42, + ComputeMode::PythonCompat, + &SolverParams::default(), + ); let eigenvalue_abs_errors: Vec = eigenvalues .iter() @@ -257,7 +255,7 @@ fn process_dataset( .collect(); let per_eigenvec_residuals: Vec = (0..eigenvectors.ncols()) - .map(|j| common::residual_spmv(&laplacian, eigenvectors.column(j), eigenvalues[j])) + .map(|j| internals::residual_spmv(&laplacian, eigenvectors.column(j), eigenvalues[j])) .collect(); let max_residual = per_eigenvec_residuals .iter() @@ -265,7 +263,7 @@ fn process_dataset( .fold(0.0f64, f64::max); let subspace_gram_det = if k >= 3 && ref_eigenvectors.ncols() >= 3 { - Some(spectral_init::metrics::subspace_gram_det( + Some(diagnostics::subspace_gram_det( eigenvectors.slice(s![.., 1..3]), ref_eigenvectors.slice(s![.., 1..3]), )) @@ -281,15 +279,14 @@ fn process_dataset( n_components_dim, ); let rust_pre_noise = compute_rust_pre_noise(&selected); - let pn_max_err = - spectral_init::metrics::sign_agnostic_max_error(&rust_pre_noise, &ref_pre_noise); + let pn_max_err = diagnostics::sign_agnostic_max_error(&rust_pre_noise, &ref_pre_noise); // Isolated scaling test: feed Python's comp_e embedding into Rust's scaler let ref_e_embedding: Array2 = - common::load_dense(&base.join("comp_e_selection.npz"), "embedding"); + fixtures::load_dense(&base.join("comp_e_selection.npz"), "embedding"); let rust_pre_noise_isolated = compute_rust_pre_noise(&ref_e_embedding); let pn_isolated_err = - spectral_init::metrics::sign_agnostic_max_error(&rust_pre_noise_isolated, &ref_pre_noise); + diagnostics::sign_agnostic_max_error(&rust_pre_noise_isolated, &ref_pre_noise); let e2e_max_residual = if is_connected { let result = spectral_init( @@ -303,7 +300,7 @@ fn process_dataset( let e2e_max = (0..n_components_dim) .map(|col| { let evec: Array1 = result.column(col).mapv(|v| v as f64 / expansion_val); - common::residual_spmv(&laplacian, evec.view(), ref_eigenvalues[col + 1]) + internals::residual_spmv(&laplacian, evec.view(), ref_eigenvalues[col + 1]) }) .fold(0.0f64, f64::max); Some(e2e_max) @@ -319,8 +316,8 @@ fn process_dataset( n, n_components: expected_n_components, is_connected, - solver_level: Some(solver_level), - solver_name: solver_name(solver_level), + solver_level: Some(solve_report.level as u8), + solver_name: solve_report.level.name(), eigenvalues_rust: eigenvalues.to_vec(), eigenvalues_ref: ref_eigenvalues.to_vec(), eigenvalue_abs_errors, @@ -342,10 +339,11 @@ fn build_tolerance_margin_table(all_metrics: &[DatasetMetrics]) -> Vec = common::load_dense(&base.join("comp_a_degrees.npz"), "degrees"); + let ref_deg: Array1 = + fixtures::load_dense(&base.join("comp_a_degrees.npz"), "degrees"); for (&got, &want) in degrees.iter().zip(ref_deg.iter()) { let rel_err = (got - want).abs() / want.abs().max(1.0); worst_deg_rel = worst_deg_rel.max(rel_err); @@ -367,16 +365,16 @@ fn build_tolerance_margin_table(all_metrics: &[DatasetMetrics]) -> Vec = - common::load_dense(&base.join("comp_a_degrees.npz"), "sqrt_deg"); + fixtures::load_dense(&base.join("comp_a_degrees.npz"), "sqrt_deg"); let inv_sqrt_deg: Vec = sqrt_deg .iter() .map(|&s| if s > 0.0 { 1.0 / s } else { 0.0 }) .collect(); let rust_lap = build_normalized_laplacian(&graph, &inv_sqrt_deg); - let ref_lap = common::load_sparse_csr(&base.join("comp_b_laplacian.npz")); + let ref_lap = fixtures::load_sparse_csr(&base.join("comp_b_laplacian.npz")); for (val, (row, col)) in ref_lap.iter() { let rust_val = rust_lap.get(row, col).copied().unwrap_or(0.0); worst_lap_iso = worst_lap_iso.max((rust_val - val).abs()); @@ -398,15 +396,15 @@ fn build_tolerance_margin_table(all_metrics: &[DatasetMetrics]) -> Vec = sqrt_deg .iter() .map(|&s| if s > 0.0 { 1.0 / s } else { 0.0 }) .collect(); let rust_lap = build_normalized_laplacian(&graph, &inv_sqrt_deg); - let ref_lap = common::load_sparse_csr(&base.join("comp_b_laplacian.npz")); + let ref_lap = fixtures::load_sparse_csr(&base.join("comp_b_laplacian.npz")); for (val, (row, col)) in ref_lap.iter() { let rust_val = rust_lap.get(row, col).copied().unwrap_or(0.0); worst_lap_chain = worst_lap_chain.max((rust_val - val).abs()); diff --git a/tests/integration/test_adversarial_graphs.rs b/tests/internals/adversarial_graphs.rs similarity index 96% rename from tests/integration/test_adversarial_graphs.rs rename to tests/internals/adversarial_graphs.rs index ba28e87..8ff3fc2 100644 --- a/tests/integration/test_adversarial_graphs.rs +++ b/tests/internals/adversarial_graphs.rs @@ -1,13 +1,11 @@ //! Adversarial synthetic graph test suite for the solver escalation chain. //! //! All tests are fully synthetic — no .npz fixture files required. -//! This test target requires `--features testing` (for solver-level tests). - -#[path = "../common/mod.rs"] -mod common; +use crate::{fixtures, internals}; use ndarray::{Array1, Array2, Axis, s}; -use spectral_init::{SpectralError, SpectralInitConfig, spectral_init}; +use spectral_init::__internal::{CsrOperator, SolverParams, lobpcg_solve, rsvd_solve}; +use spectral_init::{ComputeMode, SpectralError, SpectralInitConfig, spectral_init}; use sprs::CsMatI; // ─── Graph builder helpers ───────────────────────────────────────────────────── @@ -384,7 +382,7 @@ fn test_barbell_valid_embedding() { #[test] fn test_path_valid_embedding() { - let graph = common::make_path(100); // n = 100 + let graph = fixtures::make_path(100); // n = 100 let result = spectral_init(&graph, 2, 42, None, SpectralInitConfig::default()) .expect("path should not fail"); assert_eq!(result.shape(), &[100, 2]); @@ -432,7 +430,7 @@ fn test_complete_bipartite_valid_embedding() { #[test] fn test_ring_valid_embedding() { - let graph = common::make_ring(100); // n = 100 + let graph = fixtures::make_ring(100); // n = 100 let result = spectral_init(&graph, 2, 42, None, SpectralInitConfig::default()) .expect("ring should not fail"); assert_eq!(result.shape(), &[100, 2]); @@ -558,29 +556,33 @@ fn test_complete_bipartite_coordinate_stability() { ); } -// ─── Group 4: Solver level tests (require --features testing) ───────────────── +// ─── Group 4: Solver level tests ────────────────────────────────────────────── #[test] fn test_level_0_dense_evd_for_small_n() { let laplacian = path_laplacian_6(); // n=6 < 2000 → Level 0 - let (_, level) = spectral_init::solve_eigenproblem_pub( + let (_, report) = internals::solve_with_unit_hint( &laplacian, 2, 42, - spectral_init::ComputeMode::PythonCompat, + ComputeMode::PythonCompat, + &SolverParams::default(), ); + let level = report.level as u8; assert_eq!(level, 0, "n=6 must use Level 0 dense EVD"); } #[test] fn test_level_1_lobpcg_for_large_well_conditioned_n() { let laplacian = large_diagonal_laplacian(2001); // n=2001 >= 2000, eigengap ≈ 0.5 - let (_, level) = spectral_init::solve_eigenproblem_pub( + let (_, report) = internals::solve_with_unit_hint( &laplacian, 2, 42, - spectral_init::ComputeMode::PythonCompat, + ComputeMode::PythonCompat, + &SolverParams::default(), ); + let level = report.level as u8; assert_eq!( level, 1, "n=2001 well-conditioned diagonal must use Level 1 LOBPCG" @@ -590,16 +592,16 @@ fn test_level_1_lobpcg_for_large_well_conditioned_n() { #[test] fn test_level_2_regularized_lobpcg_produces_valid_result() { let laplacian = large_diagonal_laplacian(2001); - let op = spectral_init::operator::CsrOperator(&laplacian); + let op = CsrOperator(&laplacian); let sqrt_deg = Array1::ones(2001); - let r1 = spectral_init::solvers::lobpcg::lobpcg_solve(&op, 2, 42, false, &sqrt_deg); + let r1 = lobpcg_solve(&op, 2, 42, false, &sqrt_deg); assert!( r1.is_some(), "Level 1 (unregularized) must converge on diagonal n=2001" ); - let r2 = spectral_init::solvers::lobpcg::lobpcg_solve(&op, 2, 42, true, &sqrt_deg); + let r2 = lobpcg_solve(&op, 2, 42, true, &sqrt_deg); assert!( r2.is_some(), "Level 2 (regularized) must converge on diagonal n=2001" @@ -624,7 +626,7 @@ fn test_level_3_rsvd_valid_on_large_path() { // of the rSVD solver is therefore the appropriate approach here. let laplacian = large_path_laplacian(2001); let (eigs, vecs): (ndarray::Array1, ndarray::Array2) = - spectral_init::rsvd_solve(&laplacian, 2, 42); + rsvd_solve(&laplacian, 2, 42, &SolverParams::default()); assert_eq!( eigs.len(), 3, diff --git a/tests/integration/test_comp_a_degrees.rs b/tests/internals/comp_a_degrees.rs similarity index 89% rename from tests/integration/test_comp_a_degrees.rs rename to tests/internals/comp_a_degrees.rs index beeb46f..ed3a507 100644 --- a/tests/integration/test_comp_a_degrees.rs +++ b/tests/internals/comp_a_degrees.rs @@ -1,21 +1,20 @@ -#[path = "../common/mod.rs"] -mod common; - -use spectral_init::{ComputeMode, compute_degrees}; +use crate::fixtures; +use spectral_init::__internal::compute_degrees; +use spectral_init::ComputeMode; fn run_comp_a_test(dataset: &str, expected_n: usize, mode: ComputeMode, tol: f64) { - let base = common::fixture_path(dataset, ""); + let base = fixtures::fixture_path(dataset, ""); // Load the pruned graph (input to compute_degrees) - let graph = common::load_sparse_csr_f32_u32(&base.join("step5a_pruned.npz")); + let graph = fixtures::load_sparse_csr_f32_u32(&base.join("step5a_pruned.npz")); // Call the function under test let (degrees, sqrt_deg) = compute_degrees(&graph, mode); // Load Python reference let ref_path = base.join("comp_a_degrees.npz"); - let expected_deg: ndarray::Array1 = common::load_dense(&ref_path, "degrees"); - let expected_sqrt: ndarray::Array1 = common::load_dense(&ref_path, "sqrt_deg"); + let expected_deg: ndarray::Array1 = fixtures::load_dense(&ref_path, "degrees"); + let expected_sqrt: ndarray::Array1 = fixtures::load_dense(&ref_path, "sqrt_deg"); assert_eq!(degrees.len(), expected_n, "degrees length"); assert_eq!(sqrt_deg.len(), expected_n, "sqrt_deg length"); diff --git a/tests/integration/test_comp_b_laplacian.rs b/tests/internals/comp_b_laplacian.rs similarity index 86% rename from tests/integration/test_comp_b_laplacian.rs rename to tests/internals/comp_b_laplacian.rs index 6f9b328..db8a7d0 100644 --- a/tests/integration/test_comp_b_laplacian.rs +++ b/tests/internals/comp_b_laplacian.rs @@ -1,17 +1,15 @@ -#[path = "../common/mod.rs"] -mod common; - -use spectral_init::build_normalized_laplacian; +use crate::fixtures; +use spectral_init::__internal::build_normalized_laplacian; fn run_comp_b_test(dataset: &str, expected_n: usize) { - let base = common::fixture_path(dataset, ""); + let base = fixtures::fixture_path(dataset, ""); // Load inputs - let graph = common::load_sparse_csr_f32_u32(&base.join("step5a_pruned.npz")); + let graph = fixtures::load_sparse_csr_f32_u32(&base.join("step5a_pruned.npz")); // Load comp_a output for sqrt_deg (already validated by comp_a tests) let sqrt_deg: ndarray::Array1 = - common::load_dense(&base.join("comp_a_degrees.npz"), "sqrt_deg"); + fixtures::load_dense(&base.join("comp_a_degrees.npz"), "sqrt_deg"); let inv_sqrt_deg: Vec = sqrt_deg .iter() .map(|&s| if s > 0.0 { 1.0 / s } else { 0.0 }) @@ -24,7 +22,7 @@ fn run_comp_b_test(dataset: &str, expected_n: usize) { assert_eq!(l.cols(), expected_n, "Laplacian cols"); // Load Python reference - let ref_l = common::load_sparse_csr(&base.join("comp_b_laplacian.npz")); + let ref_l = fixtures::load_sparse_csr(&base.join("comp_b_laplacian.npz")); // Element-wise comparison of all nonzero entries in the reference for (&val, (row, col)) in ref_l.iter() { diff --git a/tests/integration/test_comp_c_components.rs b/tests/internals/comp_c_components.rs similarity index 92% rename from tests/integration/test_comp_c_components.rs rename to tests/internals/comp_c_components.rs index 695ef0c..8657132 100644 --- a/tests/integration/test_comp_c_components.rs +++ b/tests/internals/comp_c_components.rs @@ -1,16 +1,14 @@ -#[path = "../common/mod.rs"] -mod common; - +use crate::fixtures; use ndarray_npy::NpzReader; -use spectral_init::find_components; +use spectral_init::__internal::find_components; /// Load comp_c_components.npz and compare Rust output against Python reference. /// `expected_n_components` is the known ground-truth count for the dataset. fn run_comp_c_test(dataset: &str, expected_n_components: usize) { - let base = common::fixture_path(dataset, ""); + let base = fixtures::fixture_path(dataset, ""); // Run the function under test - let graph = common::load_sparse_csr_f32_u32(&base.join("step5a_pruned.npz")); + let graph = fixtures::load_sparse_csr_f32_u32(&base.join("step5a_pruned.npz")); let (labels, n_components) = find_components(&graph); // Load Python reference @@ -38,8 +36,8 @@ fn run_comp_c_test(dataset: &str, expected_n_components: usize) { "dataset {dataset}: expected {expected_n_components} components, got {n_components}" ); assert_eq!( - common::partition_of(&labels), - common::partition_of(&py_labels), + fixtures::partition_of(&labels), + fixtures::partition_of(&py_labels), "dataset {dataset}: label partitioning does not match Python" ); } diff --git a/tests/integration/test_comp_d_dense_evd.rs b/tests/internals/comp_d_dense_evd.rs similarity index 79% rename from tests/integration/test_comp_d_dense_evd.rs rename to tests/internals/comp_d_dense_evd.rs index 9d1f3c8..08c54d5 100644 --- a/tests/integration/test_comp_d_dense_evd.rs +++ b/tests/internals/comp_d_dense_evd.rs @@ -1,23 +1,21 @@ -#[path = "../common/mod.rs"] -mod common; - +use crate::{fixtures, internals}; use ndarray::Array1; -use spectral_init::dense_evd; +use spectral_init::__internal::dense_evd; fn run_comp_d_test(dataset: &str, expected_n: usize) { - let base = common::fixture_path(dataset, ""); + let base = fixtures::fixture_path(dataset, ""); // Load Laplacian from comp_b output - let laplacian = common::load_sparse_csr(&base.join("comp_b_laplacian.npz")); + let laplacian = fixtures::load_sparse_csr(&base.join("comp_b_laplacian.npz")); assert_eq!(laplacian.rows(), expected_n); // Load eigensolver reference fixture let ref_eigenvalues: Array1 = - common::load_dense(&base.join("comp_d_eigensolver.npz"), "eigenvalues"); + fixtures::load_dense(&base.join("comp_d_eigensolver.npz"), "eigenvalues"); let ref_eigenvectors: ndarray::Array2 = - common::load_dense(&base.join("comp_d_eigensolver.npz"), "eigenvectors"); + fixtures::load_dense(&base.join("comp_d_eigensolver.npz"), "eigenvectors"); let eigenvalue_gaps: Array1 = - common::load_dense(&base.join("comp_d_eigensolver.npz"), "eigenvalue_gaps"); + fixtures::load_dense(&base.join("comp_d_eigensolver.npz"), "eigenvalue_gaps"); // k is a 0-D scalar in the fixture; derive it from the eigenvalues array length. let k = ref_eigenvalues.len(); @@ -38,7 +36,7 @@ fn run_comp_d_test(dataset: &str, expected_n: usize) { // Eigenvector residual check (sign-independent) for j in 0..k { - let r = common::residual_spmv(&laplacian, eigenvectors.column(j), eigenvalues[j]); + let r = internals::residual_spmv(&laplacian, eigenvectors.column(j), eigenvalues[j]); assert!(r < 1e-10, "eigenvector residual[{j}] = {r} >= 1e-10"); } diff --git a/tests/integration/test_comp_d_rsvd.rs b/tests/internals/comp_d_rsvd.rs similarity index 86% rename from tests/integration/test_comp_d_rsvd.rs rename to tests/internals/comp_d_rsvd.rs index 24f5239..2751ef2 100644 --- a/tests/integration/test_comp_d_rsvd.rs +++ b/tests/internals/comp_d_rsvd.rs @@ -1,8 +1,5 @@ //! Integration tests for the randomized SVD solver (Component D). -#[path = "../common/mod.rs"] -mod common; - /// Compute residual ||L·v - λ·v|| / ||v|| for a single eigenpair. fn residual(laplacian: &sprs::CsMat, eigvec: ndarray::ArrayView1, eigval: f64) -> f64 { let lv = laplacian * &eigvec.to_owned(); // SpMV via sprs @@ -14,12 +11,10 @@ macro_rules! rsvd_test { ($name:ident, $dataset:expr) => { #[test] fn $name() { - let fixture_base = std::path::Path::new(env!("CARGO_MANIFEST_DIR")) - .join("tests/fixtures") - .join($dataset); + let fixture_base = crate::fixtures::fixtures_dir().join($dataset); // Load Laplacian - let laplacian = common::load_sparse_csr(&fixture_base.join("comp_b_laplacian.npz")); + let laplacian = crate::fixtures::load_sparse_csr(&fixture_base.join("comp_b_laplacian.npz")); // Load reference eigenpairs from comp_d let mut d = ndarray_npy::NpzReader::new( @@ -34,8 +29,12 @@ macro_rules! rsvd_test { let n_components = (k as usize) - 1; // Run rSVD solver - let (eigenvalues, eigenvectors) = - spectral_init::rsvd_solve(&laplacian, n_components, 42); + let (eigenvalues, eigenvectors) = spectral_init::__internal::rsvd_solve( + &laplacian, + n_components, + 42, + &spectral_init::__internal::SolverParams::default(), + ); // Check eigenvalue accuracy. The production rsvd_solve uses nbiter=2 // and n/10 oversampling, trading precision for speed. On graphs with tiny diff --git a/tests/integration/test_comp_e_selection.rs b/tests/internals/comp_e_selection.rs similarity index 85% rename from tests/integration/test_comp_e_selection.rs rename to tests/internals/comp_e_selection.rs index 3adcb78..632f4bb 100644 --- a/tests/integration/test_comp_e_selection.rs +++ b/tests/internals/comp_e_selection.rs @@ -1,20 +1,18 @@ -#[path = "../common/mod.rs"] -mod common; - -use spectral_init::select_eigenvectors; +use crate::fixtures; +use spectral_init::__internal::select_eigenvectors; fn run_comp_e_test(dataset: &str, expected_n: usize) { - let base = common::fixture_path(dataset, ""); + let base = fixtures::fixture_path(dataset, ""); let eigenvalues: ndarray::Array1 = - common::load_dense(&base.join("comp_d_eigensolver.npz"), "eigenvalues"); + fixtures::load_dense(&base.join("comp_d_eigensolver.npz"), "eigenvalues"); let eigenvectors: ndarray::Array2 = - common::load_dense(&base.join("comp_d_eigensolver.npz"), "eigenvectors"); + fixtures::load_dense(&base.join("comp_d_eigensolver.npz"), "eigenvectors"); let expected_order: ndarray::Array1 = - common::load_dense(&base.join("comp_e_selection.npz"), "order"); + fixtures::load_dense(&base.join("comp_e_selection.npz"), "order"); let expected_embedding: ndarray::Array2 = - common::load_dense(&base.join("comp_e_selection.npz"), "embedding"); + fixtures::load_dense(&base.join("comp_e_selection.npz"), "embedding"); assert_eq!(eigenvectors.shape()[0], expected_n); diff --git a/tests/integration/test_comp_f_lobpcg.rs b/tests/internals/comp_f_lobpcg.rs similarity index 78% rename from tests/integration/test_comp_f_lobpcg.rs rename to tests/internals/comp_f_lobpcg.rs index 48d1780..4ac5409 100644 --- a/tests/integration/test_comp_f_lobpcg.rs +++ b/tests/internals/comp_f_lobpcg.rs @@ -1,18 +1,15 @@ -#[path = "../common/mod.rs"] -mod common; - -use spectral_init::operator::CsrOperator; -use spectral_init::solvers::lobpcg::lobpcg_solve; +use crate::{fixtures, internals}; +use spectral_init::__internal::{CsrOperator, lobpcg_solve}; fn run_lobpcg_test(dataset: &str, _expected_n: usize, regularized: bool) { - let fixture_dir = common::fixture_path(dataset, ""); + let fixture_dir = fixtures::fixture_path(dataset, ""); let lap_path = fixture_dir.join("comp_b_laplacian.npz"); - let laplacian = common::load_sparse_csr(&lap_path); + let laplacian = fixtures::load_sparse_csr(&lap_path); let op = CsrOperator(&laplacian); let deg_path = fixture_dir.join("comp_a_degrees.npz"); - let sqrt_deg: ndarray::Array1 = common::load_dense(°_path, "sqrt_deg"); + let sqrt_deg: ndarray::Array1 = fixtures::load_dense(°_path, "sqrt_deg"); assert_eq!( sqrt_deg.len(), laplacian.rows(), @@ -28,7 +25,7 @@ fn run_lobpcg_test(dataset: &str, _expected_n: usize, regularized: bool) { if !regularized { let ref_path = fixture_dir.join("comp_d_eigensolver.npz"); - let ref_eigvals: ndarray::Array1 = common::load_dense(&ref_path, "eigenvalues"); + let ref_eigvals: ndarray::Array1 = fixtures::load_dense(&ref_path, "eigenvalues"); let k = eigvals.len().min(ref_eigvals.len()); for i in 0..k { @@ -41,7 +38,7 @@ fn run_lobpcg_test(dataset: &str, _expected_n: usize, regularized: bool) { } for i in 0..eigvals.len() { - let residual = common::eigenpair_residual(&op, eigvecs.column(i), eigvals[i]); + let residual = internals::eigenpair_residual(&op, eigvecs.column(i), eigvals[i]); assert!( residual < 1e-5, "dataset={dataset}, residual for eigenpair {i}: {residual} >= 1e-5" @@ -50,7 +47,7 @@ fn run_lobpcg_test(dataset: &str, _expected_n: usize, regularized: bool) { } else { // Level 2: residuals against the unshifted Laplacian must be < 1e-5. for i in 0..eigvals.len() { - let residual = common::eigenpair_residual(&op, eigvecs.column(i), eigvals[i]); + let residual = internals::eigenpair_residual(&op, eigvecs.column(i), eigvals[i]); assert!( residual < 1e-5, "dataset={dataset}, level2 residual for eigenpair {i}: {residual} >= 1e-5" @@ -106,14 +103,14 @@ make_lobpcg_tests!( #[test] fn lobpcg_blobs_2000_residual_below_1e5_with_chebyshev() { let dataset = "blobs_connected_2000"; - let fixture_dir = common::fixture_path(dataset, ""); + let fixture_dir = fixtures::fixture_path(dataset, ""); let lap_path = fixture_dir.join("comp_b_laplacian.npz"); - let laplacian = common::load_sparse_csr(&lap_path); + let laplacian = fixtures::load_sparse_csr(&lap_path); let op = CsrOperator(&laplacian); let deg_path = fixture_dir.join("comp_a_degrees.npz"); - let sqrt_deg: ndarray::Array1 = common::load_dense(°_path, "sqrt_deg"); + let sqrt_deg: ndarray::Array1 = fixtures::load_dense(°_path, "sqrt_deg"); let result = lobpcg_solve(&op, 2, 42, false, &sqrt_deg); assert!(result.is_some(), "lobpcg_solve returned None on {dataset}"); @@ -121,7 +118,7 @@ fn lobpcg_blobs_2000_residual_below_1e5_with_chebyshev() { // All k=3 eigenpairs must have residual < 1e-5 (REQ-PERF-001). for i in 0..eigvals.len() { - let residual = common::eigenpair_residual(&op, eigvecs.column(i), eigvals[i]); + let residual = internals::eigenpair_residual(&op, eigvecs.column(i), eigvals[i]); assert!( residual < 1e-5, "dataset={dataset}, residual for eigenpair {i}: {residual} >= 1e-5 (Chebyshev preconditioning should achieve < 1e-5)" diff --git a/tests/integration/test_comp_g_sinv.rs b/tests/internals/comp_g_sinv.rs similarity index 89% rename from tests/integration/test_comp_g_sinv.rs rename to tests/internals/comp_g_sinv.rs index 056e438..34415ff 100644 --- a/tests/integration/test_comp_g_sinv.rs +++ b/tests/internals/comp_g_sinv.rs @@ -1,15 +1,13 @@ -#[path = "../common/mod.rs"] -mod common; - +use crate::{fixtures, internals}; use ndarray::Array1; use ndarray_npy::NpzReader; -use spectral_init::lobpcg_sinv_solve; +use spectral_init::__internal::lobpcg_sinv_solve; const N_COMPONENTS: usize = 2; /// Return the number of connected components stored in comp_c_components.npz. fn load_n_conn_components(dataset: &str) -> usize { - let path = common::fixture_path(dataset, "comp_c_components.npz"); + let path = fixtures::fixture_path(dataset, "comp_c_components.npz"); let file = std::fs::File::open(&path) .unwrap_or_else(|e| panic!("dataset {dataset}: cannot open {path:?}: {e}")); let mut npz = @@ -28,12 +26,12 @@ fn max_residual( eigvals .iter() .enumerate() - .map(|(i, &lambda)| common::residual_spmv(laplacian, eigvecs.column(i), lambda)) + .map(|(i, &lambda)| internals::residual_spmv(laplacian, eigvecs.column(i), lambda)) .fold(0.0_f64, f64::max) } fn run_sinv_test(dataset: &str) { - let fixture_dir = common::fixture_path(dataset, ""); + let fixture_dir = fixtures::fixture_path(dataset, ""); // Skip disconnected datasets. let n_conn = load_n_conn_components(dataset); @@ -45,7 +43,7 @@ fn run_sinv_test(dataset: &str) { } let lap_path = fixture_dir.join("comp_b_laplacian.npz"); - let laplacian = common::load_sparse_csr(&lap_path); + let laplacian = fixtures::load_sparse_csr(&lap_path); let n = laplacian.rows(); // Skip if graph is too small for sinv (k >= n would trigger the None guard). @@ -59,7 +57,7 @@ fn run_sinv_test(dataset: &str) { // Load sqrt_deg for trivial eigenvector injection. let deg_path = fixture_dir.join("comp_a_degrees.npz"); - let sqrt_deg: Array1 = common::load_dense(°_path, "sqrt_deg"); + let sqrt_deg: Array1 = fixtures::load_dense(°_path, "sqrt_deg"); assert_eq!( sqrt_deg.len(), n, @@ -69,7 +67,7 @@ fn run_sinv_test(dataset: &str) { // Load reference eigenvalues from dense EVD. let ref_path = fixture_dir.join("comp_d_eigensolver.npz"); - let ref_eigvals: Array1 = common::load_dense(&ref_path, "eigenvalues"); + let ref_eigvals: Array1 = fixtures::load_dense(&ref_path, "eigenvalues"); // Call shift-and-invert LOBPCG. let result = lobpcg_sinv_solve(&laplacian, N_COMPONENTS, 42, &sqrt_deg); diff --git a/tests/internals/diagnostic_metrics.rs b/tests/internals/diagnostic_metrics.rs new file mode 100644 index 0000000..17aa756 --- /dev/null +++ b/tests/internals/diagnostic_metrics.rs @@ -0,0 +1,238 @@ +use crate::diagnostics::*; +use ndarray::{Array1, Array2}; + +#[test] +fn t_const_01_diagnostic_thresholds_have_required_values() { + assert_eq!(DEGENERATE_GAP_THRESHOLD, 1e-6_f64); + assert_eq!(SUBSPACE_GRAM_DET_THRESHOLD, 0.95_f64); +} + +// ── Accuracy: orthogonality_error ──────────────────────────────────────── + +#[test] +fn t_ortho_01_identity_columns_zero_error() { + let v = Array2::::eye(3); + let err = orthogonality_error(&v); + assert!( + err < 1e-14, + "identity orthogonality_error={err:.2e}, expected ≈ 0" + ); +} + +#[test] +fn t_ortho_02_non_orthogonal_positive_error() { + let v = Array2::from_shape_vec( + (3, 2), + vec![1.0_f64, 1.0_f64, 0.0_f64, 1.0_f64, 0.0_f64, 0.0_f64], + ) + .unwrap(); + let err = orthogonality_error(&v); + assert!( + err > 0.0, + "non-orthogonal matrix should have positive error, got {err:.2e}" + ); +} + +// ── Accuracy: check_eigenvalue_bounds ──────────────────────────────────── + +#[test] +fn t_bounds_01_valid_range_and_sorted() { + let eigs = Array1::from_vec(vec![0.0_f64, 0.5, 1.0]); + assert_eq!(check_eigenvalue_bounds(&eigs, 1e-8), (true, true)); +} + +#[test] +fn t_bounds_02_negative_eigenvalue_out_of_range() { + let eigs = Array1::from_vec(vec![-0.1_f64, 0.5]); + assert_eq!(check_eigenvalue_bounds(&eigs, 1e-8), (false, true)); +} + +#[test] +fn t_bounds_03_unsorted_eigenvalues() { + let eigs = Array1::from_vec(vec![0.5_f64, 0.1]); + assert_eq!(check_eigenvalue_bounds(&eigs, 1e-8), (true, false)); +} + +// ── Accuracy: separation_ratio ─────────────────────────────────────────── + +#[test] +fn t_sep_01_well_separated_clusters() { + // 4 points: cluster 0 near [0,0], cluster 1 near [10,0] + let data = vec![0.0_f64, 0.0, 0.1, 0.0, 10.0, 0.0, 10.1, 0.0]; + let embedding = Array2::from_shape_vec((4, 2), data).unwrap(); + let labels = vec![0usize, 0, 1, 1]; + let ratio = separation_ratio(embedding.view(), &labels); + assert!( + ratio > 1.0, + "well-separated clusters should have ratio > 1.0, got {ratio:.4}" + ); +} + +#[test] +fn t_sep_02_overlapping_clusters() { + // 4 points where intra-cluster spread > inter-centroid distance + let data = vec![0.0_f64, 0.0, 3.0, 0.0, 1.0, 0.0, 4.0, 0.0]; + let embedding = Array2::from_shape_vec((4, 2), data).unwrap(); + let labels = vec![0usize, 0, 1, 1]; + let ratio = separation_ratio(embedding.view(), &labels); + // Centroids [1.5,0] and [2.5,0]: inter=1.0, max_intra=1.5. ratio=0.667 + assert!( + ratio <= 1.0, + "overlapping clusters should have ratio <= 1.0, got {ratio:.4}" + ); +} + +// ── Parity: eigenvalue_abs_errors ──────────────────────────────────────── + +#[test] +fn t_abserr_01_basic_errors() { + let computed = Array1::from_vec(vec![1.0_f64, 2.0]); + let reference = Array1::from_vec(vec![1.1_f64, 2.2]); + let errors = eigenvalue_abs_errors(&computed, &reference); + assert!( + (errors[0] - 0.1).abs() < 1e-14, + "errors[0]={:.6e}, expected 0.1", + errors[0] + ); + assert!( + (errors[1] - 0.2).abs() < 1e-14, + "errors[1]={:.6e}, expected 0.2", + errors[1] + ); +} + +// ── Parity: subspace_gram_det ──────────────────────────────────────────── + +#[test] +fn t_gram2d_01_parallel_subspace_near_one() { + // u = r = [[1,0],[0,1],[0,0]] (orthonormal columns) + let data = vec![1.0_f64, 0.0, 0.0, 1.0, 0.0, 0.0]; + let u = Array2::from_shape_vec((3, 2), data.clone()).unwrap(); + let r = Array2::from_shape_vec((3, 2), data).unwrap(); + let det = subspace_gram_det(u.view(), r.view()); + assert!( + (det - 1.0).abs() < 1e-12, + "parallel orthonormal subspace: det={det:.6e}, expected ≈ 1.0" + ); +} + +#[test] +fn t_gram2d_02_orthogonal_subspace_near_zero() { + // u spans {e1, e2}, r spans {e3, e4} + let u_data = vec![1.0_f64, 0.0, 0.0, 1.0, 0.0, 0.0, 0.0, 0.0]; + let r_data = vec![0.0_f64, 0.0, 0.0, 0.0, 1.0, 0.0, 0.0, 1.0]; + let u = Array2::from_shape_vec((4, 2), u_data).unwrap(); + let r = Array2::from_shape_vec((4, 2), r_data).unwrap(); + let det = subspace_gram_det(u.view(), r.view()); + assert!( + det < 1e-12, + "orthogonal subspaces: det={det:.6e}, expected ≈ 0.0" + ); +} + +// ── Parity: subspace_gram_det_kd ───────────────────────────────────────── + +#[test] +fn t_gramkd_01_same_subspace_near_one() { + // k=3 identity columns in R^3 + let eye = Array2::::eye(3); + let det = subspace_gram_det_kd(eye.view(), eye.view()); + assert!( + (det - 1.0).abs() < 1e-10, + "same subspace: det={det:.6e}, expected ≈ 1.0" + ); +} + +#[test] +fn t_gramkd_02_orthogonal_subspaces_near_zero() { + // computed spans {e1,e2}, reference spans {e3,e4} in R^4 + let comp_data = vec![1.0_f64, 0.0, 0.0, 0.0, 0.0, 1.0, 0.0, 0.0]; + let ref_data = vec![0.0_f64, 0.0, 1.0, 0.0, 0.0, 0.0, 0.0, 1.0]; + let comp = Array2::from_shape_vec((4, 2), comp_data).unwrap(); + let reff = Array2::from_shape_vec((4, 2), ref_data).unwrap(); + let det = subspace_gram_det_kd(comp.view(), reff.view()); + assert!( + det < 1e-10, + "orthogonal subspaces: det={det:.6e}, expected ≈ 0.0" + ); +} + +// ── Parity: sign_agnostic_max_error ────────────────────────────────────── + +#[test] +fn t_signerr_01_identical_arrays_zero_error() { + let data = vec![1.0_f32, 2.0, 3.0, 4.0]; + let arr = Array2::from_shape_vec((4, 1), data).unwrap(); + let err = sign_agnostic_max_error(&arr, &arr); + assert_eq!(err, 0.0, "identical arrays: error={err:.2e}, expected 0.0"); +} + +#[test] +fn t_signerr_02_negated_columns_zero_error() { + let computed_data = vec![1.0_f32, -2.0, 3.0, -4.0]; + let reference_data = vec![-1.0_f32, 2.0, -3.0, 4.0]; + let computed = Array2::from_shape_vec((4, 1), computed_data).unwrap(); + let reference = Array2::from_shape_vec((4, 1), reference_data).unwrap(); + let err = sign_agnostic_max_error(&computed, &reference); + assert_eq!( + err, 0.0, + "fully negated column: error={err:.2e}, expected 0.0" + ); +} + +#[test] +fn t_signerr_03_small_perturbation_small_error() { + let reference_data = vec![1.0_f32, 2.0, 3.0, 4.0]; + let computed_data = vec![1.01_f32, 2.01, 3.01, 4.01]; + let reference = Array2::from_shape_vec((4, 1), reference_data).unwrap(); + let computed = Array2::from_shape_vec((4, 1), computed_data).unwrap(); + let err = sign_agnostic_max_error(&computed, &reference); + assert!( + err > 0.0 && err < 0.1, + "small perturbation: error={err:.4e}, expected small positive" + ); +} + +// ── Diagnostic: tolerance_margin ───────────────────────────────────────── + +#[test] +fn t_tolmargin_01_basic() { + let margin = tolerance_margin(1e-5, 5e-6); + assert!( + (margin - 2.0).abs() < 1e-12, + "tolerance_margin={margin:.6e}, expected 2.0" + ); +} + +#[test] +fn t_tolmargin_02_zero_worst_value_returns_infinity() { + let margin = tolerance_margin(1e-5, 0.0); + assert!( + margin.is_infinite() && margin > 0.0, + "tolerance_margin with worst_value=0.0 should be +∞, got {margin:.6e}" + ); +} + +// ── Diagnostic: spectral_gap ────────────────────────────────────────────── + +#[test] +fn t_specgap_01_basic() { + let eigs = Array1::from_vec(vec![0.0_f64, 0.5, 1.0]); + let gap = spectral_gap(&eigs); + assert!( + (gap - 0.5).abs() < 1e-14, + "spectral_gap={gap:.6e}, expected 0.5" + ); +} + +// ── Diagnostic: eigenvalue_condition_number ─────────────────────────────── + +#[test] +fn t_condnum_01_basic() { + let eigs = Array1::from_vec(vec![0.0_f64, 0.5, 1.0]); + let cn = eigenvalue_condition_number(&eigs); + assert!( + (cn - 2.0).abs() < 1e-14, + "eigenvalue_condition_number={cn:.6e}, expected 2.0" + ); +} diff --git a/tests/internals/e2e_residual.rs b/tests/internals/e2e_residual.rs new file mode 100644 index 0000000..2c9c424 --- /dev/null +++ b/tests/internals/e2e_residual.rs @@ -0,0 +1,88 @@ +//! End-to-end residual quality: the coordinates `spectral_init` returns, de-scaled, must +//! still be eigenvectors of the reference Laplacian. + +use crate::{fixtures, internals}; +use spectral_init::{SpectralInitConfig, spectral_init}; + +/// Load graph, run spectral_init, check residuals for a connected dataset. +fn run_e2e_residual_check(dataset: &str, n: usize) { + let graph_path = fixtures::fixture_path(dataset, "step5a_pruned.npz"); + let graph = fixtures::load_sparse_csr_f32_u32(&graph_path); + + let result = spectral_init(&graph, 2, 42, None, SpectralInitConfig::default()) + .unwrap_or_else(|e| panic!("spectral_init failed for {dataset}: {e}")); + assert_eq!(result.shape(), &[n, 2]); + for &v in result.iter() { + assert!(v.is_finite(), "non-finite in {dataset}: {v}"); + } + + // Load expansion factor (stored as 0-D scalar in the fixture) + let scaling_path = fixtures::fixture_path(dataset, "comp_f_scaling.npz"); + let expansion: ndarray::Array0 = fixtures::load_dense(&scaling_path, "expansion"); + let expansion_val = expansion.into_scalar(); + assert!( + expansion_val.is_normal() && expansion_val > 0.0, + "fixture expansion value must be positive and normal, got {expansion_val}" + ); + + // Load Laplacian and reference eigenvalues + let laplacian = + fixtures::load_sparse_csr(&fixtures::fixture_path(dataset, "comp_b_laplacian.npz")); + let ref_eigenvalues: ndarray::Array1 = fixtures::load_dense( + &fixtures::fixture_path(dataset, "comp_d_eigensolver.npz"), + "eigenvalues", + ); + + // De-scale to recover approximate eigenvectors + let descaled = result.mapv(|v| v as f64 / expansion_val); + + // Check residual for each of the 2 selected eigenvectors. + // Output column 0 → eigenvalue[1], column 1 → eigenvalue[2] (skip trivial index 0). + for col in 0..2usize { + let evec = descaled.column(col); + let eigval = ref_eigenvalues[col + 1]; + let r = internals::residual_spmv(&laplacian, evec, eigval); + // Tolerance is 0.005: this bound must hold across the full solver escalation + // chain (dense EVD → LOBPCG → randomized SVD). Dense EVD residuals are ~1e-8 + // pre-noise; LOBPCG and rSVD paths yield somewhat larger residuals but remain + // well below this threshold. Gaussian noise (sigma=0.0001) adds at most ~1e-4 + // after de-scaling by expansion (~10); f32→f64 de-scaling contributes ~1e-7. + // 0.005 is 50× above the expected noise floor, catching genuine solver + // failures while rejecting the misleadingly loose 0.05 bound. + let residual_tol = 0.005_f64; + assert!( + r < residual_tol, + "residual quality check failed for {dataset} column {col}: residual={r:.6e} >= {residual_tol}" + ); + } +} + +// ── residual quality tests (7 connected datasets) ──────────────────────────── +// blobs_500 and blobs_5000 are excluded: fixture generation confirms they are +// disconnected (4 and 2 components respectively). Their embeddings are produced +// by embed_disconnected() and are not Laplacian eigenvectors of the full graph. + +#[test] +fn test_e2e_residual_quality_blobs_connected_200() { + run_e2e_residual_check("blobs_connected_200", 200); +} + +#[test] +fn test_e2e_residual_quality_blobs_connected_2000() { + run_e2e_residual_check("blobs_connected_2000", 2000); +} + +#[test] +fn test_e2e_residual_quality_moons_200() { + run_e2e_residual_check("moons_200", 200); +} + +#[test] +fn test_e2e_residual_quality_circles_300() { + run_e2e_residual_check("circles_300", 300); +} + +#[test] +fn test_e2e_residual_quality_near_dupes_100() { + run_e2e_residual_check("near_dupes_100", 100); +} diff --git a/tests/internals/main.rs b/tests/internals/main.rs new file mode 100644 index 0000000..11acc62 --- /dev/null +++ b/tests/internals/main.rs @@ -0,0 +1,30 @@ +//! Integration tests of the crate's internals, reached through the `__internal` feature. + +#![cfg(feature = "__internal")] + +#[path = "../common/diagnostics.rs"] +mod diagnostics; +#[path = "../common/fixtures.rs"] +mod fixtures; +#[path = "../common/internals.rs"] +mod internals; + +mod accuracy_report; +mod adversarial_graphs; +mod comp_a_degrees; +mod comp_b_laplacian; +mod comp_c_components; +mod comp_d_dense_evd; +mod comp_d_rsvd; +mod comp_e_selection; +mod comp_f_lobpcg; +mod comp_g_sinv; +mod diagnostic_metrics; +mod e2e_residual; +mod operator_fixtures; +mod property_tests; +mod psd_contract; +mod scaling_fixtures; +mod simd; +mod solver_invariants; +mod warm_restart; diff --git a/tests/integration/test_operator_fixtures.rs b/tests/internals/operator_fixtures.rs similarity index 68% rename from tests/integration/test_operator_fixtures.rs rename to tests/internals/operator_fixtures.rs index eed4fec..a6d1d01 100644 --- a/tests/integration/test_operator_fixtures.rs +++ b/tests/internals/operator_fixtures.rs @@ -1,19 +1,18 @@ -#[path = "../common/mod.rs"] -mod common; - +use crate::{fixtures, internals}; use ndarray::{Array1, Array2}; -use spectral_init::operator::{CsrOperator, LinearOperator}; +use spectral_init::__internal::{CsrOperator, LinearOperator}; const DATASET: &str = "blobs_connected_200"; #[test] fn test_eigenpair_residual_from_fixture() { - let laplacian = common::load_sparse_csr(&common::fixture_path(DATASET, "comp_b_laplacian.npz")); + let laplacian = + fixtures::load_sparse_csr(&fixtures::fixture_path(DATASET, "comp_b_laplacian.npz")); let n = laplacian.rows(); - let eigen_path = common::fixture_path(DATASET, "comp_d_eigensolver.npz"); - let eigenvalues: Array1 = common::load_dense(&eigen_path, "eigenvalues"); - let eigenvectors: Array2 = common::load_dense(&eigen_path, "eigenvectors"); + let eigen_path = fixtures::fixture_path(DATASET, "comp_d_eigensolver.npz"); + let eigenvalues: Array1 = fixtures::load_dense(&eigen_path, "eigenvalues"); + let eigenvectors: Array2 = fixtures::load_dense(&eigen_path, "eigenvectors"); let k = eigenvalues.len(); assert_eq!(eigenvectors.shape()[0], n); assert_eq!(eigenvectors.shape()[1], k); @@ -23,7 +22,7 @@ fn test_eigenpair_residual_from_fixture() { // so near-exact residuals are expected. for j in 0..k { let lambda = eigenvalues[j]; - let residual = common::residual_spmv(&laplacian, eigenvectors.column(j), lambda); + let residual = internals::residual_spmv(&laplacian, eigenvectors.column(j), lambda); assert!( residual < 1e-10, "eigenpair {j}: residual={residual:.3e} >= 1e-10 (lambda={lambda:.6e})" @@ -33,13 +32,13 @@ fn test_eigenpair_residual_from_fixture() { #[test] fn test_multi_vector_matches_sequential_from_fixture() { - let mat = common::load_sparse_csr(&common::fixture_path(DATASET, "comp_b_laplacian.npz")); + let mat = fixtures::load_sparse_csr(&fixtures::fixture_path(DATASET, "comp_b_laplacian.npz")); let op = CsrOperator(&mat); let n = mat.rows(); // Load eigenvectors as input matrix - let eigenvectors: Array2 = common::load_dense( - &common::fixture_path(DATASET, "comp_d_eigensolver.npz"), + let eigenvectors: Array2 = fixtures::load_dense( + &fixtures::fixture_path(DATASET, "comp_d_eigensolver.npz"), "eigenvectors", ); let k = eigenvectors.shape()[1]; diff --git a/tests/integration/test_rq4_property_tests.proptest-regressions b/tests/internals/property_tests.proptest-regressions similarity index 100% rename from tests/integration/test_rq4_property_tests.proptest-regressions rename to tests/internals/property_tests.proptest-regressions diff --git a/tests/integration/test_rq4_property_tests.rs b/tests/internals/property_tests.rs similarity index 69% rename from tests/integration/test_rq4_property_tests.rs rename to tests/internals/property_tests.rs index 9fa3147..09f93c6 100644 --- a/tests/integration/test_rq4_property_tests.rs +++ b/tests/internals/property_tests.rs @@ -1,24 +1,35 @@ //! RQ4: Property-based tests for spectral_init mathematical invariants. //! //! Uses proptest to verify invariants hold across random graph sizes n in [50, 200]. -//! This test target requires `--features testing`. - -#[path = "../common/mod.rs"] -mod common; +use crate::{fixtures, internals}; use proptest::prelude::*; -use spectral_init::{SpectralInitConfig, spectral_init}; +use proptest::test_runner::FileFailurePersistence; +use spectral_init::__internal::SolverParams; +use spectral_init::{ComputeMode, SpectralInitConfig, spectral_init}; + +/// Failing cases persist to `property_tests.proptest-regressions`, next to this file. +fn config() -> ProptestConfig { + ProptestConfig { + cases: 256, + max_shrink_iters: 64, + failure_persistence: Some(Box::new(FileFailurePersistence::WithSource( + "proptest-regressions", + ))), + ..Default::default() + } +} // ─── Eigenpair invariant tests ────────────────────────────────────────────── proptest! { - #![proptest_config(ProptestConfig { cases: 256, max_shrink_iters: 64, ..Default::default() })] + #![proptest_config(config())] #[test] fn proptest_eigenvalues_sorted(n in 50usize..=200) { - let laplacian = common::ring_laplacian(n); + let laplacian = fixtures::ring_laplacian(n); let ((eigs, _vecs), _level) = - spectral_init::solve_eigenproblem_pub(&laplacian, 2, 42, spectral_init::ComputeMode::PythonCompat); + internals::solve_with_unit_hint(&laplacian, 2, 42, ComputeMode::PythonCompat, &SolverParams::default()); for i in 0..eigs.len() - 1 { prop_assert!( eigs[i] <= eigs[i + 1] + 1e-12, @@ -30,9 +41,9 @@ proptest! { #[test] fn proptest_eigenvalues_nonneg(n in 50usize..=200) { - let laplacian = common::ring_laplacian(n); + let laplacian = fixtures::ring_laplacian(n); let ((eigs, _vecs), _level) = - spectral_init::solve_eigenproblem_pub(&laplacian, 2, 42, spectral_init::ComputeMode::PythonCompat); + internals::solve_with_unit_hint(&laplacian, 2, 42, ComputeMode::PythonCompat, &SolverParams::default()); for (i, &e) in eigs.iter().enumerate() { prop_assert!(e >= 0.0, "eigenvalue λ[{}]={} is negative", i, e); } @@ -40,9 +51,9 @@ proptest! { #[test] fn proptest_eigenvalues_leq_2(n in 50usize..=200) { - let laplacian = common::ring_laplacian(n); + let laplacian = fixtures::ring_laplacian(n); let ((eigs, _vecs), _level) = - spectral_init::solve_eigenproblem_pub(&laplacian, 2, 42, spectral_init::ComputeMode::PythonCompat); + internals::solve_with_unit_hint(&laplacian, 2, 42, ComputeMode::PythonCompat, &SolverParams::default()); for (i, &e) in eigs.iter().enumerate() { prop_assert!( e <= 2.0, @@ -53,9 +64,9 @@ proptest! { #[test] fn proptest_trivial_null_space(n in 50usize..=200) { - let laplacian = common::ring_laplacian(n); + let laplacian = fixtures::ring_laplacian(n); let ((eigs, _vecs), _level) = - spectral_init::solve_eigenproblem_pub(&laplacian, 2, 42, spectral_init::ComputeMode::PythonCompat); + internals::solve_with_unit_hint(&laplacian, 2, 42, ComputeMode::PythonCompat, &SolverParams::default()); prop_assert!( eigs[0].abs() < 1e-6, "smallest eigenvalue λ₀={} not near zero for connected ring({})", @@ -65,12 +76,12 @@ proptest! { #[test] fn proptest_residual_leq_1e5(n in 50usize..=200) { - let laplacian = common::ring_laplacian(n); + let laplacian = fixtures::ring_laplacian(n); let ((eigs, vecs), _level) = - spectral_init::solve_eigenproblem_pub(&laplacian, 2, 42, spectral_init::ComputeMode::PythonCompat); + internals::solve_with_unit_hint(&laplacian, 2, 42, ComputeMode::PythonCompat, &SolverParams::default()); for i in 0..eigs.len() { let col = vecs.column(i); - let r = common::residual_spmv(&laplacian, col, eigs[i]); + let r = internals::residual_spmv(&laplacian, col, eigs[i]); prop_assert!( r < 1e-5, "residual for eigenpair {} is {} (threshold 1e-5), n={}", @@ -81,9 +92,9 @@ proptest! { #[test] fn proptest_orthogonality(n in 50usize..=200) { - let laplacian = common::ring_laplacian(n); + let laplacian = fixtures::ring_laplacian(n); let ((_eigs, vecs), _level) = - spectral_init::solve_eigenproblem_pub(&laplacian, 2, 42, spectral_init::ComputeMode::PythonCompat); + internals::solve_with_unit_hint(&laplacian, 2, 42, ComputeMode::PythonCompat, &SolverParams::default()); // vecs is (n, 3) — compute V^T * V which should be I_3 let vtv = vecs.t().dot(&vecs); let k = vtv.nrows(); @@ -105,11 +116,11 @@ proptest! { // ─── Output invariant tests ───────────────────────────────────────────────── proptest! { - #![proptest_config(ProptestConfig { cases: 256, max_shrink_iters: 64, ..Default::default() })] + #![proptest_config(config())] #[test] fn proptest_finite_output(n in 50usize..=200) { - let graph = common::make_ring(n as u32); + let graph = fixtures::make_ring(n as u32); let coords = spectral_init(&graph, 2, 42, None, SpectralInitConfig::default()) .expect("spectral_init failed"); for &v in coords.iter() { @@ -119,7 +130,7 @@ proptest! { #[test] fn proptest_output_variance(n in 50usize..=200) { - let graph = common::make_ring(n as u32); + let graph = fixtures::make_ring(n as u32); let coords = spectral_init(&graph, 2, 42, None, SpectralInitConfig::default()) .expect("spectral_init failed"); for col_idx in 0..coords.ncols() { @@ -136,7 +147,7 @@ proptest! { #[test] fn proptest_subspace_stable(n in 50usize..=200) { - let graph = common::make_ring(n as u32); + let graph = fixtures::make_ring(n as u32); let out1 = spectral_init(&graph, 2, 42, None, SpectralInitConfig::default()) .expect("spectral_init run 1 failed"); let out2 = spectral_init(&graph, 2, 42, None, SpectralInitConfig::default()) diff --git a/tests/integration/test_psd_contract_enforced.rs b/tests/internals/psd_contract.rs similarity index 68% rename from tests/integration/test_psd_contract_enforced.rs rename to tests/internals/psd_contract.rs index bdca8c8..3a12734 100644 --- a/tests/integration/test_psd_contract_enforced.rs +++ b/tests/internals/psd_contract.rs @@ -1,10 +1,9 @@ // Verifies the PSD contract: solve_eigenproblem must return eigenvalues in [0, 2] // exactly (no tolerance margin), for all fixtures and all reachable solver levels. -#[path = "../common/mod.rs"] -mod common; - -use spectral_init::{ComputeMode, solve_eigenproblem_pub}; +use crate::{fixtures, internals}; +use spectral_init::__internal::SolverParams; +use spectral_init::ComputeMode; const ALL_FIXTURES: &[&str] = &[ "blobs_50", @@ -20,11 +19,16 @@ const ALL_FIXTURES: &[&str] = &[ #[test] fn test_psd_contract_all_fixtures() { for fixture_name in ALL_FIXTURES { - let laplacian = common::load_sparse_csr( - &common::fixture_path(fixture_name, "").join("comp_b_laplacian.npz"), + let laplacian = fixtures::load_sparse_csr( + &fixtures::fixture_path(fixture_name, "").join("comp_b_laplacian.npz"), + ); + let ((eigenvalues, _eigenvectors), _report) = internals::solve_with_unit_hint( + &laplacian, + 2, + 42, + ComputeMode::PythonCompat, + &SolverParams::default(), ); - let ((eigenvalues, _eigenvectors), _level) = - solve_eigenproblem_pub(&laplacian, 2, 42, ComputeMode::PythonCompat); for (i, &lambda) in eigenvalues.iter().enumerate() { assert!( lambda >= 0.0, diff --git a/tests/integration/test_scaling_fixtures.rs b/tests/internals/scaling_fixtures.rs similarity index 91% rename from tests/integration/test_scaling_fixtures.rs rename to tests/internals/scaling_fixtures.rs index cfec59f..e7689eb 100644 --- a/tests/integration/test_scaling_fixtures.rs +++ b/tests/internals/scaling_fixtures.rs @@ -1,19 +1,17 @@ -#[path = "../common/mod.rs"] -mod common; - +use crate::fixtures; use ndarray::Array2; -use spectral_init::{scale_and_add_noise_pub, scale_coords}; +use spectral_init::__internal::{scale_and_add_noise, scale_coords}; fn load_embedding(dataset: &str) -> Array2 { - common::load_dense( - &common::fixture_path(dataset, "comp_e_selection.npz"), + fixtures::load_dense( + &fixtures::fixture_path(dataset, "comp_e_selection.npz"), "embedding", ) } fn load_pre_noise(dataset: &str) -> Array2 { - common::load_dense( - &common::fixture_path(dataset, "comp_f_scaling.npz"), + fixtures::load_dense( + &fixtures::fixture_path(dataset, "comp_f_scaling.npz"), "pre_noise", ) } @@ -61,7 +59,7 @@ fn test_noise_distribution_blobs_50() { let n = embedding.len(); let final_result = - scale_and_add_noise_pub(embedding.clone(), 42).expect("scale_and_add_noise failed"); + scale_and_add_noise(embedding.clone(), 42).expect("scale_and_add_noise failed"); let pre_noise = scale_coords(&embedding, 10.0).expect("scale_coords failed"); let noise: Array2 = &final_result - &pre_noise; diff --git a/tests/internals/simd.rs b/tests/internals/simd.rs new file mode 100644 index 0000000..cb72785 --- /dev/null +++ b/tests/internals/simd.rs @@ -0,0 +1,64 @@ +//! Parity between the scalar and the SIMD solver paths. + +#![cfg(target_arch = "x86_64")] + +use crate::{fixtures, internals}; +use spectral_init::__internal::{SolverParams, normalize_signs, scale_and_add_noise}; +use spectral_init::ComputeMode; + +const FIXTURES: &[&str] = &[ + "blobs_50", + "near_dupes_100", + "moons_200", + "blobs_connected_200", + "disconnected_200", + "circles_300", + "blobs_500", + "blobs_connected_2000", + "blobs_5000", +]; + +/// `RustNative` (AVX2 SpMV) and `PythonCompat` (scalar SpMV) must produce the same scaled +/// coordinates once the per-column sign is normalized. +#[test] +fn rust_native_and_python_compat_solver_outputs_agree() { + if !is_x86_feature_detected!("avx2") || !is_x86_feature_detected!("fma") { + eprintln!( + "rust_native_and_python_compat_solver_outputs_agree: skipping — AVX2/FMA not \ + available; ComputeMode::RustNative uses the scalar path, making the comparison vacuous" + ); + return; + } + + let params = SolverParams::default(); + for &fixture in FIXTURES { + let lap_path = fixtures::fixture_path(fixture, "comp_b_laplacian.npz"); + let laplacian = fixtures::load_sparse_csr(&lap_path); + + let ((_, mut eigvec_scalar), _) = + internals::solve_with_unit_hint(&laplacian, 2, 42, ComputeMode::PythonCompat, ¶ms); + let ((_, mut eigvec_avx2), _) = + internals::solve_with_unit_hint(&laplacian, 2, 42, ComputeMode::RustNative, ¶ms); + + normalize_signs(&mut eigvec_scalar); + normalize_signs(&mut eigvec_avx2); + + let scaled_scalar = + scale_and_add_noise(eigvec_scalar, 42).expect("scale_and_add_noise failed"); + let scaled_avx2 = scale_and_add_noise(eigvec_avx2, 42).expect("scale_and_add_noise failed"); + + let f32_max_abs_diff = scaled_scalar + .iter() + .zip(scaled_avx2.iter()) + .map(|(a, b)| (a - b).abs()) + .fold(0.0f32, f32::max); + + // 4 * f32::EPSILON ≈ 4.77e-7; allows one rounding-budget above zero for + // any residual scalar/SIMD divergence that survives normalize_signs. + assert!( + f32_max_abs_diff <= 4.77e-7, + "fixture {fixture}: max_abs_diff={f32_max_abs_diff:.3e} > 4.77e-7 after normalize_signs — \ + sign flip not resolved; SIMD kernel must be gated behind ComputeMode::RustNative" + ); + } +} diff --git a/tests/integration/test_solver_invariants.rs b/tests/internals/solver_invariants.rs similarity index 83% rename from tests/integration/test_solver_invariants.rs rename to tests/internals/solver_invariants.rs index d06e8f7..dcd05f0 100644 --- a/tests/integration/test_solver_invariants.rs +++ b/tests/internals/solver_invariants.rs @@ -2,15 +2,11 @@ // Each test validates a per-solver property that must hold on clean source // and is designed to fail when its targeted mutation (B1–B8) is applied. -#[path = "../common/mod.rs"] -mod common; - -use spectral_init::lobpcg_sinv_solve; -use spectral_init::operator::CsrOperator; -use spectral_init::rsvd_solve; -use spectral_init::solvers::lobpcg::lobpcg_solve; -use spectral_init::{ComputeMode, solve_eigenproblem_pub}; -use spectral_init::{SpectralInitConfig, spectral_init}; +use crate::{fixtures, internals}; +use spectral_init::__internal::{ + CsrOperator, SolverParams, lobpcg_sinv_solve, lobpcg_solve, rsvd_solve, +}; +use spectral_init::{ComputeMode, SpectralInitConfig, spectral_init}; /// Two-component graph: disjoint paths P_{n1} (nodes 0..n1) and P_{n2} (nodes n1..n1+n2). /// No edges cross the component boundary. Adjacency is weight 1.0 for each path edge. @@ -56,10 +52,15 @@ fn make_two_component_graph(n1: u32, n2: u32) -> sprs::CsMatI { #[test] fn test_inv_eigenvalue_ascending_order() { - let lap_path = common::fixture_path("blobs_50", "comp_b_laplacian.npz"); - let lap = common::load_sparse_csr(&lap_path); - let ((eigvals, _eigvecs), _level) = - solve_eigenproblem_pub(&lap, 2, 42, ComputeMode::PythonCompat); + let lap_path = fixtures::fixture_path("blobs_50", "comp_b_laplacian.npz"); + let lap = fixtures::load_sparse_csr(&lap_path); + let ((eigvals, _eigvecs), _report) = internals::solve_with_unit_hint( + &lap, + 2, + 42, + ComputeMode::PythonCompat, + &SolverParams::default(), + ); for i in 0..eigvals.len().saturating_sub(1) { assert!( eigvals[i] <= eigvals[i + 1] + 1e-12, @@ -75,27 +76,33 @@ fn test_inv_eigenvalue_ascending_order() { #[test] fn test_inv_escalation_routing_large_n() { - let lap = common::ring_laplacian(100); + let lap = fixtures::ring_laplacian(100); // Clean path: n=100 < DENSE_N_THRESHOLD=2000 → level 0 (dense EVD). - let (_, level) = solve_eigenproblem_pub(&lap, 2, 42, ComputeMode::PythonCompat); + let (_, report) = internals::solve_with_unit_hint( + &lap, + 2, + 42, + ComputeMode::PythonCompat, + &SolverParams::default(), + ); + let level = report.level as u8; assert_eq!( level, 0, "expected dense EVD (level 0) for n=100, got level={level}" ); - // Forced path: threshold=0 forces all n away from dense → level ≥ 1. - // Safe because nextest runs each test in a dedicated process. - unsafe { - std::env::set_var("SPECTRAL_DENSE_N_THRESHOLD", "0"); - } - let (_, level_forced) = solve_eigenproblem_pub(&lap, 2, 42, ComputeMode::PythonCompat); - unsafe { - std::env::remove_var("SPECTRAL_DENSE_N_THRESHOLD"); - } + // Forced path: a zero dense threshold routes every n away from dense → level ≥ 1. + let forced = SolverParams { + dense_n_threshold: 0, + ..SolverParams::default() + }; + let (_, report_forced) = + internals::solve_with_unit_hint(&lap, 2, 42, ComputeMode::PythonCompat, &forced); + let level_forced = report_forced.level as u8; assert!( level_forced >= 1, - "expected level ≥ 1 with SPECTRAL_DENSE_N_THRESHOLD=0, got {level_forced}" + "expected level ≥ 1 with dense_n_threshold=0, got {level_forced}" ); } @@ -110,8 +117,8 @@ fn test_inv_sign_convention() { // Ring graphs are NOT used here: their degenerate ±1 Fiedler eigenvectors cause // the argmax to shift after noise, making the check unreliable. for dataset in &["blobs_50", "blobs_connected_2000"] { - let graph_path = common::fixture_path(dataset, "step5a_pruned.npz"); - let graph = common::load_sparse_csr_f32_u32(&graph_path); + let graph_path = fixtures::fixture_path(dataset, "step5a_pruned.npz"); + let graph = fixtures::load_sparse_csr_f32_u32(&graph_path); let result = spectral_init(&graph, 2, 42, None, SpectralInitConfig::default()) .unwrap_or_else(|e| panic!("spectral_init failed for {dataset}: {e}")); let (nrows, ncols) = (result.shape()[0], result.shape()[1]); @@ -187,8 +194,8 @@ fn test_inv_multi_component_completeness() { #[test] fn test_inv_eigenvalue_non_negative() { - let lap = common::ring_laplacian(500); - let sqrt_deg = common::ring_sqrt_deg(500); + let lap = fixtures::ring_laplacian(500); + let sqrt_deg = fixtures::ring_sqrt_deg(500); let op = CsrOperator(&lap); let ((eigvals, _eigvecs), _) = lobpcg_solve(&op, 2, 42, false, &sqrt_deg) .expect("lobpcg_solve returned None on ring C_500"); @@ -211,8 +218,8 @@ fn test_inv_eigenvalue_non_negative() { // The gap is accepted: B6 is a subtle performance regression, not a correctness bug. #[test] fn test_inv_lobpcg_convergence_ill_conditioned() { - let lap = common::ring_laplacian(2000); - let sqrt_deg = common::ring_sqrt_deg(2000); + let lap = fixtures::ring_laplacian(2000); + let sqrt_deg = fixtures::ring_sqrt_deg(2000); let op = CsrOperator(&lap); let result = lobpcg_solve(&op, 2, 42, false, &sqrt_deg); let (_, restart_count) = result.expect("lobpcg_solve returned None for ring C_2000 seed=42"); @@ -234,9 +241,9 @@ fn test_inv_lobpcg_convergence_ill_conditioned() { #[test] fn test_inv_rsvd_eigenvector_distinctness() { - let lap_path = common::fixture_path("blobs_5000", "comp_b_laplacian.npz"); - let lap = common::load_sparse_csr(&lap_path); - let (_eigvals, eigvecs) = rsvd_solve(&lap, 2, 42); + let lap_path = fixtures::fixture_path("blobs_5000", "comp_b_laplacian.npz"); + let lap = fixtures::load_sparse_csr(&lap_path); + let (_eigvals, eigvecs) = rsvd_solve(&lap, 2, 42, &SolverParams::default()); let v0 = eigvecs.column(0); let v1 = eigvecs.column(1); @@ -256,8 +263,8 @@ fn test_inv_rsvd_eigenvector_distinctness() { #[test] fn test_inv_sinv_non_zero_result() { - let lap = common::ring_laplacian(2500); - let sqrt_deg = common::ring_sqrt_deg(2500); + let lap = fixtures::ring_laplacian(2500); + let sqrt_deg = fixtures::ring_sqrt_deg(2500); let (eigvals, eigvecs) = lobpcg_sinv_solve(&lap, 2, 42, &sqrt_deg) .expect("lobpcg_sinv_solve returned None on ring C_2500"); for (i, _lambda) in eigvals.iter().enumerate() { diff --git a/tests/internals/warm_restart.rs b/tests/internals/warm_restart.rs new file mode 100644 index 0000000..3e844da --- /dev/null +++ b/tests/internals/warm_restart.rs @@ -0,0 +1,113 @@ +//! Warm-restart behaviour of the LOBPCG solver on ill-conditioned Laplacians. +//! +//! The restart counts asserted here are floating-point sensitive: they hold at the +//! `opt-level = 2` this package's test profile uses. + +use crate::{fixtures, internals}; +use spectral_init::__internal::{CsrOperator, lobpcg_solve}; + +#[test] +#[ignore = "requires --release; LOBPCG convergence behaviour differs in debug mode and the test times out (>1200s) without optimisation"] +fn test_path_2000_warm_restart_majority_converged() { + // With the 1000-iteration cap on warm-restart passes, path_2000 should converge + // on a majority of seeds. + let lap = fixtures::path_laplacian(2000); + let sqrt_deg = fixtures::path_sqrt_deg(2000); + let op = CsrOperator(&lap); + let n_components = 2; + + let mut n_converged = 0usize; + for seed in [42u64, 43, 44] { + if let Some(((eigs, vecs), _)) = lobpcg_solve(&op, n_components, seed, false, &sqrt_deg) { + let residuals = (0..eigs.len()) + .map(|i| internals::eigenpair_residual(&op, vecs.column(i), eigs[i])) + .collect::>(); + if residuals.iter().all(|&r| r < 1e-5) { + n_converged += 1; + } + } + } + assert!( + n_converged >= 2, + "path_2000 should converge on >= 2/3 seeds with raised restart cap; got {n_converged}/3" + ); +} + +#[test] +fn test_ring_2000_warm_restart_converges() { + // ring_2000 seed=42: single reproducible case from the research experiment + // where warm restart achieves full convergence (residual < 1e-5). + // Research evidence: restart_count=3, improvement_ratio=33.4x + // (residual drops from 3.25e-4 to 9.74e-6). + // Only meaningful under --release; skip in debug builds where LOBPCG + // convergence behaviour differs due to reduced optimisation. + if cfg!(debug_assertions) { + return; + } + let lap = fixtures::ring_laplacian(2000); + let sqrt_deg = fixtures::ring_sqrt_deg(2000); + let op = CsrOperator(&lap); + + let result = lobpcg_solve(&op, 2, 42, false, &sqrt_deg); + assert!( + result.is_some(), + "lobpcg_solve returned None for ring_2000 seed=42" + ); + + let ((eigs, vecs), restart_count) = result.unwrap(); + assert!( + restart_count >= 3, + "warm restart should fire 3 times on ring_2000 seed=42 (research: restart_count=3); got restart_count={restart_count}" + ); + + let max_res = internals::max_operator_residual(&op, &eigs, &vecs); + assert!( + max_res < 1e-5, + "ring_2000 seed=42 should converge to max_residual < 1e-5; got {max_res:.2e}" + ); +} + +#[test] +fn test_ring_2000_warm_restart_fires() { + // ring_2000 seed=42: research shows restart_count=3 at opt-level=2. + // At opt-level=2 the solver completes 300 iters/pass quickly; warm restart fires + // because 300 iters yields residual 3.25e-4 >> 1e-5 threshold. + // If the restart loop were truncated to a single pass, restart_count would be 0. + // NOTE: This assertion is FP-sensitive — LLVM FP reassociation at opt-level=2 can + // change Gram matrix conditioning, affecting whether Cholesky triggers a restart. + // Uses restart_count > 0 (weaker than >= 3) to reduce toolchain-version fragility. + let lap = fixtures::ring_laplacian(2000); + let sqrt_deg = fixtures::ring_sqrt_deg(2000); + let op = CsrOperator(&lap); + let result = lobpcg_solve(&op, 2, 42, false, &sqrt_deg); + let (_, restart_count) = result.expect("lobpcg_solve returned None for ring_2000 seed=42"); + assert!( + restart_count > 0, + "ring_2000 seed=42 must trigger at least one warm restart at opt-level=2; \ + got restart_count={restart_count}" + ); +} + +#[test] +fn test_path_2000_warm_restart_fires() { + // path_2000 is a known hard input: high condition number, small spectral gap. + // At opt-level=2, at least one of seeds 42/43/44 will trigger warm restart. + // If the restart loop were truncated to a single pass, restart_count would be 0 + // for all seeds. + // NOTE: This assertion is FP-sensitive — same LLVM reassociation concern as above. + // Uses total_restarts > 0 across 3 seeds to reduce single-seed fragility. + let lap = fixtures::path_laplacian(2000); + let sqrt_deg = fixtures::path_sqrt_deg(2000); + let op = CsrOperator(&lap); + let mut total_restarts = 0usize; + for seed in [42u64, 43, 44] { + if let Some((_, rc)) = lobpcg_solve(&op, 2, seed, false, &sqrt_deg) { + total_restarts += rc; + } + } + assert!( + total_restarts > 0, + "path_2000: expected warm restart to fire on at least one of seeds 42/43/44 \ + at opt-level=2; got total_restarts={total_restarts}" + ); +} diff --git a/tests/integration/test_e2e_validation.rs b/tests/public_api/e2e_validation.rs similarity index 63% rename from tests/integration/test_e2e_validation.rs rename to tests/public_api/e2e_validation.rs index 761a310..c467cf7 100644 --- a/tests/integration/test_e2e_validation.rs +++ b/tests/public_api/e2e_validation.rs @@ -1,6 +1,4 @@ -#[path = "../common/mod.rs"] -mod common; - +use crate::fixtures; use spectral_init::{SpectralInitConfig, spectral_init}; // ── helpers ────────────────────────────────────────────────────────────────── @@ -19,65 +17,13 @@ fn vec_dot(a: ndarray::ArrayView1, b: ndarray::ArrayView1) -> f64 { a.iter().zip(b.iter()).map(|(x, y)| x * y).sum::() } -/// Load graph, run spectral_init, check residuals for a connected dataset. -fn run_e2e_residual_check(dataset: &str, n: usize) { - let graph_path = common::fixture_path(dataset, "step5a_pruned.npz"); - let graph = common::load_sparse_csr_f32_u32(&graph_path); - - let result = spectral_init(&graph, 2, 42, None, SpectralInitConfig::default()) - .unwrap_or_else(|e| panic!("spectral_init failed for {dataset}: {e}")); - assert_eq!(result.shape(), &[n, 2]); - for &v in result.iter() { - assert!(v.is_finite(), "non-finite in {dataset}: {v}"); - } - - // Load expansion factor (stored as 0-D scalar in the fixture) - let scaling_path = common::fixture_path(dataset, "comp_f_scaling.npz"); - let expansion: ndarray::Array0 = common::load_dense(&scaling_path, "expansion"); - let expansion_val = expansion.into_scalar(); - assert!( - expansion_val.is_normal() && expansion_val > 0.0, - "fixture expansion value must be positive and normal, got {expansion_val}" - ); - - // Load Laplacian and reference eigenvalues - let laplacian = common::load_sparse_csr(&common::fixture_path(dataset, "comp_b_laplacian.npz")); - let ref_eigenvalues: ndarray::Array1 = common::load_dense( - &common::fixture_path(dataset, "comp_d_eigensolver.npz"), - "eigenvalues", - ); - - // De-scale to recover approximate eigenvectors - let descaled = descale_embedding(&result, expansion_val); - - // Check residual for each of the 2 selected eigenvectors. - // Output column 0 → eigenvalue[1], column 1 → eigenvalue[2] (skip trivial index 0). - for col in 0..2usize { - let evec = descaled.column(col); - let eigval = ref_eigenvalues[col + 1]; - let r = common::residual_spmv(&laplacian, evec, eigval); - // Tolerance is 0.005: this bound must hold across the full solver escalation - // chain (dense EVD → LOBPCG → randomized SVD). Dense EVD residuals are ~1e-8 - // pre-noise; LOBPCG and rSVD paths yield somewhat larger residuals but remain - // well below this threshold. Gaussian noise (sigma=0.0001) adds at most ~1e-4 - // after de-scaling by expansion (~10); f32→f64 de-scaling contributes ~1e-7. - // 0.005 is 50× above the expected noise floor, catching genuine solver - // failures while rejecting the misleadingly loose 0.05 bound. - let residual_tol = 0.005_f64; - assert!( - r < residual_tol, - "residual quality check failed for {dataset} column {col}: residual={r:.6e} >= {residual_tol}" - ); - } -} - /// Load exact-KNN graph, run spectral_init, check shape and finiteness only. /// No residual check: comp_b_laplacian.npz is built from the approx-KNN graph; /// the exact-KNN graph may have different neighbor sets → different Laplacian → /// cross-path residual failures even for correct output. fn run_e2e_exact_knn_check(dataset: &str, n: usize) { - let graph_path = common::fixture_path(dataset, "step5a_pruned_exact.npz"); - let graph = common::load_sparse_csr_f32_u32(&graph_path); + let graph_path = fixtures::fixture_path(dataset, "step5a_pruned_exact.npz"); + let graph = fixtures::load_sparse_csr_f32_u32(&graph_path); let result = spectral_init(&graph, 2, 42, None, SpectralInitConfig::default()) .unwrap_or_else(|e| panic!("exact-KNN spectral_init failed for {dataset}: {e}")); assert_eq!(result.shape(), &[n, 2]); @@ -86,49 +32,19 @@ fn run_e2e_exact_knn_check(dataset: &str, n: usize) { } } -// ── residual quality tests (7 connected datasets) ──────────────────────────── -// blobs_500 and blobs_5000 are excluded: fixture generation confirms they are -// disconnected (4 and 2 components respectively). Their embeddings are produced -// by embed_disconnected() and are not Laplacian eigenvectors of the full graph. - -#[test] -fn test_e2e_residual_quality_blobs_connected_200() { - run_e2e_residual_check("blobs_connected_200", 200); -} - -#[test] -fn test_e2e_residual_quality_blobs_connected_2000() { - run_e2e_residual_check("blobs_connected_2000", 2000); -} - -#[test] -fn test_e2e_residual_quality_moons_200() { - run_e2e_residual_check("moons_200", 200); -} - -#[test] -fn test_e2e_residual_quality_circles_300() { - run_e2e_residual_check("circles_300", 300); -} - -#[test] -fn test_e2e_residual_quality_near_dupes_100() { - run_e2e_residual_check("near_dupes_100", 100); -} - // ── subspace comparison tests (near-degenerate eigenvalues) ────────────────── #[test] fn test_e2e_subspace_circles_300() { let dataset = "circles_300"; - let graph_path = common::fixture_path(dataset, "step5a_pruned.npz"); - let graph = common::load_sparse_csr_f32_u32(&graph_path); + let graph_path = fixtures::fixture_path(dataset, "step5a_pruned.npz"); + let graph = fixtures::load_sparse_csr_f32_u32(&graph_path); let result = spectral_init(&graph, 2, 42, None, SpectralInitConfig::default()) .unwrap_or_else(|e| panic!("spectral_init failed for {dataset}: {e}")); - let scaling_path = common::fixture_path(dataset, "comp_f_scaling.npz"); - let expansion: ndarray::Array0 = common::load_dense(&scaling_path, "expansion"); + let scaling_path = fixtures::fixture_path(dataset, "comp_f_scaling.npz"); + let expansion: ndarray::Array0 = fixtures::load_dense(&scaling_path, "expansion"); let expansion_val = expansion.into_scalar(); assert!( expansion_val.is_normal() && expansion_val > 0.0, @@ -137,8 +53,8 @@ fn test_e2e_subspace_circles_300() { let descaled = descale_embedding(&result, expansion_val); // Reference eigenvectors: columns 1 and 2 (skip trivial column 0) - let ref_evecs: ndarray::Array2 = common::load_dense( - &common::fixture_path(dataset, "comp_d_eigensolver.npz"), + let ref_evecs: ndarray::Array2 = fixtures::load_dense( + &fixtures::fixture_path(dataset, "comp_d_eigensolver.npz"), "eigenvectors", ); @@ -171,13 +87,13 @@ fn test_e2e_subspace_circles_300() { fn test_e2e_subspace_near_dupes_100() { let dataset = "near_dupes_100"; - let graph_path = common::fixture_path(dataset, "step5a_pruned.npz"); - let graph = common::load_sparse_csr_f32_u32(&graph_path); + let graph_path = fixtures::fixture_path(dataset, "step5a_pruned.npz"); + let graph = fixtures::load_sparse_csr_f32_u32(&graph_path); let result = spectral_init(&graph, 2, 42, None, SpectralInitConfig::default()) .unwrap_or_else(|e| panic!("spectral_init failed for {dataset}: {e}")); - let scaling_path = common::fixture_path(dataset, "comp_f_scaling.npz"); - let expansion: ndarray::Array0 = common::load_dense(&scaling_path, "expansion"); + let scaling_path = fixtures::fixture_path(dataset, "comp_f_scaling.npz"); + let expansion: ndarray::Array0 = fixtures::load_dense(&scaling_path, "expansion"); let expansion_val = expansion.into_scalar(); assert!( expansion_val.is_normal() && expansion_val > 0.0, @@ -185,8 +101,8 @@ fn test_e2e_subspace_near_dupes_100() { ); let descaled = descale_embedding(&result, expansion_val); - let ref_evecs: ndarray::Array2 = common::load_dense( - &common::fixture_path(dataset, "comp_d_eigensolver.npz"), + let ref_evecs: ndarray::Array2 = fixtures::load_dense( + &fixtures::fixture_path(dataset, "comp_d_eigensolver.npz"), "eigenvectors", ); @@ -240,8 +156,8 @@ fn test_e2e_exact_knn_near_dupes_100() { fn test_e2e_disconnected_200_component_separation() { let dataset = "disconnected_200"; - let graph_path = common::fixture_path(dataset, "step5a_pruned.npz"); - let graph = common::load_sparse_csr_f32_u32(&graph_path); + let graph_path = fixtures::fixture_path(dataset, "step5a_pruned.npz"); + let graph = fixtures::load_sparse_csr_f32_u32(&graph_path); let result = spectral_init(&graph, 2, 42, None, SpectralInitConfig::default()) .unwrap_or_else(|e| panic!("spectral_init failed for {dataset}: {e}")); @@ -252,8 +168,8 @@ fn test_e2e_disconnected_200_component_separation() { } // Load component labels (stored as int32 in the fixture) - let labels: ndarray::Array1 = common::load_dense( - &common::fixture_path(dataset, "comp_c_components.npz"), + let labels: ndarray::Array1 = fixtures::load_dense( + &fixtures::fixture_path(dataset, "comp_c_components.npz"), "labels", ); assert_eq!(labels.len(), n); @@ -311,8 +227,8 @@ fn test_e2e_disconnected_200_component_separation() { #[test] fn test_e2e_performance_blobs_5000() { - let path = common::fixture_path("blobs_5000", "step5a_pruned.npz"); - let graph = common::load_sparse_csr_f32_u32(&path); + let path = fixtures::fixture_path("blobs_5000", "step5a_pruned.npz"); + let graph = fixtures::load_sparse_csr_f32_u32(&path); let start = std::time::Instant::now(); let result = spectral_init(&graph, 2, 42, None, SpectralInitConfig::default()) .expect("blobs_5000 spectral_init failed"); diff --git a/tests/public_api/main.rs b/tests/public_api/main.rs new file mode 100644 index 0000000..6bf18d0 --- /dev/null +++ b/tests/public_api/main.rs @@ -0,0 +1,8 @@ +//! Integration tests of the public API, built with default features. + +#[path = "../common/fixtures.rs"] +mod fixtures; + +mod e2e_validation; +mod npz_loading; +mod pipeline; diff --git a/tests/npz_loading.rs b/tests/public_api/npz_loading.rs similarity index 72% rename from tests/npz_loading.rs rename to tests/public_api/npz_loading.rs index 5280b6e..c04440a 100644 --- a/tests/npz_loading.rs +++ b/tests/public_api/npz_loading.rs @@ -1,16 +1,16 @@ -mod common; +use crate::fixtures; #[test] fn smoke_load_comp_a_degrees_blobs_connected_200() { - let path = common::fixture_path("blobs_connected_200", "comp_a_degrees.npz"); + let path = fixtures::fixture_path("blobs_connected_200", "comp_a_degrees.npz"); assert!( path.exists(), "fixture not found at {:?}; run: python tests/generate_fixtures.py", path ); - let degrees: ndarray::Array1 = common::load_dense(&path, "degrees"); - let sqrt_deg: ndarray::Array1 = common::load_dense(&path, "sqrt_deg"); + let degrees: ndarray::Array1 = fixtures::load_dense(&path, "degrees"); + let sqrt_deg: ndarray::Array1 = fixtures::load_dense(&path, "sqrt_deg"); // Shape: blobs_connected_200 has n=200 assert_eq!(degrees.len(), 200, "degrees shape mismatch"); diff --git a/tests/integration/test_pipeline.rs b/tests/public_api/pipeline.rs similarity index 94% rename from tests/integration/test_pipeline.rs rename to tests/public_api/pipeline.rs index 3225d9e..99e3f42 100644 --- a/tests/integration/test_pipeline.rs +++ b/tests/public_api/pipeline.rs @@ -1,6 +1,4 @@ -#[path = "../common/mod.rs"] -mod common; - +use crate::fixtures; use spectral_init::{SpectralInitConfig, spectral_init}; use sprs::CsMatI; @@ -16,8 +14,8 @@ fn spectral_init_output_shape_all_connected_datasets() { ]; for (dataset, expected_n) in &datasets { - let path = common::fixture_path(dataset, "step5a_pruned.npz"); - let graph = common::load_sparse_csr_f32_u32(&path); + let path = fixtures::fixture_path(dataset, "step5a_pruned.npz"); + let graph = fixtures::load_sparse_csr_f32_u32(&path); let result = spectral_init(&graph, 2, 42, None, SpectralInitConfig::default()) .unwrap_or_else(|e| panic!("spectral_init failed for {dataset}: {e}")); @@ -40,14 +38,14 @@ fn spectral_init_output_close_to_pre_noise_blobs_connected_200() { // We compare against the pre-noise fixture with epsilon=0.01 to verify the output is // in the correct numeric range — the noise is negligible relative to this tolerance. let dataset = "blobs_connected_200"; - let graph_path = common::fixture_path(dataset, "step5a_pruned.npz"); - let graph = common::load_sparse_csr_f32_u32(&graph_path); + let graph_path = fixtures::fixture_path(dataset, "step5a_pruned.npz"); + let graph = fixtures::load_sparse_csr_f32_u32(&graph_path); let result = spectral_init(&graph, 2, 42, None, SpectralInitConfig::default()) .expect("spectral_init failed for blobs_connected_200"); - let fixture_path = common::fixture_path(dataset, "comp_f_scaling.npz"); - let pre_noise: ndarray::Array2 = common::load_dense(&fixture_path, "pre_noise"); + let fixture_path = fixtures::fixture_path(dataset, "comp_f_scaling.npz"); + let pre_noise: ndarray::Array2 = fixtures::load_dense(&fixture_path, "pre_noise"); assert_eq!(result.shape(), pre_noise.shape(), "shape mismatch"); @@ -186,8 +184,8 @@ fn spectral_init_synthetic_disconnected_preserves_component_structure() { #[test] fn spectral_init_disconnected_200_shape_and_finite() { - let path = common::fixture_path("disconnected_200", "step5a_pruned.npz"); - let graph = common::load_sparse_csr_f32_u32(&path); + let path = fixtures::fixture_path("disconnected_200", "step5a_pruned.npz"); + let graph = fixtures::load_sparse_csr_f32_u32(&path); let result = spectral_init(&graph, 2, 42, None, SpectralInitConfig::default()); let arr = result.expect("spectral_init on disconnected_200 should succeed"); @@ -200,8 +198,8 @@ fn spectral_init_disconnected_200_shape_and_finite() { #[test] fn spectral_init_blobs_50_produces_valid_embedding() { // blobs_50 has 3 tight clusters that may be disconnected in the k-NN graph - let path = common::fixture_path("blobs_50", "step5a_pruned.npz"); - let graph = common::load_sparse_csr_f32_u32(&path); + let path = fixtures::fixture_path("blobs_50", "step5a_pruned.npz"); + let graph = fixtures::load_sparse_csr_f32_u32(&path); let result = spectral_init(&graph, 2, 42, None, SpectralInitConfig::default()); let arr = result.expect("spectral_init on blobs_50 should succeed"); diff --git a/tests/visual_eval/README.md b/tests/visual_eval/README.md index bc67d87..2c5b8df 100644 --- a/tests/visual_eval/README.md +++ b/tests/visual_eval/README.md @@ -230,7 +230,7 @@ The `export_rust_init` test loads each `{name}_graph.npz` from Phase 1, runs `{name}_rust_init.npy`. Parameters: `n_components=2, seed=42, PythonCompat` mode. ```bash -cargo test --test export_rust_init --features testing -- --ignored --nocapture +cargo test -p spectral-init-eval --test export_rust_init -- --ignored --nocapture ``` ### Phase 2 — Comparison (`--phase compare`) diff --git a/tests/visual_eval/generate_umap_comparisons.py b/tests/visual_eval/generate_umap_comparisons.py index 5c8177e..809c9de 100644 --- a/tests/visual_eval/generate_umap_comparisons.py +++ b/tests/visual_eval/generate_umap_comparisons.py @@ -414,14 +414,14 @@ def _find_tw_binary() -> "pathlib.Path": """Resolve path to the compiled Rust trustworthiness binary. Raises RuntimeError if the binary is not present. - Build it with: cargo build --release --features cli + Build it with: cargo build --release -p trustworthiness --features cli """ import pathlib candidate = pathlib.Path(__file__).parents[2] / "target" / "release" / "trustworthiness" if not candidate.exists(): raise RuntimeError( f"Rust trustworthiness binary not found: {candidate}\n" - "Build it with: cargo build --release --features cli" + "Build it with: cargo build --release -p trustworthiness --features cli" ) return candidate diff --git a/tests/visual_eval/run_eval.sh b/tests/visual_eval/run_eval.sh index 5b21ca5..2c78865 100755 --- a/tests/visual_eval/run_eval.sh +++ b/tests/visual_eval/run_eval.sh @@ -10,7 +10,7 @@ python "$SCRIPT_DIR/generate_umap_comparisons.py" --phase baseline echo "" echo "=== Rust Export: Generate spectral init coordinates ===" cd "$PROJECT_ROOT" -cargo test --test export_rust_init --features testing -- --ignored --nocapture +cargo test -p spectral-init-eval --test export_rust_init -- --ignored --nocapture echo "" echo "=== Phase 2: Compare and evaluate ===" diff --git a/tests/visual_eval/run_merfish_eval.sh b/tests/visual_eval/run_merfish_eval.sh index b9f4096..4c1ed9c 100755 --- a/tests/visual_eval/run_merfish_eval.sh +++ b/tests/visual_eval/run_merfish_eval.sh @@ -43,9 +43,9 @@ cd "$PROJECT_ROOT" RUST_PERF_FILE="$SCRIPT_DIR/output/merfish_${SUBSET}_rust_perf.txt" /usr/bin/time -o "$RUST_PERF_FILE" -f "%e %M" \ cargo nextest run \ + -p spectral-init-eval \ --profile merfish-eval \ --run-ignored all \ - --features testing \ -E "test(export_merfish_init_${SUBSET})" echo "" diff --git a/tests/visual_eval/test_generate_umap_comparisons.py b/tests/visual_eval/test_generate_umap_comparisons.py index 2d2872c..c218ee0 100644 --- a/tests/visual_eval/test_generate_umap_comparisons.py +++ b/tests/visual_eval/test_generate_umap_comparisons.py @@ -100,7 +100,7 @@ def test_find_tw_binary_raises_when_absent(monkeypatch): lambda self: False if self.name == "trustworthiness" else _real_exists(self), ) from tests.visual_eval.generate_umap_comparisons import _find_tw_binary - with pytest.raises(RuntimeError, match="cargo build --release --features cli"): + with pytest.raises(RuntimeError, match="cargo build --release -p trustworthiness --features cli"): _find_tw_binary() diff --git a/trustworthiness/Cargo.toml b/trustworthiness/Cargo.toml new file mode 100644 index 0000000..64f21a4 --- /dev/null +++ b/trustworthiness/Cargo.toml @@ -0,0 +1,52 @@ +[package] +name = "trustworthiness" +version = "0.1.0" +edition = "2024" +description = "Trustworthiness metric for low-dimensional embeddings, with a command-line tool" +license = "MIT" +repository = "https://github.com/TalonT-Org/spectral-init" +rust-version = "1.88" +publish = false + +[features] +# Per-step timing lines on stderr (parsed by the `tw_profiler` binary). +profiling = [] +# Command-line binaries and `.npy` input. +cli = ["dep:ndarray-npy", "dep:pico-args", "dep:serde_json", "dep:libc"] + +[dependencies] +ndarray = "0.17" +rayon = "1" +rand = "0.9" +ndarray-npy = { version = "0.10", optional = true } +pico-args = { version = "0.5", optional = true } +serde_json = { version = "1", optional = true } +libc = { version = "0.2", optional = true } + +[dev-dependencies] +criterion = { version = "0.5", features = ["html_reports"] } +ndarray-npy = "0.10" +serde_json = "1" + +[[bin]] +name = "trustworthiness" +path = "src/bin/trustworthiness.rs" +required-features = ["cli"] + +[[bin]] +name = "tw_profiler" +path = "src/bin/tw_profiler.rs" +required-features = ["cli"] + +[[bench]] +name = "trustworthiness_bench" +harness = false + +[[bench]] +name = "dist_sq_bench" +harness = false + +[[test]] +name = "test_tw_profiler" +path = "tests/test_tw_profiler.rs" +required-features = ["cli"] diff --git a/benches/dist_sq_bench.rs b/trustworthiness/benches/dist_sq_bench.rs similarity index 94% rename from benches/dist_sq_bench.rs rename to trustworthiness/benches/dist_sq_bench.rs index 44e6b46..e0197a7 100644 --- a/benches/dist_sq_bench.rs +++ b/trustworthiness/benches/dist_sq_bench.rs @@ -1,12 +1,12 @@ //! Criterion microbenchmark for `dist_sq_avx2_looped` vs scalar at d_x=10 and d_x=50. //! -//! Run with: cargo bench --bench dist_sq_bench +//! Run with: cargo bench -p trustworthiness --bench dist_sq_bench use criterion::{BenchmarkId, Criterion, criterion_group, criterion_main}; use std::hint::black_box; #[cfg(target_arch = "x86_64")] -use spectral_init::metrics::dist_sq_avx2_looped; +use trustworthiness::dist_sq_avx2_looped; // Note: the avx2_looped benchmark arm runs only when AVX2 and FMA are detected at runtime; // on other hosts only the scalar variant runs. diff --git a/benches/trustworthiness_bench.rs b/trustworthiness/benches/trustworthiness_bench.rs similarity index 90% rename from benches/trustworthiness_bench.rs rename to trustworthiness/benches/trustworthiness_bench.rs index 8e6a4fb..c390d65 100644 --- a/benches/trustworthiness_bench.rs +++ b/trustworthiness/benches/trustworthiness_bench.rs @@ -26,7 +26,7 @@ fn bench_trustworthiness(c: &mut Criterion) { for &n in &[1_000, 5_000, 50_000] { let (x, y) = make_data(n, 10, 2, 42); group.bench_with_input(BenchmarkId::new("n", n), &n, |b, _| { - b.iter(|| black_box(spectral_init::trustworthiness(x.view(), y.view(), 15))); + b.iter(|| black_box(trustworthiness::trustworthiness(x.view(), y.view(), 15))); }); } group.finish(); @@ -43,7 +43,7 @@ fn bench_trustworthiness_d50(c: &mut Criterion) { for &n in &[1_000, 5_000, 10_000, 50_000] { let (x, y) = make_data(n, 50, 2, 42); group.bench_with_input(BenchmarkId::new("n", n), &n, |b, _| { - b.iter(|| black_box(spectral_init::trustworthiness(x.view(), y.view(), 15))); + b.iter(|| black_box(trustworthiness::trustworthiness(x.view(), y.view(), 15))); }); } group.finish(); diff --git a/src/bin/trustworthiness.rs b/trustworthiness/src/bin/trustworthiness.rs similarity index 93% rename from src/bin/trustworthiness.rs rename to trustworthiness/src/bin/trustworthiness.rs index e727ee3..09d41b7 100644 --- a/src/bin/trustworthiness.rs +++ b/trustworthiness/src/bin/trustworthiness.rs @@ -25,7 +25,7 @@ fn run() -> Result<(), Box> { let y: ndarray::Array2 = ndarray_npy::read_npy(&y_path) .map_err(|e| format!("failed to load Y from {}: {e}", y_path.display()))?; - let score = spectral_init::trustworthiness(x.view(), y.view(), k); + let score = trustworthiness::trustworthiness(x.view(), y.view(), k); println!("{:.15}", score); Ok(()) } diff --git a/src/bin/tw_profiler.rs b/trustworthiness/src/bin/tw_profiler.rs similarity index 96% rename from src/bin/tw_profiler.rs rename to trustworthiness/src/bin/tw_profiler.rs index 45745cb..7bd0f56 100644 --- a/src/bin/tw_profiler.rs +++ b/trustworthiness/src/bin/tw_profiler.rs @@ -40,7 +40,7 @@ fn run() -> Result<(), Box> { // Warmup iterations (results discarded). for _ in 0..warmup { - let _ = std::hint::black_box(spectral_init::trustworthiness(x.view(), y.view(), k)); + let _ = std::hint::black_box(trustworthiness::trustworthiness(x.view(), y.view(), k)); } // Timed iterations. @@ -48,7 +48,7 @@ fn run() -> Result<(), Box> { let mut score = 0.0f64; for _ in 0..iters { let start = std::time::Instant::now(); - score = spectral_init::trustworthiness(x.view(), y.view(), k); + score = trustworthiness::trustworthiness(x.view(), y.view(), k); let elapsed = start.elapsed().as_secs_f64(); times.push(elapsed); } diff --git a/trustworthiness/src/kernels.rs b/trustworthiness/src/kernels.rs new file mode 100644 index 0000000..4f71d7a --- /dev/null +++ b/trustworthiness/src/kernels.rs @@ -0,0 +1,146 @@ +//! AVX2 squared-distance kernels used by the trustworthiness metric on x86_64. + +/// Squared Euclidean distance using AVX2+FMA intrinsics, looped over all elements. +/// +/// 4-wide YMM loop with FMA accumulation, horizontal reduce, scalar tail 0-3. +/// +/// # Safety +/// Both slices must have the same length and at least 10 elements (caller ensures +/// `xi.len() == xj.len()` and `d_x >= 10` at the dispatch site). +#[doc(hidden)] +#[target_feature(enable = "avx2,fma")] +pub unsafe fn dist_sq_avx2_looped(xi: &[f64], xj: &[f64]) -> f64 { + debug_assert_eq!( + xi.len(), + xj.len(), + "dist_sq_avx2_looped: slices must have equal length" + ); + use std::arch::x86_64::*; + let n = xi.len().min(xj.len()); + unsafe { + let mut acc = _mm256_setzero_pd(); + let mut k = 0usize; + while k + 4 <= n { + let a = _mm256_loadu_pd(xi.as_ptr().add(k)); + let b = _mm256_loadu_pd(xj.as_ptr().add(k)); + let d = _mm256_sub_pd(a, b); + acc = _mm256_fmadd_pd(d, d, acc); + k += 4; + } + // Horizontal reduce: sum 4 lanes + let lo = _mm256_castpd256_pd128(acc); + let hi = _mm256_extractf128_pd(acc, 1); + let sum128 = _mm_add_pd(lo, hi); + let halved = _mm_hadd_pd(sum128, sum128); + let mut result = _mm_cvtsd_f64(halved); + // Scalar tail (0–3 remaining elements) + while k < n { + let d = xi[k] - xj[k]; + result += d * d; + k += 1; + } + result + } +} + +/// Batch squared Euclidean distances from a 2D query point to `n` target points +/// stored in row-major layout (`y_flat`, stride 2). Processes two target points per +/// SIMD iteration using `_mm256_hadd_pd` for horizontal reduction. +/// +/// # Safety +/// - `yi` must have exactly 2 elements. +/// - `y_flat` must have at least `n * 2` elements (row-major, d_y = 2). +/// - `out` must have at least `n` elements. +/// +/// Called only when `d_y == 2`, `y.is_standard_layout()`, and `avx2` is detected at runtime. +#[target_feature(enable = "avx2")] +pub(crate) unsafe fn dist_sq_2d_avx2_batch(yi: &[f64], y_flat: &[f64], n: usize, out: &mut [f64]) { + use std::arch::x86_64::*; + debug_assert!(yi.len() >= 2, "yi must have at least 2 elements"); + debug_assert!( + y_flat.len() >= n * 2, + "y_flat must have at least n*2 elements" + ); + debug_assert!(out.len() >= n, "out must have at least n elements"); + unsafe { + // Broadcast query: [yi[1], yi[0], yi[1], yi[0]] — _mm256_set_pd args are (e3,e2,e1,e0) + let yi_bc = _mm256_set_pd(yi[1], yi[0], yi[1], yi[0]); + let mut j = 0usize; + while j + 1 < n { + // Load two target points: [yj[0], yj[1], yj+1[0], yj+1[1]] + debug_assert!(j * 2 + 3 < y_flat.len(), "y_flat bounds exceeded at j={j}"); + let yj_pair = _mm256_loadu_pd(y_flat.as_ptr().add(j * 2)); + let diff = _mm256_sub_pd(yi_bc, yj_pair); + let sq = _mm256_mul_pd(diff, diff); + // hadd: lower 128-bit → sq[0]+sq[1] = dist_j; upper 128-bit → sq[2]+sq[3] = dist_{j+1} + let hadd = _mm256_hadd_pd(sq, sq); + out[j] = _mm_cvtsd_f64(_mm256_castpd256_pd128(hadd)); + out[j + 1] = _mm_cvtsd_f64(_mm256_extractf128_pd(hadd, 1)); + j += 2; + } + // Scalar tail for odd n + if j < n { + let base = j * 2; + let d0 = yi[0] - y_flat[base]; + let d1 = yi[1] - y_flat[base + 1]; + out[j] = d0 * d0 + d1 * d1; + } + } +} + +#[cfg(test)] +mod tests { + #[test] + fn t_tw_06_avx2_looped_kernel_matches_scalar() { + if !(is_x86_feature_detected!("avx2") && is_x86_feature_detected!("fma")) { + return; // skip on CPUs without AVX2+FMA + } + use rand::{Rng, SeedableRng}; + let mut rng = rand::rngs::SmallRng::seed_from_u64(42); + for len in [10, 13, 16, 50, 100] { + let a: Vec = (0..len).map(|_| rng.random::()).collect(); + let b: Vec = (0..len).map(|_| rng.random::()).collect(); + let scalar: f64 = a + .iter() + .zip(b.iter()) + .map(|(&x, &y)| (x - y) * (x - y)) + .sum(); + // SAFETY: runtime check above guarantees AVX2+FMA; both slices have `len` elements. + let avx2 = unsafe { super::dist_sq_avx2_looped(&a, &b) }; + assert!( + (avx2 - scalar).abs() < 1e-10, + "dist_sq_avx2_looped mismatch at len={len}: avx2={avx2}, scalar={scalar}" + ); + } + } + + #[test] + fn t_tw_09_avx2_2d_kernel_matches_scalar() { + if !is_x86_feature_detected!("avx2") { + return; // skip on CPUs without AVX2 + } + use rand::{Rng, SeedableRng}; + let mut rng = rand::rngs::SmallRng::seed_from_u64(55); + for n in [0usize, 1, 2, 3, 10, 20, 51] { + let y_flat: Vec = (0..n * 2).map(|_| rng.random::()).collect(); + let yi: Vec = (0..2).map(|_| rng.random::()).collect(); + let mut out_avx2 = vec![0.0f64; n]; + // SAFETY: runtime check above guarantees AVX2; y_flat has n*2, yi has 2, out has n. + unsafe { + super::dist_sq_2d_avx2_batch(&yi, &y_flat, n, &mut out_avx2); + } + for j in 0..n { + let scalar: f64 = yi + .iter() + .zip(y_flat[j * 2..j * 2 + 2].iter()) + .map(|(&a, &b)| (a - b) * (a - b)) + .sum(); + assert!( + (out_avx2[j] - scalar).abs() < 1e-10, + "dist_sq_2d_avx2_batch mismatch at n={n}, j={j}: avx2={}, scalar={scalar}", + out_avx2[j] + ); + } + } + } +} diff --git a/trustworthiness/src/lib.rs b/trustworthiness/src/lib.rs new file mode 100644 index 0000000..6e77a9c --- /dev/null +++ b/trustworthiness/src/lib.rs @@ -0,0 +1,789 @@ +//! Trustworthiness of a low-dimensional embedding. +//! +//! [`trustworthiness`] measures how well the k-nearest-neighbour structure of the +//! original data `X` is preserved in an embedding `Y`. [`trustworthiness_subsampled`] +//! evaluates the same score on a random subset of query rows. +//! +//! # Feature flags +//! +//! | Flag | Purpose | +//! |------|---------| +//! | `cli` | Builds the `trustworthiness` and `tw_profiler` binaries, which read `.npy` files. | +//! | `profiling` | Prints per-step `[timing:] ` lines to stderr. | + +use ndarray::ArrayView2; +use rayon::prelude::*; +use std::collections::HashSet; + +#[cfg(target_arch = "x86_64")] +mod kernels; + +#[cfg(target_arch = "x86_64")] +use kernels::dist_sq_2d_avx2_batch; +#[cfg(target_arch = "x86_64")] +#[doc(hidden)] +pub use kernels::dist_sq_avx2_looped; + +/// Shared inner kernel for [`trustworthiness`] and [`trustworthiness_subsampled`]. +/// +/// `query_indices` selects which rows participate as outer "query" points; values +/// must lie in `[0, n)` and should be unique (duplicates would double-count their +/// penalty contribution). The per-row computation always runs against the full +/// `n`-point population. Only the leading factor of the normalization denominator +/// uses `m = query_indices.len()` — the `(2n − 3k − 1)` factor still uses the +/// full population `n`. +pub(crate) fn trustworthiness_inner( + x: ArrayView2, + y: ArrayView2, + k: usize, + query_indices: Option<&[usize]>, +) -> f64 { + use std::cell::RefCell; + let n = x.nrows(); + assert_eq!( + y.nrows(), + n, + "trustworthiness: x and y must have the same number of rows" + ); + assert!(k > 0, "trustworthiness: k must be > 0"); + assert!( + k < n / 2, + "trustworthiness: k must be < n/2 (got k={k}, n={n}, n/2={}); \ + this constraint is required by the normalization denominator and matches sklearn's ValueError", + n / 2 + ); + let m_query = query_indices.map_or(n, |q| q.len()); + + #[cfg(feature = "profiling")] + { + use std::sync::atomic::Ordering; + X_DIST_NS.store(0, Ordering::Relaxed); + X_SORT_NS.store(0, Ordering::Relaxed); + Y_DIST_NS.store(0, Ordering::Relaxed); + PENALTY_NS.store(0, Ordering::Relaxed); + } + + #[cfg(target_arch = "x86_64")] + let use_avx2 = is_x86_feature_detected!("avx2") && is_x86_feature_detected!("fma"); + #[cfg(target_arch = "x86_64")] + let d_x = x.ncols(); + + #[cfg(target_arch = "x86_64")] + let use_avx2_y = + { y.ncols() == 2 && y.is_standard_layout() && is_x86_feature_detected!("avx2") }; + + // Validate contiguity once before the parallel loop: SIMD dispatch requires C-contiguous rows. + #[cfg(target_arch = "x86_64")] + if use_avx2 && d_x >= 10 { + assert!( + x.is_standard_layout(), + "trustworthiness: x must be in C-contiguous (standard) layout for SIMD dispatch" + ); + } + + thread_local! { + static COMB_DIST_X: RefCell> = const { RefCell::new(Vec::new()) }; + static COMB_INDICES: RefCell> = const { RefCell::new(Vec::new()) }; + } + + thread_local! { + static COMB_DIST_Y: RefCell> = const { RefCell::new(Vec::new()) }; + static COMB_INDICES_Y: RefCell> = const { RefCell::new(Vec::new()) }; + } + + #[cfg(feature = "profiling")] + static X_DIST_NS: std::sync::atomic::AtomicU64 = std::sync::atomic::AtomicU64::new(0); + #[cfg(feature = "profiling")] + static X_SORT_NS: std::sync::atomic::AtomicU64 = std::sync::atomic::AtomicU64::new(0); + #[cfg(feature = "profiling")] + static Y_DIST_NS: std::sync::atomic::AtomicU64 = std::sync::atomic::AtomicU64::new(0); + #[cfg(feature = "profiling")] + static PENALTY_NS: std::sync::atomic::AtomicU64 = std::sync::atomic::AtomicU64::new(0); + + let process_row = |i: usize| -> f64 { + let xi = x.row(i); + let yi = y.row(i); + + COMB_DIST_X.with(|dist_x_cell| { + COMB_INDICES.with(|indices_cell| { + let mut dist_x = dist_x_cell.borrow_mut(); + let mut indices = indices_cell.borrow_mut(); + + // ── x_dist step ────────────────────────────────────────────── + #[cfg(feature = "profiling")] + let t_x_dist = std::time::Instant::now(); + + dist_x.clear(); + dist_x.resize(n, 0.0f64); + for j in 0..n { + let xj = x.row(j); + dist_x[j] = { + #[cfg(target_arch = "x86_64")] + { + if use_avx2 && d_x >= 10 { + let si = xi.as_slice().expect("x row must be contiguous"); + let sj = xj.as_slice().expect("x row must be contiguous"); + // SAFETY: runtime + d_x check guarantees AVX2+FMA and >= 10 elements. + unsafe { dist_sq_avx2_looped(si, sj) } + } else { + xi.iter() + .zip(xj.iter()) + .map(|(&a, &b)| (a - b) * (a - b)) + .sum() + } + } + #[cfg(not(target_arch = "x86_64"))] + { + xi.iter() + .zip(xj.iter()) + .map(|(&a, &b)| (a - b) * (a - b)) + .sum() + } + }; + } + + #[cfg(feature = "profiling")] + X_DIST_NS.fetch_add( + t_x_dist.elapsed().as_nanos() as u64, + std::sync::atomic::Ordering::Relaxed, + ); + + // ── x_sort step ────────────────────────────────────────────── + #[cfg(feature = "profiling")] + let t_x_sort = std::time::Instant::now(); + + indices.clear(); + indices.extend(0..n); + indices.select_nth_unstable_by(k, |&a, &b| { + dist_x[a].total_cmp(&dist_x[b]).then(a.cmp(&b)) + }); + + let knn_x_set: HashSet = + indices[..=k].iter().filter(|&&m| m != i).copied().collect(); + + #[cfg(feature = "profiling")] + X_SORT_NS.fetch_add( + t_x_sort.elapsed().as_nanos() as u64, + std::sync::atomic::Ordering::Relaxed, + ); + + // ── y_dist step (flat_simd, replaces BinaryHeap) ───────────── + #[cfg(feature = "profiling")] + let t_y_dist = std::time::Instant::now(); + + COMB_DIST_Y.with(|dy_cell| { + COMB_INDICES_Y.with(|iy_cell| { + let mut dist_y = dy_cell.borrow_mut(); + let mut indices_y = iy_cell.borrow_mut(); + + dist_y.clear(); + dist_y.resize(n, 0.0f64); + + // Fill Y distances: AVX2 2D batch or scalar fallback. + #[cfg(target_arch = "x86_64")] + if use_avx2_y { + let y_flat = y + .as_slice() + .expect("y must be standard layout for AVX2 dispatch"); + let yi_slice = &y_flat[i * 2..(i + 1) * 2]; + // SAFETY: y_flat has n*d_y elements; yi_slice has 2 elements; + // dist_y has n elements; use_avx2_y guarantees d_y==2, + // standard_layout, and runtime AVX2. + unsafe { + dist_sq_2d_avx2_batch(yi_slice, y_flat, n, &mut dist_y); + } + } else { + for j in 0..n { + let yj = y.row(j); + dist_y[j] = yi + .iter() + .zip(yj.iter()) + .map(|(&a, &b)| (a - b) * (a - b)) + .sum(); + } + } + #[cfg(not(target_arch = "x86_64"))] + { + for j in 0..n { + let yj = y.row(j); + dist_y[j] = yi + .iter() + .zip(yj.iter()) + .map(|(&a, &b)| (a - b) * (a - b)) + .sum(); + } + } + + dist_y[i] = f64::INFINITY; // self-exclusion + + indices_y.clear(); + indices_y.extend(0..n); + indices_y.select_nth_unstable_by(k, |&a, &b| { + dist_y[a].total_cmp(&dist_y[b]).then(a.cmp(&b)) + }); + + #[cfg(feature = "profiling")] + Y_DIST_NS.fetch_add( + t_y_dist.elapsed().as_nanos() as u64, + std::sync::atomic::Ordering::Relaxed, + ); + + // ── penalty step ────────────────────────────────────── + #[cfg(feature = "profiling")] + let t_penalty = std::time::Instant::now(); + + let mut row_penalty = 0u64; + for &j in &indices_y[..k] { + if !knn_x_set.contains(&j) { + let dj = dist_x[j]; + let rank: usize = (0..n) + .filter(|&m| dist_x[m] < dj || (dist_x[m] == dj && m < j)) + .count(); + row_penalty += (rank - k) as u64; + } + } + + #[cfg(feature = "profiling")] + PENALTY_NS.fetch_add( + t_penalty.elapsed().as_nanos() as u64, + std::sync::atomic::Ordering::Relaxed, + ); + + row_penalty as f64 + }) + }) + }) + }) + }; + + let penalty_sum: f64 = match query_indices { + None => (0..n).into_par_iter().map(&process_row).sum(), + Some(qi) => qi.par_iter().copied().map(&process_row).sum(), + }; + + #[cfg(feature = "profiling")] + { + use std::sync::atomic::Ordering; + eprintln!("[timing:x_dist] {}", X_DIST_NS.load(Ordering::Relaxed)); + eprintln!("[timing:x_sort] {}", X_SORT_NS.load(Ordering::Relaxed)); + eprintln!("[timing:y_dist] {}", Y_DIST_NS.load(Ordering::Relaxed)); + eprintln!("[timing:penalty] {}", PENALTY_NS.load(Ordering::Relaxed)); + } + + let denom = m_query as f64 * k as f64 * (2 * n).saturating_sub(3 * k + 1) as f64; + 1.0 - penalty_sum * 2.0 / denom +} + +/// Computes the trustworthiness metric T(k) — a measure of how well the k-nearest-neighbor +/// structure of X (high-dimensional) is preserved in Y (embedding). +/// +/// Uses partial rank (introselect) for O(n)-average X-NN detection, thread-local +/// scratch buffers to eliminate per-row allocations, and AVX2+FMA SIMD dispatch +/// for X-distance computation when dimensionality >= 10. +/// +/// # Formula +/// `T(k) = 1 − (2 / (n·k·(2n−3k−1))) · Σᵢ Σ_{j ∈ U_i(k)} (r(i,j) − k)` +/// +/// where `r(i,j)` is the 0-indexed rank of j in the distance ordering from i in X +/// (self = rank 0), and `U_i(k)` is the set of j in k-NN(i, Y) but NOT in k-NN(i, X). +/// +/// # Panics +/// Panics if `k == 0`, `k >= n / 2`, or if `x` and `y` have different row counts. +/// The `k < n/2` restriction is required by the normalization denominator +/// `G_k = n·k·(2n−3k−1)`: when `k ≥ n/2` this denominator produces T > 1. +/// The guard uses integer floor division (`n / 2`), matching sklearn's exact boundary +/// condition (`n_neighbors >= n // 2` raises `ValueError` in sklearn). +pub fn trustworthiness(x: ArrayView2, y: ArrayView2, k: usize) -> f64 { + trustworthiness_inner(x, y, k, None) +} + +/// Sub-sampled trustworthiness: evaluates only `m` randomly chosen query rows +/// against the full `n`-point population. +/// +/// Identical to [`trustworthiness`] except that the outer iteration is restricted +/// to `m` query rows sampled uniformly without replacement using `seed`. The +/// per-row computation (full pairwise X-distances, full Y k-NN, rank penalty +/// scan) still runs against all `n` points — only the outer iterator and the +/// leading denominator factor change. +/// +/// # Formula +/// `T(k, m) = 1 − (2 / (m·k·(2n−3k−1))) · Σ_{i ∈ Q} Σ_{j ∈ U_i(k)} (r(i,j) − k)` +/// +/// where `Q ⊂ [0, n)` is the set of `m` sampled query rows. The +/// `(2n − 3k − 1)` factor uses the full population `n`, so when `m == n` the +/// result is identical to `trustworthiness(x, y, k)`. +/// +/// # Determinism +/// The sample is reproducible: equal `seed` values produce equal row sets. +/// When `m == n`, the function bypasses sampling entirely and uses the full +/// `0..n` range, guaranteeing parity with `trustworthiness`. +/// +/// # Panics +/// Panics if `k == 0`, `k >= n / 2`, `m == 0`, `m > n`, or if `x` and `y` have +/// different row counts. +pub fn trustworthiness_subsampled( + x: ArrayView2, + y: ArrayView2, + k: usize, + m: usize, + seed: u64, +) -> f64 { + let n = x.nrows(); + assert!(m > 0, "trustworthiness_subsampled: m must be > 0"); + assert!( + m <= n, + "trustworthiness_subsampled: m must be <= n (got m={m}, n={n})" + ); + + if m == n { + return trustworthiness_inner(x, y, k, None); + } + + use rand::SeedableRng; + let mut rng = rand::rngs::SmallRng::seed_from_u64(seed); + let query_indices = rand::seq::index::sample(&mut rng, n, m).into_vec(); + trustworthiness_inner(x, y, k, Some(&query_indices)) +} + +#[cfg(test)] +mod tests { + use super::*; + + #[test] + fn t_tw_01_perfect_preservation() { + // 20-point grid; each point embedded to its own location + let x = ndarray::Array2::from_shape_fn((20, 4), |(i, d)| (i * 4 + d) as f64); + let y = x.slice(ndarray::s![.., ..2]).to_owned(); + let t = trustworthiness(x.view(), y.view(), 5); + assert!((t - 1.0).abs() < 1e-10, "perfect preservation: T={t}"); + } + + #[test] + fn t_tw_02_result_in_unit_interval() { + use rand::{Rng, SeedableRng}; + let mut rng = rand::rngs::SmallRng::seed_from_u64(99); + let x = ndarray::Array2::from_shape_fn((20, 10), |_| rng.random::()); + let y = ndarray::Array2::from_shape_fn((20, 2), |_| rng.random::()); + let t = trustworthiness(x.view(), y.view(), 5); + assert!((0.0..=1.0).contains(&t), "T out of [0,1]: {t}"); + } + + /// Hand-verifiable 4-point, k=1 example with exactly one violation of rank penalty 1. + /// + /// n=4, k=1: denominator = 4·1·(8−3−1) = 16. + /// + /// X = [[0,0],[1,0],[0,1.5],[0,100]]: + /// KNN(0,X,1)={1} (rank_x[2]=2), KNN(1,X,1)={0}, KNN(2,X,1)={0}, KNN(3,X,1)={2} + /// + /// Y = [[0,0],[1,0],[0,0.5],[0,100]] (point 2 moved closer to 0): + /// KNN(0,Y,1)={2} → violation: rank_x[2]=2, penalty = 2−1 = 1 + /// KNN(1,Y,1)={0} → 0 ∈ KNN(1,X,1): no penalty + /// KNN(2,Y,1)={0} → 0 ∈ KNN(2,X,1): no penalty + /// KNN(3,Y,1)={2} → 2 ∈ KNN(3,X,1): no penalty + /// + /// T = 1 − 2·1/16 = 7/8 = 0.875 + #[test] + fn t_tw_03_formula_hand_check() { + let x = ndarray::Array2::from_shape_vec( + (4, 2), + vec![0.0f64, 0.0, 1.0, 0.0, 0.0, 1.5, 0.0, 100.0], + ) + .unwrap(); + let y = ndarray::Array2::from_shape_vec( + (4, 2), + vec![0.0f64, 0.0, 1.0, 0.0, 0.0, 0.5, 0.0, 100.0], + ) + .unwrap(); + let t = trustworthiness(x.view(), y.view(), 1); + let expected = 7.0 / 8.0; + assert!( + (t - expected).abs() < 1e-10, + "hand-check: T={t:.10}, expected {expected:.10} (7/8)" + ); + } + + #[test] + fn t_tw_04_k_less_than_half_n() { + use rand::{Rng, SeedableRng}; + let mut rng = rand::rngs::SmallRng::seed_from_u64(7); + let n = 20usize; + let k = n / 2 - 1; // 9, just below the boundary + let x = ndarray::Array2::from_shape_fn((n, 4), |_| rng.random::()); + let y = ndarray::Array2::from_shape_fn((n, 2), |_| rng.random::()); + let t = trustworthiness(x.view(), y.view(), k); + assert!(t.is_finite(), "T should be finite at k=n/2-1: {t}"); + assert!((0.0..=1.0).contains(&t), "T out of [0,1] at k=n/2-1: {t}"); + } + + #[test] + #[should_panic(expected = "k must be < n/2")] + fn t_tw_05_panics_on_k_gte_half_n() { + let n = 20usize; + let k = n / 2; // exactly n/2 — must panic + let x = ndarray::Array2::zeros((n, 4)); + let y = ndarray::Array2::zeros((n, 2)); + let _ = trustworthiness(x.view(), y.view(), k); + } + + #[test] + fn t_tw_07_partial_rank_matches_full_sort() { + use rand::{Rng, SeedableRng}; + use std::collections::HashSet; + let mut rng = rand::rngs::SmallRng::seed_from_u64(77); + let n = 30; + let k = 5; + let x = ndarray::Array2::from_shape_fn((n, 4), |_| rng.random::()); + + for i in 0..n { + let xi = x.row(i); + let dist_x: Vec = (0..n) + .map(|j| { + xi.iter() + .zip(x.row(j).iter()) + .map(|(&a, &b)| (a - b) * (a - b)) + .sum() + }) + .collect(); + + // Full-sort baseline: knn_x_set via sort + rank scatter + let mut sorted: Vec<(f64, usize)> = dist_x.iter().copied().zip(0..n).collect(); + sorted.sort_unstable_by(|a, b| a.0.total_cmp(&b.0).then(a.1.cmp(&b.1))); + let knn_baseline: HashSet = sorted[1..=k].iter().map(|&(_, j)| j).collect(); + + // Partial-rank approach: select_nth_unstable_by + let mut indices: Vec = (0..n).collect(); + indices.select_nth_unstable_by(k, |&a, &b| { + dist_x[a].total_cmp(&dist_x[b]).then(a.cmp(&b)) + }); + let knn_partial: HashSet = + indices[..=k].iter().filter(|&&m| m != i).copied().collect(); + + assert_eq!(knn_baseline, knn_partial, "knn_x_set mismatch at row {i}"); + + // Verify rank values for all non-knn points + let mut rank_x = vec![0usize; n]; + for (rank, &(_, j)) in sorted.iter().enumerate() { + rank_x[j] = rank; + } + for j in 0..n { + if j == i || knn_baseline.contains(&j) { + continue; + } + let dj = dist_x[j]; + let scan_rank: usize = (0..n) + .filter(|&m| dist_x[m] < dj || (dist_x[m] == dj && m < j)) + .count(); + assert_eq!( + rank_x[j], scan_rank, + "rank mismatch for point {j} from row {i}: sort={}, scan={scan_rank}", + rank_x[j] + ); + } + } + } + + /// Brute-force O(n²) reference: full-sort X distances, sort-based Y-kNN. + fn trustworthiness_brute_force( + x: ndarray::ArrayView2, + y: ndarray::ArrayView2, + k: usize, + ) -> f64 { + use std::collections::HashSet; + let n = x.nrows(); + let penalty_sum: f64 = (0..n) + .map(|i| { + let xi = x.row(i); + let yi = y.row(i); + + let mut dist_x: Vec<(f64, usize)> = (0..n) + .map(|j| { + let d: f64 = xi + .iter() + .zip(x.row(j).iter()) + .map(|(&a, &b)| (a - b) * (a - b)) + .sum(); + (d, j) + }) + .collect(); + dist_x.sort_unstable_by(|a, b| a.0.total_cmp(&b.0).then(a.1.cmp(&b.1))); + let knn_x: HashSet = dist_x[1..=k].iter().map(|&(_, j)| j).collect(); + let mut rank_x = vec![0usize; n]; + for (rank, &(_, j)) in dist_x.iter().enumerate() { + rank_x[j] = rank; + } + + let mut dist_y: Vec<(f64, usize)> = (0..n) + .filter(|&j| j != i) + .map(|j| { + let d: f64 = yi + .iter() + .zip(y.row(j).iter()) + .map(|(&a, &b)| (a - b) * (a - b)) + .sum(); + (d, j) + }) + .collect(); + dist_y.sort_unstable_by(|a, b| a.0.total_cmp(&b.0).then(a.1.cmp(&b.1))); + let knn_y: HashSet = dist_y[..k].iter().map(|&(_, j)| j).collect(); + + let mut row_penalty = 0u64; + for j in &knn_y { + if !knn_x.contains(j) { + row_penalty += (rank_x[*j] - k) as u64; + } + } + row_penalty as f64 + }) + .sum(); + let denom = n as f64 * k as f64 * (2 * n).saturating_sub(3 * k + 1) as f64; + 1.0 - penalty_sum * 2.0 / denom + } + + #[test] + fn t_tw_08_combined_matches_baseline() { + use rand::{Rng, SeedableRng}; + let mut rng = rand::rngs::SmallRng::seed_from_u64(123); + let n = 50; + let x = ndarray::Array2::from_shape_fn((n, 6), |_| rng.random::()); + let y = ndarray::Array2::from_shape_fn((n, 2), |_| rng.random::()); + + for k in [3, 7] { + let t = trustworthiness(x.view(), y.view(), k); + let t_ref = trustworthiness_brute_force(x.view(), y.view(), k); + assert!(t.is_finite(), "T(k={k}) must be finite, got {t}"); + assert!((0.0..=1.0).contains(&t), "T(k={k}) out of [0,1]: {t}"); + assert!( + (t - t_ref).abs() < 1e-12, + "T(k={k}) combined={t} diverges from brute-force reference={t_ref}" + ); + } + } + + #[test] + fn t_tw_10_self_exclusion_never_in_knn() { + // Verify that the self-exclusion (dist_y[i] = INFINITY) prevents point i + // from appearing in its own k-NN result. Catching a regression where the + // INFINITY assignment is accidentally dropped. + use rand::{Rng, SeedableRng}; + let mut rng = rand::rngs::SmallRng::seed_from_u64(77); + let n = 20; + let k = 3; + let x = ndarray::Array2::from_shape_fn((n, 4), |_| rng.random::()); + let y = ndarray::Array2::from_shape_fn((n, 2), |_| rng.random::()); + // Run trustworthiness — internally computes k-NN of Y for each row. + // We verify correctness by comparing against brute-force which also applies self-exclusion. + let t = trustworthiness(x.view(), y.view(), k); + let t_ref = trustworthiness_brute_force(x.view(), y.view(), k); + assert!( + (t - t_ref).abs() < 1e-12, + "self-exclusion regression: combined={t} diverges from brute-force={t_ref}" + ); + // Additionally, verify directly via brute-force that no point is its own neighbor. + for i in 0..n { + let yi = y.row(i); + let mut dists: Vec<(f64, usize)> = (0..n) + .filter(|&j| j != i) + .map(|j| { + let d: f64 = yi + .iter() + .zip(y.row(j).iter()) + .map(|(&a, &b)| (a - b) * (a - b)) + .sum(); + (d, j) + }) + .collect(); + dists.sort_by(|a, b| a.0.total_cmp(&b.0)); + let knn: Vec = dists[..k].iter().map(|&(_, j)| j).collect(); + assert!(!knn.contains(&i), "point {i} appeared in its own k-NN"); + } + } + + fn trustworthiness_brute_force_subsampled( + x: ndarray::ArrayView2, + y: ndarray::ArrayView2, + k: usize, + query_indices: &[usize], + ) -> f64 { + use std::collections::HashSet; + let n = x.nrows(); + let m = query_indices.len(); + let penalty_sum: f64 = query_indices + .iter() + .map(|&i| { + let xi = x.row(i); + let yi = y.row(i); + let mut dist_x: Vec<(f64, usize)> = (0..n) + .map(|j| { + let d: f64 = xi + .iter() + .zip(x.row(j).iter()) + .map(|(&a, &b)| (a - b) * (a - b)) + .sum(); + (d, j) + }) + .collect(); + dist_x.sort_unstable_by(|a, b| a.0.total_cmp(&b.0).then(a.1.cmp(&b.1))); + let knn_x: HashSet = dist_x[1..=k].iter().map(|&(_, j)| j).collect(); + let mut rank_x = vec![0usize; n]; + for (rank, &(_, j)) in dist_x.iter().enumerate() { + rank_x[j] = rank; + } + let mut dist_y: Vec<(f64, usize)> = (0..n) + .filter(|&j| j != i) + .map(|j| { + let d: f64 = yi + .iter() + .zip(y.row(j).iter()) + .map(|(&a, &b)| (a - b) * (a - b)) + .sum(); + (d, j) + }) + .collect(); + dist_y.sort_unstable_by(|a, b| a.0.total_cmp(&b.0).then(a.1.cmp(&b.1))); + let knn_y: HashSet = dist_y[..k].iter().map(|&(_, j)| j).collect(); + let mut row_penalty = 0u64; + for j in &knn_y { + if !knn_x.contains(j) { + row_penalty += (rank_x[*j] - k) as u64; + } + } + row_penalty as f64 + }) + .sum(); + let denom = m as f64 * k as f64 * (2 * n).saturating_sub(3 * k + 1) as f64; + 1.0 - penalty_sum * 2.0 / denom + } + + #[test] + fn t_tws_01_m_equals_n_matches_full_trustworthiness() { + use rand::{Rng, SeedableRng}; + let mut rng = rand::rngs::SmallRng::seed_from_u64(2026); + let n = 60; + let k = 5; + let x = ndarray::Array2::from_shape_fn((n, 8), |_| rng.random::()); + let y = ndarray::Array2::from_shape_fn((n, 2), |_| rng.random::()); + let t_full = trustworthiness(x.view(), y.view(), k); + let t_sub = trustworthiness_subsampled(x.view(), y.view(), k, n, 0); + assert!( + (t_full - t_sub).abs() < 1e-10, + "m==n parity: full={t_full}, subsampled={t_sub}" + ); + } + + #[test] + fn t_tws_02_m_less_than_n_in_unit_interval() { + use rand::{Rng, SeedableRng}; + let mut rng = rand::rngs::SmallRng::seed_from_u64(33); + let n = 200; + let k = 5; + let x = ndarray::Array2::from_shape_fn((n, 10), |_| rng.random::()); + let y = ndarray::Array2::from_shape_fn((n, 2), |_| rng.random::()); + + // Hard-coded query indices cross-checked against brute force: guards + // against constant-output regressions and is independent of the + // production sampling implementation. + let query_indices: Vec = vec![3, 17, 29, 42, 58, 71, 89, 104, 127, 145, 161, 188]; + let t = trustworthiness_inner(x.view(), y.view(), k, Some(&query_indices)); + let t_ref = trustworthiness_brute_force_subsampled(x.view(), y.view(), k, &query_indices); + assert!( + (t - t_ref).abs() < 1e-12, + "subsampled kernel vs brute force mismatch: inner={t}, brute={t_ref}" + ); + assert!(t.is_finite(), "T must be finite, got {t}"); + assert!(t > 0.0 && t <= 1.0, "T out of (0,1]: {t}"); + } + + #[test] + fn t_tws_03_same_seed_is_deterministic() { + use rand::{Rng, SeedableRng}; + let mut rng = rand::rngs::SmallRng::seed_from_u64(11); + let n = 100; + let k = 4; + let m = 30; + let x = ndarray::Array2::from_shape_fn((n, 6), |_| rng.random::()); + let y = ndarray::Array2::from_shape_fn((n, 2), |_| rng.random::()); + let a = trustworthiness_subsampled(x.view(), y.view(), k, m, 12345); + let b = trustworthiness_subsampled(x.view(), y.view(), k, m, 12345); + assert_eq!(a, b, "same seed must produce identical result"); + } + + #[test] + fn t_tws_04_different_seeds_produce_different_results() { + use rand::{Rng, SeedableRng}; + let mut rng = rand::rngs::SmallRng::seed_from_u64(99); + let n = 100; + let k = 4; + let m = 20; + let x = ndarray::Array2::from_shape_fn((n, 6), |_| rng.random::()); + let y = ndarray::Array2::from_shape_fn((n, 2), |_| rng.random::()); + + // First verify the sampling layer is seed-dependent, independent of + // the metric computation. + let mut rng_a = rand::rngs::SmallRng::seed_from_u64(1); + let indices_a = rand::seq::index::sample(&mut rng_a, n, m).into_vec(); + let mut rng_b = rand::rngs::SmallRng::seed_from_u64(2); + let indices_b = rand::seq::index::sample(&mut rng_b, n, m).into_vec(); + assert_ne!( + indices_a, indices_b, + "different seeds must produce different sampled index sets" + ); + + // Then verify that the metric values computed on different samples differ. + let a = trustworthiness_subsampled(x.view(), y.view(), k, m, 1); + let b = trustworthiness_subsampled(x.view(), y.view(), k, m, 2); + assert_ne!(a, b, "different seeds must produce different metric values"); + } + + #[test] + #[should_panic(expected = "m must be <= n")] + fn t_tws_05_panics_when_m_exceeds_n() { + let n = 20usize; + let x = ndarray::Array2::zeros((n, 4)); + let y = ndarray::Array2::zeros((n, 2)); + let _ = trustworthiness_subsampled(x.view(), y.view(), 3, n + 1, 0); + } + + #[test] + #[should_panic(expected = "m must be > 0")] + fn t_tws_06_panics_when_m_zero() { + let n = 20usize; + let x = ndarray::Array2::zeros((n, 4)); + let y = ndarray::Array2::zeros((n, 2)); + let _ = trustworthiness_subsampled(x.view(), y.view(), 3, 0, 0); + } + + #[test] + fn t_tws_07_perfect_preservation_subsampled() { + let n = 40; + let x = ndarray::Array2::from_shape_fn((n, 4), |(i, d)| (i * 4 + d) as f64); + let y = x.slice(ndarray::s![.., ..2]).to_owned(); + let t = trustworthiness_subsampled(x.view(), y.view(), 5, 10, 0); + assert!( + (t - 1.0).abs() < 1e-12, + "perfect preservation: T={t}, expected 1.0" + ); + } + + #[test] + fn t_tws_08_brute_force_reference_matches() { + use rand::{Rng, SeedableRng}; + let mut rng = rand::rngs::SmallRng::seed_from_u64(7777); + let n = 80; + let k = 4; + let x = ndarray::Array2::from_shape_fn((n, 6), |_| rng.random::()); + let y = ndarray::Array2::from_shape_fn((n, 2), |_| rng.random::()); + + // Hard-coded query indices decouple this correctness test from the + // production sampling implementation (RNG choice, call order). + let query_indices: Vec = vec![ + 2, 7, 13, 19, 23, 28, 34, 41, 46, 52, 55, 58, 61, 64, 67, 70, 73, 75, 77, 79, + ]; + + let t_kernel = trustworthiness_inner(x.view(), y.view(), k, Some(&query_indices)); + let t_ref = trustworthiness_brute_force_subsampled(x.view(), y.view(), k, &query_indices); + assert!( + (t_kernel - t_ref).abs() < 1e-12, + "subsampled brute-force mismatch: kernel={t_kernel}, ref={t_ref}" + ); + } +} diff --git a/tests/integration/test_trustworthiness.rs b/trustworthiness/tests/test_trustworthiness.rs similarity index 83% rename from tests/integration/test_trustworthiness.rs rename to trustworthiness/tests/test_trustworthiness.rs index 879c513..b7dfdeb 100644 --- a/tests/integration/test_trustworthiness.rs +++ b/trustworthiness/tests/test_trustworthiness.rs @@ -1,14 +1,17 @@ -use spectral_init::trustworthiness; +use trustworthiness::trustworthiness; + +/// The fixtures live with the rest of the reference data, under the workspace root. +const WORKSPACE_ROOT: &str = concat!(env!("CARGO_MANIFEST_DIR"), "/.."); /// Sklearn parity: load fixture and assert |rust − sklearn| < 1e-6. -/// Requires: python tests/visual_eval/generate_tw_fixture.py +/// The fixture is written by `tests/visual_eval/generate_tw_fixture.py`. #[test] fn sklearn_parity_synthetic() { use ndarray_npy::NpzReader; use std::fs::File; - let fixture_path = std::path::Path::new(env!("CARGO_MANIFEST_DIR")) - .join("tests/fixtures/tw_parity/tw_parity.npz"); + let fixture_path = + std::path::Path::new(WORKSPACE_ROOT).join("tests/fixtures/tw_parity/tw_parity.npz"); let f = File::open(&fixture_path) .unwrap_or_else(|e| panic!("could not open fixture {}: {e}", fixture_path.display())); let mut npz = NpzReader::new(f).expect("failed to read .npz"); @@ -43,8 +46,8 @@ fn sklearn_parity_50d() { use ndarray_npy::NpzReader; use std::fs::File; - let fixture_path = std::path::Path::new(env!("CARGO_MANIFEST_DIR")) - .join("tests/fixtures/tw_parity/tw_parity_50d.npz"); + let fixture_path = + std::path::Path::new(WORKSPACE_ROOT).join("tests/fixtures/tw_parity/tw_parity_50d.npz"); let f = File::open(&fixture_path) .unwrap_or_else(|e| panic!("could not open fixture {}: {e}", fixture_path.display())); let mut npz = NpzReader::new(f).expect("failed to read .npz"); diff --git a/tests/integration/test_tw_profiler.rs b/trustworthiness/tests/test_tw_profiler.rs similarity index 100% rename from tests/integration/test_tw_profiler.rs rename to trustworthiness/tests/test_tw_profiler.rs From 71749f2175e568a5c2a07d9399093ea0d06d72e7 Mon Sep 17 00:00:00 2001 From: Trecek Date: Wed, 11 Nov 2026 16:22:22 -0800 Subject: [PATCH 003/113] Phase 2: freeze a sound public API Entry point and configuration - `spectral_init(graph: CsMatViewI, data: Option>, config: &SpectralInitConfig) -> Result, SpectralError>`. - `SpectralInitConfig` is opaque: `new(n_components)`, `with_seed`, `with_compute_mode`, `with_dense_memory_budget`, getters; no `Default`. - `sprs` and `ndarray` are re-exported. - The returned array is always in standard (row-major) layout. Errors and validation - `SpectralError` gets typed, `#[non_exhaustive]` struct variants and derives `Clone + PartialEq`; the string catch-all is gone. - `src/validate.rs` checks the caller's matrix before any numerics, in a fixed precedence: InvalidParameter, NotSquare, TooFewNodes, NonFiniteWeight, NegativeWeight, NotSymmetric, DegreeOverflow, DataShapeMismatch, NonFiniteData. CSR and CSC storage are accepted; stored zeros are absent edges. Numerics - Self-loops take part in degree and adjacency (`L_ii = 1 - w_ii / d_i`), as in umap-learn; every diagonal entry is stored. - The solver chain is fallible end to end. A dense memory budget guards Level 0, Level 4, Level 5 and the centroid affinity; Level 5 is gated on finiteness and residual and reports DenseBudgetExceeded or ConvergenceFailure instead of panicking. - Random numbers come from `rand_chacha::ChaCha12Rng` (bit-identical to the previous `StdRng` stream; pinned by a golden file). Tests - Validation and tolerance calibration, self-loop reference fixture with its generator, no-panic property tests for the entry point and the solver chain, escalation and budget, trait contracts, seed contract, output layout. Gates - Public API snapshot `.github/api-snapshot.txt` with `.github/scripts/check-api.sh`; the purity gate forbids `StdRng` in `src/`; the package allow-list gains `src/error.rs` and `src/validate.rs`. Co-Authored-By: Claude --- .github/ISSUE_TEMPLATE/bug_report.yml | 2 +- .github/api-snapshot.txt | 103 ++++ .github/package-allowlist.txt | 2 + .github/scripts/check-api.sh | 30 + .github/scripts/check-purity.sh | 4 + Cargo.lock | 1 + Cargo.toml | 1 + eval/benches/spectral_bench.rs | 22 +- eval/tests/export_merfish_init.rs | 48 +- eval/tests/export_rust_init.rs | 6 +- eval/tests/test_exp_rsvd_nbiter_sweep.rs | 9 +- eval/tests/test_exp_rsvd_sweep.rs | 6 +- eval/tests/test_metrics_assess.rs | 4 +- examples/basic.rs | 13 +- examples/compute_modes.rs | 16 +- examples/from_adjacency_list.rs | 6 +- src/components.rs | 52 +- src/config.rs | 113 +++- src/error.rs | 156 ++++++ src/laplacian.rs | 144 ++++- src/lib.rs | 432 ++++++++------ src/multi_component.rs | 64 ++- src/scaling.rs | 135 +++-- src/selection.rs | 6 +- src/solvers/dense.rs | 70 ++- src/solvers/lobpcg.rs | 9 +- src/solvers/mod.rs | 194 +++++-- src/solvers/rsvd.rs | 131 +++-- src/solvers/sinv.rs | 11 +- src/validate.rs | 122 ++++ tests/README.md | 11 + tests/common/assertions.rs | 29 + tests/fixtures/selfloop/comp_a_degrees.npz | Bin 0 -> 708 bytes tests/fixtures/selfloop/comp_b_laplacian.npz | Bin 0 -> 1243 bytes .../fixtures/selfloop/comp_d_eigensolver.npz | Bin 0 -> 2144 bytes tests/fixtures/selfloop/full_spectral.npz | Bin 0 -> 464 bytes tests/fixtures/selfloop/graph.npz | Bin 0 -> 1133 bytes tests/generate_fixtures.py | 60 ++ tests/internals/accuracy_report.rs | 32 +- tests/internals/adversarial_graphs.rs | 117 +++- tests/internals/comp_a_degrees.rs | 2 +- tests/internals/comp_b_laplacian.rs | 2 +- tests/internals/comp_c_components.rs | 2 +- tests/internals/comp_d_dense_evd.rs | 2 +- tests/internals/comp_d_rsvd.rs | 3 +- tests/internals/e2e_residual.rs | 8 +- tests/internals/escalation.rs | 242 ++++++++ tests/internals/laplacian.rs | 174 ++++++ tests/internals/main.rs | 6 + tests/internals/no_panic.rs | 134 +++++ tests/internals/property_tests.rs | 8 +- tests/internals/solver_invariants.rs | 19 +- tests/public_api/determinism.rs | 64 +++ tests/public_api/e2e_validation.rs | 40 +- tests/public_api/golden/chacha12_seed42.txt | 64 +++ tests/public_api/layout.rs | 57 ++ tests/public_api/main.rs | 8 + tests/public_api/no_panic.rs | 171 ++++++ tests/public_api/pipeline.rs | 60 +- tests/public_api/traits.rs | 57 ++ tests/public_api/validation.rs | 529 ++++++++++++++++++ tests/test_generate_fixtures.py | 33 ++ tests/visual_eval/README.md | 2 +- 63 files changed, 3282 insertions(+), 566 deletions(-) create mode 100644 .github/api-snapshot.txt create mode 100755 .github/scripts/check-api.sh create mode 100644 src/error.rs create mode 100644 src/validate.rs create mode 100644 tests/common/assertions.rs create mode 100644 tests/fixtures/selfloop/comp_a_degrees.npz create mode 100644 tests/fixtures/selfloop/comp_b_laplacian.npz create mode 100644 tests/fixtures/selfloop/comp_d_eigensolver.npz create mode 100644 tests/fixtures/selfloop/full_spectral.npz create mode 100644 tests/fixtures/selfloop/graph.npz create mode 100644 tests/internals/escalation.rs create mode 100644 tests/internals/laplacian.rs create mode 100644 tests/internals/no_panic.rs create mode 100644 tests/public_api/determinism.rs create mode 100644 tests/public_api/golden/chacha12_seed42.txt create mode 100644 tests/public_api/layout.rs create mode 100644 tests/public_api/no_panic.rs create mode 100644 tests/public_api/traits.rs create mode 100644 tests/public_api/validation.rs diff --git a/.github/ISSUE_TEMPLATE/bug_report.yml b/.github/ISSUE_TEMPLATE/bug_report.yml index 4e95a70..1bfbce3 100644 --- a/.github/ISSUE_TEMPLATE/bug_report.yml +++ b/.github/ISSUE_TEMPLATE/bug_report.yml @@ -16,7 +16,7 @@ body: label: Steps to Reproduce placeholder: | 1. Build graph with N nodes, K neighbors - 2. Call spectral_init(graph, 2, config) + 2. Call spectral_init(graph.view(), None, &SpectralInitConfig::new(2)) 3. Observe ... validations: required: true diff --git a/.github/api-snapshot.txt b/.github/api-snapshot.txt new file mode 100644 index 0000000..4af2b35 --- /dev/null +++ b/.github/api-snapshot.txt @@ -0,0 +1,103 @@ +pub mod spectral_init +pub use spectral_init::ndarray +pub use spectral_init::sprs +#[non_exhaustive] pub enum spectral_init::ComputeMode +pub spectral_init::ComputeMode::PythonCompat +pub spectral_init::ComputeMode::RustNative +impl core::clone::Clone for spectral_init::ComputeMode +pub fn spectral_init::ComputeMode::clone(&self) -> spectral_init::ComputeMode +impl core::cmp::Eq for spectral_init::ComputeMode +impl core::cmp::PartialEq for spectral_init::ComputeMode +pub fn spectral_init::ComputeMode::eq(&self, &spectral_init::ComputeMode) -> bool +impl core::default::Default for spectral_init::ComputeMode +pub fn spectral_init::ComputeMode::default() -> spectral_init::ComputeMode +impl core::fmt::Debug for spectral_init::ComputeMode +pub fn spectral_init::ComputeMode::fmt(&self, &mut core::fmt::Formatter<'_>) -> core::fmt::Result +impl core::marker::Copy for spectral_init::ComputeMode +impl core::marker::StructuralPartialEq for spectral_init::ComputeMode +impl core::marker::Freeze for spectral_init::ComputeMode +impl core::marker::Send for spectral_init::ComputeMode +impl core::marker::Sync for spectral_init::ComputeMode +impl core::marker::Unpin for spectral_init::ComputeMode +impl core::marker::UnsafeUnpin for spectral_init::ComputeMode +impl core::panic::unwind_safe::RefUnwindSafe for spectral_init::ComputeMode +impl core::panic::unwind_safe::UnwindSafe for spectral_init::ComputeMode +#[non_exhaustive] pub enum spectral_init::SpectralError +#[non_exhaustive] pub spectral_init::SpectralError::ConvergenceFailure +pub spectral_init::SpectralError::ConvergenceFailure::n: usize +#[non_exhaustive] pub spectral_init::SpectralError::DataRequired +pub spectral_init::SpectralError::DataRequired::connected_components: usize +pub spectral_init::SpectralError::DataRequired::n_components: usize +#[non_exhaustive] pub spectral_init::SpectralError::DataShapeMismatch +pub spectral_init::SpectralError::DataShapeMismatch::actual_rows: usize +pub spectral_init::SpectralError::DataShapeMismatch::expected_rows: usize +pub spectral_init::SpectralError::DegenerateEmbedding +#[non_exhaustive] pub spectral_init::SpectralError::DegreeOverflow +pub spectral_init::SpectralError::DegreeOverflow::node: usize +#[non_exhaustive] pub spectral_init::SpectralError::DenseBudgetExceeded +pub spectral_init::SpectralError::DenseBudgetExceeded::budget_bytes: u64 +pub spectral_init::SpectralError::DenseBudgetExceeded::required_bytes: u64 +#[non_exhaustive] pub spectral_init::SpectralError::InvalidParameter +pub spectral_init::SpectralError::InvalidParameter::name: &'static str +pub spectral_init::SpectralError::InvalidParameter::reason: &'static str +#[non_exhaustive] pub spectral_init::SpectralError::NegativeWeight +pub spectral_init::SpectralError::NegativeWeight::col: usize +pub spectral_init::SpectralError::NegativeWeight::row: usize +#[non_exhaustive] pub spectral_init::SpectralError::NonFiniteData +pub spectral_init::SpectralError::NonFiniteData::col: usize +pub spectral_init::SpectralError::NonFiniteData::row: usize +#[non_exhaustive] pub spectral_init::SpectralError::NonFiniteWeight +pub spectral_init::SpectralError::NonFiniteWeight::col: usize +pub spectral_init::SpectralError::NonFiniteWeight::row: usize +#[non_exhaustive] pub spectral_init::SpectralError::NotSquare +pub spectral_init::SpectralError::NotSquare::cols: usize +pub spectral_init::SpectralError::NotSquare::rows: usize +#[non_exhaustive] pub spectral_init::SpectralError::NotSymmetric +pub spectral_init::SpectralError::NotSymmetric::col: usize +pub spectral_init::SpectralError::NotSymmetric::row: usize +#[non_exhaustive] pub spectral_init::SpectralError::TooFewNodes +pub spectral_init::SpectralError::TooFewNodes::n: usize +pub spectral_init::SpectralError::TooFewNodes::n_components: usize +impl core::clone::Clone for spectral_init::SpectralError +pub fn spectral_init::SpectralError::clone(&self) -> spectral_init::SpectralError +impl core::cmp::PartialEq for spectral_init::SpectralError +pub fn spectral_init::SpectralError::eq(&self, &spectral_init::SpectralError) -> bool +impl core::error::Error for spectral_init::SpectralError +impl core::fmt::Debug for spectral_init::SpectralError +pub fn spectral_init::SpectralError::fmt(&self, &mut core::fmt::Formatter<'_>) -> core::fmt::Result +impl core::fmt::Display for spectral_init::SpectralError +pub fn spectral_init::SpectralError::fmt(&self, &mut core::fmt::Formatter<'_>) -> core::fmt::Result +impl core::marker::StructuralPartialEq for spectral_init::SpectralError +impl core::marker::Freeze for spectral_init::SpectralError +impl core::marker::Send for spectral_init::SpectralError +impl core::marker::Sync for spectral_init::SpectralError +impl core::marker::Unpin for spectral_init::SpectralError +impl core::marker::UnsafeUnpin for spectral_init::SpectralError +impl core::panic::unwind_safe::RefUnwindSafe for spectral_init::SpectralError +impl core::panic::unwind_safe::UnwindSafe for spectral_init::SpectralError +pub struct spectral_init::SpectralInitConfig +impl spectral_init::SpectralInitConfig +pub const spectral_init::SpectralInitConfig::DEFAULT_DENSE_MEMORY_BUDGET: u64 +pub fn spectral_init::SpectralInitConfig::compute_mode(&self) -> spectral_init::ComputeMode +pub fn spectral_init::SpectralInitConfig::dense_memory_budget(&self) -> u64 +pub fn spectral_init::SpectralInitConfig::n_components(&self) -> usize +pub fn spectral_init::SpectralInitConfig::new(usize) -> Self +pub fn spectral_init::SpectralInitConfig::seed(&self) -> u64 +pub fn spectral_init::SpectralInitConfig::with_compute_mode(self, spectral_init::ComputeMode) -> Self +pub fn spectral_init::SpectralInitConfig::with_dense_memory_budget(self, u64) -> Self +pub fn spectral_init::SpectralInitConfig::with_seed(self, u64) -> Self +impl core::clone::Clone for spectral_init::SpectralInitConfig +pub fn spectral_init::SpectralInitConfig::clone(&self) -> spectral_init::SpectralInitConfig +impl core::cmp::PartialEq for spectral_init::SpectralInitConfig +pub fn spectral_init::SpectralInitConfig::eq(&self, &spectral_init::SpectralInitConfig) -> bool +impl core::fmt::Debug for spectral_init::SpectralInitConfig +pub fn spectral_init::SpectralInitConfig::fmt(&self, &mut core::fmt::Formatter<'_>) -> core::fmt::Result +impl core::marker::StructuralPartialEq for spectral_init::SpectralInitConfig +impl core::marker::Freeze for spectral_init::SpectralInitConfig +impl core::marker::Send for spectral_init::SpectralInitConfig +impl core::marker::Sync for spectral_init::SpectralInitConfig +impl core::marker::Unpin for spectral_init::SpectralInitConfig +impl core::marker::UnsafeUnpin for spectral_init::SpectralInitConfig +impl core::panic::unwind_safe::RefUnwindSafe for spectral_init::SpectralInitConfig +impl core::panic::unwind_safe::UnwindSafe for spectral_init::SpectralInitConfig +pub fn spectral_init::spectral_init(sprs::sparse::CsMatViewI<'_, f32, u32, usize>, core::option::Option>, &spectral_init::SpectralInitConfig) -> core::result::Result, spectral_init::SpectralError> diff --git a/.github/package-allowlist.txt b/.github/package-allowlist.txt index f628915..98edb60 100644 --- a/.github/package-allowlist.txt +++ b/.github/package-allowlist.txt @@ -10,6 +10,7 @@ examples/compute_modes.rs examples/from_adjacency_list.rs src/components.rs src/config.rs +src/error.rs src/laplacian.rs src/lib.rs src/multi_component.rs @@ -22,3 +23,4 @@ src/solvers/mod.rs src/solvers/quality.rs src/solvers/rsvd.rs src/solvers/sinv.rs +src/validate.rs diff --git a/.github/scripts/check-api.sh b/.github/scripts/check-api.sh new file mode 100755 index 0000000..0b0e371 --- /dev/null +++ b/.github/scripts/check-api.sh @@ -0,0 +1,30 @@ +#!/usr/bin/env bash +# Public API gate for the published crate. +# +# The default-feature public API must equal the committed snapshot. Blanket +# implementations are left out of the listing: they follow from the dependency +# graph, not from this crate. +# +# Needs a nightly toolchain and cargo-public-api. The listing depends on both +# versions; CI pins them. +# +# Usage: .github/scripts/check-api.sh [--update] +# --update rewrite the snapshot instead of comparing against it +set -euo pipefail + +repo_root="$(cd "$(dirname "${BASH_SOURCE[0]}")/../.." && pwd)" +cd "$repo_root" + +package="spectral-init" +snapshot=".github/api-snapshot.txt" + +current="$(cargo public-api -p "$package" --simplified)" + +if [ "${1:-}" = "--update" ]; then + printf '%s\n' "$current" > "$snapshot" + echo "wrote ${snapshot}" + exit 0 +fi + +diff -u "$snapshot" <(printf '%s\n' "$current") +echo "public API gate passed" diff --git a/.github/scripts/check-purity.sh b/.github/scripts/check-purity.sh index 90d5b87..cfbddb0 100755 --- a/.github/scripts/check-purity.sh +++ b/.github/scripts/check-purity.sh @@ -35,6 +35,10 @@ forbid "the library must not print or read the environment (src/)" \ 'println!|eprintln!|dbg!|env::var|SPECTRAL_' \ src +forbid "random numbers come from the named generator ChaCha12Rng, not StdRng (src/)" \ + 'StdRng' \ + src + forbid "no package has a 'testing' feature" \ 'feature *= *"testing"' \ src tests examples eval trustworthiness diff --git a/Cargo.lock b/Cargo.lock index 67c9640..73a2c28 100644 --- a/Cargo.lock +++ b/Cargo.lock @@ -1736,6 +1736,7 @@ dependencies = [ "ndarray-npy", "proptest", "rand 0.9.5", + "rand_chacha 0.9.0", "rand_distr", "serde_json", "sprs", diff --git a/Cargo.toml b/Cargo.toml index 707b5a1..a33a0b4 100644 --- a/Cargo.toml +++ b/Cargo.toml @@ -27,6 +27,7 @@ sprs = "0.11" ndarray = "0.17" faer = "0.24" rand = "0.9" +rand_chacha = "0.9" # the named generator behind the reproducibility contract rand_distr = "0.5" thiserror = "2" linfa-linalg = "0.2" # pure-Rust LOBPCG; no LAPACK backend required diff --git a/eval/benches/spectral_bench.rs b/eval/benches/spectral_bench.rs index 092c724..a92eb4d 100644 --- a/eval/benches/spectral_bench.rs +++ b/eval/benches/spectral_bench.rs @@ -52,12 +52,12 @@ fn make_ring_graph(n: usize, half: usize) -> sprs::CsMatI { /// to SpMV, dense EVD, LOBPCG, and rSVD benchmarks. fn make_laplacian(n: usize, half: usize) -> sprs::CsMatI { let graph = make_ring_graph(n, half); - let (_deg, sqrt_deg) = compute_degrees(&graph, ComputeMode::PythonCompat); + let (_deg, sqrt_deg) = compute_degrees(graph.view(), ComputeMode::PythonCompat); let inv_sqrt_deg: Vec = sqrt_deg .iter() .map(|&s| if s > 0.0 { 1.0 / s } else { 0.0 }) .collect(); - build_normalized_laplacian(&graph, &inv_sqrt_deg) + build_normalized_laplacian(graph.view(), &inv_sqrt_deg) } // ─── Benchmark Groups ───────────────────────────────────────────────────────── @@ -93,14 +93,14 @@ fn bench_spmv(c: &mut Criterion) { fn bench_dense_evd(c: &mut Criterion) { let lap = make_laplacian(200, 2); c.bench_function("dense_evd_200", |b| { - b.iter(|| black_box(dense_evd(black_box(&lap), black_box(3)))) + b.iter(|| black_box(dense_evd(black_box(&lap), black_box(3), u64::MAX))) }); } /// LOBPCG: iterative eigensolver for large n. Production Level 1. fn bench_lobpcg(c: &mut Criterion) { let graph = make_ring_graph(2000, 2); - let (_, sqrt_deg) = compute_degrees(&graph, ComputeMode::PythonCompat); + let (_, sqrt_deg) = compute_degrees(graph.view(), ComputeMode::PythonCompat); let lap = make_laplacian(2000, 2); let op = CsrOperator(&lap); c.bench_function("lobpcg_2000", |b| { @@ -135,7 +135,7 @@ fn bench_rsvd(c: &mut Criterion) { /// Laplacian construction: degrees + D^{-1/2} W D^{-1/2} build. fn bench_laplacian_build(c: &mut Criterion) { let graph = make_ring_graph(2000, 2); - let (_deg, sqrt_deg) = compute_degrees(&graph, ComputeMode::PythonCompat); + let (_deg, sqrt_deg) = compute_degrees(graph.view(), ComputeMode::PythonCompat); let inv_sqrt_deg: Vec = sqrt_deg .iter() .map(|&s| if s > 0.0 { 1.0 / s } else { 0.0 }) @@ -143,7 +143,7 @@ fn bench_laplacian_build(c: &mut Criterion) { c.bench_function("laplacian_build_2000", |b| { b.iter(|| { black_box(build_normalized_laplacian( - black_box(&graph), + black_box(graph.view()), black_box(&inv_sqrt_deg), )) }) @@ -154,7 +154,7 @@ fn bench_laplacian_build(c: &mut Criterion) { fn bench_components(c: &mut Criterion) { let graph = make_ring_graph(2000, 2); c.bench_function("components_bfs_2000", |b| { - b.iter(|| black_box(find_components(black_box(&graph)))) + b.iter(|| black_box(find_components(black_box(graph.view())))) }); } @@ -168,11 +168,9 @@ fn bench_full_pipeline(c: &mut Criterion) { b.iter(|| { black_box( spectral_init( - black_box(&graph), - black_box(2), - black_box(42_u64), - black_box(None), - SpectralInitConfig::default(), + graph.view(), + None, + &SpectralInitConfig::new(2).with_seed(42_u64), ) .expect("bench: spectral_init failed on synthetic ring graph"), ) diff --git a/eval/tests/export_merfish_init.rs b/eval/tests/export_merfish_init.rs index da5804e..af48361 100644 --- a/eval/tests/export_merfish_init.rs +++ b/eval/tests/export_merfish_init.rs @@ -42,12 +42,12 @@ fn export_merfish_init_10k() { // Emit solver level via the internal seam so the Python sweep harness can parse it. // Builds the Laplacian independently of spectral_init(); the actual embedding below // still uses spectral_init() as the authoritative pipeline path. - let (_degrees, sqrt_deg) = compute_degrees(&graph, ComputeMode::PythonCompat); + let (_degrees, sqrt_deg) = compute_degrees(graph.view(), ComputeMode::PythonCompat); let inv_sqrt_deg: Vec = sqrt_deg .iter() .map(|&s| if s > 0.0 { 1.0 / s } else { 0.0 }) .collect(); - let lap = build_normalized_laplacian(&graph, &inv_sqrt_deg); + let lap = build_normalized_laplacian(graph.view(), &inv_sqrt_deg); let (_, report) = solve_with_unit_hint( &lap, 2, @@ -58,8 +58,12 @@ fn export_merfish_init_10k() { println!("SOLVER_LEVEL={}", report.level as u8); let start = Instant::now(); - let coords = spectral_init(&graph, 2, 42, None, SpectralInitConfig::default()) - .unwrap_or_else(|e| panic!("spectral_init failed on merfish_10k: {e}")); + let coords = spectral_init( + graph.view(), + None, + &SpectralInitConfig::new(2).with_seed(42), + ) + .unwrap_or_else(|e| panic!("spectral_init failed on merfish_10k: {e}")); let elapsed = start.elapsed(); assert_eq!( @@ -116,12 +120,12 @@ fn export_merfish_init_20k() { println!("====================================="); println!("Graph: {} nodes", n); - let (_degrees, sqrt_deg) = compute_degrees(&graph, ComputeMode::PythonCompat); + let (_degrees, sqrt_deg) = compute_degrees(graph.view(), ComputeMode::PythonCompat); let inv_sqrt_deg: Vec = sqrt_deg .iter() .map(|&s| if s > 0.0 { 1.0 / s } else { 0.0 }) .collect(); - let lap = build_normalized_laplacian(&graph, &inv_sqrt_deg); + let lap = build_normalized_laplacian(graph.view(), &inv_sqrt_deg); let (_, report) = solve_with_unit_hint( &lap, 2, @@ -132,8 +136,12 @@ fn export_merfish_init_20k() { println!("SOLVER_LEVEL={}", report.level as u8); let start = Instant::now(); - let coords = spectral_init(&graph, 2, 42, None, SpectralInitConfig::default()) - .unwrap_or_else(|e| panic!("spectral_init failed on merfish_20k: {e}")); + let coords = spectral_init( + graph.view(), + None, + &SpectralInitConfig::new(2).with_seed(42), + ) + .unwrap_or_else(|e| panic!("spectral_init failed on merfish_20k: {e}")); let elapsed = start.elapsed(); // Measure peak RSS via /proc/self/status (Linux only) @@ -213,12 +221,12 @@ fn export_merfish_init_100k() { // Emit solver level via the internal seam so the Python sweep harness can parse it. // Builds the Laplacian independently of spectral_init(); the actual embedding below // still uses spectral_init() as the authoritative pipeline path. - let (_degrees, sqrt_deg) = compute_degrees(&graph, ComputeMode::PythonCompat); + let (_degrees, sqrt_deg) = compute_degrees(graph.view(), ComputeMode::PythonCompat); let inv_sqrt_deg: Vec = sqrt_deg .iter() .map(|&s| if s > 0.0 { 1.0 / s } else { 0.0 }) .collect(); - let lap = build_normalized_laplacian(&graph, &inv_sqrt_deg); + let lap = build_normalized_laplacian(graph.view(), &inv_sqrt_deg); let (_, report) = solve_with_unit_hint( &lap, 2, @@ -229,8 +237,12 @@ fn export_merfish_init_100k() { println!("SOLVER_LEVEL={}", report.level as u8); let start = Instant::now(); - let coords = spectral_init(&graph, 2, 42, None, SpectralInitConfig::default()) - .unwrap_or_else(|e| panic!("spectral_init failed on merfish_100k: {e}")); + let coords = spectral_init( + graph.view(), + None, + &SpectralInitConfig::new(2).with_seed(42), + ) + .unwrap_or_else(|e| panic!("spectral_init failed on merfish_100k: {e}")); let elapsed = start.elapsed(); assert_eq!( @@ -305,12 +317,12 @@ fn export_merfish_init_250k() { println!("======================================"); println!("Graph: {} nodes", n); - let (_degrees, sqrt_deg) = compute_degrees(&graph, ComputeMode::PythonCompat); + let (_degrees, sqrt_deg) = compute_degrees(graph.view(), ComputeMode::PythonCompat); let inv_sqrt_deg: Vec = sqrt_deg .iter() .map(|&s| if s > 0.0 { 1.0 / s } else { 0.0 }) .collect(); - let lap = build_normalized_laplacian(&graph, &inv_sqrt_deg); + let lap = build_normalized_laplacian(graph.view(), &inv_sqrt_deg); let (_, report) = solve_with_unit_hint( &lap, 2, @@ -321,8 +333,12 @@ fn export_merfish_init_250k() { println!("SOLVER_LEVEL={}", report.level as u8); let start = Instant::now(); - let coords = spectral_init(&graph, 2, 42, None, SpectralInitConfig::default()) - .unwrap_or_else(|e| panic!("spectral_init failed on merfish_250k: {e}")); + let coords = spectral_init( + graph.view(), + None, + &SpectralInitConfig::new(2).with_seed(42), + ) + .unwrap_or_else(|e| panic!("spectral_init failed on merfish_250k: {e}")); let elapsed = start.elapsed(); assert_eq!( diff --git a/eval/tests/export_rust_init.rs b/eval/tests/export_rust_init.rs index 68e3bc3..07d35f3 100644 --- a/eval/tests/export_rust_init.rs +++ b/eval/tests/export_rust_init.rs @@ -53,7 +53,11 @@ fn export_all_rust_inits() { let n = graph.rows(); let start = Instant::now(); - match spectral_init(&graph, 2, 42, None, SpectralInitConfig::default()) { + match spectral_init( + graph.view(), + None, + &SpectralInitConfig::new(2).with_seed(42), + ) { Ok(coords) => { let elapsed = start.elapsed(); let out_path = output_dir.join(format!("{name}_rust_init.npy")); diff --git a/eval/tests/test_exp_rsvd_nbiter_sweep.rs b/eval/tests/test_exp_rsvd_nbiter_sweep.rs index d738e2a..14afd3a 100644 --- a/eval/tests/test_exp_rsvd_nbiter_sweep.rs +++ b/eval/tests/test_exp_rsvd_nbiter_sweep.rs @@ -67,9 +67,11 @@ fn run_solver( rsvd_nbiter: nbiter, ..SolverParams::default() }; - rsvd_solve(lap, nc, SEED, ¶ms) + rsvd_solve(lap, nc, SEED, ¶ms).expect("rsvd_solve failed") + } + "direct_l" => { + rsvd_solve_accurate(lap, nc, SEED, k_sub, nbiter).expect("rsvd_solve_accurate failed") } - "direct_l" => rsvd_solve_accurate(lap, nc, SEED, k_sub, nbiter), _ => panic!("unknown method: {method}"), } } @@ -134,7 +136,8 @@ fn direction_c_subspace() { for (fixture, (lap, n, nc)) in &fixture_data { // Reference: high-accuracy solve at nbiter=10, p=100. let k_sub_ref = (nc + 1 + 100).min(*n); - let (_, ref_vecs) = rsvd_solve_accurate(lap, *nc, SEED, k_sub_ref, 10); + let (_, ref_vecs) = + rsvd_solve_accurate(lap, *nc, SEED, k_sub_ref, 10).expect("rsvd_solve_accurate failed"); let ref_nt_vecs = ref_vecs.slice(s![.., 1..]).to_owned(); let ref_f32: ndarray::Array2 = ref_nt_vecs.mapv(|x| x as f32); diff --git a/eval/tests/test_exp_rsvd_sweep.rs b/eval/tests/test_exp_rsvd_sweep.rs index 26bd365..c3ec03c 100644 --- a/eval/tests/test_exp_rsvd_sweep.rs +++ b/eval/tests/test_exp_rsvd_sweep.rs @@ -37,7 +37,8 @@ fn accurate_sweep() { for &p in P_VALUES_ACCURATE { let k_sub = N_COMPONENTS + 1 + p; // rank=3, so k_sub = 3 + p let t0 = std::time::Instant::now(); - let (eigs, vecs) = rsvd_solve_accurate(&laplacian, N_COMPONENTS, SEED, k_sub, 6); + let (eigs, vecs) = rsvd_solve_accurate(&laplacian, N_COMPONENTS, SEED, k_sub, 6) + .expect("rsvd_solve_accurate failed"); let wall_time = t0.elapsed().as_secs_f64(); // max residual over non-trivial pairs (indices 1..=n_components) @@ -80,7 +81,8 @@ fn production_sweep() { }; let t0 = std::time::Instant::now(); - let (eigs, vecs) = rsvd_solve(&laplacian, N_COMPONENTS, SEED, ¶ms); + let (eigs, vecs) = + rsvd_solve(&laplacian, N_COMPONENTS, SEED, ¶ms).expect("rsvd_solve failed"); let wall_time = t0.elapsed().as_secs_f64(); let max_res = (1..=N_COMPONENTS) diff --git a/eval/tests/test_metrics_assess.rs b/eval/tests/test_metrics_assess.rs index 271d220..538447d 100644 --- a/eval/tests/test_metrics_assess.rs +++ b/eval/tests/test_metrics_assess.rs @@ -245,10 +245,10 @@ fn assess_accuracy() { if !is_connected { let graph = fixtures::load_sparse_csr_f32_u32(&base.join("step5a_pruned.npz")); - let (rust_labels, rust_n_components) = find_components(&graph); + let (rust_labels, rust_n_components) = find_components(graph.view()); let embedding = embed_disconnected( - &graph, + graph.view(), &rust_labels, rust_n_components, n_components_dim, diff --git a/examples/basic.rs b/examples/basic.rs index 89cc2ea..24f0888 100644 --- a/examples/basic.rs +++ b/examples/basic.rs @@ -5,12 +5,13 @@ //! //! Run with: cargo run --example basic +use spectral_init::sprs::{CsMatI, TriMatI}; use spectral_init::{SpectralInitConfig, spectral_init}; -use sprs::{CsMatI, TriMatI}; fn main() -> Result<(), Box> { // Build a 10-node ring graph: every node is connected to its two neighbours. - // spectral_init expects CsMatI — the same type as umap_rs::Umap::graph(). + // spectral_init takes a view of a CsMatI — the type that + // umap_rs::LearnedManifold::graph() returns. let n = 10usize; let mut tri: TriMatI = TriMatI::new((n, n)); for i in 0..n { @@ -20,10 +21,10 @@ fn main() -> Result<(), Box> { } let graph: CsMatI = tri.to_csr(); - // SpectralInitConfig::default() uses ComputeMode::PythonCompat, which matches - // Python UMAP's initialization behaviour exactly. - let config = SpectralInitConfig::default(); - let embedding = spectral_init(&graph, 2, 42, None, config)?; + // Two embedding dimensions, seed 42. The default compute mode is + // ComputeMode::PythonCompat, which follows umap-learn's spectral layout. + let config = SpectralInitConfig::new(2).with_seed(42); + let embedding = spectral_init(graph.view(), None, &config)?; println!("Embedding shape: {:?}", embedding.shape()); println!("First few coordinates:"); diff --git a/examples/compute_modes.rs b/examples/compute_modes.rs index 823d432..bcd6120 100644 --- a/examples/compute_modes.rs +++ b/examples/compute_modes.rs @@ -5,8 +5,8 @@ //! //! Run with: cargo run --example compute_modes +use spectral_init::sprs::{CsMatI, TriMatI}; use spectral_init::{ComputeMode, SpectralInitConfig, spectral_init}; -use sprs::{CsMatI, TriMatI}; fn make_ring(n: usize) -> CsMatI { let mut tri: TriMatI = TriMatI::new((n, n)); @@ -22,15 +22,17 @@ fn main() -> Result<(), Box> { let graph = make_ring(20); // PythonCompat: matches Python UMAP's degree accumulation and solver path. - let mut cfg_compat = SpectralInitConfig::default(); - cfg_compat.compute_mode = ComputeMode::PythonCompat; - let emb_compat = spectral_init(&graph, 2, 42, None, cfg_compat)?; + let cfg_compat = SpectralInitConfig::new(2) + .with_seed(42) + .with_compute_mode(ComputeMode::PythonCompat); + let emb_compat = spectral_init(graph.view(), None, &cfg_compat)?; // RustNative: uses AVX2+FMA SIMD kernel on x86_64; falls back on other platforms. // Eigenvectors are subspace-equivalent to PythonCompat (same span, may differ by sign). - let mut cfg_native = SpectralInitConfig::default(); - cfg_native.compute_mode = ComputeMode::RustNative; - let emb_native = spectral_init(&graph, 2, 42, None, cfg_native)?; + let cfg_native = SpectralInitConfig::new(2) + .with_seed(42) + .with_compute_mode(ComputeMode::RustNative); + let emb_native = spectral_init(graph.view(), None, &cfg_native)?; println!("PythonCompat shape: {:?}", emb_compat.shape()); println!("RustNative shape: {:?}", emb_native.shape()); diff --git a/examples/from_adjacency_list.rs b/examples/from_adjacency_list.rs index 24a58f4..26444a4 100644 --- a/examples/from_adjacency_list.rs +++ b/examples/from_adjacency_list.rs @@ -5,8 +5,8 @@ //! //! Run with: cargo run --example from_adjacency_list +use spectral_init::sprs::{CsMatI, TriMatI}; use spectral_init::{SpectralInitConfig, spectral_init}; -use sprs::{CsMatI, TriMatI}; fn main() -> Result<(), Box> { // Represent an undirected weighted graph as (src, dst, weight) triplets. @@ -33,8 +33,8 @@ fn main() -> Result<(), Box> { } let graph: CsMatI = tri.to_csr(); - let config = SpectralInitConfig::default(); - let embedding = spectral_init(&graph, 2, 42, None, config)?; + let config = SpectralInitConfig::new(2).with_seed(42); + let embedding = spectral_init(graph.view(), None, &config)?; println!( "Nodes: {}, Embedding dims: {}", diff --git a/src/components.rs b/src/components.rs index 78b355c..993890f 100644 --- a/src/components.rs +++ b/src/components.rs @@ -1,10 +1,10 @@ -use sprs::CsMatI; +use sprs::CsMatViewI; use std::collections::VecDeque; -/// BFS connected-component labelling on a sparse graph. +/// BFS connected-component labelling on a sparse graph in CSR storage. /// Returns a Vec of length n where `result[i]` is the component index for node i, -/// and the number of distinct components. -pub fn find_components(graph: &CsMatI) -> (Vec, usize) { +/// and the number of distinct components. Stored zeros are absent edges. +pub fn find_components(graph: CsMatViewI<'_, f32, u32, usize>) -> (Vec, usize) { debug_assert!( graph.is_csr(), "find_components requires CSR storage; a CSC matrix would silently traverse \ @@ -24,13 +24,13 @@ pub fn find_components(graph: &CsMatI) -> (Vec, usize) { queue.push_back(start); while let Some(node) = queue.pop_front() { - for &col in graph - .outer_view(node) - .expect("node index in bounds") - .indices() - { - let neighbor = col as usize; - if labels[neighbor] == usize::MAX { + // `node` is a row index below `n`, so the row always exists. + let Some(row) = graph.outer_view(node) else { + continue; + }; + for (neighbor, &weight) in row.iter() { + // Column indices of a square matrix are below `n`. + if weight != 0.0 && labels[neighbor] == usize::MAX { labels[neighbor] = n_components; queue.push_back(neighbor); } @@ -46,11 +46,12 @@ pub fn find_components(graph: &CsMatI) -> (Vec, usize) { #[cfg(test)] mod tests { use super::*; + use sprs::CsMatI; #[test] fn test_empty_graph() { let g = CsMatI::::new((0, 0), vec![0usize], vec![], vec![]); - let (labels, n) = find_components(&g); + let (labels, n) = find_components(g.view()); assert_eq!(n, 0); assert!(labels.is_empty()); } @@ -58,7 +59,7 @@ mod tests { #[test] fn test_single_node_no_edges() { let g = CsMatI::::new((1, 1), vec![0usize, 0], vec![], vec![]); - let (labels, n) = find_components(&g); + let (labels, n) = find_components(g.view()); assert_eq!(n, 1); assert_eq!(labels, vec![0]); } @@ -66,7 +67,7 @@ mod tests { #[test] fn test_two_isolated_nodes() { let g = CsMatI::::new((2, 2), vec![0usize, 0, 0], vec![], vec![]); - let (labels, n) = find_components(&g); + let (labels, n) = find_components(g.view()); assert_eq!(n, 2); assert_ne!(labels[0], labels[1]); } @@ -80,7 +81,7 @@ mod tests { vec![1u32, 0u32], vec![1.0f32, 1.0f32], ); - let (labels, n) = find_components(&g); + let (labels, n) = find_components(g.view()); assert_eq!(n, 1); assert_eq!(labels[0], labels[1]); } @@ -94,7 +95,7 @@ mod tests { vec![1u32, 0u32, 2u32, 1u32], vec![1.0f32; 4], ); - let (labels, n) = find_components(&g); + let (labels, n) = find_components(g.view()); assert_eq!(n, 1); assert_eq!(labels[0], labels[1]); assert_eq!(labels[1], labels[2]); @@ -103,13 +104,28 @@ mod tests { #[test] fn test_three_isolated_nodes() { let g = CsMatI::::new((3, 3), vec![0usize, 0, 0, 0], vec![], vec![]); - let (labels, n) = find_components(&g); + let (labels, n) = find_components(g.view()); assert_eq!(n, 3); assert_ne!(labels[0], labels[1]); assert_ne!(labels[1], labels[2]); assert_ne!(labels[0], labels[2]); } + #[test] + fn test_stored_zero_does_not_connect() { + // 0-1 joined by a real edge; 1-2 joined only by a stored zero. + let g = CsMatI::::new( + (3, 3), + vec![0usize, 1, 3, 4], + vec![1u32, 0u32, 2u32, 1u32], + vec![1.0f32, 1.0, 0.0, 0.0], + ); + let (labels, n) = find_components(g.view()); + assert_eq!(n, 2); + assert_eq!(labels[0], labels[1]); + assert_ne!(labels[1], labels[2]); + } + #[test] fn test_two_components_four_nodes() { // Edges: 0-1 and 2-3, no cross edges @@ -119,7 +135,7 @@ mod tests { vec![1u32, 0u32, 3u32, 2u32], vec![1.0f32; 4], ); - let (labels, n) = find_components(&g); + let (labels, n) = find_components(g.view()); assert_eq!(n, 2); assert_eq!(labels[0], labels[1]); assert_eq!(labels[2], labels[3]); diff --git a/src/config.rs b/src/config.rs index 5339240..fb62c16 100644 --- a/src/config.rs +++ b/src/config.rs @@ -1,5 +1,17 @@ /// Controls whether to match Python UMAP behavior exactly or use /// best-available Rust-native algorithms. +/// +/// # Examples +/// +/// ``` +/// use spectral_init::{ComputeMode, SpectralInitConfig}; +/// +/// // `PythonCompat` is the default. +/// assert_eq!(SpectralInitConfig::new(2).compute_mode(), ComputeMode::PythonCompat); +/// +/// let config = SpectralInitConfig::new(2).with_compute_mode(ComputeMode::RustNative); +/// assert_eq!(config.compute_mode(), ComputeMode::RustNative); +/// ``` #[non_exhaustive] #[derive(Debug, Clone, Copy, Default, PartialEq, Eq)] pub enum ComputeMode { @@ -20,27 +32,100 @@ pub enum ComputeMode { RustNative, } -/// Configuration for the spectral initialization pipeline. +/// Configuration for [`spectral_init`](crate::spectral_init). /// -/// Construct with `SpectralInitConfig::default()` for Python-compatible behavior. +/// Create one with [`SpectralInitConfig::new`], giving the number of embedding +/// dimensions, and adjust it with the `with_*` methods. /// /// # Examples /// /// ``` -/// use spectral_init::{SpectralInitConfig, ComputeMode}; +/// use spectral_init::{ComputeMode, SpectralInitConfig}; /// -/// // Default: Python-compatible behavior -/// let config = SpectralInitConfig::default(); -/// assert_eq!(config.compute_mode, ComputeMode::PythonCompat); +/// let config = SpectralInitConfig::new(2); +/// assert_eq!(config.n_components(), 2); +/// assert_eq!(config.seed(), 0); +/// assert_eq!(config.compute_mode(), ComputeMode::PythonCompat); /// -/// // Custom: Rust-native SIMD acceleration (may differ ~1 ULP from Python) -/// let mut fast = SpectralInitConfig::default(); -/// fast.compute_mode = ComputeMode::RustNative; +/// let config = SpectralInitConfig::new(3) +/// .with_seed(42) +/// .with_compute_mode(ComputeMode::RustNative) +/// .with_dense_memory_budget(1 << 30); +/// assert_eq!(config.seed(), 42); +/// assert_eq!(config.dense_memory_budget(), 1 << 30); /// ``` -#[non_exhaustive] -#[derive(Debug, Clone, Default)] +#[derive(Debug, Clone, PartialEq)] pub struct SpectralInitConfig { - /// Controls which algorithm variant to use when Rust-native and Python-compatible - /// implementations differ in quality. - pub compute_mode: ComputeMode, + n_components: usize, + seed: u64, + compute_mode: ComputeMode, + dense_memory_budget: u64, +} + +impl SpectralInitConfig { + /// Default [dense memory budget](Self::with_dense_memory_budget): 4 GiB. + pub const DEFAULT_DENSE_MEMORY_BUDGET: u64 = 4 * 1024 * 1024 * 1024; + + /// Creates a configuration for an embedding with `n_components` dimensions. + /// + /// The seed is 0, the compute mode is [`ComputeMode::PythonCompat`] and the dense + /// memory budget is [`Self::DEFAULT_DENSE_MEMORY_BUDGET`]. + #[must_use] + pub fn new(n_components: usize) -> Self { + Self { + n_components, + seed: 0, + compute_mode: ComputeMode::default(), + dense_memory_budget: Self::DEFAULT_DENSE_MEMORY_BUDGET, + } + } + + /// Sets the seed of the random number generators the solvers and the final noise use. + #[must_use] + pub fn with_seed(mut self, seed: u64) -> Self { + self.seed = seed; + self + } + + /// Sets the [`ComputeMode`]. + #[must_use] + pub fn with_compute_mode(mut self, compute_mode: ComputeMode) -> Self { + self.compute_mode = compute_mode; + self + } + + /// Sets the dense memory budget, in bytes. + /// + /// The budget caps the size of every dense matrix a solver allocates: a solver that + /// would need a larger one is skipped, and [`SpectralError::DenseBudgetExceeded`] is + /// returned when no remaining solver can run within it. It bounds each dense matrix + /// individually, not the peak memory of the process — some solvers hold a few + /// matrices of that size at once. + /// + /// [`SpectralError::DenseBudgetExceeded`]: crate::SpectralError::DenseBudgetExceeded + #[must_use] + pub fn with_dense_memory_budget(mut self, bytes: u64) -> Self { + self.dense_memory_budget = bytes; + self + } + + /// Number of embedding dimensions. + pub fn n_components(&self) -> usize { + self.n_components + } + + /// Seed of the random number generators. + pub fn seed(&self) -> u64 { + self.seed + } + + /// The [`ComputeMode`]. + pub fn compute_mode(&self) -> ComputeMode { + self.compute_mode + } + + /// Dense memory budget, in bytes. + pub fn dense_memory_budget(&self) -> u64 { + self.dense_memory_budget + } } diff --git a/src/error.rs b/src/error.rs new file mode 100644 index 0000000..a47a65e --- /dev/null +++ b/src/error.rs @@ -0,0 +1,156 @@ +/// Errors returned by [`spectral_init`](crate::spectral_init). +/// +/// The enum and each of its struct-like variants are `#[non_exhaustive]`: match with a +/// wildcard arm and with `..` in variant patterns, so that variants and fields added in +/// later releases do not break the build. +/// +/// # Examples +/// +/// ``` +/// use spectral_init::{SpectralError, SpectralInitConfig, spectral_init, sprs::CsMatI}; +/// +/// // One directed edge 0 → 1 with no edge back: not a symmetric graph. +/// let graph = CsMatI::::new( +/// (3, 3), +/// vec![0, 1, 1, 1], +/// vec![1], +/// vec![1.0], +/// ); +/// match spectral_init(graph.view(), None, &SpectralInitConfig::new(2)) { +/// Err(SpectralError::NotSymmetric { row, col, .. }) => assert_eq!((row, col), (0, 1)), +/// other => panic!("expected NotSymmetric, got {other:?}"), +/// } +/// ``` +#[derive(Debug, Clone, PartialEq, thiserror::Error)] +#[non_exhaustive] +pub enum SpectralError { + /// A configuration value is outside its valid range. + #[error("invalid parameter `{name}`: {reason}")] + #[non_exhaustive] + InvalidParameter { + /// Name of the rejected parameter. + name: &'static str, + /// Why the value was rejected. + reason: &'static str, + }, + + /// The graph matrix is not square. + #[error("graph matrix is not square: {rows} rows, {cols} columns")] + #[non_exhaustive] + NotSquare { + /// Number of rows of the graph matrix. + rows: usize, + /// Number of columns of the graph matrix. + cols: usize, + }, + + /// The graph has too few nodes for the requested embedding dimensionality: + /// `n_components` coordinates need at least `n_components + 1` nodes. + #[error("graph has too few nodes ({n}) for a {n_components}-dimensional embedding")] + #[non_exhaustive] + TooFewNodes { + /// Number of nodes in the graph. + n: usize, + /// Requested number of embedding dimensions. + n_components: usize, + }, + + /// A stored edge weight is NaN or infinite. + #[error("edge weight at ({row}, {col}) is not finite")] + #[non_exhaustive] + NonFiniteWeight { + /// Row of the offending entry, in the orientation the caller supplied. + row: usize, + /// Column of the offending entry. + col: usize, + }, + + /// A stored edge weight is negative. + #[error("edge weight at ({row}, {col}) is negative")] + #[non_exhaustive] + NegativeWeight { + /// Row of the offending entry, in the orientation the caller supplied. + row: usize, + /// Column of the offending entry. + col: usize, + }, + + /// The graph matrix is not symmetric: the entry at `(row, col)` has no matching + /// entry at `(col, row)`. + #[error("graph matrix is not symmetric: entry ({row}, {col}) differs from ({col}, {row})")] + #[non_exhaustive] + NotSymmetric { + /// Row of the offending entry, in the orientation the caller supplied. + row: usize, + /// Column of the offending entry. + col: usize, + }, + + /// The summed edge weights of a node overflow single precision. + #[error("degree of node {node} is not finite")] + #[non_exhaustive] + DegreeOverflow { + /// Index of the node whose degree overflowed. + node: usize, + }, + + /// The graph has more than `2 · n_components` connected components, and placing + /// that many components relative to each other needs the original data. + #[error( + "graph has {connected_components} connected components; `data` is required when \ + there are more than twice the {n_components} embedding dimensions" + )] + #[non_exhaustive] + DataRequired { + /// Number of connected components found in the graph. + connected_components: usize, + /// Requested number of embedding dimensions. + n_components: usize, + }, + + /// `data` does not have one row per graph node. + #[error("data has {actual_rows} rows but the graph has {expected_rows} nodes")] + #[non_exhaustive] + DataShapeMismatch { + /// Number of graph nodes. + expected_rows: usize, + /// Number of rows in `data`. + actual_rows: usize, + }, + + /// A value in `data` is NaN or infinite. + #[error("data value at ({row}, {col}) is not finite")] + #[non_exhaustive] + NonFiniteData { + /// Row of the offending value. + row: usize, + /// Column of the offending value. + col: usize, + }, + + /// Solving the problem would need a dense matrix larger than the configured + /// [dense memory budget](crate::SpectralInitConfig::with_dense_memory_budget). + #[error( + "a dense matrix of {required_bytes} bytes exceeds the dense memory budget of \ + {budget_bytes} bytes" + )] + #[non_exhaustive] + DenseBudgetExceeded { + /// Size in bytes of the dense matrix that was needed. + required_bytes: u64, + /// The configured budget in bytes. + budget_bytes: u64, + }, + + /// No solver in the escalation chain produced eigenvectors of acceptable quality. + #[error("eigensolver failed to converge on a problem of size {n}")] + #[non_exhaustive] + ConvergenceFailure { + /// Size of the eigenproblem whose solve failed. + n: usize, + }, + + /// The computed coordinates are all zero, so they cannot be scaled. + #[error("the embedding is degenerate: all coordinates are zero")] + DegenerateEmbedding, +} diff --git a/src/laplacian.rs b/src/laplacian.rs index 1db1538..c592a3a 100644 --- a/src/laplacian.rs +++ b/src/laplacian.rs @@ -1,12 +1,12 @@ use crate::ComputeMode; use ndarray::Array1; -use sprs::{CsMatI, TriMat}; +use sprs::{CsMatI, CsMatViewI, TriMat}; /// f32 column-sum scatter-add: iterates nonzeros and accumulates deg_f32[col] += val in f32, /// then returns the raw f32 accumulator. #[inline(never)] prevents LLVM from reordering /// f32 additions across inlining boundaries, ensuring platform-consistent order. #[inline(never)] -fn column_sum_f32(graph: &CsMatI) -> Vec { +pub(crate) fn column_sum_f32(graph: CsMatViewI<'_, f32, u32, usize>) -> Vec { let n = graph.cols(); let mut deg_f32 = vec![0.0f32; n]; for (val, (_row, col)) in graph.iter() { @@ -24,10 +24,12 @@ fn column_sum_f32(graph: &CsMatI) -> Vec { /// - `ComputeMode::RustNative`: f64 row-sum — iterates CSR rows and accumulates f32 weights /// with f64 accumulation. Numerically superior but may differ from Python by ~1 ULP. /// +/// Diagonal weights (self-loops) count towards the degree; stored zeros add nothing. +/// /// Returns `(degrees, sqrt_deg)`. Zero-degree (isolated) nodes produce /// `degrees[i] = 0.0` and `sqrt_deg[i] = 0.0`. pub fn compute_degrees( - graph: &CsMatI, + graph: CsMatViewI<'_, f32, u32, usize>, mode: ComputeMode, ) -> (Array1, Array1) { let n = graph.rows(); @@ -51,37 +53,42 @@ pub fn compute_degrees( /// Builds the symmetric normalized Laplacian L = I - D^{-1/2} W D^{-1/2} in f64. /// /// Accepts the fuzzy k-NN graph in f32/u32 format from umap-rs and upcasts weights -/// to f64 for numerical stability. `inv_sqrt_deg[i]` must equal `1/sqrt(degree[i])` -/// for connected nodes and `0.0` for isolated (zero-degree) nodes. +/// to f64 for numerical stability. `inv_sqrt_deg` must have one entry per node: +/// `1/sqrt(degree[i])` for connected nodes and `0.0` for isolated (zero-degree) nodes. /// /// Returns a symmetric CSR matrix of shape `(n, n)` with: -/// - Diagonal entries exactly 1.0 for all nodes (including isolated ones) +/// - Diagonal entries `L[i,i] = 1 - inv_sqrt_deg[i]² * W[i,i]`, stored for every node +/// (exactly 1.0 where the graph has no self-loop) /// - Off-diagonal entries `L[i,j] = -inv_sqrt_deg[i] * W[i,j] * inv_sqrt_deg[j]` +/// +/// Stored zeros in `graph` are absent edges and produce no entry. pub fn build_normalized_laplacian( - graph: &CsMatI, + graph: CsMatViewI<'_, f32, u32, usize>, inv_sqrt_deg: &[f64], ) -> CsMatI { let n = graph.rows(); - // Capacity: all off-diagonal nonzeros from W, plus n diagonal entries + debug_assert_eq!( + inv_sqrt_deg.len(), + n, + "inv_sqrt_deg must have one entry per node" + ); + // Capacity: every nonzero of W, plus n diagonal entries let mut tri: TriMat = TriMat::with_capacity((n, n), graph.nnz() + n); - // Off-diagonal entries: L[i,j] = -inv_sqrt_deg[i] * W[i,j] * inv_sqrt_deg[j] for (row_idx, row_vec) in graph.outer_iterator().enumerate() { + let mut diagonal = 1.0_f64; for (col_idx, &val) in row_vec.iter() { - if row_idx != col_idx { - tri.add_triplet( - row_idx, - col_idx, - -inv_sqrt_deg[row_idx] * (val as f64) * inv_sqrt_deg[col_idx], - ); + if val == 0.0 { + continue; + } + let normalized = inv_sqrt_deg[row_idx] * (val as f64) * inv_sqrt_deg[col_idx]; + if row_idx == col_idx { + diagonal -= normalized; + } else { + tri.add_triplet(row_idx, col_idx, -normalized); } } - } - - // Diagonal entries: L[i,i] = 1.0 for all i - // (holds exactly: k-NN graphs have no self-loops, so D^{-1/2} W D^{-1/2} diagonal is 0) - for i in 0..n { - tri.add_triplet(i, i, 1.0); + tri.add_triplet(row_idx, row_idx, diagonal); } tri.to_csr() @@ -92,6 +99,87 @@ mod tests { use super::*; use sprs::CsMatI; + /// Degrees, inverse square-root degrees and Laplacian of `graph`, as the pipeline + /// computes them. + fn laplacian_of(graph: &CsMatI) -> (Array1, CsMatI) { + let (degrees, sqrt_deg) = compute_degrees(graph.view(), ComputeMode::PythonCompat); + let inv_sqrt_deg: Vec = sqrt_deg + .iter() + .map(|&s| if s > 0.0 { 1.0 / s } else { 0.0 }) + .collect(); + ( + degrees, + build_normalized_laplacian(graph.view(), &inv_sqrt_deg), + ) + } + + #[test] + fn self_loops_count_in_degree_and_laplacian_diagonal() { + // 3 nodes; edges 0-1 (2.0), 1-2 (1.0); self-loops on node 0 (1.0) and node 2 (3.0). + // W = [[1, 2, 0], + // [2, 0, 1], + // [0, 1, 3]] degrees = [3, 3, 4] + let graph = CsMatI::new( + (3, 3), + vec![0usize, 2, 4, 6], + vec![0u32, 1, 0, 2, 1, 2], + vec![1.0f32, 2.0, 2.0, 1.0, 1.0, 3.0], + ); + let (degrees, l) = laplacian_of(&graph); + assert_eq!(degrees.to_vec(), vec![3.0, 3.0, 4.0]); + + let entry = |i, j| l.get(i, j).copied().unwrap_or(0.0); + assert!((entry(0, 0) - (1.0 - 1.0 / 3.0)).abs() < 1e-15); + assert!((entry(1, 1) - 1.0).abs() < 1e-15); + assert!((entry(2, 2) - (1.0 - 3.0 / 4.0)).abs() < 1e-15); + assert!((entry(0, 1) + 2.0 / 3.0).abs() < 1e-15); + assert!((entry(1, 2) + 1.0 / 12.0_f64.sqrt()).abs() < 1e-15); + + // sqrt(degree) spans the null space: L · sqrt(d) = 0. + let sqrt_deg = degrees.mapv(f64::sqrt); + let residual = &l * &sqrt_deg; + for (i, r) in residual.iter().enumerate() { + assert!(r.abs() < 1e-14, "(L·sqrt(d))[{i}] = {r}"); + } + } + + #[test] + fn every_diagonal_entry_is_stored() { + // Node 2 has only a self-loop, so L[2,2] = 1 - w/d = 0; the entry is still stored. + let graph = CsMatI::new( + (3, 3), + vec![0usize, 1, 2, 3], + vec![1u32, 0, 2], + vec![1.0f32, 1.0, 5.0], + ); + let (_, l) = laplacian_of(&graph); + for i in 0..3 { + assert!(l.get(i, i).is_some(), "diagonal entry {i} is not stored"); + } + assert!(l.get(2, 2).copied().unwrap().abs() < 1e-15); + } + + #[test] + fn stored_zeros_are_absent_edges() { + // The same path 0-1-2, once with an explicit zero stored at (0,2) and (2,0). + let with_zeros = CsMatI::new( + (3, 3), + vec![0usize, 2, 4, 6], + vec![1u32, 2, 0, 2, 0, 1], + vec![1.0f32, 0.0, 1.0, 1.0, 0.0, 1.0], + ); + let canonical = CsMatI::new( + (3, 3), + vec![0usize, 1, 3, 4], + vec![1u32, 0, 2, 1], + vec![1.0f32, 1.0, 1.0, 1.0], + ); + let (deg_zeros, l_zeros) = laplacian_of(&with_zeros); + let (deg_canonical, l_canonical) = laplacian_of(&canonical); + assert_eq!(deg_zeros, deg_canonical); + assert_eq!(l_zeros, l_canonical); + } + #[test] fn compute_degrees_zero_degree_node() { // 3-node graph: only nodes 0 and 1 are connected @@ -101,7 +189,7 @@ mod tests { let data = vec![2.0f32, 2.0f32]; let graph = CsMatI::new((3, 3), indptr, indices, data); - let (degrees, sqrt_deg) = compute_degrees(&graph, ComputeMode::PythonCompat); + let (degrees, sqrt_deg) = compute_degrees(graph.view(), ComputeMode::PythonCompat); assert!((degrees[0] - 2.0_f64).abs() < 1e-15); assert!((degrees[1] - 2.0_f64).abs() < 1e-15); @@ -139,7 +227,7 @@ mod tests { d }; - let (deg, _) = compute_degrees(&graph, ComputeMode::PythonCompat); + let (deg, _) = compute_degrees(graph.view(), ComputeMode::PythonCompat); for i in 0..4 { let expected = expected_col_sums[i] as f64; @@ -161,7 +249,7 @@ mod tests { let data = vec![1.0f32; 6]; let graph = CsMatI::new((4, 4), indptr, indices, data); - let (deg, sqrt_deg) = compute_degrees(&graph, ComputeMode::RustNative); + let (deg, sqrt_deg) = compute_degrees(graph.view(), ComputeMode::RustNative); // Node 0 and 3 have degree 1, nodes 1 and 2 have degree 2 assert!((deg[0] - 1.0_f64).abs() < 1e-15, "deg[0]={}", deg[0]); @@ -181,7 +269,7 @@ mod tests { let graph = CsMatI::new((2, 2), indptr, indices, data); let inv_sqrt_deg = vec![1.0f64, 1.0f64]; // sqrt_deg = [1.0, 1.0] - let l = build_normalized_laplacian(&graph, &inv_sqrt_deg); + let l = build_normalized_laplacian(graph.view(), &inv_sqrt_deg); // Diagonal assert!((l.get(0, 0).copied().unwrap_or(0.0) - 1.0).abs() < 1e-15); @@ -201,7 +289,7 @@ mod tests { let graph = CsMatI::new((2, 2), indptr, indices, data); let inv_sqrt_deg = vec![0.5f64, 0.5f64]; - let l = build_normalized_laplacian(&graph, &inv_sqrt_deg); + let l = build_normalized_laplacian(graph.view(), &inv_sqrt_deg); // L[0,1] = -0.5 * 4.0 * 0.5 = -1.0 assert!((l.get(0, 1).copied().unwrap_or(0.0) - (-1.0)).abs() < 1e-15); @@ -221,7 +309,7 @@ mod tests { let graph = CsMatI::new((3, 3), indptr, indices, data); let inv_sqrt_deg = vec![1.0f64, 1.0f64, 0.0f64]; - let l = build_normalized_laplacian(&graph, &inv_sqrt_deg); + let l = build_normalized_laplacian(graph.view(), &inv_sqrt_deg); // Diagonal is always 1.0 including isolated node assert!((l.get(2, 2).copied().unwrap_or(0.0) - 1.0).abs() < 1e-15); @@ -250,7 +338,7 @@ mod tests { // inv_sqrt_deg[3] = 1/sqrt(1) = 1.0 let inv_sqrt_deg = vec![1.0f64, 1.0 / 2.0f64.sqrt(), 1.0 / 2.0f64.sqrt(), 1.0f64]; - let l = build_normalized_laplacian(&graph, &inv_sqrt_deg); + let l = build_normalized_laplacian(graph.view(), &inv_sqrt_deg); // All diagonal entries must be exactly 1.0 for i in 0..4 { diff --git a/src/lib.rs b/src/lib.rs index 3155a72..37abb9f 100644 --- a/src/lib.rs +++ b/src/lib.rs @@ -9,8 +9,8 @@ //! # Quick Start //! //! ``` -//! use sprs::CsMatI; -//! use spectral_init::{spectral_init, SpectralInitConfig}; +//! use spectral_init::sprs::CsMatI; +//! use spectral_init::{SpectralInitConfig, spectral_init}; //! //! // 4-node path graph: 0 – 1 – 2 – 3 (symmetric, f32 weights) //! let graph = CsMatI::::new( @@ -19,8 +19,8 @@ //! vec![1u32, 0u32, 2u32, 1u32, 3u32, 2u32], //! vec![1.0f32; 6], //! ); -//! let coords = spectral_init(&graph, 2, 42, None, SpectralInitConfig::default()) -//! .expect("spectral_init failed"); +//! let config = SpectralInitConfig::new(2).with_seed(42); +//! let coords = spectral_init(graph.view(), None, &config).expect("spectral_init failed"); //! assert_eq!(coords.shape(), &[4, 2]); //! for &v in coords.iter() { //! assert!(v.is_finite()); @@ -62,11 +62,21 @@ //! //! # Error Handling //! -//! All errors are returned as [`SpectralError`] variants. The most common are -//! [`SpectralError::InvalidGraph`] (malformed input) and -//! [`SpectralError::TooFewNodes`] (embedding dimensionality exceeds graph size). -//! [`SpectralError::ConvergenceFailure`] should not occur in practice; if it does, -//! it indicates a degenerate graph or a bug — please file an issue. +//! Every failure is a [`SpectralError`] variant; the crate never substitutes a random +//! layout. Inputs are validated before any computation: the graph must be square, +//! symmetric and have finite, non-negative weights +//! ([`SpectralError::NotSquare`], [`SpectralError::NotSymmetric`], +//! [`SpectralError::NonFiniteWeight`], [`SpectralError::NegativeWeight`]), with more +//! nodes than embedding dimensions ([`SpectralError::TooFewNodes`]). +//! [`SpectralError::DenseBudgetExceeded`] and [`SpectralError::ConvergenceFailure`] +//! report that no solver could produce acceptable eigenvectors within the configured +//! dense memory budget. See [`spectral_init`] for the full list and a fallback example. +//! +//! # Public Dependencies +//! +//! The graph and array types in the signature of [`spectral_init`] come from the +//! [`sprs`] and [`ndarray`] crates, which are re-exported so that callers can name the +//! exact versions this crate was built against. //! //! # User Guide //! @@ -76,14 +86,18 @@ mod components; mod config; +mod error; mod laplacian; mod multi_component; mod operator; mod scaling; mod selection; mod solvers; +mod validate; pub use config::{ComputeMode, SpectralInitConfig}; +pub use error::SpectralError; +pub use {ndarray, sprs}; /// Internal pipeline pieces for this crate's own integration tests and research harness. /// @@ -123,58 +137,69 @@ pub mod __internal { } use ndarray::{Array2, ArrayView2}; -use sprs::CsMatI; - -/// Errors returned by the spectral initialization pipeline. -#[derive(Debug, thiserror::Error)] -pub enum SpectralError { - /// The eigensolver escalation chain exhausted all levels without converging. - /// This should never occur in practice; if seen, it indicates a degenerate graph. - /// This indicates a degenerate graph or a bug in the solver chain. If encountered - /// in production, please file an issue at the repository. - #[error("eigensolver failed to converge after full escalation chain")] - ConvergenceFailure, - - /// The graph adjacency matrix is malformed (non-square, negative weights, NaN/Inf). - /// Verify that the adjacency matrix is square, has non-negative finite weights, - /// and that `n > 0` and `n_components > 0`. - #[error("invalid graph: {0}")] - InvalidGraph(String), - - /// The graph has fewer nodes than the requested embedding dimensionality. - /// Reduce `n_components` or provide a graph with more nodes than the requested - /// embedding dimensionality. - #[error("graph has too few nodes ({n}) for {dims}-dimensional embedding")] - TooFewNodes { - /// Number of nodes in the graph. - n: usize, - /// Requested number of embedding dimensions. - dims: usize, - }, -} +use sprs::CsMatViewI; -/// Compute spectral initialization coordinates for a UMAP fuzzy k-NN graph. +/// Computes spectral initialization coordinates for a symmetric, non-negative graph. /// /// Builds the symmetric normalized Laplacian of `graph`, computes its `n_components` /// smallest non-trivial eigenvectors via an automatic solver escalation chain, scales -/// coordinates to `[-10, 10]`, and adds small Gaussian noise. +/// the coordinates so that the largest magnitude is 10, and adds Gaussian noise with +/// standard deviation 10⁻⁴. +/// +/// # Inputs +/// +/// - `graph` — the weighted adjacency matrix: square, symmetric, with finite +/// non-negative weights, in CSR or CSC storage. Stored zeros are absent edges. +/// Diagonal entries (self-loops) count towards both degree and adjacency. +/// - `data` — the points the graph was built from, one row per node. It is consulted +/// only when the graph has more than `2 · n_components` connected components, where +/// it places the components relative to one another; otherwise it may be `None`. +/// When supplied it is always validated, even if it ends up unused. +/// - `config` — embedding dimensionality, seed, [`ComputeMode`] and dense memory +/// budget; see [`SpectralInitConfig`]. +/// +/// # Returns +/// +/// An `(n, n_components)` array in standard layout (C-contiguous, row-major), so +/// `as_slice()` succeeds on it. For a fixed `Cargo.lock`, target, CPU feature set and +/// thread configuration the result is deterministic in `config`. /// /// # Errors /// -/// - [`SpectralError::InvalidGraph`] — `n == 0`, `n_components == 0`, or the graph -/// adjacency matrix is malformed (non-square, negative weights, NaN/Inf values). -/// **Fix:** validate your adjacency matrix before calling this function. -/// - [`SpectralError::TooFewNodes`] — the graph has fewer nodes than `n_components`. -/// **Fix:** reduce `n_components` or use a larger dataset. -/// - [`SpectralError::ConvergenceFailure`] — the full 6-level solver escalation chain -/// exhausted without converging. This should not occur on any valid graph. -/// **Fix:** file a bug at . +/// Inputs are validated first, in this order of precedence: +/// +/// - [`SpectralError::InvalidParameter`] — `n_components` is 0. +/// - [`SpectralError::NotSquare`] — `graph` is not square. +/// - [`SpectralError::TooFewNodes`] — the graph does not have more nodes than +/// `n_components` (this covers the empty graph). +/// - [`SpectralError::NonFiniteWeight`] — a weight is NaN or infinite. +/// - [`SpectralError::NegativeWeight`] — a weight is negative. +/// - [`SpectralError::NotSymmetric`] — an entry has no matching mirror entry (relative +/// differences up to 10⁻⁶ are tolerated). +/// - [`SpectralError::DegreeOverflow`] — a node's summed weights overflow `f32`. +/// - [`SpectralError::DataShapeMismatch`] — `data` does not have one row per node. +/// - [`SpectralError::NonFiniteData`] — `data` contains NaN or an infinity. +/// +/// The computation itself can fail with: +/// +/// - [`SpectralError::DataRequired`] — the graph has more than `2 · n_components` +/// connected components and `data` is `None`. +/// - [`SpectralError::DenseBudgetExceeded`] — the iterative solvers did not converge and +/// the dense fallback needs a matrix larger than the dense memory budget, or the graph +/// has so many connected components that their affinity matrix exceeds it. +/// - [`SpectralError::ConvergenceFailure`] — no solver produced eigenvectors of +/// acceptable quality. +/// - [`SpectralError::DegenerateEmbedding`] — the computed coordinates are all zero. +/// +/// The function does not panic on any input. A dense matrix within the budget is +/// allocated like any other Rust allocation: if the system cannot provide the memory, +/// the process aborts. /// /// # Examples /// /// ``` -/// use sprs::CsMatI; -/// use spectral_init::{spectral_init, SpectralInitConfig}; +/// use spectral_init::sprs::CsMatI; +/// use spectral_init::{SpectralInitConfig, spectral_init}; /// /// // 4-node path graph: 0 – 1 – 2 – 3 /// let graph = CsMatI::::new( @@ -183,116 +208,174 @@ pub enum SpectralError { /// vec![1u32, 0u32, 2u32, 1u32, 3u32, 2u32], /// vec![1.0f32; 6], /// ); -/// let coords = spectral_init(&graph, 2, 42, None, SpectralInitConfig::default())?; +/// let coords = spectral_init(graph.view(), None, &SpectralInitConfig::new(2))?; /// assert_eq!(coords.shape(), &[4, 2]); +/// assert!(coords.is_standard_layout()); /// # Ok::<(), spectral_init::SpectralError>(()) /// ``` +/// +/// umap-learn falls back to a random layout when its spectral layout fails. This crate +/// reports the failure instead, so the caller decides what to substitute: +/// +/// ``` +/// use spectral_init::ndarray::Array2; +/// use spectral_init::sprs::CsMatI; +/// use spectral_init::{SpectralError, SpectralInitConfig, spectral_init}; +/// +/// /// The caller's own fallback layout (here: a fixed grid). +/// fn fallback_init(n: usize, n_components: usize) -> Array2 { +/// Array2::from_shape_fn((n, n_components), |(i, j)| (i * (j + 1)) as f32) +/// } +/// +/// fn initial_coordinates( +/// graph: &CsMatI, +/// config: &SpectralInitConfig, +/// ) -> Result, SpectralError> { +/// match spectral_init(graph.view(), None, config) { +/// Ok(coords) => Ok(coords), +/// // The solvers gave up: substitute the fallback. +/// Err( +/// SpectralError::ConvergenceFailure { .. } +/// | SpectralError::DenseBudgetExceeded { .. } +/// | SpectralError::DegenerateEmbedding, +/// ) => Ok(fallback_init(graph.rows(), config.n_components())), +/// // Anything else is a problem with the inputs: report it. +/// Err(other) => Err(other), +/// } +/// } +/// +/// let graph = CsMatI::::new( +/// (4, 4), +/// vec![0usize, 1, 3, 5, 6], +/// vec![1u32, 0u32, 2u32, 1u32, 3u32, 2u32], +/// vec![1.0f32; 6], +/// ); +/// let coords = initial_coordinates(&graph, &SpectralInitConfig::new(2))?; +/// assert_eq!(coords.shape(), &[4, 2]); +/// # Ok::<(), SpectralError>(()) +/// ``` pub fn spectral_init( - graph: &CsMatI, - n_components: usize, - seed: u64, + graph: CsMatViewI<'_, f32, u32, usize>, data: Option>, - config: SpectralInitConfig, + config: &SpectralInitConfig, ) -> Result, SpectralError> { - // ── Input validation ────────────────────────────────────────────────── + let graph = validate::validate(graph, data, config)?; let n = graph.rows(); - if n == 0 || n_components == 0 { - return Err(SpectralError::InvalidGraph(format!( - "spectral_init requires n > 0 and n_components > 0; got n={n}, n_components={n_components}" - ))); - } - if n <= n_components { - return Err(SpectralError::TooFewNodes { - n, - dims: n_components, - }); - } - - let solver_params = solvers::SolverParams::default(); + let n_components = config.n_components(); + let seed = config.seed(); + let compute_mode = config.compute_mode(); + let solver_params = solvers::SolverParams::from_config(config); // ── Component A: connectivity check ─────────────────────────────────── let (labels, n_conn_components) = components::find_components(graph); - if n_conn_components > 1 { - let coords = crate::multi_component::embed_disconnected( + let coords = if n_conn_components > 1 { + multi_component::embed_disconnected( graph, &labels, n_conn_components, n_components, seed, data, - config.compute_mode, + compute_mode, &solver_params, - )?; - return scaling::scale_and_add_noise(coords, seed); - } + )? + } else { + // ── Component B: degrees and inverse-square-root degrees ────────── + let (_degrees, sqrt_deg) = laplacian::compute_degrees(graph, compute_mode); + let inv_sqrt_deg: Vec = sqrt_deg + .iter() + .map(|&s| if s > 0.0 { 1.0 / s } else { 0.0 }) + .collect(); - // ── Component B: degrees and inverse-square-root degrees ────────────── - let (_degrees, sqrt_deg) = laplacian::compute_degrees(graph, config.compute_mode); - let inv_sqrt_deg: Vec = sqrt_deg - .iter() - .map(|&s| if s > 0.0 { 1.0 / s } else { 0.0 }) - .collect(); + // ── Component C: normalized Laplacian ───────────────────────────── + let lap = laplacian::build_normalized_laplacian(graph, &inv_sqrt_deg); - // ── Component C: normalized Laplacian ───────────────────────────────── - let lap = laplacian::build_normalized_laplacian(graph, &inv_sqrt_deg); - - // ── Component D: eigensolver escalation chain ───────────────────────── - let ((eigenvalues, eigenvectors), report) = solvers::solve_eigenproblem( - &lap, - n_components, - seed, - &sqrt_deg, - config.compute_mode, - &solver_params, - )?; - report.log("connected graph", n); + // ── Component D: eigensolver escalation chain ───────────────────── + let ((eigenvalues, eigenvectors), report) = solvers::solve_eigenproblem( + &lap, + n_components, + seed, + &sqrt_deg, + compute_mode, + &solver_params, + )?; + report.log("connected graph", n); - // ── Component E: eigenvector selection ──────────────────────────────── - let mut selected = selection::select_eigenvectors( - eigenvalues - .as_slice_memory_order() - .expect("eigenvalues must be contiguous"), - &eigenvectors, - n_components, - ); + // ── Component E: eigenvector selection ──────────────────────────── + // The solver returns `n_components + 1` eigenpairs, as `select_eigenvectors` needs. + let mut selected = + selection::select_eigenvectors(&eigenvalues.to_vec(), &eigenvectors, n_components); - // ── Component E.5: sign normalization ───────────────────────────────── - // Enforce argmax sign convention: element with largest absolute value must be positive. - // Ensures consistent signs across runs; verified by the sign-convention integration test. - scaling::normalize_signs(&mut selected); + // ── Component E.5: sign normalization ───────────────────────────── + // Enforce argmax sign convention: element with largest absolute value must be positive. + // Ensures consistent signs across runs; verified by the sign-convention integration test. + scaling::normalize_signs(&mut selected); + selected + }; // ── Component F: scale and add noise ────────────────────────────────── - scaling::scale_and_add_noise(selected, seed) + let embedding = scaling::scale_and_add_noise(coords, seed)?; + Ok(into_standard_layout(embedding)) +} + +/// Returns `array` in standard (C-contiguous, row-major) layout, copying only when it is +/// not already laid out that way. +fn into_standard_layout(array: Array2) -> Array2 { + if array.is_standard_layout() { + array + } else { + array.as_standard_layout().into_owned() + } } #[cfg(test)] mod tests { use super::*; + use sprs::CsMatI; + + /// 4-node path graph: 0-1-2-3 + fn path_4() -> CsMatI { + CsMatI::::new( + (4, 4), + vec![0usize, 1, 3, 5, 6], + vec![1u32, 0u32, 2u32, 1u32, 3u32, 2u32], + vec![1.0f32; 6], + ) + } + + fn config() -> SpectralInitConfig { + SpectralInitConfig::new(2).with_seed(42) + } #[test] fn spectral_error_is_std_error() { - let e: &dyn std::error::Error = &SpectralError::ConvergenceFailure; + let e: &dyn std::error::Error = &SpectralError::ConvergenceFailure { n: 3 }; assert!(!e.to_string().is_empty()); } #[test] fn spectral_init_zero_components_returns_error() { - // 3-node path graph (0-1-2): valid CSR construction - let g = CsMatI::::new( - (3, 3), - vec![0usize, 1, 3, 4], - vec![1u32, 0u32, 2u32, 1u32], - vec![1.0f32; 4], - ); - let result = spectral_init(&g, 0, 42, None, SpectralInitConfig::default()); - assert!(matches!(result, Err(SpectralError::InvalidGraph(_)))); + let result = spectral_init(path_4().view(), None, &SpectralInitConfig::new(0)); + assert!(matches!( + result, + Err(SpectralError::InvalidParameter { + name: "n_components", + .. + }) + )); } #[test] fn spectral_init_empty_graph_returns_error() { let g = CsMatI::::new((0, 0), vec![0usize], vec![], vec![]); - let result = spectral_init(&g, 2, 42, None, SpectralInitConfig::default()); - assert!(matches!(result, Err(SpectralError::InvalidGraph(_)))); + let result = spectral_init(g.view(), None, &config()); + assert_eq!( + result, + Err(SpectralError::TooFewNodes { + n: 0, + n_components: 2 + }) + ); } #[test] @@ -304,23 +387,19 @@ mod tests { vec![1u32, 0u32], vec![1.0f32; 2], ); - let result = spectral_init(&g, 3, 42, None, SpectralInitConfig::default()); - assert!(matches!( + let result = spectral_init(g.view(), None, &SpectralInitConfig::new(3)); + assert_eq!( result, - Err(SpectralError::TooFewNodes { n: 2, dims: 3 }) - )); + Err(SpectralError::TooFewNodes { + n: 2, + n_components: 3 + }) + ); } #[test] fn spectral_init_connected_graph_succeeds_and_has_correct_shape() { - // 4-node path graph: 0-1-2-3 - let g = CsMatI::::new( - (4, 4), - vec![0usize, 1, 3, 5, 6], - vec![1u32, 0u32, 2u32, 1u32, 3u32, 2u32], - vec![1.0f32; 6], - ); - let result = spectral_init(&g, 2, 42, None, SpectralInitConfig::default()); + let result = spectral_init(path_4().view(), None, &config()); let arr = result.expect("spectral_init on connected graph should succeed"); assert_eq!(arr.shape(), &[4, 2]); for &v in arr.iter() { @@ -330,15 +409,8 @@ mod tests { #[test] fn spectral_init_output_respects_sign_convention() { - // 4-node path graph: 0-1-2-3 - let g = CsMatI::::new( - (4, 4), - vec![0usize, 1, 3, 5, 6], - vec![1u32, 0u32, 2u32, 1u32, 3u32, 2u32], - vec![1.0f32; 6], - ); - let result = spectral_init(&g, 2, 42, None, SpectralInitConfig::default()) - .expect("spectral_init should succeed"); + let result = + spectral_init(path_4().view(), None, &config()).expect("spectral_init should succeed"); // For each column, the element with the largest absolute value must be positive. // normalize_signs (argmax convention) runs before scale_and_add_noise. // Noise scale is 1e-4; scaled coords are ~10 — noise cannot flip the argmax sign. @@ -359,16 +431,59 @@ mod tests { ); } } + + #[test] + fn into_standard_layout_preserves_values() { + let fortran = ndarray::Array2::from_shape_vec( + ndarray::ShapeBuilder::f((3, 2)), + vec![1.0_f32, 3.0, 5.0, 2.0, 4.0, 6.0], + ) + .unwrap(); + assert!(!fortran.is_standard_layout()); + assert_eq!( + fortran, + ndarray::array![[1.0_f32, 2.0], [3.0, 4.0], [5.0, 6.0]] + ); + + let standard = into_standard_layout(fortran); + assert!(standard.is_standard_layout()); + assert_eq!( + standard.as_slice(), + Some(&[1.0_f32, 2.0, 3.0, 4.0, 5.0, 6.0][..]) + ); + } } #[cfg(test)] mod config_tests { use super::*; + use sprs::CsMatI; #[test] - fn default_config_is_python_compat() { - let cfg = SpectralInitConfig::default(); - assert_eq!(cfg.compute_mode, ComputeMode::PythonCompat); + fn new_config_has_documented_defaults() { + let cfg = SpectralInitConfig::new(3); + assert_eq!(cfg.n_components(), 3); + assert_eq!(cfg.seed(), 0); + assert_eq!(cfg.compute_mode(), ComputeMode::PythonCompat); + assert_eq!( + cfg.dense_memory_budget(), + SpectralInitConfig::DEFAULT_DENSE_MEMORY_BUDGET + ); + assert_eq!(SpectralInitConfig::DEFAULT_DENSE_MEMORY_BUDGET, 1 << 32); + } + + #[test] + fn config_setters_change_only_their_field() { + let cfg = SpectralInitConfig::new(2) + .with_seed(7) + .with_compute_mode(ComputeMode::RustNative) + .with_dense_memory_budget(1024); + assert_eq!(cfg.n_components(), 2); + assert_eq!(cfg.seed(), 7); + assert_eq!(cfg.compute_mode(), ComputeMode::RustNative); + assert_eq!(cfg.dense_memory_budget(), 1024); + assert_eq!(cfg.clone(), cfg); + assert_ne!(cfg, SpectralInitConfig::new(2)); } #[test] @@ -412,18 +527,13 @@ mod config_tests { vec![1u32, 0u32, 2u32, 1u32, 3u32, 2u32], vec![1.0f32; 6], ); - let r1 = spectral_init(&g, 2, 42, None, SpectralInitConfig::default()) - .expect("PythonCompat should succeed"); - let r2 = spectral_init( - &g, - 2, - 42, - None, - SpectralInitConfig { - compute_mode: ComputeMode::RustNative, - }, - ) - .expect("RustNative should succeed"); + let python_compat = SpectralInitConfig::new(2).with_seed(42); + let rust_native = python_compat + .clone() + .with_compute_mode(ComputeMode::RustNative); + let r1 = + spectral_init(g.view(), None, &python_compat).expect("PythonCompat should succeed"); + let r2 = spectral_init(g.view(), None, &rust_native).expect("RustNative should succeed"); assert_eq!(r1.shape(), r2.shape()); let n_cols = r1.shape()[1]; for col in 0..n_cols { @@ -439,16 +549,4 @@ mod config_tests { ); } } - - #[test] - fn spectral_init_with_default_config_compiles_and_runs() { - let g = CsMatI::::new( - (4, 4), - vec![0usize, 1, 3, 5, 6], - vec![1u32, 0u32, 2u32, 1u32, 3u32, 2u32], - vec![1.0f32; 6], - ); - let result = spectral_init(&g, 2, 42, None, SpectralInitConfig::default()); - assert!(result.is_ok()); - } } diff --git a/src/multi_component.rs b/src/multi_component.rs index ba7a4cf..e59ae83 100644 --- a/src/multi_component.rs +++ b/src/multi_component.rs @@ -1,20 +1,25 @@ use ndarray::{Array2, ArrayView1, ArrayView2}; -use sprs::{CsMatI, TriMat}; +use sprs::{CsMatI, CsMatViewI, TriMat}; use crate::{ ComputeMode, SpectralError, laplacian::{build_normalized_laplacian, compute_degrees}, scaling, selection::select_eigenvectors, - solvers::{SolverParams, solve_eigenproblem}, + solvers::{SolverParams, check_dense_budget, solve_eigenproblem}, }; /// Computes spectral embedding for disconnected graphs. /// Each component is embedded independently; component embeddings are aligned /// into a common coordinate frame via centroid meta-embedding. +/// +/// `graph` must be a square, symmetric CSR matrix, `component_labels` its component +/// labelling with `n_conn_components` distinct labels, and `data`, when given, must have +/// one row per node. `data` is read only when there are more than `2 * n_embedding_dims` +/// components; without it that case returns [`SpectralError::DataRequired`]. #[allow(clippy::too_many_arguments)] pub fn embed_disconnected( - graph: &CsMatI, + graph: CsMatViewI<'_, f32, u32, usize>, component_labels: &[usize], n_conn_components: usize, n_embedding_dims: usize, @@ -41,11 +46,10 @@ pub fn embed_disconnected( params, )?, None => { - return Err(SpectralError::InvalidGraph( - "data is required for spectral meta-embedding when \ - n_conn_components > 2 * n_embedding_dims" - .into(), - )); + return Err(SpectralError::DataRequired { + connected_components: n_conn_components, + n_components: n_embedding_dims, + }); } } } else { @@ -83,6 +87,7 @@ pub fn embed_disconnected( fn collect_component_members(labels: &[usize], n_conn_components: usize) -> Vec> { let mut members: Vec> = vec![Vec::new(); n_conn_components]; for (node, &label) in labels.iter().enumerate() { + // Labels come from `find_components`, which numbers components `0..n_conn_components`. members[label].push(node); } members @@ -91,7 +96,7 @@ fn collect_component_members(labels: &[usize], n_conn_components: usize) -> Vec< /// Extracts the subgraph induced by `node_indices` from the full graph, /// re-indexing nodes to `0..node_indices.len()`. fn extract_subgraph( - graph: &CsMatI, + graph: CsMatViewI<'_, f32, u32, usize>, node_indices: &[usize], ) -> CsMatI { let n_global = graph.rows(); @@ -115,6 +120,8 @@ fn extract_subgraph( if let Some(row_vec) = graph.outer_view(orig_row) { for (orig_col, &weight) in row_vec.iter() { if lookup[orig_col] != usize::MAX { + // A member's local index never exceeds its original index, and + // original column indices are stored as u32. let local_col = u32::try_from(lookup[orig_col]) .expect("local index overflows u32; component size exceeds u32::MAX"); indices.push(local_col); @@ -125,6 +132,8 @@ fn extract_subgraph( indptr[local_row + 1] = indices.len(); } + // `node_indices` is ascending, so the re-indexed columns of each row stay sorted and + // the structure is valid CSR. CsMatI::::new((n_comp, n_comp), indptr, indices, data) } @@ -157,6 +166,9 @@ fn spectral_meta_embedding( ) -> Result, SpectralError> { let n_features = data.ncols(); + // The centroid affinity matrix is dense: one entry per pair of components. + check_dense_budget(n_comp, n_comp, params.dense_memory_budget)?; + // Compute per-component centroids in f64 let mut centroids = Array2::::zeros((n_comp, n_features)); for (c, members) in component_members.iter().enumerate() { @@ -220,16 +232,12 @@ fn spectral_meta_embedding( params, )?; report.log("component meta-embedding", n_comp); - let evals_slice = evals - .as_slice_memory_order() - .ok_or(SpectralError::ConvergenceFailure)?; - let selected = select_eigenvectors(evals_slice, &evecs, n_embedding_dims); + // The solver returns `n_embedding_dims + 1` eigenpairs, as `select_eigenvectors` needs. + let selected = select_eigenvectors(&evals.to_vec(), &evecs, n_embedding_dims); let max_abs = selected.fold(0.0_f64, |a, &x| a.max(x.abs())); if max_abs == 0.0 { - return Err(SpectralError::InvalidGraph( - "spectral meta-embedding produced all-zero result".into(), - )); + return Err(SpectralError::DegenerateEmbedding); } Ok(selected / max_abs) } @@ -275,7 +283,7 @@ fn compute_data_range(meta_embedding: &Array2) -> Vec { /// Tiny components (`size < 2 * n_embedding_dims`) are placed directly at `meta_pos`. #[allow(clippy::too_many_arguments)] fn embed_single_component( - graph: &CsMatI, + graph: CsMatViewI<'_, f32, u32, usize>, members: &[usize], n_embedding_dims: usize, data_range: f64, @@ -299,12 +307,12 @@ fn embed_single_component( // Large component: run the standard spectral pipeline on the subgraph let sub_graph = extract_subgraph(graph, members); - let (_degrees, sqrt_deg) = compute_degrees(&sub_graph, compute_mode); + let (_degrees, sqrt_deg) = compute_degrees(sub_graph.view(), compute_mode); let inv_sqrt_deg: Vec = sqrt_deg .iter() .map(|&s| if s > 0.0 { 1.0 / s } else { 0.0 }) .collect(); - let laplacian = build_normalized_laplacian(&sub_graph, &inv_sqrt_deg); + let laplacian = build_normalized_laplacian(sub_graph.view(), &inv_sqrt_deg); let ((evals, evecs), report) = solve_eigenproblem( &laplacian, n_embedding_dims, @@ -314,10 +322,8 @@ fn embed_single_component( params, )?; report.log("component", size); - let evals_slice = evals - .as_slice_memory_order() - .ok_or(SpectralError::ConvergenceFailure)?; - let mut coords = select_eigenvectors(evals_slice, &evecs, n_embedding_dims); + // The solver returns `n_embedding_dims + 1` eigenpairs, as `select_eigenvectors` needs. + let mut coords = select_eigenvectors(&evals.to_vec(), &evecs, n_embedding_dims); scaling::normalize_signs(&mut coords); // Scale to data_range @@ -385,7 +391,7 @@ mod tests { let g = make_two_pair_graph(); // Extract component {0, 1} - let sub01 = extract_subgraph(&g, &[0, 1]); + let sub01 = extract_subgraph(g.view(), &[0, 1]); assert_eq!(sub01.rows(), 2); assert_eq!(sub01.cols(), 2); assert_eq!(sub01.nnz(), 2, "should have edges (0,1) and (1,0)"); @@ -394,7 +400,7 @@ mod tests { } // Extract component {2, 3} – re-indexed to {0, 1} - let sub23 = extract_subgraph(&g, &[2, 3]); + let sub23 = extract_subgraph(g.view(), &[2, 3]); assert_eq!(sub23.rows(), 2); assert_eq!(sub23.cols(), 2); assert_eq!(sub23.nnz(), 2); @@ -404,7 +410,7 @@ mod tests { fn test_extract_subgraph_single_node() { let g = make_two_pair_graph(); // Node 1 has an edge to node 0, but node 0 is not in this subgraph - let sub = extract_subgraph(&g, &[1]); + let sub = extract_subgraph(g.view(), &[1]); assert_eq!(sub.rows(), 1); assert_eq!(sub.cols(), 1); assert_eq!(sub.nnz(), 0, "single-node subgraph should have no edges"); @@ -452,7 +458,7 @@ mod tests { let g = make_two_pair_graph(); let labels = vec![0usize, 0, 1, 1]; let result = embed_disconnected( - &g, + g.view(), &labels, 2, 2, @@ -476,7 +482,7 @@ mod tests { let g = make_empty_pair_graph(); let labels = vec![0usize, 1]; let result = embed_disconnected( - &g, + g.view(), &labels, 2, 2, @@ -520,7 +526,7 @@ mod tests { let g = make_3_clique_graph(); let labels: Vec = (0..12).map(|i| i / 4).collect(); let result = embed_disconnected( - &g, + g.view(), &labels, 3, 2, diff --git a/src/scaling.rs b/src/scaling.rs index 0bc7dc4..8e6459e 100644 --- a/src/scaling.rs +++ b/src/scaling.rs @@ -1,52 +1,29 @@ +use crate::SpectralError; use ndarray::Array2; use rand::SeedableRng; -use rand::rngs::StdRng; -use rand_distr::{Distribution, Normal}; +use rand_chacha::ChaCha12Rng; +use rand_distr::{Distribution, StandardNormal}; + +/// Largest absolute coordinate after scaling. +const MAX_COORD: f64 = 10.0; + +/// Standard deviation of the Gaussian noise added to the scaled coordinates. +const NOISE_SCALE: f32 = 0.0001; /// Internal helper: deterministic scaling only (no noise). /// Scales `coords` so the global max absolute value equals `max_coord`, then /// casts to f32. -pub fn scale_coords( - coords: &Array2, - max_coord: f64, -) -> Result, crate::SpectralError> { +/// +/// Returns [`SpectralError::DegenerateEmbedding`] when every coordinate is zero. +pub fn scale_coords(coords: &Array2, max_coord: f64) -> Result, SpectralError> { let max_abs = coords.iter().cloned().map(f64::abs).fold(0.0_f64, f64::max); if max_abs <= 0.0 { - return Err(crate::SpectralError::InvalidGraph(format!( - "scale_coords: embedding is all-zero; cannot scale to max={max_coord}" - ))); + return Err(SpectralError::DegenerateEmbedding); } let expansion = max_coord / max_abs; Ok(coords.mapv(|x| (x * expansion) as f32)) } -/// Internal helper: scale then add per-element Gaussian noise. -pub(crate) fn noisy_scale_coords( - coords: &Array2, - rng: &mut impl rand::Rng, - max_coord: f64, - noise_scale: f64, -) -> Result, crate::SpectralError> { - if !noise_scale.is_finite() || noise_scale <= 0.0 { - return Err(crate::SpectralError::InvalidGraph(format!( - "noise_scale must be finite and positive, got {noise_scale}" - ))); - } - let noise_scale_f32 = noise_scale as f32; - if noise_scale_f32 <= 0.0 { - return Err(crate::SpectralError::InvalidGraph(format!( - "noise_scale {noise_scale} underflows to zero when cast to f32" - ))); - } - let mut scaled = scale_coords(coords, max_coord)?; - let normal = Normal::::new(0.0, noise_scale_f32) - .expect("noise_scale_f32 is validated positive and finite"); - for elem in scaled.iter_mut() { - *elem += normal.sample(rng); - } - Ok(scaled) -} - /// Enforces a deterministic sign convention (argmax convention) on each eigenvector column. /// /// For each column of `coords`, finds the element with the largest absolute value. @@ -80,17 +57,79 @@ pub fn normalize_signs(coords: &mut Array2) { } } -/// Scales columns so max absolute value is 10.0, then adds Gaussian noise -/// with scale=0.0001. Downcasts to f32. -pub fn scale_and_add_noise( - coords: Array2, - seed: u64, -) -> Result, crate::SpectralError> { - if coords.is_empty() { - return Err(crate::SpectralError::InvalidGraph( - "scale_and_add_noise: input embedding is empty".to_string(), - )); +/// Scales all coordinates by one factor so the largest absolute value is 10.0, then adds +/// Gaussian noise with standard deviation 0.0001. Downcasts to f32. +/// +/// The noise is drawn in logical (row-major) element order from a generator seeded with +/// `seed`. Returns [`SpectralError::DegenerateEmbedding`] when every coordinate is zero, +/// which includes an empty input. +pub fn scale_and_add_noise(coords: Array2, seed: u64) -> Result, SpectralError> { + let mut scaled = scale_coords(&coords, MAX_COORD)?; + let mut rng = ChaCha12Rng::seed_from_u64(seed); + for elem in scaled.iter_mut() { + let z: f32 = StandardNormal.sample(&mut rng); + // Mean 0 plus scale times a standard-normal draw, as `rand_distr::Normal` computes it. + *elem += 0.0 + NOISE_SCALE * z; + } + Ok(scaled) +} + +#[cfg(test)] +mod tests { + use super::*; + use rand_distr::Normal; + + #[test] + fn scale_coords_maps_the_largest_magnitude_to_max_coord() { + let coords = Array2::from_shape_vec((2, 2), vec![0.5_f64, -2.0, 1.0, 0.25]).unwrap(); + let scaled = scale_coords(&coords, 10.0).unwrap(); + assert_eq!(scaled, ndarray::array![[2.5_f32, -10.0], [5.0, 1.25]]); + } + + #[test] + fn scale_coords_rejects_all_zero_input() { + let coords = Array2::::zeros((3, 2)); + assert_eq!( + scale_coords(&coords, 10.0), + Err(SpectralError::DegenerateEmbedding) + ); + } + + #[test] + fn scale_and_add_noise_rejects_empty_input() { + let coords = Array2::::zeros((0, 2)); + assert_eq!( + scale_and_add_noise(coords, 42), + Err(SpectralError::DegenerateEmbedding) + ); + } + + #[test] + fn noise_equals_a_normal_distribution_with_the_documented_scale() { + // Same seed, same draw order: the noise must be bit-identical to sampling + // `Normal(0, NOISE_SCALE)` element by element. + let coords = Array2::from_shape_fn((7, 3), |(i, j)| (i as f64 - 3.0) * (j as f64 + 1.0)); + let seed = 42; + let noisy = scale_and_add_noise(coords.clone(), seed).unwrap(); + + let mut expected = scale_coords(&coords, MAX_COORD).unwrap(); + let mut rng = ChaCha12Rng::seed_from_u64(seed); + let normal = Normal::::new(0.0, NOISE_SCALE).unwrap(); + for elem in expected.iter_mut() { + *elem += normal.sample(&mut rng); + } + assert_eq!(noisy, expected); + } + + #[test] + fn normalize_signs_makes_the_largest_magnitude_positive() { + let mut coords = + Array2::from_shape_vec((3, 2), vec![1.0_f64, 0.5, -3.0, -0.25, 2.0, 0.1]).unwrap(); + normalize_signs(&mut coords); + // Column 0: largest magnitude is -3.0 → flipped. Column 1: 0.5 is positive → kept. + assert_eq!( + coords, + ndarray::array![[-1.0_f64, 0.5], [3.0, -0.25], [-2.0, 0.1]] + ); } - let mut rng = StdRng::seed_from_u64(seed); - noisy_scale_coords(&coords, &mut rng, 10.0, 0.0001) } diff --git a/src/selection.rs b/src/selection.rs index 205f672..ed97942 100644 --- a/src/selection.rs +++ b/src/selection.rs @@ -19,11 +19,7 @@ pub fn select_eigenvectors( eigenvalues.len() ); let mut indices: Vec = (0..eigenvalues.len()).collect(); - indices.sort_by(|&a, &b| { - eigenvalues[a] - .partial_cmp(&eigenvalues[b]) - .unwrap_or(std::cmp::Ordering::Equal) - }); + indices.sort_by(|&a, &b| eigenvalues[a].total_cmp(&eigenvalues[b])); eigenvectors.select(Axis(1), &indices[1..1 + n_components]) } diff --git a/src/solvers/dense.rs b/src/solvers/dense.rs index 96e8f3a..38aac67 100644 --- a/src/solvers/dense.rs +++ b/src/solvers/dense.rs @@ -1,29 +1,43 @@ -//! Dense eigendecomposition via faer (Level 0 of the solver escalation chain). +//! Dense eigendecomposition via faer (Levels 0 and 5 of the solver escalation chain). //! -//! Used when `n < 2000`. Converts the sparse Laplacian to a dense `faer::Mat`, -//! calls `self_adjoint_eigen`, and returns the `k` smallest eigenpairs sorted ascending. +//! Converts the sparse Laplacian to a dense `faer::Mat`, calls `self_adjoint_eigen`, +//! and returns the `k` smallest eigenpairs sorted ascending. //! -//! **Chain position:** Level 0 — exact, O(n³). Skipped for `n ≥ 2000`. +//! **Chain position:** Level 0 — exact, O(n³), tried first for `n < 2000` — and Level 5, +//! the last resort for any `n`. //! -//! **Failure mode:** Returns [`SpectralError::ConvergenceFailure`] if faer's -//! self-adjoint EVD fails (practically impossible for a valid PSD matrix). -//! The residual quality gate (`< 1e-6`) then determines whether to accept the result -//! or escalate to Level 1. +//! **Failure modes:** Returns [`SpectralError::DenseBudgetExceeded`] when the dense +//! `n × n` matrix would exceed the dense memory budget, and +//! [`SpectralError::ConvergenceFailure`] if faer's self-adjoint EVD fails (practically +//! impossible for a valid PSD matrix). The residual quality gate (`< 1e-6`) then +//! determines whether the chain accepts the result. -use super::EigenResult; +use super::{EigenResult, check_dense_budget}; use crate::SpectralError; use faer::{Mat, Side}; use ndarray::{Array1, Array2}; use sprs::CsMatI; -/// Dense eigendecomposition via faer for small n. +/// Dense eigendecomposition via faer. /// Returns (eigenvalues of shape `[k]`, eigenvectors of shape `[n, k]`) sorted ascending by /// eigenvalue. -pub fn dense_evd(laplacian: &CsMatI, k: usize) -> Result { +/// +/// `k` is the number of eigenpairs, i.e. the embedding dimensionality plus one. Errors +/// with `TooFewNodes` when `k > n` and with `DenseBudgetExceeded` when the dense `n × n` +/// matrix needs more than `dense_memory_budget` bytes. +pub fn dense_evd( + laplacian: &CsMatI, + k: usize, + dense_memory_budget: u64, +) -> Result { let n = laplacian.rows(); if k > n { - return Err(SpectralError::TooFewNodes { n, dims: k }); + return Err(SpectralError::TooFewNodes { + n, + n_components: k.saturating_sub(1), + }); } + check_dense_budget(n, n, dense_memory_budget)?; let mut dense = Mat::::zeros(n, n); for (val, (row, col)) in laplacian.iter() { @@ -32,7 +46,7 @@ pub fn dense_evd(laplacian: &CsMatI, k: usize) -> Result, k: usize) -> Result CsMatI { let mut mat = sprs::TriMat::new((n, n)); for &(r, c, v) in triplets { @@ -87,7 +103,7 @@ mod tests { fn dense_evd_trivial_2x2() { // L = [[1, -1], [-1, 1]] eigenvalues: 0.0, 2.0 let l = make_csr(2, &[(0, 0, 1.0), (0, 1, -1.0), (1, 0, -1.0), (1, 1, 1.0)]); - let (eigenvalues, eigenvectors) = dense_evd(&l, 2).expect("dense_evd failed"); + let (eigenvalues, eigenvectors) = dense_evd(&l, 2, NO_LIMIT).expect("dense_evd failed"); assert_eq!(eigenvalues.len(), 2); assert!( @@ -111,7 +127,7 @@ mod tests { fn dense_evd_identity_3x3() { // L = I_3, all eigenvalues = 1.0 let l = make_csr(3, &[(0, 0, 1.0), (1, 1, 1.0), (2, 2, 1.0)]); - let (eigenvalues, eigenvectors) = dense_evd(&l, 3).expect("dense_evd failed"); + let (eigenvalues, eigenvectors) = dense_evd(&l, 3, NO_LIMIT).expect("dense_evd failed"); assert_eq!(eigenvalues.len(), 3); for i in 0..3 { @@ -141,7 +157,7 @@ mod tests { (2, 2, 1.0), ], ); - let (eigenvalues, eigenvectors) = dense_evd(&l, 2).expect("dense_evd failed"); + let (eigenvalues, eigenvectors) = dense_evd(&l, 2, NO_LIMIT).expect("dense_evd failed"); assert_eq!(eigenvalues.len(), 2); assert_eq!(eigenvectors.shape(), &[3, 2]); @@ -161,6 +177,26 @@ mod tests { #[test] fn dense_evd_k_greater_than_n_returns_error() { let l = make_csr(2, &[(0, 0, 1.0), (0, 1, -1.0), (1, 0, -1.0), (1, 1, 1.0)]); - assert!(dense_evd(&l, 3).is_err(), "expected Err when k > n"); + assert_eq!( + dense_evd(&l, 3, NO_LIMIT), + Err(SpectralError::TooFewNodes { + n: 2, + n_components: 2 + }) + ); + } + + #[test] + fn dense_evd_respects_the_dense_memory_budget() { + let l = make_csr(2, &[(0, 0, 1.0), (0, 1, -1.0), (1, 0, -1.0), (1, 1, 1.0)]); + // A 2 × 2 f64 matrix needs 32 bytes. + assert!(dense_evd(&l, 2, 32).is_ok()); + assert_eq!( + dense_evd(&l, 2, 31), + Err(SpectralError::DenseBudgetExceeded { + required_bytes: 32, + budget_bytes: 31 + }) + ); } } diff --git a/src/solvers/lobpcg.rs b/src/solvers/lobpcg.rs index bc4362a..dd84b4d 100644 --- a/src/solvers/lobpcg.rs +++ b/src/solvers/lobpcg.rs @@ -28,10 +28,13 @@ use faer::{Mat as FaerMat, Side}; use linfa_linalg::lobpcg::{Order, lobpcg}; use ndarray::{Array1, Array2}; use rand::SeedableRng; -use rand::rngs::StdRng; +use rand_chacha::ChaCha12Rng; use rand_distr::{Distribution, StandardNormal}; // ─── ndarray 0.16 ↔ 0.17 conversion helpers ────────────────────────────────── +// +// Each helper rebuilds an array from exactly `rows * cols` elements read off the source, +// so the `from_shape_vec` calls cannot fail. /// Convert an owned ndarray 0.17 `Array2` to ndarray 0.16 `Array2`. fn to_nd16_array2(a: Array2) -> nd16::Array2 { @@ -256,7 +259,7 @@ pub fn lobpcg_solve( } // Build random initial block [n, k] in ndarray 0.17, then convert to 0.16 for lobpcg. - let mut rng = StdRng::seed_from_u64(seed); + let mut rng = ChaCha12Rng::seed_from_u64(seed); let mut x_init_17: Array2 = Array2::from_shape_fn((n, k), |_| StandardNormal.sample(&mut rng)); @@ -337,6 +340,7 @@ pub fn lobpcg_solve( }; // Extract x_init for this iteration (moved into lobpcg; repopulated on warm restart). + // Every path that reaches the next iteration stores a new starting block first. debug_assert!( x_init_opt.is_some(), "x_init_opt must be set at every loop entry" @@ -426,6 +430,7 @@ pub fn lobpcg_solve( } // ── Rayleigh-Ritz refinement ───────────────────────────────────────── + // `raw_opt` is `Some` here: the `None` case continued or broke out above. let (_, raw_eigvecs) = raw_opt.unwrap(); let refined_opt = rayleigh_ritz_refine(op, raw_eigvecs.clone()); diff --git a/src/solvers/mod.rs b/src/solvers/mod.rs index 2ead191..f5a82e8 100644 --- a/src/solvers/mod.rs +++ b/src/solvers/mod.rs @@ -3,8 +3,8 @@ //! The chain tries progressively more robust (and expensive) solvers in order, //! accepting a result as soon as the max eigenpair residual //! `‖Lv − λv‖ / ‖v‖` falls below the level's quality threshold. -//! Level 5 (forced dense EVD) is the nuclear option — it cannot fail mathematically -//! and is always accepted regardless of residual. +//! Level 5 (forced dense EVD) is the last resort: it runs for any `n` that fits the +//! dense memory budget, and its result is held to the same residual gate as Level 0. //! //! ## Escalation Chain //! @@ -15,14 +15,16 @@ //! | 2 | Level 1 quality failed | Shift-invert LOBPCG (`sinv`) via faer Cholesky | 1e-6 | //! | 3 | Level 2 quality failed | LOBPCG (`lobpcg`) with ε·I regularization | 2e-5 | //! | 4 | Level 3 quality failed | Randomized SVD (`rsvd`) via 2I−L trick | 1e-2 | -//! | 5 | Level 4 quality failed | Forced dense EVD — always accepted | — | +//! | 5 | Level 4 quality failed | Forced dense EVD | 1e-6 | //! -//! A level "fails" when its residual exceeds the threshold, not when it returns an -//! error. Errors (e.g., Cholesky factorization failure in Level 2) also cause -//! escalation, but are treated as silent fallbacks, not panics. +//! A level "fails" when its residual exceeds the threshold, when it returns no result +//! (e.g., Cholesky factorization failure in Level 2), or when the dense matrix it needs +//! (Levels 0 and 4) would exceed the dense memory budget. Each of these escalates to the +//! next level. //! -//! The only panic in this module occurs if Level 5's forced dense EVD returns `Err`, -//! which would indicate an OOM or a faer bug — both are unrecoverable. +//! The chain never panics. It returns an error only from Level 5: +//! `DenseBudgetExceeded` when the dense `n × n` matrix does not fit the budget, and +//! `ConvergenceFailure` when the dense result is not finite or misses its residual gate. mod dense; pub(crate) mod lobpcg; @@ -33,7 +35,7 @@ pub(crate) mod sinv; pub use dense::dense_evd; use crate::SpectralError; -use crate::config::ComputeMode; +use crate::config::{ComputeMode, SpectralInitConfig}; use crate::operator::CsrOperator; use ndarray::{Array1, Array2}; use quality::{ @@ -85,7 +87,7 @@ impl SolverLevel { /// max eigenpair residual is strictly below the level's gate. #[derive(Debug, Clone, Copy, PartialEq)] pub struct QualityGates { - /// Gate for Level 0 (dense EVD). + /// Gate for Levels 0 and 5 (dense EVD). pub dense: f64, /// Gate for Levels 1 and 3 (LOBPCG, plain and regularized). pub lobpcg: f64, @@ -117,6 +119,8 @@ pub struct SolverParams { pub rsvd_nbiter: usize, /// Per-level residual acceptance thresholds. pub gates: QualityGates, + /// Largest dense matrix, in bytes, a solver may allocate. + pub dense_memory_budget: u64, } impl Default for SolverParams { @@ -126,10 +130,46 @@ impl Default for SolverParams { rsvd_oversampling: None, rsvd_nbiter: rsvd::DEFAULT_NBITER, gates: QualityGates::default(), + dense_memory_budget: SpectralInitConfig::DEFAULT_DENSE_MEMORY_BUDGET, } } } +impl SolverParams { + /// The parameters `spectral_init` runs the chain with for `config`. + pub fn from_config(config: &SpectralInitConfig) -> Self { + Self { + dense_memory_budget: config.dense_memory_budget(), + ..Self::default() + } + } +} + +/// Bytes a dense `rows × cols` f64 matrix occupies, saturating at `u64::MAX`. +pub(crate) fn dense_bytes(rows: usize, cols: usize) -> u64 { + (rows as u64) + .checked_mul(cols as u64) + .and_then(|cells| cells.checked_mul(8)) + .unwrap_or(u64::MAX) +} + +/// Errors with `DenseBudgetExceeded` unless a dense `rows × cols` f64 matrix fits in +/// `budget_bytes`. +pub(crate) fn check_dense_budget( + rows: usize, + cols: usize, + budget_bytes: u64, +) -> Result<(), SpectralError> { + let required_bytes = dense_bytes(rows, cols); + if required_bytes > budget_bytes { + return Err(SpectralError::DenseBudgetExceeded { + required_bytes, + budget_bytes, + }); + } + Ok(()) +} + /// What the escalation chain did to produce a result. #[derive(Debug, Clone, PartialEq)] pub struct SolveReport { @@ -198,12 +238,11 @@ fn accepted( /// Level 2: Shift-and-invert LOBPCG via sparse Cholesky. /// Level 3: LOBPCG with ε·I regularization. /// Level 4: Randomized SVD via 2I-L trick. -/// Level 5: Forced dense EVD (nuclear option, cannot fail). +/// Level 5: Forced dense EVD. /// -/// # Panics +/// # Errors /// -/// Panics at Level 5 exhaustion — this represents a bug, not a user error. -/// The spectral theorem guarantees eigenvectors exist for any symmetric PSD matrix. +/// Only Level 5 produces errors; see the module documentation. fn solve_eigenproblem_with_op( laplacian: &CsMatI, op: O, @@ -219,7 +258,7 @@ fn solve_eigenproblem_with_op( // Level 0: Dense EVD — exact, used for small n where O(n³) is acceptable. if n < params.dense_n_threshold { let started = Instant::now(); - let l0_result = dense_evd(laplacian, n_components + 1); + let l0_result = dense_evd(laplacian, n_components + 1, params.dense_memory_budget); level_elapsed[SolverLevel::DenseEvd as usize] = Some(started.elapsed()); match l0_result { Ok((eigs, vecs)) => { @@ -240,6 +279,9 @@ fn solve_eigenproblem_with_op( (max_residual={quality:.2e}), escalating to Level 1" ); } + Err(e @ SpectralError::DenseBudgetExceeded { .. }) => { + log::debug!("[spectral] Level 0 (dense EVD) skipped ({e}), escalating to Level 1"); + } Err(e) => { log::warn!("[spectral] Level 0 (dense EVD) failed ({e}), escalating to Level 1"); } @@ -321,48 +363,54 @@ fn solve_eigenproblem_with_op( ); } - // Level 4: Randomized SVD via 2I-L trick. - // rsvd_solve is infallible; gate on output quality via residual check. - { - let started = Instant::now(); - let (eigs, vecs) = rsvd::rsvd_solve(laplacian, n_components, seed, params); - level_elapsed[SolverLevel::Rsvd as usize] = Some(started.elapsed()); - let quality = max_eigenpair_residual(laplacian, &eigs, &vecs); - if quality < gates.rsvd { - log::debug!("[spectral] Level 4 (rSVD) succeeded (n={n}, max_residual={quality:.2e})"); - return Ok(accepted( - (eigs, vecs), - SolverLevel::Rsvd, - quality, - level_elapsed, - )); + // Level 4: Randomized SVD via 2I-L trick. Produces no result when its dense sketch + // would exceed the dense memory budget. + let started = Instant::now(); + let l4 = rsvd::rsvd_solve(laplacian, n_components, seed, params); + level_elapsed[SolverLevel::Rsvd as usize] = Some(started.elapsed()); + match l4 { + Some((eigs, vecs)) => { + let quality = max_eigenpair_residual(laplacian, &eigs, &vecs); + if quality < gates.rsvd { + log::debug!( + "[spectral] Level 4 (rSVD) succeeded (n={n}, max_residual={quality:.2e})" + ); + return Ok(accepted( + (eigs, vecs), + SolverLevel::Rsvd, + quality, + level_elapsed, + )); + } + log::debug!( + "[spectral] Level 4 (rSVD) poor quality (max_residual={quality:.2e}), \ + escalating to Level 5" + ); + } + None => { + log::debug!("[spectral] Level 4 (rSVD) produced no result, escalating to Level 5"); } - log::debug!( - "[spectral] Level 4 (rSVD) poor quality (max_residual={quality:.2e}), \ - escalating to Level 5" - ); } - // Level 5: Forced dense EVD — O(n³) nuclear option. - // This level CANNOT fail mathematically (spectral theorem). - // If it returns Err, that indicates an OOM or a faer bug — both are - // unrecoverable and should surface as an assertion failure, not a silent - // ConvergenceFailure that would produce a garbage embedding. + // Level 5: Forced dense EVD — O(n³) last resort. Over budget it reports + // DenseBudgetExceeded; a result that is not finite or misses the dense gate is a + // ConvergenceFailure rather than a silently wrong embedding. log::debug!("[spectral] Level 5 (forced dense EVD) (n={n})"); let started = Instant::now(); - let (eigs, vecs) = dense_evd(laplacian, n_components + 1).expect( - "solve_eigenproblem: Level 5 forced dense EVD failed — \ - this is a bug; the spectral theorem guarantees eigenvectors \ - exist for any symmetric positive semidefinite matrix", - ); + let (eigs, vecs) = dense_evd(laplacian, n_components + 1, params.dense_memory_budget)?; level_elapsed[SolverLevel::ForcedDense as usize] = Some(started.elapsed()); let quality = max_eigenpair_residual(laplacian, &eigs, &vecs); - Ok(accepted( - (eigs, vecs), - SolverLevel::ForcedDense, - quality, - level_elapsed, - )) + let finite = eigs.iter().all(|v| v.is_finite()) && vecs.iter().all(|v| v.is_finite()); + if finite && quality < gates.dense { + return Ok(accepted( + (eigs, vecs), + SolverLevel::ForcedDense, + quality, + level_elapsed, + )); + } + log::debug!("[spectral] Level 5 (forced dense EVD) rejected (max_residual={quality:.2e})"); + Err(SpectralError::ConvergenceFailure { n }) } /// Solver escalation chain with runtime operator dispatch. @@ -373,9 +421,13 @@ fn solve_eigenproblem_with_op( /// /// Returns the `n_components + 1` smallest eigenpairs together with a [`SolveReport`]. /// -/// # Panics +/// # Errors /// -/// Panics at Level 5 exhaustion — this represents a bug, not a user error. +/// - `DenseBudgetExceeded` — every earlier level failed and the dense `n × n` matrix of +/// the forced dense EVD does not fit `params.dense_memory_budget`. +/// - `ConvergenceFailure` — the forced dense EVD produced a result that is not finite or +/// misses its residual gate. +/// - `TooFewNodes` — the problem has fewer than `n_components + 1` rows. pub fn solve_eigenproblem( laplacian: &CsMatI, n_components: usize, @@ -652,6 +704,44 @@ mod tests { assert_eq!(params.gates.lobpcg, LOBPCG_QUALITY_THRESHOLD); assert_eq!(params.gates.sinv, SINV_LOBPCG_QUALITY_THRESHOLD); assert_eq!(params.gates.rsvd, RSVD_QUALITY_THRESHOLD); + assert_eq!( + params.dense_memory_budget, + SpectralInitConfig::DEFAULT_DENSE_MEMORY_BUDGET + ); + } + + #[test] + fn from_config_carries_the_dense_memory_budget() { + let config = SpectralInitConfig::new(2).with_dense_memory_budget(12_345); + let params = SolverParams::from_config(&config); + assert_eq!(params.dense_memory_budget, 12_345); + assert_eq!( + SolverParams { + dense_memory_budget: SpectralInitConfig::DEFAULT_DENSE_MEMORY_BUDGET, + ..params + }, + SolverParams::default() + ); + } + + #[test] + fn dense_bytes_saturates_instead_of_overflowing() { + assert_eq!(dense_bytes(3, 5), 120); + assert_eq!(dense_bytes(0, 5), 0); + assert_eq!(dense_bytes(usize::MAX, usize::MAX), u64::MAX); + assert_eq!(dense_bytes(usize::MAX, 1), u64::MAX); + } + + #[test] + fn check_dense_budget_reports_both_sizes() { + assert_eq!(check_dense_budget(10, 10, 800), Ok(())); + assert_eq!( + check_dense_budget(10, 10, 799), + Err(SpectralError::DenseBudgetExceeded { + required_bytes: 800, + budget_bytes: 799 + }) + ); } #[test] diff --git a/src/solvers/rsvd.rs b/src/solvers/rsvd.rs index 322b2d5..cb4616f 100644 --- a/src/solvers/rsvd.rs +++ b/src/solvers/rsvd.rs @@ -8,15 +8,18 @@ //! **Chain position:** Level 4 — approximate but highly robust fallback for large `n` //! after Levels 1–3 fail. Quality threshold: 1e-2 (looser than other levels). //! -//! **Failure mode:** `rsvd_solve` is infallible (returns directly). The looser -//! residual threshold (1e-2) means Level 4 rarely fails its quality gate. If it does, -//! Level 5 (forced dense EVD) is the final fallback. +//! **Failure mode:** `rsvd_solve` returns `None` when its dense `n × k` sketch would +//! exceed the dense memory budget, when the problem is too small for the requested +//! number of components, or when the small projected eigenproblem fails. The looser +//! residual threshold (1e-2) means Level 4 rarely fails its quality gate. In every +//! failing case Level 5 (forced dense EVD) is the final fallback. -use super::{EigenResult, SolverParams}; +use super::{EigenResult, SolverParams, dense_bytes}; use faer::linalg::solvers::{Qr, SelfAdjointEigen}; use faer::{Mat as FaerMat, Side}; use ndarray::{Array1, Array2}; use rand::SeedableRng; +use rand_chacha::ChaCha12Rng; use rand_distr::{Distribution, StandardNormal}; use sprs::{CsMatI, TriMat}; @@ -80,17 +83,17 @@ fn qr_thin_q(y: &Array2) -> Array2 { /// Compute symmetric eigendecomposition of the small matrix B using `faer`. /// /// Returns `(eigenvalues, eigenvectors)` where eigenvalues are in ASCENDING order -/// and eigenvectors are columns of the returned Array2. -fn sym_eig(b: &Array2) -> (Vec, Array2) { +/// and eigenvectors are columns of the returned Array2, or `None` if the +/// decomposition fails. +fn sym_eig(b: &Array2) -> Option<(Vec, Array2)> { let faer_b = to_faer(b); - let eigen = SelfAdjointEigen::new(faer_b.as_ref(), Side::Lower) - .expect("rsvd_solve: SelfAdjointEigen failed on B = Q^T M Q"); + let eigen = SelfAdjointEigen::new(faer_b.as_ref(), Side::Lower).ok()?; // Eigenvalues in ASCENDING order (smallest first). // Use for_each since ColRef may have non-contiguous stride (no as_slice guarantee). let mut eigenvalues: Vec = Vec::new(); eigen.S().for_each(|x| eigenvalues.push(*x)); let eigenvectors = from_faer(&eigen.U().to_owned()); - (eigenvalues, eigenvectors) + Some((eigenvalues, eigenvectors)) } /// Default number of QR-stabilized power-iteration passes. @@ -115,32 +118,34 @@ fn rsvd_k_sub(n: usize, rank: usize, oversampling: Option) -> usize { /// - Computes the top-(n_components+1) eigenvalues/vectors of M via randomized SVD /// - Discards the trivial eigenvector (column 0, corresponding to λ_L ≈ 0) /// - Maps eigenvalues back to L eigenvalues via λ_L = 2 − σ_M +/// +/// Returns `None` when `n_components` is 0 or not below `n`, when the dense `n × k` +/// sketch needs more than `params.dense_memory_budget` bytes, or when the projected +/// eigenproblem fails. pub fn rsvd_solve( laplacian: &CsMatI, n_components: usize, seed: u64, params: &SolverParams, -) -> EigenResult { +) -> Option { let n = laplacian.rows(); - assert!( - n_components > 0, - "rsvd_solve: n_components must be >= 1, got 0" - ); - assert!( - n_components < n, - "rsvd_solve: n_components ({n_components}) must be < n ({n})" - ); + if n_components == 0 || n_components >= n { + return None; + } // rank = n_components + 1: request one extra so we can discard the trivial vector let rank = n_components + 1; // k = total random vectors; see rsvd_k_sub for the oversampling formula. let k = rsvd_k_sub(n, rank, params.rsvd_oversampling); + if dense_bytes(n, k) > params.dense_memory_budget { + return None; + } let nbiter = params.rsvd_nbiter; // QR-stabilized subspace iterations (Halko-Tropp Algorithm 4.4) // ── Step A: Form M = 2I - L ────────────────────────────────────────────── let m = two_i_minus_laplacian(laplacian); // ── Step B: Generate random Gaussian sketch matrix Ω ∈ ℝ^{n × k} ──────── - let mut rng = rand::rngs::StdRng::seed_from_u64(seed); + let mut rng = ChaCha12Rng::seed_from_u64(seed); let normal = StandardNormal; let mut omega = Array2::from_shape_fn((n, k), |_| normal.sample(&mut rng)); @@ -164,7 +169,7 @@ pub fn rsvd_solve( // ── Step F: Eigendecompose B (small k×k symmetric matrix) ───────────────── // eigenvalues ascending (smallest M eigenvalue first = largest L eigenvalue) - let (m_eigenvals, u_b) = sym_eig(&b); // m_eigenvals[k-1] ≈ 2 (trivial) + let (m_eigenvals, u_b) = sym_eig(&b)?; // m_eigenvals[k-1] ≈ 2 (trivial) // ── Step G: Recover full eigenvectors V = Q U_B ─────────────────────────── let v = q.dot(&u_b); // [n, k] @@ -173,7 +178,8 @@ pub fn rsvd_solve( // // M eigenvalues (ascending): index actual_n-1 is the trivial (λ_M ≈ 2.0 → λ_L ≈ 0). // Non-trivial L eigenvalues (ascending): indices actual_n-2, actual_n-3, ..., - // actual_n-1-n_components in the M ascending array. + // actual_n-1-n_components in the M ascending array. `k >= rank` (because + // `rank <= n`), so all of these indices exist. let actual_n = m_eigenvals.len(); let trivial_m_idx = actual_n - 1; let mut eig_vals_vec: Vec = Vec::with_capacity(n_components + 1); @@ -196,7 +202,7 @@ pub fn rsvd_solve( } let eigenvalues = Array1::from_vec(eig_vals_vec); - (eigenvalues, eigenvectors) + Some((eigenvalues, eigenvectors)) } /// Accurate eigensolver via random subspace + direct L-projection. @@ -212,7 +218,9 @@ pub fn rsvd_solve( /// `n_components` non-trivial pairs in ascending eigenvalue order). /// /// `k_sub` controls the subspace size; larger values give higher accuracy at -/// higher cost. Must satisfy `k_sub > n_components + 1`. +/// higher cost. Returns `None` unless `k_sub > n_components + 1` and the subspace, +/// capped at `n`, still holds `n_components + 1` vectors, or if the projected +/// eigenproblem fails. #[cfg(feature = "__internal")] pub fn rsvd_solve_accurate( laplacian: &CsMatI, @@ -220,14 +228,17 @@ pub fn rsvd_solve_accurate( seed: u64, k_sub: usize, nbiter: usize, -) -> (Array1, Array2) { +) -> Option { let n = laplacian.rows(); - assert!(k_sub > n_components + 1, "k_sub must be > n_components + 1"); + let n_out = n_components + 1; let k = k_sub.min(n); + if k_sub <= n_out || k < n_out { + return None; + } // ── Step A: Build power-iteration subspace using M = 2I − L ───────────── let m = two_i_minus_laplacian(laplacian); - let mut rng = rand::rngs::StdRng::seed_from_u64(seed); + let mut rng = ChaCha12Rng::seed_from_u64(seed); let normal = StandardNormal; let mut omega = Array2::from_shape_fn((n, k), |_| normal.sample(&mut rng)); @@ -246,20 +257,19 @@ pub fn rsvd_solve_accurate( let b_l = q.t().dot(&lq); // B_L [k, k] symmetric PSD // ── Step C: Dense EVD of B_L (ascending = smallest L eigenvalue first) ── - let (l_eigenvals, u_b) = sym_eig(&b_l); + let (l_eigenvals, u_b) = sym_eig(&b_l)?; // ── Step D: Recover full Ritz vectors V = Q U_B ────────────────────────── let v = q.dot(&u_b); // [n, k] // ── Step E: Build output — trivial first (index 0), then non-trivials ──── // l_eigenvals[0] ≈ 0 (trivial), l_eigenvals[1..=n_components] non-trivials - let n_out = n_components + 1; let eigenvalues = Array1::from_iter(l_eigenvals[..n_out].iter().copied()); let mut eigenvectors = Array2::::zeros((n, n_out)); for i in 0..n_out { eigenvectors.column_mut(i).assign(&v.column(i)); } - (eigenvalues, eigenvectors) + Some((eigenvalues, eigenvectors)) } #[cfg(test)] @@ -291,9 +301,10 @@ mod tests { #[test] fn test_two_i_minus_laplacian_path_3() { let graph = make_graph(3, &[(0, 1, 1.0), (1, 2, 1.0)]); - let (_, sqrt_deg) = crate::laplacian::compute_degrees(&graph, ComputeMode::PythonCompat); + let (_, sqrt_deg) = + crate::laplacian::compute_degrees(graph.view(), ComputeMode::PythonCompat); let inv_sqrt_deg = sqrt_deg.mapv(|x| if x == 0.0 { 0.0 } else { 1.0 / x }); - let l = build_normalized_laplacian(&graph, inv_sqrt_deg.as_slice().unwrap()); + let l = build_normalized_laplacian(graph.view(), inv_sqrt_deg.as_slice().unwrap()); let m = two_i_minus_laplacian(&l); let n = l.rows(); @@ -342,13 +353,14 @@ mod tests { .flat_map(|i| (i + 1..n).map(move |j| (i, j, 1.0f32))) .collect(); let graph = make_graph(n, &edges); - let (_, sqrt_deg) = crate::laplacian::compute_degrees(&graph, ComputeMode::PythonCompat); + let (_, sqrt_deg) = + crate::laplacian::compute_degrees(graph.view(), ComputeMode::PythonCompat); let inv_sqrt_deg = sqrt_deg.mapv(|x| if x == 0.0 { 0.0 } else { 1.0 / x }); - let l = build_normalized_laplacian(&graph, inv_sqrt_deg.as_slice().unwrap()); + let l = build_normalized_laplacian(graph.view(), inv_sqrt_deg.as_slice().unwrap()); let n_components = 2; let (eigenvalues, eigenvectors) = - rsvd_solve(&l, n_components, 42, &SolverParams::default()); + rsvd_solve(&l, n_components, 42, &SolverParams::default()).expect("rsvd_solve failed"); assert_eq!( eigenvalues.shape(), @@ -395,12 +407,14 @@ mod tests { let n = 6; let edges: Vec<(usize, usize, f32)> = (0..n).map(|i| (i, (i + 1) % n, 1.0f32)).collect(); let graph = make_graph(n, &edges); - let (_, sqrt_deg) = crate::laplacian::compute_degrees(&graph, ComputeMode::PythonCompat); + let (_, sqrt_deg) = + crate::laplacian::compute_degrees(graph.view(), ComputeMode::PythonCompat); let inv_sqrt_deg = sqrt_deg.mapv(|x| if x == 0.0 { 0.0 } else { 1.0 / x }); - let l = build_normalized_laplacian(&graph, inv_sqrt_deg.as_slice().unwrap()); + let l = build_normalized_laplacian(graph.view(), inv_sqrt_deg.as_slice().unwrap()); let n_components = 2; - let (eigenvalues, eigenvectors) = rsvd_solve(&l, n_components, 0, &SolverParams::default()); + let (eigenvalues, eigenvectors) = + rsvd_solve(&l, n_components, 0, &SolverParams::default()).expect("rsvd_solve failed"); let eig_slice = eigenvalues.as_slice().unwrap(); @@ -464,19 +478,56 @@ mod tests { let n = 6; let edges: Vec<(usize, usize, f32)> = (0..n).map(|i| (i, (i + 1) % n, 1.0f32)).collect(); let graph = make_graph(n, &edges); - let (_, sqrt_deg) = crate::laplacian::compute_degrees(&graph, ComputeMode::PythonCompat); + let (_, sqrt_deg) = + crate::laplacian::compute_degrees(graph.view(), ComputeMode::PythonCompat); let inv_sqrt_deg = sqrt_deg.mapv(|x| if x == 0.0 { 0.0 } else { 1.0 / x }); - let l = build_normalized_laplacian(&graph, inv_sqrt_deg.as_slice().unwrap()); + let l = build_normalized_laplacian(graph.view(), inv_sqrt_deg.as_slice().unwrap()); let params = SolverParams { rsvd_oversampling: Some(2), rsvd_nbiter: 4, ..SolverParams::default() }; - let (eigenvalues, eigenvectors) = rsvd_solve(&l, 2, 0, ¶ms); + let (eigenvalues, eigenvectors) = rsvd_solve(&l, 2, 0, ¶ms).expect("rsvd_solve failed"); assert_eq!(eigenvectors.shape(), &[n, 3]); assert!(eigenvalues[0].abs() < 1e-3); assert!((eigenvalues[1] - 0.5).abs() < 1e-4); assert!((eigenvalues[2] - 0.5).abs() < 1e-4); } + + /// 6-node ring Laplacian, as in the residual test above. + fn ring_6_laplacian() -> CsMatI { + let n = 6; + let edges: Vec<(usize, usize, f32)> = (0..n).map(|i| (i, (i + 1) % n, 1.0f32)).collect(); + let graph = make_graph(n, &edges); + let (_, sqrt_deg) = + crate::laplacian::compute_degrees(graph.view(), ComputeMode::PythonCompat); + let inv_sqrt_deg = sqrt_deg.mapv(|x| if x == 0.0 { 0.0 } else { 1.0 / x }); + build_normalized_laplacian(graph.view(), inv_sqrt_deg.as_slice().unwrap()) + } + + #[test] + fn rsvd_solve_returns_none_for_unsolvable_requests() { + let l = ring_6_laplacian(); + let params = SolverParams::default(); + assert!(rsvd_solve(&l, 0, 42, ¶ms).is_none(), "n_components = 0"); + assert!(rsvd_solve(&l, 6, 42, ¶ms).is_none(), "n_components = n"); + assert!(rsvd_solve(&l, 7, 42, ¶ms).is_none(), "n_components > n"); + } + + #[test] + fn rsvd_solve_returns_none_over_the_dense_memory_budget() { + let l = ring_6_laplacian(); + // n = 6, rank = 3, default oversampling 3 → a 6 × 6 sketch of 288 bytes. + let within = SolverParams { + dense_memory_budget: 288, + ..SolverParams::default() + }; + let over = SolverParams { + dense_memory_budget: 287, + ..SolverParams::default() + }; + assert!(rsvd_solve(&l, 2, 42, &within).is_some()); + assert!(rsvd_solve(&l, 2, 42, &over).is_none()); + } } diff --git a/src/solvers/sinv.rs b/src/solvers/sinv.rs index cf06655..89d43b1 100644 --- a/src/solvers/sinv.rs +++ b/src/solvers/sinv.rs @@ -23,7 +23,7 @@ use faer::prelude::Solve; use linfa_linalg::lobpcg::{Order, lobpcg}; use ndarray::{Array1, Array2, ArrayView2}; use rand::SeedableRng; -use rand::rngs::StdRng; +use rand_chacha::ChaCha12Rng; use rand_distr::{Distribution, StandardNormal}; use sprs::CsMatI; @@ -34,6 +34,9 @@ use super::quality::{SINV_LINFA_TOL, SINV_LOBPCG_QUALITY_THRESHOLD}; pub(crate) const SINV_SHIFT: f64 = 1e-4; // ─── ndarray 0.16 ↔ 0.17 conversion helpers ────────────────────────────────── +// +// Each helper rebuilds an array from exactly `rows * cols` elements read off the source, +// so the `from_shape_vec` calls cannot fail. fn to_nd16_array2(a: Array2) -> nd16::Array2 { let (rows, cols) = (a.nrows(), a.ncols()); @@ -83,6 +86,8 @@ fn sprs_csc_to_faer( } } + // `col_ptr` and `row_idx` come straight from a valid sprs CSC matrix, so they + // satisfy the structure `new_checked` verifies. let symbolic = faer::sparse::SymbolicSparseColMat::::new_checked(n, n, col_ptr, None, row_idx); faer::sparse::SparseColMat::::new(symbolic, values) @@ -140,7 +145,7 @@ pub fn lobpcg_sinv_solve( let chol = m_faer.sp_cholesky(faer::Side::Lower).ok()?; // Build random initial block [n, k] with trivial eigenvector injected at col 0. - let mut rng = StdRng::seed_from_u64(seed); + let mut rng = ChaCha12Rng::seed_from_u64(seed); let mut x_init_17: Array2 = Array2::from_shape_fn((n, k), |_| StandardNormal.sample(&mut rng)); let sqrt_deg_norm = sqrt_deg.dot(sqrt_deg).sqrt(); @@ -198,7 +203,7 @@ pub fn lobpcg_sinv_solve( .enumerate() .map(|(i, v)| (v, i)) .collect(); - pairs.sort_by(|a, b| a.0.partial_cmp(&b.0).unwrap()); + pairs.sort_by(|a, b| a.0.total_cmp(&b.0)); let sorted_vals = Array1::from_iter(pairs.iter().map(|&(v, _)| v)); let sorted_vecs = Array2::from_shape_fn((eigvecs.nrows(), eigvecs.ncols()), |(i, j)| { diff --git a/src/validate.rs b/src/validate.rs new file mode 100644 index 0000000..832d72e --- /dev/null +++ b/src/validate.rs @@ -0,0 +1,122 @@ +//! Boundary validation of the caller's configuration, graph and data. + +use crate::laplacian::column_sum_f32; +use crate::{SpectralError, SpectralInitConfig}; +use ndarray::ArrayView2; +use sprs::CsMatViewI; + +/// Largest relative difference between `W[i,j]` and `W[j,i]` that still counts as +/// symmetric. Single-precision graphs built as `A + Aᵀ − A∘Aᵀ` agree to a few ULPs. +const SYMMETRY_REL_TOL: f64 = 1e-6; + +/// Validates the inputs of `spectral_init` and returns the graph as a CSR view. +/// +/// Checks run on the matrix as the caller supplied it, so reported coordinates are in +/// the caller's orientation, in this order of precedence: `InvalidParameter`, +/// `NotSquare`, `TooFewNodes`, `NonFiniteWeight`, `NegativeWeight`, `NotSymmetric`, +/// `DegreeOverflow`, `DataShapeMismatch`, `NonFiniteData`. +/// +/// Stored zeros count as absent edges. A CSC view of a symmetric matrix is returned as +/// the CSR view of its transpose. +pub(crate) fn validate<'a>( + graph: CsMatViewI<'a, f32, u32, usize>, + data: Option>, + config: &SpectralInitConfig, +) -> Result, SpectralError> { + let n_components = config.n_components(); + if n_components == 0 { + return Err(SpectralError::InvalidParameter { + name: "n_components", + reason: "must be at least 1", + }); + } + + let (rows, cols) = graph.shape(); + if rows != cols { + return Err(SpectralError::NotSquare { rows, cols }); + } + let n = rows; + if n <= n_components { + return Err(SpectralError::TooFewNodes { n, n_components }); + } + + check_weights(graph)?; + check_symmetry(graph)?; + + let graph = if graph.is_csr() { + graph + } else { + graph.transpose_into() + }; + + check_degrees(graph)?; + if let Some(data) = data { + check_data(data, n)?; + } + Ok(graph) +} + +/// Every stored weight must be finite and non-negative. A non-finite weight anywhere +/// takes precedence over a negative one. +fn check_weights(graph: CsMatViewI<'_, f32, u32, usize>) -> Result<(), SpectralError> { + let mut first_negative = None; + for (&weight, (row, col)) in graph.iter() { + if !weight.is_finite() { + return Err(SpectralError::NonFiniteWeight { + row: row as usize, + col: col as usize, + }); + } + if weight < 0.0 && first_negative.is_none() { + first_negative = Some((row as usize, col as usize)); + } + } + match first_negative { + Some((row, col)) => Err(SpectralError::NegativeWeight { row, col }), + None => Ok(()), + } +} + +/// Every non-zero off-diagonal entry must have a mirror entry of the same weight, within +/// `SYMMETRY_REL_TOL`. A missing or zero mirror entry fails the comparison, so the +/// pattern is checked along with the values. +fn check_symmetry(graph: CsMatViewI<'_, f32, u32, usize>) -> Result<(), SpectralError> { + for (&weight, (row, col)) in graph.iter() { + let (row, col) = (row as usize, col as usize); + if weight == 0.0 || row == col { + continue; + } + let weight = f64::from(weight); + let mirrored = graph.get(col, row).map_or(0.0, |&w| f64::from(w)); + if (weight - mirrored).abs() > SYMMETRY_REL_TOL * weight.max(mirrored) { + return Err(SpectralError::NotSymmetric { row, col }); + } + } + Ok(()) +} + +/// Every node's degree must stay finite in the single-precision accumulation the +/// `PythonCompat` degree computation uses. +fn check_degrees(graph: CsMatViewI<'_, f32, u32, usize>) -> Result<(), SpectralError> { + match column_sum_f32(graph) + .iter() + .position(|degree| !degree.is_finite()) + { + Some(node) => Err(SpectralError::DegreeOverflow { node }), + None => Ok(()), + } +} + +/// `data` must have one row per node and only finite values. +fn check_data(data: ArrayView2<'_, f32>, n: usize) -> Result<(), SpectralError> { + if data.nrows() != n { + return Err(SpectralError::DataShapeMismatch { + expected_rows: n, + actual_rows: data.nrows(), + }); + } + match data.indexed_iter().find(|(_, value)| !value.is_finite()) { + Some(((row, col), _)) => Err(SpectralError::NonFiniteData { row, col }), + None => Ok(()), + } +} diff --git a/tests/README.md b/tests/README.md index 49c2a42..1a8a5e9 100644 --- a/tests/README.md +++ b/tests/README.md @@ -190,6 +190,17 @@ Sparse `.npz` files (scipy format): these are not directly loadable by standard readers; for Rust tests, prefer loading the dense intermediate steps (comp_a through comp_f) which are all standard numpy `.npz` archives. +### Self-loop mini-fixture + +`tests/fixtures/selfloop/` holds reference data for a 12-node graph with non-zero +diagonal weights (`graph.npz`, `comp_a_degrees.npz`, `comp_b_laplacian.npz`, +`comp_d_eigensolver.npz`, `full_spectral.npz`, in the formats above). It is not part of +the dataset registry; regenerate it with: + +```bash +python tests/generate_fixtures.py --selfloop +``` + --- ## Datasets diff --git a/tests/common/assertions.rs b/tests/common/assertions.rs new file mode 100644 index 0000000..3e07d3d --- /dev/null +++ b/tests/common/assertions.rs @@ -0,0 +1,29 @@ +//! Assertion macros shared by the test binaries. + +/// Asserts that an expression is an `Err` matching a pattern. +/// +/// The variants of `SpectralError` are `#[non_exhaustive]`, so code outside the crate +/// cannot build one to compare against; it matches them with `..` instead. +macro_rules! assert_err { + ($result:expr, $pattern:pat $(,)?) => { + match $result { + Err($pattern) => {} + other => panic!( + "expected Err({}), got {:?}", + stringify!($pattern), + other + ), + } + }; + ($result:expr, $pattern:pat, $($context:tt)+) => { + match $result { + Err($pattern) => {} + other => panic!( + "{}: expected Err({}), got {:?}", + format_args!($($context)+), + stringify!($pattern), + other + ), + } + }; +} diff --git a/tests/fixtures/selfloop/comp_a_degrees.npz b/tests/fixtures/selfloop/comp_a_degrees.npz new file mode 100644 index 0000000000000000000000000000000000000000..d75ecf9521e4391dfe67304f8ad5a4ac0fc1e980 GIT binary patch literal 708 zcmWIWW@gc4fB;2?)cgM&|3d*cg9t-PYI;#>YO!8kK_w%D0K)^QLKr>SFVr_6l98c| zp;|p9wK%y*-AX~-Ce1=!M?pO;zo?`rF)u#9C?ypn?v|KSoC*{#&PXgs1@bivjdV11 z6lxX72V5ZMY}>-(0HhNBKmKD6q#Jxb{07ksmT$rQ1%bc5g7^y#*#7|03CyJ*LG%G; z>rWuMA!qA95Y3=1#pD2_8Wc+2gZK`-BA@L8Py#0-@yAYB;P3zgr?{}FBpw(-gEe&i zOl{U#y7#Ajmtgsk|Mg$(RUHgx^{affcRT&UCa?Lc{iRQ}+!GFbvQIsvc%XUHXM3wn z7R`m*KG;|E$}t*=e6-Jqd-JVR>zjT2wBohdf7UI2hobxLCee($-Q0Ez+0Bee zdM~b+ zE{qe-SwkpP!9gm*xbDd#B{T=5uetLT<^WD$5EW-67No-Lp8&Pj6QBLSSY1fSerTkM zFzCs#aWq^+bHm%n^<6MGZ~)zql30=mbHW8^!jgp2I1*MGK_?&**1FU7|4(?-)g|v& zjHugw^2+AlJ1>QAGW)l0Z~grI{AY)g`M)1NB6;9J^WLC}_mfZl*{kz=xW%2E8dlD-@U#fe2)#YmH!?Jh|B|2U>M z)Hr``(`|cEExzFIk=`l0o3FM0HLz-Y9pCltAp5tx*35Y0J?GzmbmgwJI$zx+cla*n zg4jH>a1?-1u_o-=sgXwO1Fh|JHZToMCr9mh*m{pZ(5ydy^WQ z1vN8lfI-U0q|1z&VL`bOlry=Z@du(BzyXPrebF_7G7Tt8fU*Y{NCy-&Fm461fEuA$ z2wfj2DT5L!DAA(o3kO<>NZ9E5Kq(NEz(9$O6Nq7;f$;`VA3QyxYXc=3P@(`O5Ks{X c0}YHZObqZO6yVLu29jX~LNTDq^~@k105rj07%l7_9cX?c6xoAH*_uA>42N&%Z?K`pNOXxZKWRBGH3JmA%x2jI)W0$*Pe{9>) z>=)Os+8Pzh33)&!2G3euwia?yWyA+V8zl8T0-4hW+m*X?dS2KfYi5_f*Aq zTh8tOviil7p41Kdx9S$>%yPJa7Q-<&dUn8Km=_qsMXAM^DW$*!H&_$yUY|!N^3C0B z%_K|aGcQuH4Yu38PkTzx(W||O{4=GEjpzO=V z40I2w)48t5>A{>1Dol#=bIMYS;`0)7Q(>NHg?a);WA#K$uqnMf0W9x|Gf;ier2FGC z%om_^m7Jdk^hJ7V3d|3UP(Q$E?0!fxq?aEUQQf~((ZwI;eqo^d5k-1@dSU@QcT9l# z0!Cx?1+m4t5#`1D^X=kOK*jljIeDy19t(h(osmhG8MUSYRY4%k4|O|;Y5*7F2v34N zh^`q_8-PlA5Eekud=tonXhzfx=(<5A4a{m@6y3X-7*NX{bgiJ=49c(|%!;CQ5-|UO z^ESE`P%Z*x4-iK6s4oixdY(ep3`)G9bP2+!P89}PkCK$pwSv+OC^3MrFc8B)1LI|& ZRzv{9Q&E67D;r1=I}k1c2J8wj4*=Y=L!$ry literal 0 HcmV?d00001 diff --git a/tests/fixtures/selfloop/full_spectral.npz b/tests/fixtures/selfloop/full_spectral.npz new file mode 100644 index 0000000000000000000000000000000000000000..95c52011be9f657bc32fad6d43795c4aba1f0640 GIT binary patch literal 464 zcmWIWW@gc4fB;2?r5A+~{zCyTg9t-vZc=JWN@iZVUS2^ZBZB~g10zH!jGpWl>KhQr z$WX>mt)7xvoLr=CrJ!z;W}&X5pq`drR8o|f7oT60k_r+JDJo3`3KwT27Ni2X8iqzX z3Pzeb3bhJk1FmCf^ZG3$Pwt=FpR`2p#o7I~dv3)0y}hyDW6`-=*}*sWN85zR%TylR z|KM}y;p?Bb?6+>3uV3}{l>M7`_RlRPZrCq&*sq}e>88Eg)=%XT88_{1uP>6X(>-rL zo$J#~<+q#n>-;khy7}&b{lwLK>j*U}em}lpf4|*b*Hh)k_p{#HIQ`w0bNk~Xe_ZHI-LSv( xN=)G_ha2_*-i%DT%%~9n3R@87g+>dAY5<2jN^}Hxv$BDt7=h3lNY{gv007*&qeuV% literal 0 HcmV?d00001 diff --git a/tests/fixtures/selfloop/graph.npz b/tests/fixtures/selfloop/graph.npz new file mode 100644 index 0000000000000000000000000000000000000000..bde4fae53527f0a2178329f4a904d99ccdae55a6 GIT binary patch literal 1133 zcmWIWW@gc4U|`??Vnv4SUmec>hXQT}5r)jXl+5JRV!gbAN=60&1`bA`Dj=waPzeYOu$mwd+ksAw= z6lTeK9saV}`RXQzqYgQG8oZnNkFYZYptw8ll;tFtySX6lE+{F2IeQD#xoMO-yX_dV zvl)}h6rQmp$tgTzPf}D6V@)bln8uW3sSw7Hq^iJ%=EB8?OQs{cFfG3*H?aif!e*$; zT=BUuPB>=`p@0R4stDt{Cy$iS9FV@|&R3WNIDtV_oRL_N3bTI#)Lu_~_5&k!AtC$S zAOR%8peM)1(QpyX4Ji>n%VBQd0JS##Jr{ykWp&L70TDE_ql#@UI_lK2n34m)ehm1_R%&1uils`cJ z;fDGJL^Xi(4pN3f*9c0(pcD#9ty~}-P|(1*1IPkugr;b8eV~*DN;jZ1gsLwJXeA<@ zq3Z)B2vB^3;+_+TVW5HWHc%ftd7x_p#UUt;K>h<28Zgkn7|+B2kI?{cRyL3fD-enS JRXQ?*cmRwAXOsW{ literal 0 HcmV?d00001 diff --git a/tests/generate_fixtures.py b/tests/generate_fixtures.py index bba51b8..9f2510a 100644 --- a/tests/generate_fixtures.py +++ b/tests/generate_fixtures.py @@ -4,6 +4,7 @@ Usage: python tests/generate_fixtures.py [--output-dir DIR] [--datasets NAME ...] [--verify] + python tests/generate_fixtures.py [--output-dir DIR] --selfloop """ from __future__ import annotations @@ -594,6 +595,56 @@ def generate_all_for_dataset( return entry +# --------------------------------------------------------------------------- +# Self-loop mini-fixture (not part of the DATASETS registry) +# --------------------------------------------------------------------------- + +SELFLOOP_DIR = "selfloop" + + +def make_selfloop_graph(n: int = 12, seed: int = 42) -> scipy.sparse.csr_matrix: + """ + Build a small connected, symmetric f32 graph with non-zero diagonal weights. + + A ring plus a few chords keeps the graph connected; every third node carries + a self-loop. + """ + rng = RandomState(seed) + W = np.zeros((n, n), dtype=np.float32) + for i in range(n): + j = (i + 1) % n + W[i, j] = W[j, i] = np.float32(rng.uniform(0.2, 1.0)) + for i in range(0, n, 4): + j = (i + 5) % n + W[i, j] = W[j, i] = np.float32(rng.uniform(0.2, 1.0)) + for i in range(0, n, 3): + W[i, i] = np.float32(rng.uniform(0.1, 0.9)) + return scipy.sparse.csr_matrix(W) + + +def generate_selfloop_fixture(outdir: Path, n_components: int = 2) -> None: + """ + Write the self-loop mini-fixture to `outdir`/selfloop. + + Reference data for graphs with diagonal weights. umap-learn keeps self-loops + in both the degree and the adjacency, so L = I - D^{-1/2} A D^{-1/2} has + L[i,i] = 1 - w_ii / d_i. + + Files (formats as for the registry datasets): graph.npz (scipy CSR, f32), + comp_a_degrees.npz, comp_b_laplacian.npz, comp_d_eigensolver.npz and + full_spectral.npz. + """ + fixture_dir = outdir / SELFLOOP_DIR + fixture_dir.mkdir(parents=True, exist_ok=True) + + graph = make_selfloop_graph() + scipy.sparse.save_npz(str(fixture_dir / "graph"), graph) + _, sqrt_deg = generate_comp_a_degrees(graph, fixture_dir) + L = generate_comp_b_laplacian(graph, sqrt_deg, fixture_dir) + generate_comp_d_eigensolver(L, n_components, fixture_dir) + generate_full_spectral(graph, None, 1, n_components, fixture_dir) + + # --------------------------------------------------------------------------- # CLI entry point # --------------------------------------------------------------------------- @@ -632,11 +683,20 @@ def main() -> None: "'both' generates approx and exact fixture sets." ), ) + parser.add_argument( + "--selfloop", action="store_true", + help="Generate only the self-loop mini-fixture (/selfloop) and exit", + ) args = parser.parse_args() outdir = Path(args.output_dir) outdir.mkdir(parents=True, exist_ok=True) + if args.selfloop: + generate_selfloop_fixture(outdir, n_components=args.n_components) + print(f"self-loop fixture → {outdir / SELFLOOP_DIR}") + return + selected = DATASETS if args.datasets: name_set = set(args.datasets) diff --git a/tests/internals/accuracy_report.rs b/tests/internals/accuracy_report.rs index 53e4864..f9ba32f 100644 --- a/tests/internals/accuracy_report.rs +++ b/tests/internals/accuracy_report.rs @@ -111,7 +111,7 @@ fn process_disconnected_path(dataset: &str, n_embedding_dims: usize) -> Disconne f64_data.mapv(|x| x as f32) }; - let (labels, n_conn_components) = find_components(&graph); + let (labels, n_conn_components) = find_components(graph.view()); let mut component_members: Vec> = vec![Vec::new(); n_conn_components]; for (node, &label) in labels.iter().enumerate() { @@ -119,7 +119,7 @@ fn process_disconnected_path(dataset: &str, n_embedding_dims: usize) -> Disconne } let embedding = embed_disconnected( - &graph, + graph.view(), &labels, n_conn_components, n_embedding_dims, @@ -142,12 +142,12 @@ fn process_disconnected_path(dataset: &str, n_embedding_dims: usize) -> Disconne return 0.0; } let sub_graph = extract_subgraph_local(&graph, members); - let (_, sqrt_deg_c) = compute_degrees(&sub_graph, ComputeMode::PythonCompat); + let (_, sqrt_deg_c) = compute_degrees(sub_graph.view(), ComputeMode::PythonCompat); let inv_sqrt_c: Vec = sqrt_deg_c .iter() .map(|&s| if s > 0.0 { 1.0 / s } else { 0.0 }) .collect(); - let lap_c = build_normalized_laplacian(&sub_graph, &inv_sqrt_c); + let lap_c = build_normalized_laplacian(sub_graph.view(), &inv_sqrt_c); let ((evals, evecs), _) = internals::solve_with_unit_hint( &lap_c, @@ -165,11 +165,9 @@ fn process_disconnected_path(dataset: &str, n_embedding_dims: usize) -> Disconne let separation_ratio = diagnostics::separation_ratio(embedding.view(), &labels); let e2e_result = spectral_init( - &graph, - n_embedding_dims, - 42, + graph.view(), Some(raw_data.view()), - SpectralInitConfig::default(), + &SpectralInitConfig::new(n_embedding_dims).with_seed(42), ) .unwrap_or_else(|e| panic!("{dataset}: spectral_init failed: {e}")); let e2e_output_is_finite = e2e_result.iter().all(|&v: &f32| v.is_finite()); @@ -209,7 +207,7 @@ fn process_dataset( let n_components_dim = k - 1; if !is_connected { - let (_, rust_n_components) = find_components(&graph); + let (_, rust_n_components) = find_components(graph.view()); let component_count_matches = rust_n_components == expected_n_components; let disconnected_path = Some(process_disconnected_path(dataset, n_components_dim)); return DatasetMetrics { @@ -290,11 +288,9 @@ fn process_dataset( let e2e_max_residual = if is_connected { let result = spectral_init( - &graph, - n_components_dim, - 42, + graph.view(), None, - SpectralInitConfig::default(), + &SpectralInitConfig::new(n_components_dim).with_seed(42), ) .unwrap_or_else(|e| panic!("{dataset}: spectral_init failed: {e}")); let e2e_max = (0..n_components_dim) @@ -308,7 +304,7 @@ fn process_dataset( None }; - let (_, rust_n_components) = find_components(&graph); + let (_, rust_n_components) = find_components(graph.view()); let component_count_matches = rust_n_components == expected_n_components; DatasetMetrics { @@ -341,7 +337,7 @@ fn build_tolerance_margin_table(all_metrics: &[DatasetMetrics]) -> Vec = fixtures::load_dense(&base.join("comp_a_degrees.npz"), "degrees"); for (&got, &want) in degrees.iter().zip(ref_deg.iter()) { @@ -373,7 +369,7 @@ fn build_tolerance_margin_table(all_metrics: &[DatasetMetrics]) -> Vec 0.0 { 1.0 / s } else { 0.0 }) .collect(); - let rust_lap = build_normalized_laplacian(&graph, &inv_sqrt_deg); + let rust_lap = build_normalized_laplacian(graph.view(), &inv_sqrt_deg); let ref_lap = fixtures::load_sparse_csr(&base.join("comp_b_laplacian.npz")); for (val, (row, col)) in ref_lap.iter() { let rust_val = rust_lap.get(row, col).copied().unwrap_or(0.0); @@ -398,12 +394,12 @@ fn build_tolerance_margin_table(all_metrics: &[DatasetMetrics]) -> Vec = sqrt_deg .iter() .map(|&s| if s > 0.0 { 1.0 / s } else { 0.0 }) .collect(); - let rust_lap = build_normalized_laplacian(&graph, &inv_sqrt_deg); + let rust_lap = build_normalized_laplacian(graph.view(), &inv_sqrt_deg); let ref_lap = fixtures::load_sparse_csr(&base.join("comp_b_laplacian.npz")); for (val, (row, col)) in ref_lap.iter() { let rust_val = rust_lap.get(row, col).copied().unwrap_or(0.0); diff --git a/tests/internals/adversarial_graphs.rs b/tests/internals/adversarial_graphs.rs index 8ff3fc2..acc7821 100644 --- a/tests/internals/adversarial_graphs.rs +++ b/tests/internals/adversarial_graphs.rs @@ -371,8 +371,12 @@ fn max_intra_1d_spread(emb: &Array2, range: std::ops::Range, dim: us #[test] fn test_barbell_valid_embedding() { let graph = make_barbell(20); // n = 40 - let result = spectral_init(&graph, 2, 42, None, SpectralInitConfig::default()) - .expect("barbell should not fail"); + let result = spectral_init( + graph.view(), + None, + &SpectralInitConfig::new(2).with_seed(42), + ) + .expect("barbell should not fail"); assert_eq!(result.shape(), &[40, 2]); assert!( result.iter().all(|v| v.is_finite()), @@ -383,8 +387,12 @@ fn test_barbell_valid_embedding() { #[test] fn test_path_valid_embedding() { let graph = fixtures::make_path(100); // n = 100 - let result = spectral_init(&graph, 2, 42, None, SpectralInitConfig::default()) - .expect("path should not fail"); + let result = spectral_init( + graph.view(), + None, + &SpectralInitConfig::new(2).with_seed(42), + ) + .expect("path should not fail"); assert_eq!(result.shape(), &[100, 2]); assert!( result.iter().all(|v| v.is_finite()), @@ -395,8 +403,12 @@ fn test_path_valid_embedding() { #[test] fn test_star_valid_embedding() { let graph = make_star(50); // n = 50 - let result = spectral_init(&graph, 2, 42, None, SpectralInitConfig::default()) - .expect("star should not fail"); + let result = spectral_init( + graph.view(), + None, + &SpectralInitConfig::new(2).with_seed(42), + ) + .expect("star should not fail"); assert_eq!(result.shape(), &[50, 2]); assert!( result.iter().all(|v| v.is_finite()), @@ -407,8 +419,12 @@ fn test_star_valid_embedding() { #[test] fn test_epsilon_bridge_valid_embedding() { let graph = make_epsilon_bridge(20, 1e-6f32); // n = 40 - let result = spectral_init(&graph, 2, 42, None, SpectralInitConfig::default()) - .expect("epsilon-bridge should not fail"); + let result = spectral_init( + graph.view(), + None, + &SpectralInitConfig::new(2).with_seed(42), + ) + .expect("epsilon-bridge should not fail"); assert_eq!(result.shape(), &[40, 2]); assert!( result.iter().all(|v| v.is_finite()), @@ -419,8 +435,12 @@ fn test_epsilon_bridge_valid_embedding() { #[test] fn test_complete_bipartite_valid_embedding() { let graph = make_complete_bipartite(10, 10); // n = 20 - let result = spectral_init(&graph, 2, 42, None, SpectralInitConfig::default()) - .expect("complete bipartite should not fail"); + let result = spectral_init( + graph.view(), + None, + &SpectralInitConfig::new(2).with_seed(42), + ) + .expect("complete bipartite should not fail"); assert_eq!(result.shape(), &[20, 2]); assert!( result.iter().all(|v| v.is_finite()), @@ -431,8 +451,12 @@ fn test_complete_bipartite_valid_embedding() { #[test] fn test_ring_valid_embedding() { let graph = fixtures::make_ring(100); // n = 100 - let result = spectral_init(&graph, 2, 42, None, SpectralInitConfig::default()) - .expect("ring should not fail"); + let result = spectral_init( + graph.view(), + None, + &SpectralInitConfig::new(2).with_seed(42), + ) + .expect("ring should not fail"); assert_eq!(result.shape(), &[100, 2]); assert!( result.iter().all(|v| v.is_finite()), @@ -443,8 +467,12 @@ fn test_ring_valid_embedding() { #[test] fn test_weighted_exponential_valid_embedding() { let graph = make_weighted_exponential_path(100); // n = 100 - let result = spectral_init(&graph, 2, 42, None, SpectralInitConfig::default()) - .expect("weighted exponential path should not fail"); + let result = spectral_init( + graph.view(), + None, + &SpectralInitConfig::new(2).with_seed(42), + ) + .expect("weighted exponential path should not fail"); assert_eq!(result.shape(), &[100, 2]); assert!( result.iter().all(|v| v.is_finite()), @@ -455,9 +483,20 @@ fn test_weighted_exponential_valid_embedding() { #[test] fn test_single_edge_returns_too_few_nodes() { let graph = make_single_edge(); // n = 2, n_components = 2: 2 <= 2 → TooFewNodes - let result = spectral_init(&graph, 2, 42, None, SpectralInitConfig::default()); + let result = spectral_init( + graph.view(), + None, + &SpectralInitConfig::new(2).with_seed(42), + ); assert!( - matches!(result, Err(SpectralError::TooFewNodes { n: 2, dims: 2 })), + matches!( + result, + Err(SpectralError::TooFewNodes { + n: 2, + n_components: 2, + .. + }) + ), "expected TooFewNodes error, got: {:?}", result ); @@ -466,8 +505,12 @@ fn test_single_edge_returns_too_few_nodes() { #[test] fn test_complete_k20_valid_embedding() { let graph = make_complete(20); // n = 20 - let result = spectral_init(&graph, 2, 42, None, SpectralInitConfig::default()) - .expect("K_20 should not fail"); + let result = spectral_init( + graph.view(), + None, + &SpectralInitConfig::new(2).with_seed(42), + ) + .expect("K_20 should not fail"); assert_eq!(result.shape(), &[20, 2]); assert!( result.iter().all(|v| v.is_finite()), @@ -478,8 +521,12 @@ fn test_complete_k20_valid_embedding() { #[test] fn test_lollipop_valid_embedding() { let graph = make_lollipop(10, 20); // n = 30 - let result = spectral_init(&graph, 2, 42, None, SpectralInitConfig::default()) - .expect("lollipop should not fail"); + let result = spectral_init( + graph.view(), + None, + &SpectralInitConfig::new(2).with_seed(42), + ) + .expect("lollipop should not fail"); assert_eq!(result.shape(), &[30, 2]); assert!( result.iter().all(|v| v.is_finite()), @@ -492,7 +539,12 @@ fn test_lollipop_valid_embedding() { #[test] fn test_barbell_separates_communities() { let graph = make_barbell(20); // n=40; clique_0=nodes[0..20], clique_1=nodes[20..40] - let emb = spectral_init(&graph, 2, 42, None, SpectralInitConfig::default()).unwrap(); + let emb = spectral_init( + graph.view(), + None, + &SpectralInitConfig::new(2).with_seed(42), + ) + .unwrap(); // The Fiedler vector (dim 0) encodes community membership: all nodes in each K_20 // clique have nearly identical Fiedler values, so separation is measured along dim 0. @@ -514,7 +566,12 @@ fn test_barbell_separates_communities() { #[test] fn test_epsilon_bridge_separates_communities() { let graph = make_epsilon_bridge(20, 1e-6f32); // n=40; same clique layout - let emb = spectral_init(&graph, 2, 42, None, SpectralInitConfig::default()).unwrap(); + let emb = spectral_init( + graph.view(), + None, + &SpectralInitConfig::new(2).with_seed(42), + ) + .unwrap(); // Same rationale as test_barbell_separates_communities: compare along the Fiedler // direction (dim 0) where the near-zero bridge weight still produces opposite-sign @@ -537,7 +594,12 @@ fn test_epsilon_bridge_separates_communities() { #[test] fn test_star_coordinate_stability() { let graph = make_star(50); - let emb = spectral_init(&graph, 2, 42, None, SpectralInitConfig::default()).unwrap(); + let emb = spectral_init( + graph.view(), + None, + &SpectralInitConfig::new(2).with_seed(42), + ) + .unwrap(); let max_abs = emb.iter().map(|v| v.abs()).fold(0.0f32, f32::max); assert!( max_abs < 20.0, @@ -548,7 +610,12 @@ fn test_star_coordinate_stability() { #[test] fn test_complete_bipartite_coordinate_stability() { let graph = make_complete_bipartite(10, 10); - let emb = spectral_init(&graph, 2, 42, None, SpectralInitConfig::default()).unwrap(); + let emb = spectral_init( + graph.view(), + None, + &SpectralInitConfig::new(2).with_seed(42), + ) + .unwrap(); let max_abs = emb.iter().map(|v| v.abs()).fold(0.0f32, f32::max); assert!( max_abs < 20.0, @@ -626,7 +693,7 @@ fn test_level_3_rsvd_valid_on_large_path() { // of the rSVD solver is therefore the appropriate approach here. let laplacian = large_path_laplacian(2001); let (eigs, vecs): (ndarray::Array1, ndarray::Array2) = - rsvd_solve(&laplacian, 2, 42, &SolverParams::default()); + rsvd_solve(&laplacian, 2, 42, &SolverParams::default()).expect("rsvd_solve failed"); assert_eq!( eigs.len(), 3, diff --git a/tests/internals/comp_a_degrees.rs b/tests/internals/comp_a_degrees.rs index ed3a507..9e582d0 100644 --- a/tests/internals/comp_a_degrees.rs +++ b/tests/internals/comp_a_degrees.rs @@ -9,7 +9,7 @@ fn run_comp_a_test(dataset: &str, expected_n: usize, mode: ComputeMode, tol: f64 let graph = fixtures::load_sparse_csr_f32_u32(&base.join("step5a_pruned.npz")); // Call the function under test - let (degrees, sqrt_deg) = compute_degrees(&graph, mode); + let (degrees, sqrt_deg) = compute_degrees(graph.view(), mode); // Load Python reference let ref_path = base.join("comp_a_degrees.npz"); diff --git a/tests/internals/comp_b_laplacian.rs b/tests/internals/comp_b_laplacian.rs index db8a7d0..b50fb51 100644 --- a/tests/internals/comp_b_laplacian.rs +++ b/tests/internals/comp_b_laplacian.rs @@ -16,7 +16,7 @@ fn run_comp_b_test(dataset: &str, expected_n: usize) { .collect(); // Call function under test - let l = build_normalized_laplacian(&graph, &inv_sqrt_deg); + let l = build_normalized_laplacian(graph.view(), &inv_sqrt_deg); assert_eq!(l.rows(), expected_n, "Laplacian rows"); assert_eq!(l.cols(), expected_n, "Laplacian cols"); diff --git a/tests/internals/comp_c_components.rs b/tests/internals/comp_c_components.rs index 8657132..a0e668a 100644 --- a/tests/internals/comp_c_components.rs +++ b/tests/internals/comp_c_components.rs @@ -9,7 +9,7 @@ fn run_comp_c_test(dataset: &str, expected_n_components: usize) { // Run the function under test let graph = fixtures::load_sparse_csr_f32_u32(&base.join("step5a_pruned.npz")); - let (labels, n_components) = find_components(&graph); + let (labels, n_components) = find_components(graph.view()); // Load Python reference let ref_path = base.join("comp_c_components.npz"); diff --git a/tests/internals/comp_d_dense_evd.rs b/tests/internals/comp_d_dense_evd.rs index 08c54d5..a66d510 100644 --- a/tests/internals/comp_d_dense_evd.rs +++ b/tests/internals/comp_d_dense_evd.rs @@ -20,7 +20,7 @@ fn run_comp_d_test(dataset: &str, expected_n: usize) { let k = ref_eigenvalues.len(); // Call dense_evd - let (eigenvalues, eigenvectors) = dense_evd(&laplacian, k).expect("dense_evd failed"); + let (eigenvalues, eigenvectors) = dense_evd(&laplacian, k, u64::MAX).expect("dense_evd failed"); // Eigenvalue accuracy check for i in 0..k { diff --git a/tests/internals/comp_d_rsvd.rs b/tests/internals/comp_d_rsvd.rs index 2751ef2..5791a65 100644 --- a/tests/internals/comp_d_rsvd.rs +++ b/tests/internals/comp_d_rsvd.rs @@ -34,7 +34,8 @@ macro_rules! rsvd_test { n_components, 42, &spectral_init::__internal::SolverParams::default(), - ); + ) + .expect("rsvd_solve failed"); // Check eigenvalue accuracy. The production rsvd_solve uses nbiter=2 // and n/10 oversampling, trading precision for speed. On graphs with tiny diff --git a/tests/internals/e2e_residual.rs b/tests/internals/e2e_residual.rs index 2c9c424..2e5f297 100644 --- a/tests/internals/e2e_residual.rs +++ b/tests/internals/e2e_residual.rs @@ -9,8 +9,12 @@ fn run_e2e_residual_check(dataset: &str, n: usize) { let graph_path = fixtures::fixture_path(dataset, "step5a_pruned.npz"); let graph = fixtures::load_sparse_csr_f32_u32(&graph_path); - let result = spectral_init(&graph, 2, 42, None, SpectralInitConfig::default()) - .unwrap_or_else(|e| panic!("spectral_init failed for {dataset}: {e}")); + let result = spectral_init( + graph.view(), + None, + &SpectralInitConfig::new(2).with_seed(42), + ) + .unwrap_or_else(|e| panic!("spectral_init failed for {dataset}: {e}")); assert_eq!(result.shape(), &[n, 2]); for &v in result.iter() { assert!(v.is_finite(), "non-finite in {dataset}: {v}"); diff --git a/tests/internals/escalation.rs b/tests/internals/escalation.rs new file mode 100644 index 0000000..79aa0c0 --- /dev/null +++ b/tests/internals/escalation.rs @@ -0,0 +1,242 @@ +//! Escalation and the dense memory budget: which level answers, and which error is +//! returned when none can. + +use crate::fixtures; +use ndarray::{Array1, Array2}; +use spectral_init::__internal::{ + QualityGates, SolveReport, SolverLevel, SolverParams, solve_eigenproblem, +}; +use spectral_init::sprs::{CsMatI, TriMatI}; +use spectral_init::{ComputeMode, SpectralError, SpectralInitConfig, spectral_init}; + +/// Size of the ring Laplacian the solver tests run on. +const N: usize = 100; + +/// Bytes of the dense `N × N` matrix Levels 0 and 5 need. +const DENSE_BYTES: u64 = (N * N * 8) as u64; + +/// Bytes of the dense `N × k` sketch Level 4 needs for two components: rank 3 plus the +/// default oversampling of `N / 10`. +const SKETCH_BYTES: u64 = (N * (3 + N / 10) * 8) as u64; + +/// Gates that no iterative result can pass (`residual < 0.0` never holds). +fn failing_iterative_gates() -> QualityGates { + QualityGates { + lobpcg: 0.0, + sinv: 0.0, + rsvd: 0.0, + ..QualityGates::default() + } +} + +/// Asserts that `result` is `DenseBudgetExceeded` reporting exactly these sizes. +fn assert_budget_exceeded( + result: Result, + required: u64, + budget: u64, +) { + match result { + Err(SpectralError::DenseBudgetExceeded { + required_bytes, + budget_bytes, + .. + }) => assert_eq!((required_bytes, budget_bytes), (required, budget)), + other => panic!("expected DenseBudgetExceeded, got {other:?}"), + } +} + +fn solve(params: &SolverParams) -> Result { + let laplacian = fixtures::ring_laplacian(N); + let sqrt_deg: Array1 = fixtures::ring_sqrt_deg(N); + solve_eigenproblem( + &laplacian, + 2, + 42, + &sqrt_deg, + ComputeMode::PythonCompat, + params, + ) + .map(|(_eigenpairs, report)| report) +} + +#[test] +fn forced_dense_answers_when_every_other_level_fails() { + let params = SolverParams { + dense_n_threshold: 0, + gates: failing_iterative_gates(), + dense_memory_budget: DENSE_BYTES, + ..SolverParams::default() + }; + let report = solve(¶ms).expect("Level 5 fits the budget exactly"); + assert_eq!(report.level, SolverLevel::ForcedDense); + assert!(report.residual < params.gates.dense); + assert!(report.level_elapsed[SolverLevel::DenseEvd as usize].is_none()); + for level in 1..=5 { + assert!( + report.level_elapsed[level].is_some(), + "level {level} must have run" + ); + } +} + +#[test] +fn forced_dense_over_budget_is_an_error() { + let params = SolverParams { + dense_n_threshold: 0, + gates: failing_iterative_gates(), + dense_memory_budget: DENSE_BYTES - 1, + ..SolverParams::default() + }; + assert_budget_exceeded(solve(¶ms), DENSE_BYTES, DENSE_BYTES - 1); +} + +#[test] +fn forced_dense_result_must_pass_the_dense_gate() { + let params = SolverParams { + dense_n_threshold: 0, + gates: QualityGates { + dense: 0.0, + ..failing_iterative_gates() + }, + dense_memory_budget: DENSE_BYTES, + ..SolverParams::default() + }; + assert_err!( + solve(¶ms), + SpectralError::ConvergenceFailure { n: N, .. } + ); +} + +#[test] +fn level_0_over_budget_escalates_to_an_iterative_level() { + // n = 100 is below the dense threshold, so Level 0 is tried first. + let within = SolverParams::default(); + assert_eq!(solve(&within).unwrap().level, SolverLevel::DenseEvd); + + let over = SolverParams { + dense_memory_budget: DENSE_BYTES - 1, + ..SolverParams::default() + }; + let report = solve(&over).expect("an iterative level converges on the ring"); + assert!( + report.level > SolverLevel::DenseEvd && report.level < SolverLevel::ForcedDense, + "expected an iterative level, got {:?}", + report.level + ); +} + +#[test] +fn level_4_runs_within_budget_and_is_skipped_over_it() { + // Levels 1–3 are made to fail; any Level 4 result is accepted. + let gates = QualityGates { + lobpcg: 0.0, + sinv: 0.0, + rsvd: f64::INFINITY, + ..QualityGates::default() + }; + let within = SolverParams { + dense_n_threshold: 0, + gates, + dense_memory_budget: SKETCH_BYTES, + ..SolverParams::default() + }; + assert_eq!(solve(&within).unwrap().level, SolverLevel::Rsvd); + + // One byte less: Level 4 is skipped, and Level 5 needs even more. + let over = SolverParams { + dense_memory_budget: SKETCH_BYTES - 1, + ..within + }; + assert_budget_exceeded(solve(&over), DENSE_BYTES, SKETCH_BYTES - 1); +} + +// ── the budget of `SpectralInitConfig` reaches every dense allocation ──────── + +fn params_with_config_budget(budget: u64) -> SolverParams { + let config = SpectralInitConfig::new(2).with_dense_memory_budget(budget); + let params = SolverParams::from_config(&config); + assert_eq!(params.dense_memory_budget, budget); + params +} + +#[test] +fn config_budget_reaches_level_0() { + let report = solve(¶ms_with_config_budget(DENSE_BYTES - 1)).unwrap(); + assert_ne!(report.level, SolverLevel::DenseEvd); + let report = solve(¶ms_with_config_budget(DENSE_BYTES)).unwrap(); + assert_eq!(report.level, SolverLevel::DenseEvd); +} + +#[test] +fn config_budget_reaches_level_4() { + let with_budget = |budget| SolverParams { + dense_n_threshold: 0, + gates: QualityGates { + lobpcg: 0.0, + sinv: 0.0, + rsvd: f64::INFINITY, + ..QualityGates::default() + }, + ..params_with_config_budget(budget) + }; + assert_eq!( + solve(&with_budget(SKETCH_BYTES)).unwrap().level, + SolverLevel::Rsvd + ); + assert!(matches!( + solve(&with_budget(SKETCH_BYTES - 1)), + Err(SpectralError::DenseBudgetExceeded { .. }) + )); +} + +#[test] +fn config_budget_reaches_level_5() { + let with_budget = |budget| SolverParams { + dense_n_threshold: 0, + gates: failing_iterative_gates(), + ..params_with_config_budget(budget) + }; + assert_eq!( + solve(&with_budget(DENSE_BYTES)).unwrap().level, + SolverLevel::ForcedDense + ); + assert_budget_exceeded( + solve(&with_budget(DENSE_BYTES - 1)), + DENSE_BYTES, + DENSE_BYTES - 1, + ); +} + +/// Six separate triangles with well-separated data: more components than +/// `2 · n_components`, so the component centroids get a spectral embedding of their own. +fn six_triangles() -> (CsMatI, Array2) { + let mut tri: TriMatI = TriMatI::new((18, 18)); + for component in 0..6usize { + let base = 3 * component; + for (a, b) in [(0, 1), (1, 2), (0, 2)] { + tri.add_triplet(base + a, base + b, 1.0); + tri.add_triplet(base + b, base + a, 1.0); + } + } + let data = Array2::from_shape_fn((18, 2), |(node, feature)| { + (node / 3) as f32 * 0.5 + feature as f32 * 0.1 + }); + (tri.to_csr(), data) +} + +#[test] +fn config_budget_reaches_the_centroid_affinity() { + let (graph, data) = six_triangles(); + // The affinity between six component centroids is a dense 6 × 6 matrix: 288 bytes. + let config = SpectralInitConfig::new(2).with_dense_memory_budget(288); + let coords = spectral_init(graph.view(), Some(data.view()), &config) + .expect("the affinity matrix fits the budget exactly"); + assert_eq!(coords.dim(), (18, 2)); + + let config = config.with_dense_memory_budget(287); + assert_budget_exceeded( + spectral_init(graph.view(), Some(data.view()), &config), + 288, + 287, + ); +} diff --git a/tests/internals/laplacian.rs b/tests/internals/laplacian.rs new file mode 100644 index 0000000..98e7109 --- /dev/null +++ b/tests/internals/laplacian.rs @@ -0,0 +1,174 @@ +//! Self-loops: diagonal graph weights take part in both the degree and the adjacency, +//! as in umap-learn. Checked against the Python reference in `tests/fixtures/selfloop`. + +use crate::{diagnostics, fixtures, internals}; +use ndarray::{Array1, Array2}; +use spectral_init::__internal::{build_normalized_laplacian, compute_degrees, dense_evd}; +use spectral_init::sprs::CsMatI; +use spectral_init::{ComputeMode, SpectralInitConfig, spectral_init}; + +const DATASET: &str = "selfloop"; + +fn graph() -> CsMatI { + let graph = fixtures::load_sparse_csr_f32_u32(&fixtures::fixture_path(DATASET, "graph.npz")); + let self_loops = (0..graph.rows()) + .filter(|&i| graph.get(i, i).is_some_and(|&w| w > 0.0)) + .count(); + assert!(self_loops >= 3, "the fixture graph must carry self-loops"); + graph +} + +/// Degrees and Laplacian of the fixture graph, as the pipeline computes them. +fn degrees_and_laplacian(mode: ComputeMode) -> (Array1, CsMatI) { + let graph = graph(); + let (degrees, sqrt_deg) = compute_degrees(graph.view(), mode); + let inv_sqrt_deg: Vec = sqrt_deg.iter().map(|&s| 1.0 / s).collect(); + ( + degrees, + build_normalized_laplacian(graph.view(), &inv_sqrt_deg), + ) +} + +#[test] +fn degrees_include_the_diagonal_and_match_python() { + let (degrees, _) = degrees_and_laplacian(ComputeMode::PythonCompat); + let reference: Array1 = fixtures::load_dense( + &fixtures::fixture_path(DATASET, "comp_a_degrees.npz"), + "degrees", + ); + assert_eq!(degrees.len(), reference.len()); + for (i, (&got, &want)) in degrees.iter().zip(reference.iter()).enumerate() { + assert!( + (got - want).abs() <= 1e-15 * want.abs().max(1.0), + "degrees[{i}]: got {got}, want {want}" + ); + } + + // Each degree is the full row sum, diagonal included. + let graph = graph(); + for (i, row) in graph.outer_iterator().enumerate() { + let row_sum: f64 = row.data().iter().map(|&w| f64::from(w)).sum(); + assert!((degrees[i] - row_sum).abs() < 1e-6, "row {i}"); + } +} + +#[test] +fn laplacian_matches_python() { + let (_, laplacian) = degrees_and_laplacian(ComputeMode::PythonCompat); + let reference = + fixtures::load_sparse_csr(&fixtures::fixture_path(DATASET, "comp_b_laplacian.npz")); + let n = laplacian.rows(); + assert_eq!(reference.shape(), (n, n)); + for i in 0..n { + for j in 0..n { + let got = laplacian.get(i, j).copied().unwrap_or(0.0); + let want = reference.get(i, j).copied().unwrap_or(0.0); + assert!( + (got - want).abs() < 1e-14, + "L[{i},{j}]: got {got}, want {want}" + ); + } + } +} + +#[test] +fn laplacian_equals_the_dense_formula() { + for mode in [ComputeMode::PythonCompat, ComputeMode::RustNative] { + let graph = graph(); + let n = graph.rows(); + let (degrees, laplacian) = degrees_and_laplacian(mode); + + // L = I − D^{-1/2} A D^{-1/2}, evaluated densely with the diagonal of A kept. + let mut expected = Array2::::eye(n); + for (&weight, (i, j)) in graph.iter() { + let (i, j) = (i as usize, j as usize); + expected[[i, j]] -= f64::from(weight) / (degrees[i].sqrt() * degrees[j].sqrt()); + } + for i in 0..n { + assert!( + laplacian.get(i, i).is_some(), + "diagonal entry {i} is not stored" + ); + for j in 0..n { + let got = laplacian.get(i, j).copied().unwrap_or(0.0); + assert!( + (got - expected[[i, j]]).abs() < 1e-14, + "{mode:?} L[{i},{j}]: got {got}, want {}", + expected[[i, j]] + ); + } + } + } +} + +#[test] +fn sqrt_degree_is_the_null_vector() { + // `PythonCompat` accumulates degrees in single precision, as umap-learn does, so its + // null vector is exact only to f32 rounding; `RustNative` sums in double precision. + for (mode, tolerance) in [ + (ComputeMode::PythonCompat, 1e-6), + (ComputeMode::RustNative, 1e-14), + ] { + let (degrees, laplacian) = degrees_and_laplacian(mode); + let sqrt_deg = degrees.mapv(f64::sqrt); + let residual = &laplacian * &sqrt_deg; + let norm = residual.dot(&residual).sqrt(); + assert!(norm < tolerance, "{mode:?}: ‖L·√d‖ = {norm:e}"); + } +} + +#[test] +fn spectrum_lies_in_zero_two_and_matches_python() { + let (_, laplacian) = degrees_and_laplacian(ComputeMode::PythonCompat); + let n = laplacian.rows(); + let (eigenvalues, eigenvectors) = dense_evd(&laplacian, n, u64::MAX).expect("dense EVD"); + // Single-precision degrees perturb the spectrum by about one f32 rounding error. + for (i, &lambda) in eigenvalues.iter().enumerate() { + assert!( + (-1e-6..=2.0 + 1e-6).contains(&lambda), + "eigenvalue[{i}] = {lambda} outside [0, 2]" + ); + } + assert!( + eigenvalues[0].abs() < 1e-6, + "smallest eigenvalue {} is not 0", + eigenvalues[0] + ); + + let reference_path = fixtures::fixture_path(DATASET, "comp_d_eigensolver.npz"); + let reference: Array1 = fixtures::load_dense(&reference_path, "eigenvalues"); + for (i, &want) in reference.iter().enumerate() { + assert!( + (eigenvalues[i] - want).abs() < 1e-7, + "eigenvalue[{i}]: got {}, want {want}", + eigenvalues[i] + ); + } + for i in 0..reference.len() { + let residual = internals::residual_spmv(&laplacian, eigenvectors.column(i), eigenvalues[i]); + assert!(residual < 1e-12, "residual[{i}] = {residual:e}"); + } +} + +#[test] +fn spectral_init_spans_the_python_embedding() { + let graph = graph(); + let reference: Array2 = fixtures::load_dense( + &fixtures::fixture_path(DATASET, "full_spectral.npz"), + "embedding", + ); + for mode in [ComputeMode::PythonCompat, ComputeMode::RustNative] { + let config = SpectralInitConfig::new(2) + .with_seed(42) + .with_compute_mode(mode); + let coords = spectral_init(graph.view(), None, &config) + .expect("spectral_init") + .mapv(f64::from); + assert_eq!(coords.dim(), reference.dim()); + let gram_det = diagnostics::subspace_gram_det(coords.view(), reference.view()); + assert!( + gram_det > 0.999, + "{mode:?}: subspace Gram determinant {gram_det}" + ); + } +} diff --git a/tests/internals/main.rs b/tests/internals/main.rs index 11acc62..b2b9dab 100644 --- a/tests/internals/main.rs +++ b/tests/internals/main.rs @@ -2,6 +2,9 @@ #![cfg(feature = "__internal")] +#[macro_use] +#[path = "../common/assertions.rs"] +mod assertions; #[path = "../common/diagnostics.rs"] mod diagnostics; #[path = "../common/fixtures.rs"] @@ -21,6 +24,9 @@ mod comp_f_lobpcg; mod comp_g_sinv; mod diagnostic_metrics; mod e2e_residual; +mod escalation; +mod laplacian; +mod no_panic; mod operator_fixtures; mod property_tests; mod psd_contract; diff --git a/tests/internals/no_panic.rs b/tests/internals/no_panic.rs new file mode 100644 index 0000000..94658f3 --- /dev/null +++ b/tests/internals/no_panic.rs @@ -0,0 +1,134 @@ +//! No valid Laplacian makes the solver chain panic: with the dense first level switched +//! off, every later level runs and the chain still returns `Ok` or `Err`. + +use ndarray::Array2; +use proptest::prelude::*; +use proptest::test_runner::FileFailurePersistence; +use spectral_init::__internal::{ + SolverParams, build_normalized_laplacian, compute_degrees, solve_eigenproblem, +}; +use spectral_init::sprs::{CsMatI, TriMatI}; +use spectral_init::{ComputeMode, SpectralError, SpectralInitConfig, spectral_init}; + +/// Failing cases persist to `no_panic.proptest-regressions`, next to this file. +fn config() -> ProptestConfig { + ProptestConfig { + cases: 256, + max_shrink_iters: 256, + failure_persistence: Some(Box::new(FileFailurePersistence::WithSource( + "proptest-regressions", + ))), + ..Default::default() + } +} + +/// A symmetric, positively weighted graph (self-loops allowed) and a solve request. +#[derive(Debug, Clone)] +struct Case { + n: usize, + edges: Vec<(usize, usize, f32)>, + n_components: usize, + seed: u64, + rust_native: bool, + dense_memory_budget: u64, +} + +impl Case { + fn graph(&self) -> CsMatI { + let mut tri: TriMatI = TriMatI::new((self.n, self.n)); + for &(row, col, weight) in &self.edges { + tri.add_triplet(row, col, weight); + if row != col { + tri.add_triplet(col, row, weight); + } + } + tri.to_csr() + } + + fn compute_mode(&self) -> ComputeMode { + if self.rust_native { + ComputeMode::RustNative + } else { + ComputeMode::PythonCompat + } + } +} + +fn case() -> impl Strategy { + (2usize..=14).prop_flat_map(|n| { + ( + proptest::collection::vec((0..n, 0..n, 0.05f32..4.0), 0..=40), + // Up to and beyond the largest solvable request (n - 1). + 0..=n + 1, + any::(), + any::(), + prop_oneof![ + Just(0u64), + Just(256u64), + Just(SpectralInitConfig::DEFAULT_DENSE_MEMORY_BUDGET), + ], + ) + .prop_map( + move |(edges, n_components, seed, rust_native, dense_memory_budget)| Case { + n, + edges, + n_components, + seed, + rust_native, + dense_memory_budget, + }, + ) + }) +} + +/// Whether `graph` passes the boundary validation of `spectral_init`. A data argument +/// without rows is rejected last-but-one, after every check on the graph. +fn passes_validation(graph: &CsMatI) -> bool { + let no_rows = Array2::::zeros((0, 1)); + matches!( + spectral_init( + graph.view(), + Some(no_rows.view()), + &SpectralInitConfig::new(1) + ), + Err(SpectralError::DataShapeMismatch { .. }) + ) +} + +proptest! { + #![proptest_config(config())] + + #[test] + fn solver_chain_never_panics(case in case()) { + let graph = case.graph(); + prop_assert!(passes_validation(&graph)); + + let mode = case.compute_mode(); + let (_degrees, sqrt_deg) = compute_degrees(graph.view(), mode); + let inv_sqrt_deg: Vec = sqrt_deg + .iter() + .map(|&s| if s > 0.0 { 1.0 / s } else { 0.0 }) + .collect(); + let laplacian = build_normalized_laplacian(graph.view(), &inv_sqrt_deg); + + let params = SolverParams { + dense_n_threshold: 0, + dense_memory_budget: case.dense_memory_budget, + ..SolverParams::default() + }; + let result = solve_eigenproblem( + &laplacian, + case.n_components, + case.seed, + &sqrt_deg, + mode, + ¶ms, + ); + if let Ok(((eigenvalues, eigenvectors), _report)) = result { + prop_assert_eq!(eigenvalues.len(), case.n_components + 1); + prop_assert_eq!(eigenvectors.dim(), (case.n, case.n_components + 1)); + prop_assert!(eigenvalues.iter().all(|&v| (0.0..=2.0).contains(&v))); + prop_assert!(eigenvectors.iter().all(|v| v.is_finite())); + } + } +} diff --git a/tests/internals/property_tests.rs b/tests/internals/property_tests.rs index 09f93c6..d7b6e0e 100644 --- a/tests/internals/property_tests.rs +++ b/tests/internals/property_tests.rs @@ -121,7 +121,7 @@ proptest! { #[test] fn proptest_finite_output(n in 50usize..=200) { let graph = fixtures::make_ring(n as u32); - let coords = spectral_init(&graph, 2, 42, None, SpectralInitConfig::default()) + let coords = spectral_init(graph.view(), None, &SpectralInitConfig::new(2).with_seed(42)) .expect("spectral_init failed"); for &v in coords.iter() { prop_assert!(v.is_finite(), "non-finite value {} in output, n={}", v, n); @@ -131,7 +131,7 @@ proptest! { #[test] fn proptest_output_variance(n in 50usize..=200) { let graph = fixtures::make_ring(n as u32); - let coords = spectral_init(&graph, 2, 42, None, SpectralInitConfig::default()) + let coords = spectral_init(graph.view(), None, &SpectralInitConfig::new(2).with_seed(42)) .expect("spectral_init failed"); for col_idx in 0..coords.ncols() { let col = coords.column(col_idx); @@ -148,9 +148,9 @@ proptest! { #[test] fn proptest_subspace_stable(n in 50usize..=200) { let graph = fixtures::make_ring(n as u32); - let out1 = spectral_init(&graph, 2, 42, None, SpectralInitConfig::default()) + let out1 = spectral_init(graph.view(), None, &SpectralInitConfig::new(2).with_seed(42)) .expect("spectral_init run 1 failed"); - let out2 = spectral_init(&graph, 2, 42, None, SpectralInitConfig::default()) + let out2 = spectral_init(graph.view(), None, &SpectralInitConfig::new(2).with_seed(42)) .expect("spectral_init run 2 failed"); prop_assert!( out1 == out2, diff --git a/tests/internals/solver_invariants.rs b/tests/internals/solver_invariants.rs index dcd05f0..c832c60 100644 --- a/tests/internals/solver_invariants.rs +++ b/tests/internals/solver_invariants.rs @@ -119,8 +119,12 @@ fn test_inv_sign_convention() { for dataset in &["blobs_50", "blobs_connected_2000"] { let graph_path = fixtures::fixture_path(dataset, "step5a_pruned.npz"); let graph = fixtures::load_sparse_csr_f32_u32(&graph_path); - let result = spectral_init(&graph, 2, 42, None, SpectralInitConfig::default()) - .unwrap_or_else(|e| panic!("spectral_init failed for {dataset}: {e}")); + let result = spectral_init( + graph.view(), + None, + &SpectralInitConfig::new(2).with_seed(42), + ) + .unwrap_or_else(|e| panic!("spectral_init failed for {dataset}: {e}")); let (nrows, ncols) = (result.shape()[0], result.shape()[1]); for col in 0..ncols { // Check the argmax-absolute-value element is positive (the sign convention). @@ -155,8 +159,12 @@ fn test_inv_multi_component_completeness() { let graph = make_two_component_graph(N1, N2); let total = (N1 + N2) as usize; - let result = spectral_init(&graph, 2, 42, None, SpectralInitConfig::default()) - .unwrap_or_else(|e| panic!("spectral_init failed on synthetic 2-component graph: {e}")); + let result = spectral_init( + graph.view(), + None, + &SpectralInitConfig::new(2).with_seed(42), + ) + .unwrap_or_else(|e| panic!("spectral_init failed on synthetic 2-component graph: {e}")); assert_eq!(result.shape()[0], total, "expected {total} rows in output"); @@ -243,7 +251,8 @@ fn test_inv_lobpcg_convergence_ill_conditioned() { fn test_inv_rsvd_eigenvector_distinctness() { let lap_path = fixtures::fixture_path("blobs_5000", "comp_b_laplacian.npz"); let lap = fixtures::load_sparse_csr(&lap_path); - let (_eigvals, eigvecs) = rsvd_solve(&lap, 2, 42, &SolverParams::default()); + let (_eigvals, eigvecs) = + rsvd_solve(&lap, 2, 42, &SolverParams::default()).expect("rsvd_solve failed"); let v0 = eigvecs.column(0); let v1 = eigvecs.column(1); diff --git a/tests/public_api/determinism.rs b/tests/public_api/determinism.rs new file mode 100644 index 0000000..bbc4dab --- /dev/null +++ b/tests/public_api/determinism.rs @@ -0,0 +1,64 @@ +//! The seed contract: equal configurations give equal output within one process, +//! different seeds give different output, and the generator behind the seed is the +//! ChaCha12 stream pinned by a golden file. + +use crate::fixtures; +use rand::{RngCore, SeedableRng}; +use rand_chacha::ChaCha12Rng; +use spectral_init::{ComputeMode, SpectralInitConfig, spectral_init}; + +const MODES: [ComputeMode; 2] = [ComputeMode::PythonCompat, ComputeMode::RustNative]; + +#[test] +fn same_config_gives_identical_output() { + // A small graph (dense solver) and a fixture graph large enough for the iterative, + // randomly initialized solvers. + let small = fixtures::make_ring(60); + let large = fixtures::load_sparse_csr_f32_u32(&fixtures::fixture_path( + "blobs_connected_2000", + "step5a_pruned.npz", + )); + for graph in [&small, &large] { + for mode in MODES { + let config = SpectralInitConfig::new(2) + .with_seed(42) + .with_compute_mode(mode); + let first = spectral_init(graph.view(), None, &config).expect("first run"); + let second = spectral_init(graph.view(), None, &config).expect("second run"); + assert_eq!(first, second, "n={} mode={mode:?}", graph.rows()); + } + } +} + +#[test] +fn different_seeds_give_different_output() { + let graph = fixtures::make_ring(60); + for mode in MODES { + let base = SpectralInitConfig::new(2).with_compute_mode(mode); + let a = spectral_init(graph.view(), None, &base.clone().with_seed(1)).expect("seed 1"); + let b = spectral_init(graph.view(), None, &base.with_seed(2)).expect("seed 2"); + assert_eq!(a.dim(), b.dim()); + assert_ne!(a, b, "mode={mode:?}"); + } +} + +#[test] +fn default_seed_is_zero() { + let graph = fixtures::make_ring(60); + let implicit = spectral_init(graph.view(), None, &SpectralInitConfig::new(2)); + let explicit = spectral_init(graph.view(), None, &SpectralInitConfig::new(2).with_seed(0)); + assert_eq!(implicit, explicit); +} + +#[test] +fn chacha12_stream_matches_the_golden_file() { + let golden: Vec = include_str!("golden/chacha12_seed42.txt") + .lines() + .map(|line| u64::from_str_radix(line, 16).expect("golden line is a hex u64")) + .collect(); + assert_eq!(golden.len(), 64); + + let mut rng = ChaCha12Rng::seed_from_u64(42); + let stream: Vec = (0..golden.len()).map(|_| rng.next_u64()).collect(); + assert_eq!(stream, golden); +} diff --git a/tests/public_api/e2e_validation.rs b/tests/public_api/e2e_validation.rs index c467cf7..3664e0f 100644 --- a/tests/public_api/e2e_validation.rs +++ b/tests/public_api/e2e_validation.rs @@ -24,8 +24,12 @@ fn vec_dot(a: ndarray::ArrayView1, b: ndarray::ArrayView1) -> f64 { fn run_e2e_exact_knn_check(dataset: &str, n: usize) { let graph_path = fixtures::fixture_path(dataset, "step5a_pruned_exact.npz"); let graph = fixtures::load_sparse_csr_f32_u32(&graph_path); - let result = spectral_init(&graph, 2, 42, None, SpectralInitConfig::default()) - .unwrap_or_else(|e| panic!("exact-KNN spectral_init failed for {dataset}: {e}")); + let result = spectral_init( + graph.view(), + None, + &SpectralInitConfig::new(2).with_seed(42), + ) + .unwrap_or_else(|e| panic!("exact-KNN spectral_init failed for {dataset}: {e}")); assert_eq!(result.shape(), &[n, 2]); for &v in result.iter() { assert!(v.is_finite(), "non-finite in exact-KNN {dataset}: {v}"); @@ -40,8 +44,12 @@ fn test_e2e_subspace_circles_300() { let graph_path = fixtures::fixture_path(dataset, "step5a_pruned.npz"); let graph = fixtures::load_sparse_csr_f32_u32(&graph_path); - let result = spectral_init(&graph, 2, 42, None, SpectralInitConfig::default()) - .unwrap_or_else(|e| panic!("spectral_init failed for {dataset}: {e}")); + let result = spectral_init( + graph.view(), + None, + &SpectralInitConfig::new(2).with_seed(42), + ) + .unwrap_or_else(|e| panic!("spectral_init failed for {dataset}: {e}")); let scaling_path = fixtures::fixture_path(dataset, "comp_f_scaling.npz"); let expansion: ndarray::Array0 = fixtures::load_dense(&scaling_path, "expansion"); @@ -89,8 +97,12 @@ fn test_e2e_subspace_near_dupes_100() { let graph_path = fixtures::fixture_path(dataset, "step5a_pruned.npz"); let graph = fixtures::load_sparse_csr_f32_u32(&graph_path); - let result = spectral_init(&graph, 2, 42, None, SpectralInitConfig::default()) - .unwrap_or_else(|e| panic!("spectral_init failed for {dataset}: {e}")); + let result = spectral_init( + graph.view(), + None, + &SpectralInitConfig::new(2).with_seed(42), + ) + .unwrap_or_else(|e| panic!("spectral_init failed for {dataset}: {e}")); let scaling_path = fixtures::fixture_path(dataset, "comp_f_scaling.npz"); let expansion: ndarray::Array0 = fixtures::load_dense(&scaling_path, "expansion"); @@ -158,8 +170,12 @@ fn test_e2e_disconnected_200_component_separation() { let graph_path = fixtures::fixture_path(dataset, "step5a_pruned.npz"); let graph = fixtures::load_sparse_csr_f32_u32(&graph_path); - let result = spectral_init(&graph, 2, 42, None, SpectralInitConfig::default()) - .unwrap_or_else(|e| panic!("spectral_init failed for {dataset}: {e}")); + let result = spectral_init( + graph.view(), + None, + &SpectralInitConfig::new(2).with_seed(42), + ) + .unwrap_or_else(|e| panic!("spectral_init failed for {dataset}: {e}")); let n = result.shape()[0]; assert!(result.shape()[1] == 2); @@ -230,8 +246,12 @@ fn test_e2e_performance_blobs_5000() { let path = fixtures::fixture_path("blobs_5000", "step5a_pruned.npz"); let graph = fixtures::load_sparse_csr_f32_u32(&path); let start = std::time::Instant::now(); - let result = spectral_init(&graph, 2, 42, None, SpectralInitConfig::default()) - .expect("blobs_5000 spectral_init failed"); + let result = spectral_init( + graph.view(), + None, + &SpectralInitConfig::new(2).with_seed(42), + ) + .expect("blobs_5000 spectral_init failed"); let elapsed = start.elapsed(); assert_eq!(result.shape()[1], 2); let budget_secs: u64 = std::env::var("CI_PERF_BUDGET_SECS") diff --git a/tests/public_api/golden/chacha12_seed42.txt b/tests/public_api/golden/chacha12_seed42.txt new file mode 100644 index 0000000..a5c58ef --- /dev/null +++ b/tests/public_api/golden/chacha12_seed42.txt @@ -0,0 +1,64 @@ +86cc7763222724a2 +8af00a133fad517d +a2ef6071de5134d1 +67e92d78fd7630b2 +08cab0dff8119fea +6a3a9ca39e0f81a8 +bcc7d8e8590878fb +d9688d9b2f8eb737 +219b7e47a11c835e +00d5211f7aba3a1e +eea11039d26bae37 +8193012e994eac09 +64019743ddd2f652 +2410b617b5c73fda +85e5e480cd5aadfc +37fd16ebd1802190 +03394b7ca3072fca +84ed7c21290ed3f3 +0cdebc7a765a56e4 +a57dc7c9a983551f +d885b9d042c5f5bf +7f6b05ab76afa832 +8187c01bfa9a4fc3 +0ef9833f6a0a3f25 +59dbd86317cecb50 +7293421f4d4e3852 +cb5cceb423cf90d5 +341ade3195244fc4 +66d6afcd84ea33f2 +a793e7fe2a07abd3 +6c8a64b4dd8a46e1 +e373bd0032102eec +ec0619b0ee66b7a9 +de8aa9696c100e0f +a61dc1b0a5465bd3 +388486e7cf08a133 +93b87b4a5aab1cb6 +63de0af2607885cf +1115642b997b2c67 +6da293fb18d37054 +fc9562c3091f55b7 +9b7e5961cb414813 +73df1642e2a23995 +073a4ae23f556051 +27797b39e0382235 +627338ea43b2a45d +7dcd37d60133ba8b +f7fc05accfd993dc +d9ee88a87ff45726 +8bb88317f1dee5a4 +c4d38653f3b17db5 +cf946b8dc94bd4b1 +932dec02ff9f7113 +3c205523d9235a7c +62188a01fc599ee8 +64cdf534fb3cda6c +3aa1ddb8e242d766 +3ee79b70f426951e +a26bde22e25bd883 +7a5d9e364cf83c54 +f78edf51ececafb5 +2b2a00c1f3ba4a43 +77167bf3be13f027 +88c5bacb2698ccc0 diff --git a/tests/public_api/layout.rs b/tests/public_api/layout.rs new file mode 100644 index 0000000..5bdd917 --- /dev/null +++ b/tests/public_api/layout.rs @@ -0,0 +1,57 @@ +//! The returned array is always in standard (C-contiguous, row-major) layout. + +use crate::fixtures; +use spectral_init::ndarray::Array2; +use spectral_init::sprs::{CsMatI, TriMatI}; +use spectral_init::{SpectralInitConfig, spectral_init}; + +fn assert_standard_layout(coords: &Array2, expected_dim: (usize, usize)) { + assert_eq!(coords.dim(), expected_dim); + assert!( + coords.is_standard_layout(), + "array is not in standard layout" + ); + let slice = coords.as_slice().expect("as_slice() must succeed"); + // Row-major: element (i, j) sits at i * n_components + j. + let n_components = expected_dim.1; + for ((i, j), &value) in coords.indexed_iter() { + assert_eq!(slice[i * n_components + j], value); + } +} + +#[test] +fn connected_graph_output_is_standard_layout() { + let graph = fixtures::make_ring(40); + for n_components in [2usize, 3] { + let coords = spectral_init( + graph.view(), + None, + &SpectralInitConfig::new(n_components).with_seed(42), + ) + .expect("ring graph"); + assert_standard_layout(&coords, (40, n_components)); + } +} + +#[test] +fn disconnected_graph_output_is_standard_layout() { + // Two rings of 12 nodes each. + let mut tri: TriMatI = TriMatI::new((24, 24)); + for base in [0usize, 12] { + for i in 0..12 { + let (a, b) = (base + i, base + (i + 1) % 12); + tri.add_triplet(a, b, 1.0); + tri.add_triplet(b, a, 1.0); + } + } + let graph: CsMatI = tri.to_csr(); + for n_components in [2usize, 3] { + let coords = spectral_init( + graph.view(), + None, + &SpectralInitConfig::new(n_components).with_seed(42), + ) + .expect("two-ring graph"); + assert_standard_layout(&coords, (24, n_components)); + } +} diff --git a/tests/public_api/main.rs b/tests/public_api/main.rs index 6bf18d0..90f5cb5 100644 --- a/tests/public_api/main.rs +++ b/tests/public_api/main.rs @@ -1,8 +1,16 @@ //! Integration tests of the public API, built with default features. +#[macro_use] +#[path = "../common/assertions.rs"] +mod assertions; #[path = "../common/fixtures.rs"] mod fixtures; +mod determinism; mod e2e_validation; +mod layout; +mod no_panic; mod npz_loading; mod pipeline; +mod traits; +mod validation; diff --git a/tests/public_api/no_panic.rs b/tests/public_api/no_panic.rs new file mode 100644 index 0000000..1843790 --- /dev/null +++ b/tests/public_api/no_panic.rs @@ -0,0 +1,171 @@ +//! No input makes `spectral_init` panic: every call returns `Ok` or `Err`. + +use proptest::prelude::*; +use proptest::test_runner::FileFailurePersistence; +use spectral_init::ndarray::Array2; +use spectral_init::sprs::{CsMatI, TriMatI}; +use spectral_init::{ComputeMode, SpectralInitConfig, spectral_init}; + +/// Failing cases persist to `no_panic.proptest-regressions`, next to this file. +fn config() -> ProptestConfig { + ProptestConfig { + cases: 512, + max_shrink_iters: 256, + failure_persistence: Some(Box::new(FileFailurePersistence::WithSource( + "proptest-regressions", + ))), + ..Default::default() + } +} + +/// An arbitrary input to `spectral_init`. +#[derive(Debug, Clone)] +struct Case { + rows: usize, + cols: usize, + entries: Vec<(usize, usize, f32)>, + mirror: bool, + csc: bool, + data: Option<(usize, usize, Vec)>, + n_components: usize, + seed: u64, + rust_native: bool, + dense_memory_budget: u64, +} + +impl Case { + fn graph(&self) -> CsMatI { + let mut tri: TriMatI = TriMatI::new((self.rows, self.cols)); + for &(row, col, weight) in &self.entries { + if row < self.rows && col < self.cols { + tri.add_triplet(row, col, weight); + } + if self.mirror && row != col && col < self.rows && row < self.cols { + tri.add_triplet(col, row, weight); + } + } + if self.csc { tri.to_csc() } else { tri.to_csr() } + } + + fn data(&self) -> Option> { + self.data.as_ref().map(|(rows, cols, values)| { + Array2::from_shape_vec((*rows, *cols), values.clone()).expect("rows * cols values") + }) + } + + fn spectral_config(&self) -> SpectralInitConfig { + SpectralInitConfig::new(self.n_components) + .with_seed(self.seed) + .with_compute_mode(if self.rust_native { + ComputeMode::RustNative + } else { + ComputeMode::PythonCompat + }) + .with_dense_memory_budget(self.dense_memory_budget) + } +} + +/// Weights a well-formed graph carries. +fn clean_weight() -> BoxedStrategy { + (0.05f32..4.0).boxed() +} + +/// Weights of every kind, valid or not. +fn any_weight() -> BoxedStrategy { + prop_oneof![ + 6 => 0.05f32..4.0, + 1 => Just(0.0f32), + 1 => Just(-0.0f32), + 1 => Just(-1.5f32), + 1 => Just(f32::NAN), + 1 => Just(f32::INFINITY), + 1 => Just(f32::MAX), + 1 => Just(f32::MIN_POSITIVE), + ] + .boxed() +} + +fn data_value() -> BoxedStrategy { + prop_oneof![ + 8 => -100.0f32..100.0, + 1 => Just(f32::NAN), + 1 => Just(f32::NEG_INFINITY), + ] + .boxed() +} + +fn budget() -> BoxedStrategy { + prop_oneof![ + Just(0u64), + Just(64u64), + Just(512u64), + Just(4096u64), + Just(SpectralInitConfig::DEFAULT_DENSE_MEMORY_BUDGET), + ] + .boxed() +} + +fn case() -> impl Strategy { + // `clean` cases are square, symmetric and positively weighted, so that the solvers + // run; the others exercise the validation boundary. + (0usize..=9, 0usize..=9, any::()).prop_flat_map(|(rows, other, clean)| { + let cols = if clean || other % 3 != 0 { rows } else { other }; + let weight = if clean { clean_weight() } else { any_weight() }; + let entries = proptest::collection::vec((0..rows.max(1), 0..cols.max(1), weight), 0..=28); + let data = proptest::option::of( + (prop_oneof![3 => Just(rows), 1 => 0usize..=10], 0usize..=3).prop_flat_map( + |(data_rows, data_cols)| { + ( + Just(data_rows), + Just(data_cols), + proptest::collection::vec(data_value(), data_rows * data_cols), + ) + }, + ), + ); + ( + entries, + any::(), + any::(), + data, + 0usize..=4, + any::(), + any::(), + budget(), + ) + .prop_map( + move |(entries, mirror, csc, data, n_components, seed, rust_native, budget)| Case { + rows, + cols, + entries, + mirror: clean || mirror, + csc, + data, + n_components, + seed, + rust_native, + dense_memory_budget: budget, + }, + ) + }) +} + +proptest! { + #![proptest_config(config())] + + #[test] + fn spectral_init_never_panics(case in case()) { + let graph = case.graph(); + let data = case.data(); + let result = spectral_init( + graph.view(), + data.as_ref().map(|d| d.view()), + &case.spectral_config(), + ); + if let Ok(coords) = result { + prop_assert_eq!(coords.dim(), (case.rows, case.n_components)); + prop_assert!(coords.is_standard_layout()); + prop_assert!(coords.iter().all(|v| v.is_finite())); + } + } +} diff --git a/tests/public_api/pipeline.rs b/tests/public_api/pipeline.rs index 99e3f42..a35a635 100644 --- a/tests/public_api/pipeline.rs +++ b/tests/public_api/pipeline.rs @@ -17,8 +17,12 @@ fn spectral_init_output_shape_all_connected_datasets() { let path = fixtures::fixture_path(dataset, "step5a_pruned.npz"); let graph = fixtures::load_sparse_csr_f32_u32(&path); - let result = spectral_init(&graph, 2, 42, None, SpectralInitConfig::default()) - .unwrap_or_else(|e| panic!("spectral_init failed for {dataset}: {e}")); + let result = spectral_init( + graph.view(), + None, + &SpectralInitConfig::new(2).with_seed(42), + ) + .unwrap_or_else(|e| panic!("spectral_init failed for {dataset}: {e}")); assert_eq!( result.shape(), @@ -41,8 +45,12 @@ fn spectral_init_output_close_to_pre_noise_blobs_connected_200() { let graph_path = fixtures::fixture_path(dataset, "step5a_pruned.npz"); let graph = fixtures::load_sparse_csr_f32_u32(&graph_path); - let result = spectral_init(&graph, 2, 42, None, SpectralInitConfig::default()) - .expect("spectral_init failed for blobs_connected_200"); + let result = spectral_init( + graph.view(), + None, + &SpectralInitConfig::new(2).with_seed(42), + ) + .expect("spectral_init failed for blobs_connected_200"); let fixture_path = fixtures::fixture_path(dataset, "comp_f_scaling.npz"); let pre_noise: ndarray::Array2 = fixtures::load_dense(&fixture_path, "pre_noise"); @@ -116,11 +124,9 @@ fn spectral_init_synthetic_disconnected_produces_valid_embedding() { .unwrap(); let result = spectral_init( - &g, - 2, - 42, + g.view(), Some(data_arr.view()), - SpectralInitConfig::default(), + &SpectralInitConfig::new(2).with_seed(42), ); let arr = result.expect("spectral_init on disconnected graph should succeed"); assert_eq!(arr.shape(), &[6, 2]); @@ -155,7 +161,7 @@ fn spectral_init_synthetic_disconnected_produces_valid_embedding() { fn spectral_init_synthetic_disconnected_preserves_component_structure() { // Same 6-node two-clique graph let g = make_two_clique_graph(); - let result = spectral_init(&g, 2, 42, None, SpectralInitConfig::default()); + let result = spectral_init(g.view(), None, &SpectralInitConfig::new(2).with_seed(42)); let arr = result.expect("spectral_init on disconnected graph should succeed"); assert_eq!(arr.shape(), &[6, 2]); @@ -187,7 +193,11 @@ fn spectral_init_disconnected_200_shape_and_finite() { let path = fixtures::fixture_path("disconnected_200", "step5a_pruned.npz"); let graph = fixtures::load_sparse_csr_f32_u32(&path); - let result = spectral_init(&graph, 2, 42, None, SpectralInitConfig::default()); + let result = spectral_init( + graph.view(), + None, + &SpectralInitConfig::new(2).with_seed(42), + ); let arr = result.expect("spectral_init on disconnected_200 should succeed"); assert_eq!(arr.shape()[1], 2); for &v in arr.iter() { @@ -201,7 +211,11 @@ fn spectral_init_blobs_50_produces_valid_embedding() { let path = fixtures::fixture_path("blobs_50", "step5a_pruned.npz"); let graph = fixtures::load_sparse_csr_f32_u32(&path); - let result = spectral_init(&graph, 2, 42, None, SpectralInitConfig::default()); + let result = spectral_init( + graph.view(), + None, + &SpectralInitConfig::new(2).with_seed(42), + ); let arr = result.expect("spectral_init on blobs_50 should succeed"); assert_eq!(arr.shape()[1], 2); for &v in arr.iter() { @@ -218,11 +232,15 @@ fn spectral_init_single_point() { let indices: Vec = vec![]; let data: Vec = vec![]; let g = CsMatI::::new((1, 1), indptr, indices, data); - let result = spectral_init(&g, 2, 42, None, SpectralInitConfig::default()); + let result = spectral_init(g.view(), None, &SpectralInitConfig::new(2).with_seed(42)); assert!( matches!( result, - Err(spectral_init::SpectralError::TooFewNodes { n: 1, dims: 2 }) + Err(spectral_init::SpectralError::TooFewNodes { + n: 1, + n_components: 2, + .. + }) ), "single-point graph should return TooFewNodes, got: {:?}", result @@ -236,11 +254,15 @@ fn spectral_init_two_points_connected() { let indices = vec![1u32, 0u32]; let data = vec![1.0f32, 1.0f32]; let g = CsMatI::::new((2, 2), indptr, indices, data); - let result = spectral_init(&g, 2, 42, None, SpectralInitConfig::default()); + let result = spectral_init(g.view(), None, &SpectralInitConfig::new(2).with_seed(42)); assert!( matches!( result, - Err(spectral_init::SpectralError::TooFewNodes { n: 2, dims: 2 }) + Err(spectral_init::SpectralError::TooFewNodes { + n: 2, + n_components: 2, + .. + }) ), "two-point graph with n_components=2 should return TooFewNodes, got: {:?}", result @@ -265,7 +287,7 @@ fn spectral_init_fully_connected_uniform() { indptr.push(indices.len()); } let g = CsMatI::::new((n, n), indptr, indices, data); - let result = spectral_init(&g, 2, 42, None, SpectralInitConfig::default()); + let result = spectral_init(g.view(), None, &SpectralInitConfig::new(2).with_seed(42)); let arr = result.expect("spectral_init on fully-connected graph should succeed"); assert_eq!(arr.shape(), &[n, 2]); for &v in arr.iter() { @@ -314,11 +336,9 @@ fn spectral_init_ten_component_graph() { } let data_arr = ndarray::Array2::from_shape_vec((n, 2), flat).unwrap(); let result = spectral_init( - &g, - 2, - 42, + g.view(), Some(data_arr.view()), - SpectralInitConfig::default(), + &SpectralInitConfig::new(2).with_seed(42), ); let arr = result.expect("spectral_init on 10-component graph should succeed"); assert_eq!(arr.shape(), &[n, 2]); diff --git a/tests/public_api/traits.rs b/tests/public_api/traits.rs new file mode 100644 index 0000000..b432649 --- /dev/null +++ b/tests/public_api/traits.rs @@ -0,0 +1,57 @@ +//! Static contracts of the public types. + +use spectral_init::{ComputeMode, SpectralError, SpectralInitConfig}; + +fn assert_send_sync_static() {} +fn assert_clone_partial_eq() {} +fn assert_debug() {} +fn assert_error() {} + +#[test] +fn spectral_error_contracts() { + assert_send_sync_static::(); + assert_clone_partial_eq::(); + assert_debug::(); + assert_error::(); +} + +#[test] +fn spectral_init_config_contracts() { + assert_send_sync_static::(); + assert_clone_partial_eq::(); + assert_debug::(); +} + +#[test] +fn compute_mode_contracts() { + fn assert_copy_eq() {} + assert_send_sync_static::(); + assert_copy_eq::(); + assert_debug::(); +} + +#[test] +fn spectral_error_converts_into_a_boxed_error() { + fn fallible() -> Result<(), Box> { + Err(SpectralError::DegenerateEmbedding)? + } + let message = fallible().unwrap_err().to_string(); + assert!(message.contains("degenerate"), "{message}"); +} + +#[test] +fn every_error_has_a_message() { + let errors = [ + SpectralError::DegenerateEmbedding, + spectral_init::spectral_init( + spectral_init::sprs::CsMatI::::zero((0, 0)).view(), + None, + &SpectralInitConfig::new(1), + ) + .unwrap_err(), + ]; + for error in errors { + assert!(!error.to_string().is_empty()); + assert!(!format!("{error:?}").is_empty()); + } +} diff --git a/tests/public_api/validation.rs b/tests/public_api/validation.rs new file mode 100644 index 0000000..9945152 --- /dev/null +++ b/tests/public_api/validation.rs @@ -0,0 +1,529 @@ +//! Boundary validation: every defect maps to its own error variant, in a fixed order of +//! precedence, and equivalent encodings of a valid graph give the same result. + +use crate::fixtures; +use spectral_init::ndarray::Array2; +use spectral_init::sprs::{CsMatI, TriMatI}; +use spectral_init::{ComputeMode, SpectralError, SpectralInitConfig, spectral_init}; + +type Graph = CsMatI; + +fn triplets(shape: (usize, usize), entries: &[(usize, usize, f32)]) -> TriMatI { + let mut tri = TriMatI::new(shape); + for &(row, col, weight) in entries { + tri.add_triplet(row, col, weight); + } + tri +} + +fn csr(shape: (usize, usize), entries: &[(usize, usize, f32)]) -> Graph { + triplets(shape, entries).to_csr() +} + +fn csc(shape: (usize, usize), entries: &[(usize, usize, f32)]) -> Graph { + triplets(shape, entries).to_csc() +} + +/// Entries of the symmetric matrix with the given upper-triangle edges. +fn symmetric(edges: &[(usize, usize, f32)]) -> Vec<(usize, usize, f32)> { + edges + .iter() + .flat_map(|&(i, j, w)| [(i, j, w), (j, i, w)]) + .collect() +} + +/// A valid 5-node path graph 0-1-2-3-4. +fn path_5() -> Vec<(usize, usize, f32)> { + symmetric(&[(0, 1, 1.0), (1, 2, 0.5), (2, 3, 0.25), (3, 4, 2.0)]) +} + +fn run(graph: &Graph, n_components: usize) -> Result, SpectralError> { + spectral_init(graph.view(), None, &SpectralInitConfig::new(n_components)) +} + +/// Outcome of validating `graph` alone: a data argument with no rows turns "the graph is +/// valid" into `DataShapeMismatch`, the last-but-one check, without running a solver. +fn validate_graph(graph: &Graph) -> Result<(), SpectralError> { + let no_rows = Array2::::zeros((0, 1)); + match spectral_init( + graph.view(), + Some(no_rows.view()), + &SpectralInitConfig::new(1), + ) { + Err(SpectralError::DataShapeMismatch { .. }) => Ok(()), + Err(other) => Err(other), + Ok(_) => panic!("a data argument without rows must be rejected"), + } +} + +// ── one defect, one variant ────────────────────────────────────────────────── + +#[test] +fn zero_components_is_an_invalid_parameter() { + let graph = csr((5, 5), &path_5()); + assert!(matches!( + run(&graph, 0), + Err(SpectralError::InvalidParameter { + name: "n_components", + .. + }) + )); +} + +#[test] +fn non_square_matrix_is_rejected() { + let graph = csr((3, 4), &[(0, 1, 1.0), (1, 0, 1.0)]); + assert_err!( + run(&graph, 2), + SpectralError::NotSquare { + rows: 3, + cols: 4, + .. + } + ); +} + +#[test] +fn too_few_nodes_covers_the_empty_graph() { + let empty = csr((0, 0), &[]); + assert_err!( + run(&empty, 2), + SpectralError::TooFewNodes { + n: 0, + n_components: 2, + .. + } + ); + + // n must exceed n_components: n == n_components is still too few. + let pair = csr((2, 2), &symmetric(&[(0, 1, 1.0)])); + assert_err!( + run(&pair, 2), + SpectralError::TooFewNodes { + n: 2, + n_components: 2, + .. + } + ); +} + +#[test] +fn non_finite_weights_are_rejected() { + for bad in [f32::NAN, f32::INFINITY, f32::NEG_INFINITY] { + let mut entries = path_5(); + entries.extend([(1, 3, bad), (3, 1, bad)]); + let graph = csr((5, 5), &entries); + // Row 1 comes first in CSR order. + assert_err!( + run(&graph, 2), + SpectralError::NonFiniteWeight { row: 1, col: 3, .. }, + "weight {bad}" + ); + } +} + +#[test] +fn negative_weights_are_rejected() { + let mut entries = path_5(); + entries.extend([(0, 4, -0.5), (4, 0, -0.5)]); + let graph = csr((5, 5), &entries); + assert_err!( + run(&graph, 2), + SpectralError::NegativeWeight { row: 0, col: 4, .. } + ); +} + +#[test] +fn negative_zero_is_an_absent_edge_not_a_negative_weight() { + let mut entries = path_5(); + entries.push((0, 4, -0.0)); + let graph = csr((5, 5), &entries); + assert!(run(&graph, 2).is_ok()); +} + +#[test] +fn missing_mirror_entry_is_not_symmetric() { + let mut entries = path_5(); + entries.push((0, 3, 0.7)); + let graph = csr((5, 5), &entries); + assert_err!( + run(&graph, 2), + SpectralError::NotSymmetric { row: 0, col: 3, .. } + ); +} + +#[test] +fn unequal_mirror_weights_are_not_symmetric() { + let mut entries = path_5(); + entries.extend([(0, 3, 0.7), (3, 0, 0.6)]); + let graph = csr((5, 5), &entries); + assert_err!( + run(&graph, 2), + SpectralError::NotSymmetric { row: 0, col: 3, .. } + ); +} + +#[test] +fn overflowing_degree_is_rejected() { + // Node 1 has two edges of weight f32::MAX: their single-precision sum is infinite. + let entries = symmetric(&[(0, 1, f32::MAX), (1, 2, f32::MAX), (2, 3, 1.0)]); + let graph = csr((4, 4), &entries); + assert_err!( + run(&graph, 2), + SpectralError::DegreeOverflow { node: 1, .. } + ); +} + +#[test] +fn data_with_the_wrong_row_count_is_rejected() { + let graph = csr((5, 5), &path_5()); + let data = Array2::::zeros((4, 3)); + assert_err!( + spectral_init(graph.view(), Some(data.view()), &SpectralInitConfig::new(2)), + SpectralError::DataShapeMismatch { + expected_rows: 5, + actual_rows: 4, + .. + } + ); +} + +#[test] +fn non_finite_data_is_rejected_even_when_data_is_unused() { + // A connected graph never reads `data`, but it is validated all the same. + let graph = csr((5, 5), &path_5()); + let mut data = Array2::::zeros((5, 3)); + data[[2, 1]] = f32::NAN; + assert_err!( + spectral_init(graph.view(), Some(data.view()), &SpectralInitConfig::new(2)), + SpectralError::NonFiniteData { row: 2, col: 1, .. } + ); +} + +// ── precedence ─────────────────────────────────────────────────────────────── + +#[test] +fn invalid_parameter_precedes_not_square() { + let graph = csr((3, 4), &[(0, 1, f32::NAN)]); + assert!(matches!( + run(&graph, 0), + Err(SpectralError::InvalidParameter { .. }) + )); +} + +#[test] +fn not_square_precedes_too_few_nodes_and_weight_checks() { + // 2 × 3 with n_components = 5 and a NaN weight. + let graph = csr((2, 3), &[(0, 1, f32::NAN)]); + assert_err!( + run(&graph, 5), + SpectralError::NotSquare { + rows: 2, + cols: 3, + .. + } + ); +} + +#[test] +fn too_few_nodes_precedes_weight_checks() { + let graph = csr((2, 2), &[(0, 1, f32::NAN), (1, 0, -1.0)]); + assert_err!( + run(&graph, 2), + SpectralError::TooFewNodes { + n: 2, + n_components: 2, + .. + } + ); +} + +#[test] +fn non_finite_precedes_negative_wherever_it_is_stored() { + // The negative weight is stored first (row 0); the NaN sits in the last row. + let mut entries = path_5(); + entries.extend([(0, 2, -1.0), (2, 0, -1.0), (4, 4, f32::NAN)]); + let graph = csr((5, 5), &entries); + assert_err!( + run(&graph, 2), + SpectralError::NonFiniteWeight { row: 4, col: 4, .. } + ); +} + +#[test] +fn nan_on_both_sides_is_non_finite_not_asymmetric() { + let mut entries = path_5(); + entries.extend([(0, 3, f32::NAN), (3, 0, f32::NAN)]); + let graph = csr((5, 5), &entries); + assert_err!( + run(&graph, 2), + SpectralError::NonFiniteWeight { row: 0, col: 3, .. } + ); +} + +#[test] +fn negative_precedes_not_symmetric() { + let mut entries = path_5(); + entries.extend([(0, 3, 0.7), (4, 2, -0.1)]); + let graph = csr((5, 5), &entries); + assert_err!( + run(&graph, 2), + SpectralError::NegativeWeight { row: 4, col: 2, .. } + ); +} + +#[test] +fn not_symmetric_precedes_degree_overflow() { + let mut entries = symmetric(&[(0, 1, f32::MAX), (1, 2, f32::MAX), (2, 3, 1.0)]); + entries.push((3, 0, 0.5)); + let graph = csr((4, 4), &entries); + assert_err!( + run(&graph, 2), + SpectralError::NotSymmetric { row: 3, col: 0, .. } + ); +} + +#[test] +fn degree_overflow_precedes_data_checks() { + let entries = symmetric(&[(0, 1, f32::MAX), (1, 2, f32::MAX), (2, 3, 1.0)]); + let graph = csr((4, 4), &entries); + let data = Array2::::from_elem((9, 2), f32::NAN); + assert_err!( + spectral_init(graph.view(), Some(data.view()), &SpectralInitConfig::new(2)), + SpectralError::DegreeOverflow { node: 1, .. } + ); +} + +#[test] +fn data_shape_precedes_data_values() { + let graph = csr((5, 5), &path_5()); + let data = Array2::::from_elem((4, 2), f32::INFINITY); + assert_err!( + spectral_init(graph.view(), Some(data.view()), &SpectralInitConfig::new(2)), + SpectralError::DataShapeMismatch { + expected_rows: 5, + actual_rows: 4, + .. + } + ); +} + +// ── caller's orientation ───────────────────────────────────────────────────── + +#[test] +fn csc_errors_use_the_callers_row_and_column() { + let mut entries = path_5(); + entries.push((0, 3, 0.7)); + assert_err!( + run(&csc((5, 5), &entries), 2), + SpectralError::NotSymmetric { row: 0, col: 3, .. } + ); + + let mut entries = path_5(); + entries.push((4, 1, f32::NAN)); + assert_err!( + run(&csc((5, 5), &entries), 2), + SpectralError::NonFiniteWeight { row: 4, col: 1, .. } + ); +} + +// ── equivalent encodings ───────────────────────────────────────────────────── + +/// A 9-node connected graph with uneven weights, as upper-triangle edges. +fn connected_edges() -> Vec<(usize, usize, f32)> { + let mut edges: Vec<(usize, usize, f32)> = (0..9usize) + .map(|i| (i, (i + 1) % 9, 0.3 + 0.07 * i as f32)) + .collect(); + edges.extend([(0, 4, 0.45), (2, 7, 0.81), (3, 8, 0.12)]); + edges +} + +/// Three separate triangles: a disconnected graph. +fn disconnected_edges() -> Vec<(usize, usize, f32)> { + (0..3usize) + .flat_map(|c| { + let base = 3 * c; + [ + (base, base + 1, 0.9 - 0.1 * c as f32), + (base + 1, base + 2, 0.5 + 0.2 * c as f32), + (base, base + 2, 0.35), + ] + }) + .collect() +} + +fn outputs(graph: &Graph) -> Vec> { + [ComputeMode::PythonCompat, ComputeMode::RustNative] + .into_iter() + .map(|mode| { + let config = SpectralInitConfig::new(2) + .with_seed(7) + .with_compute_mode(mode); + spectral_init(graph.view(), None, &config).expect("valid graph") + }) + .collect() +} + +#[test] +fn csc_storage_gives_the_same_result_as_csr() { + for edges in [connected_edges(), disconnected_edges()] { + let entries = symmetric(&edges); + let as_csr = csr((9, 9), &entries); + let as_csc = csc((9, 9), &entries); + assert!(as_csr.is_csr() && as_csc.is_csc()); + assert_eq!(outputs(&as_csr), outputs(&as_csc)); + } +} + +#[test] +fn stored_zeros_give_the_same_result_as_no_entry() { + for edges in [connected_edges(), disconnected_edges()] { + let entries = symmetric(&edges); + let canonical = csr((9, 9), &entries); + + // Explicit zeros: a mirrored pair, a one-sided entry and a diagonal one. + let mut with_zeros = entries.clone(); + with_zeros.extend([(1, 5, 0.0), (5, 1, 0.0), (6, 2, 0.0), (4, 4, 0.0)]); + let padded = csr((9, 9), &with_zeros); + assert!(padded.nnz() > canonical.nnz()); + + assert_eq!(outputs(&canonical), outputs(&padded)); + } +} + +#[test] +fn stored_zeros_do_not_join_components() { + // Two triangles joined only by a stored zero stay two components, each placed at + // its own position. Were the zero an edge, the six nodes would form one component + // and get a different layout. + let mut entries = symmetric(&[ + (0, 1, 1.0), + (1, 2, 1.0), + (0, 2, 1.0), + (3, 4, 1.0), + (4, 5, 1.0), + (3, 5, 1.0), + ]); + let separate = csr((6, 6), &entries); + entries.extend([(2, 3, 0.0), (3, 2, 0.0)]); + let zero_bridged = csr((6, 6), &entries); + assert_eq!(outputs(&separate), outputs(&zero_bridged)); +} + +#[test] +fn data_is_ignored_when_there_are_few_components() { + // Three components and two dimensions: 3 <= 2 * 2, so `data` is not consulted. + let graph = csr((9, 9), &symmetric(&disconnected_edges())); + let data = Array2::from_shape_fn((9, 4), |(i, j)| (i * 31 + j * 7) as f32); + let config = SpectralInitConfig::new(2).with_seed(3); + assert_eq!( + spectral_init(graph.view(), Some(data.view()), &config), + spectral_init(graph.view(), None, &config) + ); +} + +#[test] +fn many_components_require_data() { + // Five isolated pairs: 5 components > 2 * 2. + let edges: Vec<(usize, usize, f32)> = (0..5usize).map(|c| (2 * c, 2 * c + 1, 1.0)).collect(); + let graph = csr((10, 10), &symmetric(&edges)); + let config = SpectralInitConfig::new(2); + assert_err!( + spectral_init(graph.view(), None, &config), + SpectralError::DataRequired { + connected_components: 5, + n_components: 2, + .. + } + ); + + let data = Array2::from_shape_fn((10, 2), |(i, j)| (i / 2 + j) as f32); + let coords = + spectral_init(graph.view(), Some(data.view()), &config).expect("data was supplied"); + assert_eq!(coords.dim(), (10, 2)); + assert!(coords.iter().all(|v| v.is_finite())); +} + +// ── tolerance calibration ──────────────────────────────────────────────────── + +const DATASETS: &[&str] = &[ + "blobs_50", + "blobs_500", + "blobs_5000", + "blobs_connected_200", + "blobs_connected_2000", + "circles_300", + "disconnected_200", + "moons_200", + "near_dupes_100", +]; + +fn fixture_graphs() -> impl Iterator { + DATASETS.iter().flat_map(|dataset| { + ["step5a_pruned.npz", "step5a_pruned_exact.npz"].map(|file| { + let graph = fixtures::load_sparse_csr_f32_u32(&fixtures::fixture_path(dataset, file)); + (format!("{dataset}/{file}"), graph) + }) + }) +} + +/// Scales the first off-diagonal weight of `graph` by `factor`, leaving its mirror alone. +fn perturb_one_weight(graph: &Graph, factor: f32) -> Graph { + let (position, _) = graph + .iter() + .enumerate() + .find(|(_, (weight, (row, col)))| row != col && **weight != 0.0) + .expect("graph has an off-diagonal edge"); + let mut data = graph.data().to_vec(); + data[position] *= factor; + CsMatI::new( + graph.shape(), + graph.indptr().to_owned().into_raw_storage(), + graph.indices().to_vec(), + data, + ) +} + +#[test] +fn every_fixture_graph_passes_validation() { + let mut count = 0; + for (name, graph) in fixture_graphs() { + assert_eq!(validate_graph(&graph), Ok(()), "{name}"); + count += 1; + } + assert_eq!(count, 18); +} + +#[test] +fn a_one_part_in_a_thousand_asymmetry_fails_validation() { + for (name, graph) in fixture_graphs() { + let perturbed = perturb_one_weight(&graph, 1.0 + 1e-3); + assert!( + matches!( + validate_graph(&perturbed), + Err(SpectralError::NotSymmetric { .. }) + ), + "{name}" + ); + } +} + +#[test] +fn a_one_ulp_asymmetry_passes_validation() { + for (name, graph) in fixture_graphs() { + let (position, _) = graph + .iter() + .enumerate() + .find(|(_, (weight, (row, col)))| row != col && **weight != 0.0) + .expect("graph has an off-diagonal edge"); + let mut data = graph.data().to_vec(); + data[position] = f32::from_bits(data[position].to_bits() + 1); + let nudged: Graph = CsMatI::new( + graph.shape(), + graph.indptr().to_owned().into_raw_storage(), + graph.indices().to_vec(), + data, + ); + assert_eq!(validate_graph(&nudged), Ok(()), "{name}"); + } +} diff --git a/tests/test_generate_fixtures.py b/tests/test_generate_fixtures.py index a335f10..6ceda09 100644 --- a/tests/test_generate_fixtures.py +++ b/tests/test_generate_fixtures.py @@ -415,3 +415,36 @@ def test_suffix_parameter_step5a(): generate_step5a_prune(symmetric, outdir, n, suffix="_exact") assert (outdir / "step5a_pruned_exact.npz").exists() assert not (outdir / "step5a_pruned.npz").exists() + + +def test_selfloop_fixture(tmp_path: Path): + """The self-loop mini-fixture keeps diagonal weights in degree and Laplacian.""" + from generate_fixtures import generate_selfloop_fixture + + generate_selfloop_fixture(tmp_path) + d = tmp_path / "selfloop" + + graph = scipy.sparse.load_npz(d / "graph.npz") + assert graph.dtype == np.float32 + assert (graph != graph.T).nnz == 0, "graph must be exactly symmetric" + diagonal = graph.diagonal().astype(np.float64) + assert (diagonal > 0).sum() >= 3, "fixture needs several self-loops" + + degrees = np.load(d / "comp_a_degrees.npz")["degrees"] + L = scipy.sparse.load_npz(d / "comp_b_laplacian.npz").toarray() + np.testing.assert_allclose(np.diag(L), 1.0 - diagonal / degrees, atol=1e-12) + np.testing.assert_allclose(L @ np.sqrt(degrees), 0.0, atol=1e-12) + + eig = np.load(d / "comp_d_eigensolver.npz") + assert eig["eigenvalues"].shape == (3,) + assert np.load(d / "full_spectral.npz")["embedding"].shape == (graph.shape[0], 2) + + +def test_selfloop_fixture_is_deterministic(tmp_path: Path): + from generate_fixtures import generate_selfloop_fixture + + first, second = tmp_path / "a", tmp_path / "b" + generate_selfloop_fixture(first) + generate_selfloop_fixture(second) + for name in ["graph.npz", "comp_a_degrees.npz", "comp_b_laplacian.npz"]: + assert (first / "selfloop" / name).read_bytes() == (second / "selfloop" / name).read_bytes() diff --git a/tests/visual_eval/README.md b/tests/visual_eval/README.md index 2c5b8df..5f7a137 100644 --- a/tests/visual_eval/README.md +++ b/tests/visual_eval/README.md @@ -226,7 +226,7 @@ random_state=42, n_jobs=1`. ### Rust Export (between Phase 1 and Phase 2) The `export_rust_init` test loads each `{name}_graph.npz` from Phase 1, runs -`spectral_init(&graph, 2, 42, None, SpectralInitConfig::default())`, and writes +`spectral_init(graph.view(), None, &SpectralInitConfig::new(2).with_seed(42))`, and writes `{name}_rust_init.npy`. Parameters: `n_components=2, seed=42, PythonCompat` mode. ```bash From 6c52fa4676d2e691da83806e7a4d77ae2f3286dd Mon Sep 17 00:00:00 2001 From: Trecek Date: Wed, 11 Nov 2026 16:45:46 -0800 Subject: [PATCH 004/113] Phase 3: portability, unsafe hygiene and dependencies SIMD soundness - `CsrOperatorSimd::new` returns `Option`: `None` unless the matrix is square CSR with a zero-based index pointer, its column indices fit 32 bits (`simd_index_fits`) and the CPU has AVX2 and FMA. `solve_eigenproblem` uses the scalar operator on `None`. - `apply` hard-asserts the vector lengths the gather kernel relies on; the raw-slice test entry `spmv_avx2_gather` is an `unsafe fn` with a `# Safety` section. Every `unsafe` block carries a `// SAFETY:` comment. - SIMD code is gated on `target_arch = "x86_64"` throughout. Lints - `[lints]`: `unsafe_op_in_unsafe_fn`, `missing_docs`, `clippy::undocumented_unsafe_blocks` and `rustdoc::broken_intra_doc_links` are denied for every target of the root package. Dependencies - `sprs` without default features; `faer` with `std`, `rayon` and `sparse-linalg` only. - `src/solvers/nd16_bridge.rs` is the only user of `ndarray16` and `linfa_linalg`; the purity gate enforces it. Tests - `tests/internals/simd.rs`: scalar/AVX2 SpMV parity on the fixture Laplacians, end-to-end agreement of the two compute modes, refusal of non-square and CSC input, the `i32::MAX` boundary, panics on mismatched lengths, and a compile-time check that the raw entry stays `unsafe`. - `tests/determinism_threads.rs`: one and four threads agree within 1e-5 (observed: identical for n = 500, 1.2e-10 for n = 1500); the crate docs state the figure and how to pin the thread configuration. - A unit test with 1 to 12 non-zeros per row drives the kernel's vector loop and scalar tail; it runs under Miri. CI - The test job becomes a matrix (`ubuntu-latest`, `ubuntu-24.04-arm`, `macos-15`, `windows-latest`, and x86-64-v3), with no RUSTFLAGS on the default legs. A job named `cargo nextest` reports the aggregate result. - Add a Miri job for the AVX2 kernel. - `t_profiler_02_stderr_capture_writes_file` is Unix-only, like the feature it tests. Co-Authored-By: Claude --- .github/package-allowlist.txt | 1 + .github/scripts/check-purity.sh | 16 +- .github/workflows/test.yml | 66 ++++- Cargo.toml | 15 +- eval/benches/simd_spmv_exp.rs | 21 +- eval/tests/test_simd_lobpcg_parity.rs | 8 +- eval/tests/test_simd_parity.rs | 15 +- src/lib.rs | 20 +- src/operator.rs | 283 +++++++++++++++------- src/solvers/lobpcg.rs | 105 ++------ src/solvers/mod.rs | 16 +- src/solvers/nd16_bridge.rs | 164 +++++++++++++ src/solvers/sinv.rs | 60 +---- tests/determinism_threads.rs | 82 +++++++ tests/internals/simd.rs | 222 ++++++++++++++++- trustworthiness/tests/test_tw_profiler.rs | 2 + 16 files changed, 840 insertions(+), 256 deletions(-) create mode 100644 src/solvers/nd16_bridge.rs create mode 100644 tests/determinism_threads.rs diff --git a/.github/package-allowlist.txt b/.github/package-allowlist.txt index 98edb60..a7c1ca1 100644 --- a/.github/package-allowlist.txt +++ b/.github/package-allowlist.txt @@ -20,6 +20,7 @@ src/selection.rs src/solvers/dense.rs src/solvers/lobpcg.rs src/solvers/mod.rs +src/solvers/nd16_bridge.rs src/solvers/quality.rs src/solvers/rsvd.rs src/solvers/sinv.rs diff --git a/.github/scripts/check-purity.sh b/.github/scripts/check-purity.sh index cfbddb0..1bac01e 100755 --- a/.github/scripts/check-purity.sh +++ b/.github/scripts/check-purity.sh @@ -14,17 +14,22 @@ status=0 # forbid ... # Fails the gate when the pattern occurs in any Rust source under the given paths. +# Files named in the space-separated variable `allowed` are exempt. forbid() { local description="$1" pattern="$2" shift 2 - local path hits - for path in "$@"; do + local path hits file + for path in "$@" ${allowed:-}; do if [ ! -e "$path" ]; then echo "error: ${path} does not exist" >&2 exit 2 fi done - if hits="$(grep -rnE --include='*.rs' -e "$pattern" "$@")"; then + hits="$(grep -rnE --include='*.rs' -e "$pattern" "$@" || true)" + for file in ${allowed:-}; do + hits="$(grep -v "^${file}:" <<< "$hits" || true)" + done + if [ -n "$hits" ]; then echo "error: ${description}" >&2 echo "$hits" >&2 status=1 @@ -39,6 +44,11 @@ forbid "random numbers come from the named generator ChaCha12Rng, not StdRng (sr 'StdRng' \ src +allowed="src/solvers/nd16_bridge.rs" \ +forbid "ndarray 0.16 and linfa-linalg are reached only through src/solvers/nd16_bridge.rs" \ + 'ndarray16|linfa_linalg' \ + src + forbid "no package has a 'testing' feature" \ 'feature *= *"testing"' \ src tests examples eval trustworthiness diff --git a/.github/workflows/test.yml b/.github/workflows/test.yml index 3ce4969..2a4e37b 100644 --- a/.github/workflows/test.yml +++ b/.github/workflows/test.yml @@ -14,8 +14,24 @@ permissions: jobs: test: - name: cargo nextest - runs-on: ubuntu-latest + name: test (${{ matrix.label }}) + runs-on: ${{ matrix.os }} + strategy: + fail-fast: false + matrix: + include: + - label: ubuntu-latest + os: ubuntu-latest + - label: ubuntu-24.04-arm + os: ubuntu-24.04-arm + - label: macos-15 + os: macos-15 + - label: windows-latest + os: windows-latest + # The default x86_64 build detects AVX2 at run time; this leg compiles it in. + - label: ubuntu-latest-x86-64-v3 + os: ubuntu-latest + rustflags: -C target-cpu=x86-64-v3 steps: - uses: actions/checkout@v4 @@ -23,8 +39,15 @@ jobs: - name: Install Rust stable uses: dtolnay/rust-toolchain@stable + - name: Set RUSTFLAGS + if: matrix.rustflags != '' + shell: bash + run: echo "RUSTFLAGS=${{ matrix.rustflags }}" >> "$GITHUB_ENV" + - name: Cache Rust build artifacts uses: Swatinem/rust-cache@v2 + with: + key: ${{ matrix.label }} - name: Install cargo-nextest uses: taiki-e/install-action@v2 @@ -38,7 +61,7 @@ jobs: uses: actions/upload-artifact@v4 if: always() with: - name: junit-results + name: junit-results-${{ matrix.label }} path: target/nextest/ci/junit.xml retention-days: 30 @@ -46,10 +69,47 @@ jobs: uses: mikepenz/action-junit-report@v6 if: always() with: + check_name: JUnit (${{ matrix.label }}) report_paths: target/nextest/ci/junit.xml fail_on_failure: false annotate_only: ${{ github.event.pull_request.head.repo.full_name != github.repository }} + # The required check: one result for the whole test matrix. + nextest: + name: cargo nextest + runs-on: ubuntu-latest + needs: [test] + if: always() + + steps: + - name: Every test leg passed + run: | + if [ "${{ needs.test.result }}" != "success" ]; then + echo "test matrix result: ${{ needs.test.result }}" >&2 + exit 1 + fi + + miri: + name: miri + runs-on: ubuntu-latest + + steps: + - uses: actions/checkout@v4 + + - name: Install Rust nightly with Miri + uses: dtolnay/rust-toolchain@master + with: + toolchain: nightly-2026-08-10 + components: miri, rust-src + + - name: Cache Rust build artifacts + uses: Swatinem/rust-cache@v2 + + - name: Run the AVX2 kernel tests under Miri + run: cargo miri test --locked -p spectral-init --lib operator + env: + RUSTFLAGS: "-C target-feature=+avx2,+fma" + lint: name: fmt + clippy runs-on: ubuntu-latest diff --git a/Cargo.toml b/Cargo.toml index a33a0b4..e044600 100644 --- a/Cargo.toml +++ b/Cargo.toml @@ -22,10 +22,21 @@ members = ["trustworthiness", "eval"] # the `eval` research harness. Exempt from semver; not for downstream use. __internal = [] +[lints.rust] +unsafe_op_in_unsafe_fn = "deny" +missing_docs = "deny" + +[lints.clippy] +undocumented_unsafe_blocks = "deny" + +[lints.rustdoc] +broken_intra_doc_links = "deny" + [dependencies] -sprs = "0.11" +sprs = { version = "0.11", default-features = false } ndarray = "0.17" -faer = "0.24" +# `rayon` keeps faer's parallel dense solvers; `sparse-linalg` provides the sparse Cholesky. +faer = { version = "0.24", default-features = false, features = ["std", "rayon", "sparse-linalg"] } rand = "0.9" rand_chacha = "0.9" # the named generator behind the reproducibility contract rand_distr = "0.5" diff --git a/eval/benches/simd_spmv_exp.rs b/eval/benches/simd_spmv_exp.rs index 8d3d663..fb1834c 100644 --- a/eval/benches/simd_spmv_exp.rs +++ b/eval/benches/simd_spmv_exp.rs @@ -161,7 +161,7 @@ impl SellCsigma { // ─── AVX2 gather kernel ─────────────────────────────────────────────────────── -#[cfg(any(target_arch = "x86", target_arch = "x86_64"))] +#[cfg(target_arch = "x86_64")] #[target_feature(enable = "avx2,fma")] unsafe fn spmv_avx2_gather( indptr: &[usize], @@ -215,7 +215,7 @@ unsafe fn spmv_avx2_gather( } } -#[cfg(any(target_arch = "x86", target_arch = "x86_64"))] +#[cfg(target_arch = "x86_64")] fn spmv_avx2_dispatch(indptr: &[usize], indices: &[usize], data: &[f64], x: &[f64], y: &mut [f64]) { if is_x86_feature_detected!("avx2") && is_x86_feature_detected!("fma") { // SAFETY: feature detection above guarantees avx2+fma are available. @@ -227,7 +227,7 @@ fn spmv_avx2_dispatch(indptr: &[usize], indices: &[usize], data: &[f64], x: &[f6 // ─── AVX-512 gather kernel ─────────────────────────────────────────────────── -#[cfg(any(target_arch = "x86", target_arch = "x86_64"))] +#[cfg(target_arch = "x86_64")] #[target_feature(enable = "avx512f")] unsafe fn spmv_avx512_gather( indptr: &[usize], @@ -292,7 +292,7 @@ unsafe fn spmv_avx512_gather( } } -#[cfg(any(target_arch = "x86", target_arch = "x86_64"))] +#[cfg(target_arch = "x86_64")] fn spmv_avx512_dispatch( indptr: &[usize], indices: &[usize], @@ -340,9 +340,9 @@ fn verify_avx512(n: usize) { spmv_csr(&indptr, &indices, &data, &x, &mut y_csr); let mut y_avx512 = vec![0.0_f64; n]; - #[cfg(any(target_arch = "x86", target_arch = "x86_64"))] + #[cfg(target_arch = "x86_64")] spmv_avx512_dispatch(&indptr, &indices, &data, &x, &mut y_avx512); - #[cfg(not(any(target_arch = "x86", target_arch = "x86_64")))] + #[cfg(not(target_arch = "x86_64"))] spmv_csr(&indptr, &indices, &data, &x, &mut y_avx512); for i in 0..n { @@ -363,9 +363,9 @@ fn verify_avx2(n: usize) { spmv_csr(&indptr, &indices, &data, &x, &mut y_csr); let mut y_avx2 = vec![0.0_f64; n]; - #[cfg(any(target_arch = "x86", target_arch = "x86_64"))] + #[cfg(target_arch = "x86_64")] spmv_avx2_dispatch(&indptr, &indices, &data, &x, &mut y_avx2); - #[cfg(not(any(target_arch = "x86", target_arch = "x86_64")))] + #[cfg(not(target_arch = "x86_64"))] spmv_csr(&indptr, &indices, &data, &x, &mut y_avx2); for i in 0..n { @@ -441,6 +441,7 @@ fn bench_spmv_sell_c_conversion(c: &mut Criterion) { fn bench_spmv_avx2(c: &mut Criterion) { // ISA detection: emits "[isa] avx512f=true/false" so results files can confirm // the hardware context that produced the benchmark data. + #[cfg(target_arch = "x86_64")] eprintln!("[isa] avx512f={}", is_x86_feature_detected!("avx512f")); verify_avx2(200); verify_avx512(200); @@ -462,7 +463,7 @@ fn bench_spmv_avx2(c: &mut Criterion) { }); }); - #[cfg(any(target_arch = "x86", target_arch = "x86_64"))] + #[cfg(target_arch = "x86_64")] group.bench_with_input(BenchmarkId::new("avx2_gather", n), &n, |b, _| { b.iter(|| { spmv_avx2_dispatch( @@ -475,7 +476,7 @@ fn bench_spmv_avx2(c: &mut Criterion) { }); }); - #[cfg(any(target_arch = "x86", target_arch = "x86_64"))] + #[cfg(target_arch = "x86_64")] if is_x86_feature_detected!("avx512f") { group.bench_with_input(BenchmarkId::new("avx512_gather", n), &n, |b, _| { b.iter(|| { diff --git a/eval/tests/test_simd_lobpcg_parity.rs b/eval/tests/test_simd_lobpcg_parity.rs index 587a842..cc8c58f 100644 --- a/eval/tests/test_simd_lobpcg_parity.rs +++ b/eval/tests/test_simd_lobpcg_parity.rs @@ -130,7 +130,7 @@ fn dk_bound_predicted(gap: f64, n_iterations: u32, avg_nnz_per_row: usize) -> f6 /// /// `bridge_weight` is recorded verbatim; `n` is the per-clique cluster size /// used to estimate `avg_nnz_per_row` for the DK bound. -#[cfg(any(target_arch = "x86", target_arch = "x86_64"))] +#[cfg(target_arch = "x86_64")] fn measure_solver_pair( laplacian: &CsMatI, n: usize, @@ -197,7 +197,7 @@ fn measure_solver_pair( }) } -#[cfg(any(target_arch = "x86", target_arch = "x86_64"))] +#[cfg(target_arch = "x86_64")] #[test] fn test_gap_sweep() { if !is_x86_feature_detected!("avx2") || !is_x86_feature_detected!("fma") { @@ -236,7 +236,7 @@ fn test_gap_sweep() { println!("Wrote gap_sweep.json ({} entries)", records.len()); } -#[cfg(any(target_arch = "x86", target_arch = "x86_64"))] +#[cfg(target_arch = "x86_64")] #[test] fn test_discrete_multi_seed() { if !is_x86_feature_detected!("avx2") || !is_x86_feature_detected!("fma") { @@ -267,7 +267,7 @@ fn test_discrete_multi_seed() { println!("Wrote discrete_gaps.json ({} entries)", records.len()); } -#[cfg(any(target_arch = "x86", target_arch = "x86_64"))] +#[cfg(target_arch = "x86_64")] #[test] fn test_solver_level_parity() { if !is_x86_feature_detected!("avx2") || !is_x86_feature_detected!("fma") { diff --git a/eval/tests/test_simd_parity.rs b/eval/tests/test_simd_parity.rs index e3eb3c9..19dcdde 100644 --- a/eval/tests/test_simd_parity.rs +++ b/eval/tests/test_simd_parity.rs @@ -49,6 +49,12 @@ fn ulp_distance(a: f64, b: f64) -> u64 { #[test] fn test_spmv_divergence() { + #[cfg(target_arch = "x86_64")] + if !is_x86_feature_detected!("avx2") || !is_x86_feature_detected!("fma") { + eprintln!("test_spmv_divergence: skipping — AVX2/FMA not available"); + return; + } + let results_dir = results_dir(); std::fs::create_dir_all(&results_dir).expect("cannot create RESULTS_DIR"); @@ -59,7 +65,7 @@ fn test_spmv_divergence() { let laplacian = fixtures::load_sparse_csr(&lap_path); let n = laplacian.rows(); let nnz = laplacian.nnz(); - let indptr = laplacian.indptr().raw_storage().to_vec(); + let indptr = laplacian.proper_indptr().into_owned(); let indices = laplacian.indices().to_vec(); let data = laplacian.data().to_vec(); @@ -74,7 +80,12 @@ fn test_spmv_divergence() { #[cfg(target_arch = "x86_64")] let (max_abs_diff, rms_diff, max_ulp) = { let mut y_avx2 = vec![0.0_f64; n]; - spmv_avx2_gather(&indptr, &indices, &data, &x, &mut y_avx2); + // SAFETY: AVX2 and FMA were detected at the top of the test. `indptr` + // (zero-based), `indices` and `data` are the storage of a valid `n × n` + // CSR matrix, so `indptr` has `n + 1` non-decreasing entries ending at + // the length of `indices` and `data`, and every column index is below + // `n`, the length of `x`, which is far below `i32::MAX`. + unsafe { spmv_avx2_gather(&indptr, &indices, &data, &x, &mut y_avx2) }; let mut max_abs: f64 = 0.0; let mut sum_sq: f64 = 0.0; diff --git a/src/lib.rs b/src/lib.rs index 37abb9f..6609f46 100644 --- a/src/lib.rs +++ b/src/lib.rs @@ -72,6 +72,23 @@ //! report that no solver could produce acceptable eigenvectors within the configured //! dense memory budget. See [`spectral_init`] for the full list and a fallback example. //! +//! # Reproducibility +//! +//! For a fixed `Cargo.lock`, target, CPU feature set and thread configuration, the output +//! is a deterministic function of the graph, the data and the configuration. Random +//! numbers come from the ChaCha12 generator (`rand_chacha::ChaCha12Rng`), seeded with +//! [`SpectralInitConfig::with_seed`]. +//! +//! Across thread configurations the output agrees to rounding, not bit for bit: the dense +//! eigensolver splits larger problems across threads. Measured on x86_64 with faer 0.24.4, +//! one thread against four changed no coordinate for a 500-node graph and changed +//! coordinates by at most 1.2 × 10⁻¹⁰ for a 1500-node graph (coordinates are scaled to a +//! maximum magnitude of 10); the test suite accepts differences up to 10⁻⁵. To pin the +//! thread configuration, call `faer::set_global_parallelism` before [`spectral_init`], or +//! set the `RAYON_NUM_THREADS` environment variable, which sizes the thread pool the +//! solvers share. A different target or CPU feature set can change results by rounding in +//! the same way; no bitwise agreement is promised across them. +//! //! # Public Dependencies //! //! The graph and array types in the signature of [`spectral_init`] come from the @@ -82,7 +99,6 @@ //! //! For step-by-step integration instructions with `umap-rs` and standalone usage, //! see the [user guide](https://github.com/TalonT-Org/spectral-init/blob/main/docs/user-guide.md). -#![warn(missing_docs)] mod components; mod config; @@ -115,7 +131,7 @@ pub mod __internal { pub use crate::operator::{CsrOperator, LinearOperator, spmv_csr}; #[cfg(target_arch = "x86_64")] #[doc(hidden)] - pub use crate::operator::{CsrOperatorSimd, spmv_avx2_gather}; + pub use crate::operator::{CsrOperatorSimd, simd_index_fits, spmv_avx2_gather}; #[doc(hidden)] pub use crate::scaling::{normalize_signs, scale_and_add_noise, scale_coords}; #[doc(hidden)] diff --git a/src/operator.rs b/src/operator.rs index 120a976..21fde8d 100644 --- a/src/operator.rs +++ b/src/operator.rs @@ -49,9 +49,26 @@ pub fn spmv_csr(indptr: &[usize], indices: &[usize], data: &[f64], x: &[f64], y: } } -// ─── AVX2 gather kernel (x86 only) ─────────────────────────────────────────── +// ─── AVX2 gather kernel (x86_64 only) ──────────────────────────────────────── -#[cfg(any(target_arch = "x86", target_arch = "x86_64"))] +/// Whether the column indices of a matrix with `cols` columns fit the signed 32-bit +/// gather indices of the AVX2 kernel. +#[cfg(target_arch = "x86_64")] +#[doc(hidden)] +pub fn simd_index_fits(cols: usize) -> bool { + cols <= i32::MAX as usize +} + +/// CSR sparse-matrix × dense-vector product `y = A * x` with an AVX2 gather and FMA. +/// +/// # Safety +/// +/// - The CPU supports AVX2 and FMA. +/// - `indptr` holds `y.len() + 1` non-decreasing entries, and `data` holds at least +/// `indptr[y.len()]` elements. +/// - Every column index in `indices[..indptr[y.len()]]` is below `x.len()` and at most +/// `i32::MAX`. +#[cfg(target_arch = "x86_64")] #[target_feature(enable = "avx2,fma")] unsafe fn spmv_avx2_gather_inner( indptr: &[usize], @@ -67,6 +84,11 @@ unsafe fn spmv_avx2_gather_inner( let start = indptr[i]; let end = indptr[i + 1]; + // SAFETY: AVX2 and FMA are present (caller's contract). Every column index is + // below `x.len()` and at most `i32::MAX`, so each `as i32` cast is lossless and + // the gather reads four elements inside `x`. `base + 4 <= end <= indptr[n]` and + // `data` holds at least `indptr[n]` elements, so the unaligned load reads + // `data[base..base + 4]` in bounds. let (mut result, mut base) = unsafe { let mut acc = _mm256_setzero_pd(); let mut base = start; @@ -102,26 +124,25 @@ unsafe fn spmv_avx2_gather_inner( } } -/// Safe wrapper around the AVX2+FMA gather SpMV kernel, for tests. +/// Raw-slice entry to the AVX2+FMA gather SpMV kernel, for tests. /// -/// Panics if AVX2 or FMA is not available on the current CPU. -#[cfg(all( - any(test, feature = "__internal"), - any(target_arch = "x86", target_arch = "x86_64") -))] +/// # Safety +/// +/// - The CPU supports AVX2 and FMA. +/// - `indptr` holds `y.len() + 1` non-decreasing entries, and `indices` and `data` each +/// hold at least `indptr[y.len()]` elements. +/// - Every column index in `indices[..indptr[y.len()]]` is below `x.len()` and at most +/// `i32::MAX`. +#[cfg(all(any(test, feature = "__internal"), target_arch = "x86_64"))] #[doc(hidden)] -pub fn spmv_avx2_gather( +pub unsafe fn spmv_avx2_gather( indptr: &[usize], indices: &[usize], data: &[f64], x: &[f64], y: &mut [f64], ) { - assert!( - is_x86_feature_detected!("avx2") && is_x86_feature_detected!("fma"), - "spmv_avx2_gather: AVX2+FMA not available on this CPU" - ); - // SAFETY: feature detection above guarantees avx2+fma are present. + // SAFETY: this function's contract is the kernel's. unsafe { spmv_avx2_gather_inner(indptr, indices, data, x, y) } } @@ -207,50 +228,55 @@ impl<'a> LinearOperator for CsrOperator<'a> { /// SIMD-accelerated variant of `CsrOperator`. Routes k=1 through /// `spmv_avx2_gather_inner` (AVX2 gather kernel); k>1 falls back to `csr_mulacc_dense_rowmaj`. /// -/// Only available on x86/x86_64. Construct via [`CsrOperatorSimd::new`], which panics if -/// AVX2 or FMA are not available at runtime, ensuring the `unsafe` SIMD kernel in `apply` -/// is never invoked on unsupported hardware. -#[cfg(any(target_arch = "x86", target_arch = "x86_64"))] +/// Only available on x86_64. The only way to build one is [`CsrOperatorSimd::new`], which +/// checks everything the `unsafe` SIMD kernel in `apply` relies on that can be checked +/// once per matrix. +#[cfg(target_arch = "x86_64")] pub struct CsrOperatorSimd<'a>(&'a CsMatI); -#[cfg(any(target_arch = "x86", target_arch = "x86_64"))] +#[cfg(target_arch = "x86_64")] impl<'a> CsrOperatorSimd<'a> { - /// Constructs a `CsrOperatorSimd` operator. + /// Wraps `mat` if the AVX2 kernel can run on it. /// - /// # Panics - /// - /// Panics if AVX2 or FMA CPU features are not available at runtime. - pub fn new(mat: &'a CsMatI) -> Self { - assert!( - is_x86_feature_detected!("avx2") && is_x86_feature_detected!("fma"), - "CsrOperatorSimd requires AVX2 and FMA CPU features; \ - check is_x86_feature_detected!(\"avx2\") && is_x86_feature_detected!(\"fma\") before constructing" - ); - Self(mat) + /// Returns `None` unless `mat` is a square CSR matrix whose index pointer starts at + /// zero, its column indices fit 32 bits ([`simd_index_fits`]), and the CPU supports + /// AVX2 and FMA. Callers fall back to [`CsrOperator`] on `None`. + pub fn new(mat: &'a CsMatI) -> Option { + let usable = mat.is_csr() + && mat.rows() == mat.cols() + && mat.indptr().is_proper() + && simd_index_fits(mat.cols()) + && is_x86_feature_detected!("avx2") + && is_x86_feature_detected!("fma"); + usable.then_some(Self(mat)) } } -#[cfg(any(target_arch = "x86", target_arch = "x86_64"))] +#[cfg(target_arch = "x86_64")] impl<'a> LinearOperator for CsrOperatorSimd<'a> { + /// # Panics + /// + /// Panics if `x` does not have one row per matrix column or `y` one row per matrix + /// row. fn apply(&self, x: ArrayView2, y: &mut Array2) { - debug_assert_eq!( - x.shape()[0], - self.0.rows(), - "CsrOperatorSimd::apply: x row count {} != matrix rows {}", - x.shape()[0], - self.0.rows() + let mat = self.0; + assert_eq!( + x.nrows(), + mat.cols(), + "CsrOperatorSimd::apply: x has {} rows, the matrix has {} columns", + x.nrows(), + mat.cols() ); - debug_assert_eq!( - y.shape()[0], - self.0.rows(), - "CsrOperatorSimd::apply: y row count {} != matrix rows {}", - y.shape()[0], - self.0.rows() + assert_eq!( + y.nrows(), + mat.rows(), + "CsrOperatorSimd::apply: y has {} rows, the matrix has {} rows", + y.nrows(), + mat.rows() ); y.fill(0.0); let k = x.shape()[1]; if k == 1 { - let mat = self.0; let x_col0 = x.column(0); let x_col_vec: Vec; let x_col: &[f64] = match x_col0.as_slice() { @@ -260,42 +286,40 @@ impl<'a> LinearOperator for CsrOperatorSimd<'a> { &x_col_vec } }; - match y.column_mut(0).as_slice_mut() { - Some(y_col) => { - // SAFETY: AVX2+FMA availability is enforced at construction time by - // `CsrOperatorSimd::new()`, which panics if either feature is absent. - // The private field prevents bypassing the constructor. - unsafe { - spmv_avx2_gather_inner( - mat.indptr().raw_storage(), - mat.indices(), - mat.data(), - x_col, - y_col, - ); - } + let kernel = |y_col: &mut [f64]| { + // SAFETY: + // - `new` detected AVX2 and FMA, and the private field admits no other + // constructor. + // - `new` checked that `mat` is CSR with an index pointer starting at + // zero. With the structure invariants sprs maintains for every + // `CsMatI`, `indptr` then holds `rows + 1` non-decreasing entries + // ending at `nnz`, `indices` and `data` hold `nnz` elements, and every + // column index is below `cols`. + // - `x_col.len() == cols` and `y_col.len() == rows` by the asserts above, + // and `cols <= i32::MAX` by `new`, so every column index is below + // `x_col.len()` and fits an `i32`. + unsafe { + spmv_avx2_gather_inner( + mat.indptr().raw_storage(), + mat.indices(), + mat.data(), + x_col, + y_col, + ); } + }; + match y.column_mut(0).as_slice_mut() { + Some(y_col) => kernel(y_col), None => { let mut y_col = vec![0.0_f64; mat.rows()]; - // SAFETY: AVX2+FMA availability is enforced at construction time by - // `CsrOperatorSimd::new()`, which panics if either feature is absent. - // The private field prevents bypassing the constructor. - unsafe { - spmv_avx2_gather_inner( - mat.indptr().raw_storage(), - mat.indices(), - mat.data(), - x_col, - &mut y_col, - ); - } + kernel(&mut y_col); for (i, v) in y_col.into_iter().enumerate() { y[[i, 0]] = v; } } } } else { - sprs::prod::csr_mulacc_dense_rowmaj(self.0.view(), x, y.view_mut()); + sprs::prod::csr_mulacc_dense_rowmaj(mat.view(), x, y.view_mut()); } } @@ -528,10 +552,38 @@ mod tests { // ─── AVX2/SIMD operator tests ──────────────────────────────────────────── - #[cfg(any(target_arch = "x86", target_arch = "x86_64"))] + /// Whether the build or the CPU provides the features the AVX2 kernel needs. + #[cfg(target_arch = "x86_64")] + fn avx2_fma_available() -> bool { + is_x86_feature_detected!("avx2") && is_x86_feature_detected!("fma") + } + + /// A 12×12 CSR matrix whose rows hold between 1 and 12 non-zeros, so the kernel's + /// four-wide loop runs zero to three times per row, with and without a scalar tail. + #[cfg(target_arch = "x86_64")] + fn wide_row_matrix() -> CsMatI { + let n = 12usize; + let mut indptr = vec![0usize]; + let mut indices = Vec::new(); + let mut data = Vec::new(); + for i in 0..n { + for j in 0..n { + // Rows 0..6 hold columns 0..=i+8; rows 6..12 hold columns i..12. + let stored = if i < 6 { j <= i + 8 } else { j >= i }; + if stored { + indices.push(j); + data.push(1.0 / (1.0 + (i * n + j) as f64)); + } + } + indptr.push(indices.len()); + } + CsMatI::new((n, n), indptr, indices, data) + } + + #[cfg(target_arch = "x86_64")] #[test] fn test_spmv_avx2_gather_matches_scalar() { - if !is_x86_feature_detected!("avx2") || !is_x86_feature_detected!("fma") { + if !avx2_fma_available() { return; // skip on non-AVX2 machines } let indptr = vec![0usize, 2, 5, 7]; @@ -541,7 +593,10 @@ mod tests { let mut y_scalar = vec![0.0_f64; 3]; let mut y_avx2 = vec![0.0_f64; 3]; spmv_csr(&indptr, &indices, &data, &x, &mut y_scalar); - spmv_avx2_gather(&indptr, &indices, &data, &x, &mut y_avx2); + // SAFETY: AVX2 and FMA were detected above; `indptr` has `y.len() + 1` + // non-decreasing entries ending at 7, the length of `indices` and `data`; every + // column index is below `x.len()` = 3. + unsafe { spmv_avx2_gather(&indptr, &indices, &data, &x, &mut y_avx2) }; for i in 0..3 { assert!( (y_avx2[i] - y_scalar[i]).abs() < 1e-13, @@ -552,15 +607,78 @@ mod tests { } } - #[cfg(any(target_arch = "x86", target_arch = "x86_64"))] + #[cfg(target_arch = "x86_64")] #[test] - fn test_csr_operator_simd_single_vector_matches_scalar() { - if !is_x86_feature_detected!("avx2") || !is_x86_feature_detected!("fma") { + fn test_csr_operator_simd_wide_rows_match_scalar() { + // Skipped only where the kernel cannot run. A build with AVX2 and FMA enabled + // at compile time never skips, so there the operator must be constructible. + if !avx2_fma_available() { return; } + let mat = wide_row_matrix(); + let row_nnz: Vec = mat.outer_iterator().map(|row| row.nnz()).collect(); + assert!( + row_nnz.contains(&9), + "need a row with two vector steps and a tail" + ); + assert!(row_nnz.contains(&12), "need a row without a tail"); + assert!(row_nnz.contains(&3), "need a row with only a tail"); + + let op_scalar = CsrOperator(&mat); + let op_simd = CsrOperatorSimd::new(&mat).expect("AVX2 and FMA are available"); + let x = Array2::from_shape_fn((12, 1), |(i, _)| (i as f64 + 1.0) * 0.25); + let mut y_scalar = Array2::zeros((12, 1)); + let mut y_simd = Array2::zeros((12, 1)); + op_scalar.apply(x.view(), &mut y_scalar); + op_simd.apply(x.view(), &mut y_simd); + for i in 0..12 { + assert!( + (y_simd[[i, 0]] - y_scalar[[i, 0]]).abs() < 1e-13, + "row {i}: simd={}, scalar={}", + y_simd[[i, 0]], + y_scalar[[i, 0]] + ); + } + } + + #[cfg(target_arch = "x86_64")] + #[test] + fn test_csr_operator_simd_rejects_unsupported_matrices() { + // Non-square. + let rect = CsMatI::::new((2, 3), vec![0, 1, 2], vec![0, 2], vec![1.0, 1.0]); + assert!(CsrOperatorSimd::new(&rect).is_none()); + // CSC storage. + let csc = laplacian_3x3().to_csc(); + assert!(CsrOperatorSimd::new(&csc).is_none()); + // Index pointer not starting at zero: the last two rows of a 4×2 matrix. + let tall = CsMatI::::new( + (4, 2), + vec![0, 1, 2, 3, 4], + vec![0, 1, 0, 1], + vec![1.0, 2.0, 3.0, 4.0], + ); + let tail = tall.slice_outer(2..4).to_owned(); + assert_eq!(tail.shape(), (2, 2)); + assert!(!tail.indptr().is_proper()); + assert!(CsrOperatorSimd::new(&tail).is_none()); + } + + #[cfg(target_arch = "x86_64")] + #[test] + fn simd_index_fits_is_bounded_by_i32_max() { + assert!(simd_index_fits(0)); + assert!(simd_index_fits(i32::MAX as usize)); + assert!(!simd_index_fits(i32::MAX as usize + 1)); + } + + #[cfg(target_arch = "x86_64")] + #[test] + fn test_csr_operator_simd_single_vector_matches_scalar() { let mat = laplacian_3x3(); let op_scalar = CsrOperator(&mat); - let op_simd = CsrOperatorSimd(&mat); + let Some(op_simd) = CsrOperatorSimd::new(&mat) else { + return; // skip on non-AVX2 machines + }; let x: ndarray::Array2 = ndarray::array![[1.0], [2.0], [3.0]]; let mut y_scalar = ndarray::Array2::zeros((3, 1)); let mut y_simd = ndarray::Array2::zeros((3, 1)); @@ -576,14 +694,13 @@ mod tests { } } - #[cfg(any(target_arch = "x86", target_arch = "x86_64"))] + #[cfg(target_arch = "x86_64")] #[test] fn test_csr_operator_simd_block_matches_sequential() { - if !is_x86_feature_detected!("avx2") || !is_x86_feature_detected!("fma") { - return; - } let mat = laplacian_3x3(); - let op = CsrOperatorSimd(&mat); + let Some(op) = CsrOperatorSimd::new(&mat) else { + return; // skip on non-AVX2 machines + }; let x_block: ndarray::Array2 = ndarray::array![[1.0, 0.0], [0.0, 1.0], [0.0, 0.0]]; let mut y_block = ndarray::Array2::zeros((3, 2)); op.apply(x_block.view(), &mut y_block); diff --git a/src/solvers/lobpcg.rs b/src/solvers/lobpcg.rs index dd84b4d..9112686 100644 --- a/src/solvers/lobpcg.rs +++ b/src/solvers/lobpcg.rs @@ -1,6 +1,6 @@ //! LOBPCG iterative eigensolver (Levels 1 and 3 of the solver escalation chain). //! -//! Wraps `linfa_linalg::lobpcg` with an ndarray 0.16 ↔ 0.17 bridging layer. +//! Runs linfa-linalg's LOBPCG, reached through the `nd16_bridge` module. //! Level 1 runs without regularization; Level 3 applies an ε·I diagonal shift //! ([`REGULARIZATION_EPS`]) to widen the eigengap and improve convergence on //! near-degenerate graphs. @@ -14,64 +14,17 @@ //! within its iteration budget. The residual quality gate then determines whether //! to accept a converged result or escalate. -// linfa-linalg 0.2 uses ndarray 0.16, while this crate uses ndarray 0.17. -// We alias ndarray 0.16 as `nd16` for use at the linfa-linalg boundary only. -// All internal types and return values use ndarray 0.17 (the `ndarray` crate). -extern crate ndarray16; -use ndarray16 as nd16; - use super::EigenResult; +use super::nd16_bridge::{self, LobpcgOutcome, Order, from_nd16_view2, nd16, to_nd16_array2}; use super::quality::LOBPCG_ACCEPT_TOL; use crate::operator::LinearOperator; use faer::linalg::solvers::SelfAdjointEigen; use faer::{Mat as FaerMat, Side}; -use linfa_linalg::lobpcg::{Order, lobpcg}; use ndarray::{Array1, Array2}; use rand::SeedableRng; use rand_chacha::ChaCha12Rng; use rand_distr::{Distribution, StandardNormal}; -// ─── ndarray 0.16 ↔ 0.17 conversion helpers ────────────────────────────────── -// -// Each helper rebuilds an array from exactly `rows * cols` elements read off the source, -// so the `from_shape_vec` calls cannot fail. - -/// Convert an owned ndarray 0.17 `Array2` to ndarray 0.16 `Array2`. -fn to_nd16_array2(a: Array2) -> nd16::Array2 { - let (rows, cols) = (a.nrows(), a.ncols()); - // iter() respects logical shape regardless of memory layout or slicing. - let raw: Vec = a.iter().copied().collect(); - nd16::Array2::from_shape_vec((rows, cols), raw) - .expect("shape/data mismatch converting nd17→nd16 Array2") -} - -/// Convert an ndarray 0.16 `ArrayView2` to an owned ndarray 0.17 `Array2`. -fn from_nd16_view2(v: nd16::ArrayView2) -> Array2 { - let (rows, cols) = (v.nrows(), v.ncols()); - let raw: Vec = v.iter().copied().collect(); - Array2::from_shape_vec((rows, cols), raw) - .expect("shape/data mismatch converting nd16→nd17 ArrayView2") -} - -/// Convert an owned ndarray 0.16 `Array1` to ndarray 0.17 `Array1`. -/// -/// Uses `iter()` instead of `into_raw_vec()` because linfa-linalg can return sliced arrays -/// whose backing Vec is longer than the logical length. `iter()` always respects logical size. -fn from_nd16_array1(a: nd16::Array1) -> Array1 { - Array1::from_iter(a.iter().copied()) -} - -/// Convert an owned ndarray 0.16 `Array2` to ndarray 0.17 `Array2`. -/// -/// Uses `iter()` for the same reason as `from_nd16_array1`: slice_move can leave backing -/// Vecs larger than the logical extent, and `into_raw_vec()` would return all elements. -fn from_nd16_array2(a: nd16::Array2) -> Array2 { - let (rows, cols) = (a.nrows(), a.ncols()); - let raw: Vec = a.iter().copied().collect(); - Array2::from_shape_vec((rows, cols), raw) - .expect("shape/data mismatch converting nd16→nd17 Array2") -} - // ─── Constants ──────────────────────────────────────────────────────────────── /// Epsilon shift applied to the operator in Level 2 (regularized) LOBPCG. @@ -258,7 +211,7 @@ pub fn lobpcg_solve( return None; } - // Build random initial block [n, k] in ndarray 0.17, then convert to 0.16 for lobpcg. + // Build the random initial block [n, k]. let mut rng = ChaCha12Rng::seed_from_u64(seed); let mut x_init_17: Array2 = Array2::from_shape_fn((n, k), |_| StandardNormal.sample(&mut rng)); @@ -310,7 +263,7 @@ pub fn lobpcg_solve( } } - let mut x_init_opt: Option> = Some(to_nd16_array2(x_init_17)); + let mut x_init_opt: Option> = Some(x_init_17); let mut last_result: Option = None; // restart_count semantics (returned as the second element of the tuple): // 0 — converged in initial pass; no warm restart was needed @@ -326,12 +279,6 @@ pub fn lobpcg_solve( // LOBPCG_RESTART_MAXITER_CAP (1000). See Issue #123. let tol: f32 = LOBPCG_ACCEPT_TOL as f32; - // Defined outside the loop: captures nothing from the environment, so no need to - // re-create it on every iteration. - let extract = |r: linfa_linalg::lobpcg::Lobpcg| -> EigenResult { - (from_nd16_array1(r.eigvals), from_nd16_array2(r.eigvecs)) - }; - for restart in 0..=MAX_WARM_RESTARTS { let maxiter = if restart == 0 { (n * 5).min(LOBPCG_INITIAL_MAXITER_CAP) @@ -345,13 +292,13 @@ pub fn lobpcg_solve( x_init_opt.is_some(), "x_init_opt must be set at every loop entry" ); - let x_init_nd16 = x_init_opt + let x_init = x_init_opt .take() .expect("x_init_opt is always set at loop entry"); // ── Run linfa-linalg LOBPCG ────────────────────────────────────────── - let lobpcg_result = if regularize { - lobpcg( + let outcome = if regularize { + nd16_bridge::lobpcg( |x: nd16::ArrayView2| -> nd16::Array2 { let x17 = from_nd16_view2(x); let mut y17 = Array2::zeros((n, x17.ncols())); @@ -359,24 +306,20 @@ pub fn lobpcg_solve( y17.zip_mut_with(&x17, |yi, &xi| *yi += REGULARIZATION_EPS * xi); to_nd16_array2(y17) }, - x_init_nd16, - |_: nd16::ArrayViewMut2| {}, - None, + x_init, tol, maxiter, Order::Smallest, ) } else { - lobpcg( + nd16_bridge::lobpcg( |x: nd16::ArrayView2| -> nd16::Array2 { let x17 = from_nd16_view2(x); let mut y17 = Array2::zeros((n, x17.ncols())); op.apply(x17.view(), &mut y17); to_nd16_array2(y17) }, - x_init_nd16, - |_: nd16::ArrayViewMut2| {}, - None, + x_init, tol, maxiter, Order::Smallest, @@ -387,19 +330,17 @@ pub fn lobpcg_solve( // When rnorms fail the gate but partial eigvecs exist, preserve them as a // warm-restart seed (comment 2971872705): a partially-converged subspace is // better than a cold random start. - let (raw_opt, partial_seed): (Option, Option>) = - match lobpcg_result { - Ok(r) => (Some(extract(r)), None), - Err((_, Some(r))) => { - if r.rnorm.iter().all(|&norm| norm < LOBPCG_ACCEPT_TOL) { - (Some(extract(r)), None) - } else { - let seed_vecs = from_nd16_array2(r.eigvecs); - (None, Some(seed_vecs)) - } + let (raw_opt, partial_seed): (Option, Option>) = match outcome { + LobpcgOutcome::Converged(eigenpairs) => (Some(eigenpairs), None), + LobpcgOutcome::Partial { eigenpairs, rnorm } => { + if rnorm.iter().all(|&norm| norm < LOBPCG_ACCEPT_TOL) { + (Some(eigenpairs), None) + } else { + (None, Some(eigenpairs.1)) } - Err((_, None)) => (None, None), - }; + } + LobpcgOutcome::Failed => (None, None), + }; // If no primary result is available, attempt a warm restart with partial eigvecs // before giving up (addresses the silent-discard bug in comment 2971872705). @@ -411,7 +352,7 @@ pub fn lobpcg_solve( "[lobpcg] rnorm gate failed at restart {restart}/{MAX_WARM_RESTARTS}; \ seeding next restart with partial eigvecs" ); - x_init_opt = Some(to_nd16_array2(seed)); + x_init_opt = Some(seed); continue; } // No eigvecs to seed the next restart, or restarts exhausted: @@ -444,7 +385,7 @@ pub fn lobpcg_solve( "[lobpcg] Rayleigh-Ritz failed at restart {restart}/{MAX_WARM_RESTARTS}; \ seeding next restart with raw eigvecs" ); - x_init_opt = Some(to_nd16_array2(raw_eigvecs)); + x_init_opt = Some(raw_eigvecs); continue; } // Restarts exhausted: same dual-outcome break as the rnorm-fail path above. @@ -479,7 +420,7 @@ pub fn lobpcg_solve( (max_residual={max_res:.2e}); firing warm restart {}/{MAX_WARM_RESTARTS}", restart + 1 ); - x_init_opt = Some(to_nd16_array2(result.1.clone())); + x_init_opt = Some(result.1.clone()); } else { log::debug!( "[lobpcg] unconvergence detected after Rayleigh-Ritz \ diff --git a/src/solvers/mod.rs b/src/solvers/mod.rs index f5a82e8..5ee1bf9 100644 --- a/src/solvers/mod.rs +++ b/src/solvers/mod.rs @@ -28,6 +28,7 @@ mod dense; pub(crate) mod lobpcg; +mod nd16_bridge; pub(crate) mod quality; pub(crate) mod rsvd; pub(crate) mod sinv; @@ -415,8 +416,9 @@ fn solve_eigenproblem_with_op( /// Solver escalation chain with runtime operator dispatch. /// -/// On x86/x86_64, `ComputeMode::RustNative` with AVX2+FMA available routes LOBPCG -/// levels through `CsrOperatorSimd`; all other configurations use scalar `CsrOperator`. +/// On x86_64, `ComputeMode::RustNative` routes LOBPCG levels through `CsrOperatorSimd` +/// when the CPU supports AVX2 and FMA and the Laplacian's column indices fit 32 bits; +/// all other configurations use scalar `CsrOperator`. /// `ComputeMode::PythonCompat` always uses the scalar path regardless of CPU features. /// /// Returns the `n_components + 1` smallest eigenpairs together with a [`SolveReport`]. @@ -436,15 +438,15 @@ pub fn solve_eigenproblem( compute_mode: ComputeMode, params: &SolverParams, ) -> Result<(EigenResult, SolveReport), SpectralError> { - #[cfg(any(target_arch = "x86", target_arch = "x86_64"))] + #[cfg(target_arch = "x86_64")] if matches!(compute_mode, ComputeMode::RustNative) - && is_x86_feature_detected!("avx2") - && is_x86_feature_detected!("fma") + && let Some(op) = crate::operator::CsrOperatorSimd::new(laplacian) { - use crate::operator::CsrOperatorSimd; - let op = CsrOperatorSimd::new(laplacian); return solve_eigenproblem_with_op(laplacian, op, n_components, seed, sqrt_deg, params); } + // Other architectures have no SIMD operator: both modes use the scalar one. + #[cfg(not(target_arch = "x86_64"))] + let _ = compute_mode; let op = CsrOperator(laplacian); solve_eigenproblem_with_op(laplacian, op, n_components, seed, sqrt_deg, params) } diff --git a/src/solvers/nd16_bridge.rs b/src/solvers/nd16_bridge.rs new file mode 100644 index 0000000..22c90c5 --- /dev/null +++ b/src/solvers/nd16_bridge.rs @@ -0,0 +1,164 @@ +//! Bridge to `linfa-linalg`, whose LOBPCG is built on ndarray 0.16 while this crate uses +//! ndarray 0.17. +//! +//! This module is the crate's only user of the `ndarray16` and `linfa_linalg` crates: the +//! LOBPCG solvers call linfa through [`lobpcg`] and see its array types only through the +//! [`nd16`] re-export, in the operator closures they hand over. + +pub(super) use linfa_linalg::lobpcg::Order; +pub(super) use ndarray16 as nd16; + +use super::EigenResult; +use ndarray::{Array1, Array2}; + +// ─── ndarray 0.16 ↔ 0.17 conversion helpers ────────────────────────────────── +// +// Each helper rebuilds an array from exactly `rows * cols` elements read off the source, +// so the `from_shape_vec` calls cannot fail. + +/// Convert an owned ndarray 0.17 `Array2` to ndarray 0.16 `Array2`. +pub(super) fn to_nd16_array2(a: Array2) -> nd16::Array2 { + let (rows, cols) = (a.nrows(), a.ncols()); + // iter() respects logical shape regardless of memory layout or slicing. + let raw: Vec = a.iter().copied().collect(); + nd16::Array2::from_shape_vec((rows, cols), raw) + .expect("shape/data mismatch converting nd17→nd16 Array2") +} + +/// Convert an ndarray 0.16 `ArrayView2` to an owned ndarray 0.17 `Array2`. +pub(super) fn from_nd16_view2(v: nd16::ArrayView2) -> Array2 { + let (rows, cols) = (v.nrows(), v.ncols()); + let raw: Vec = v.iter().copied().collect(); + Array2::from_shape_vec((rows, cols), raw) + .expect("shape/data mismatch converting nd16→nd17 ArrayView2") +} + +/// Convert an owned ndarray 0.16 `Array1` to ndarray 0.17 `Array1`. +/// +/// Uses `iter()` instead of `into_raw_vec()` because linfa-linalg can return sliced arrays +/// whose backing Vec is longer than the logical length. `iter()` always respects logical size. +fn from_nd16_array1(a: nd16::Array1) -> Array1 { + Array1::from_iter(a.iter().copied()) +} + +/// Convert an owned ndarray 0.16 `Array2` to ndarray 0.17 `Array2`. +/// +/// Uses `iter()` for the same reason as `from_nd16_array1`: slice_move can leave backing +/// Vecs larger than the logical extent, and `into_raw_vec()` would return all elements. +fn from_nd16_array2(a: nd16::Array2) -> Array2 { + let (rows, cols) = (a.nrows(), a.ncols()); + let raw: Vec = a.iter().copied().collect(); + Array2::from_shape_vec((rows, cols), raw) + .expect("shape/data mismatch converting nd16→nd17 Array2") +} + +// ─── LOBPCG ─────────────────────────────────────────────────────────────────── + +/// Outcome of one LOBPCG run, in this crate's array types. +pub(super) enum LobpcgOutcome { + /// Every eigenpair converged to the requested tolerance. + Converged(EigenResult), + /// The iteration stopped early. Carries the eigenpairs reached so far and their + /// residual norms, one per eigenpair. + Partial { + eigenpairs: EigenResult, + rnorm: Vec, + }, + /// The iteration failed without producing eigenpairs. + Failed, +} + +/// Runs linfa-linalg's LOBPCG without a preconditioner or constraints. +/// +/// `operator` maps a block of column vectors to the operator applied to it, in ndarray +/// 0.16 types; `x_init` is the starting block; `order` selects the end of the spectrum. +pub(super) fn lobpcg( + operator: F, + x_init: Array2, + tol: f32, + maxiter: usize, + order: Order, +) -> LobpcgOutcome +where + F: Fn(nd16::ArrayView2) -> nd16::Array2, +{ + let eigenpairs = |eigvals: nd16::Array1, eigvecs: nd16::Array2| -> EigenResult { + (from_nd16_array1(eigvals), from_nd16_array2(eigvecs)) + }; + let result = linfa_linalg::lobpcg::lobpcg( + operator, + to_nd16_array2(x_init), + |_: nd16::ArrayViewMut2| {}, + None, + tol, + maxiter, + order, + ); + match result { + Ok(r) => LobpcgOutcome::Converged(eigenpairs(r.eigvals, r.eigvecs)), + Err((_, Some(r))) => LobpcgOutcome::Partial { + eigenpairs: eigenpairs(r.eigvals, r.eigvecs), + rnorm: r.rnorm, + }, + Err((_, None)) => LobpcgOutcome::Failed, + } +} + +#[cfg(test)] +mod tests { + use super::*; + + #[test] + fn array_conversions_round_trip() { + let a = Array2::from_shape_fn((3, 2), |(i, j)| (i * 2 + j) as f64); + let a16 = to_nd16_array2(a.clone()); + assert_eq!(a16.dim(), (3, 2)); + assert_eq!(from_nd16_view2(a16.view()), a); + assert_eq!(from_nd16_array2(a16), a); + assert_eq!( + from_nd16_array1(nd16::Array1::from_vec(vec![1.0, 2.0])), + Array1::from_vec(vec![1.0, 2.0]) + ); + } + + #[test] + fn conversions_respect_the_logical_layout_of_sliced_arrays() { + // A column-major 0.17 array and a sliced 0.16 array: both must convert by + // logical position, not by backing storage. + let fortran = + Array2::from_shape_vec(ndarray::ShapeBuilder::f((2, 2)), vec![1.0, 3.0, 2.0, 4.0]) + .unwrap(); + let converted = to_nd16_array2(fortran); + assert_eq!(converted, nd16::arr2(&[[1.0, 2.0], [3.0, 4.0]])); + + let wide = nd16::arr2(&[[1.0, 2.0, 9.0], [3.0, 4.0, 9.0]]); + let sliced = wide.slice_move(nd16::s![.., ..2]); + assert_eq!( + from_nd16_array2(sliced), + ndarray::arr2(&[[1.0, 2.0], [3.0, 4.0]]) + ); + } + + #[test] + fn lobpcg_finds_the_smallest_eigenvalues_of_a_diagonal_matrix() { + // diag(1, 2, ..., 8): the two smallest eigenvalues are 1 and 2. + let diagonal: Vec = (1..=8).map(f64::from).collect(); + let multiply = |x: nd16::ArrayView2| { + let mut y = x.to_owned(); + for (mut row, &d) in y.rows_mut().into_iter().zip(&diagonal) { + row *= d; + } + y + }; + let x_init = Array2::from_shape_fn((8, 2), |(i, j)| 1.0 / (1.0 + (i + 3 * j) as f64)); + match lobpcg(multiply, x_init, 1e-8, 200, Order::Smallest) { + LobpcgOutcome::Converged((eigenvalues, eigenvectors)) => { + assert_eq!(eigenvectors.dim(), (8, 2)); + assert!((eigenvalues[0] - 1.0).abs() < 1e-6); + assert!((eigenvalues[1] - 2.0).abs() < 1e-6); + } + LobpcgOutcome::Partial { rnorm, .. } => panic!("did not converge: rnorm {rnorm:?}"), + LobpcgOutcome::Failed => panic!("LOBPCG failed"), + } + } +} diff --git a/src/solvers/sinv.rs b/src/solvers/sinv.rs index 89d43b1..490d2be 100644 --- a/src/solvers/sinv.rs +++ b/src/solvers/sinv.rs @@ -14,13 +14,7 @@ //! In that case, execution falls through silently to Level 3 (LOBPCG + ε·I //! regularization). -// linfa-linalg 0.2 uses ndarray 0.16, while this crate uses ndarray 0.17. -// We alias ndarray 0.16 as `nd16` for use at the linfa-linalg boundary only. -extern crate ndarray16; -use ndarray16 as nd16; - use faer::prelude::Solve; -use linfa_linalg::lobpcg::{Order, lobpcg}; use ndarray::{Array1, Array2, ArrayView2}; use rand::SeedableRng; use rand_chacha::ChaCha12Rng; @@ -28,41 +22,12 @@ use rand_distr::{Distribution, StandardNormal}; use sprs::CsMatI; use super::EigenResult; +use super::nd16_bridge::{self, LobpcgOutcome, Order, from_nd16_view2, nd16, to_nd16_array2}; use super::quality::{SINV_LINFA_TOL, SINV_LOBPCG_QUALITY_THRESHOLD}; /// Diagonal shift ε making M = L + εI strictly SPD (REQ-SINV-002). pub(crate) const SINV_SHIFT: f64 = 1e-4; -// ─── ndarray 0.16 ↔ 0.17 conversion helpers ────────────────────────────────── -// -// Each helper rebuilds an array from exactly `rows * cols` elements read off the source, -// so the `from_shape_vec` calls cannot fail. - -fn to_nd16_array2(a: Array2) -> nd16::Array2 { - let (rows, cols) = (a.nrows(), a.ncols()); - let raw: Vec = a.iter().copied().collect(); - nd16::Array2::from_shape_vec((rows, cols), raw) - .expect("shape/data mismatch converting nd17→nd16 Array2") -} - -fn from_nd16_view2(v: nd16::ArrayView2) -> Array2 { - let (rows, cols) = (v.nrows(), v.ncols()); - let raw: Vec = v.iter().copied().collect(); - Array2::from_shape_vec((rows, cols), raw) - .expect("shape/data mismatch converting nd16→nd17 ArrayView2") -} - -fn from_nd16_array1(a: nd16::Array1) -> Array1 { - Array1::from_iter(a.iter().copied()) -} - -fn from_nd16_array2(a: nd16::Array2) -> Array2 { - let (rows, cols) = (a.nrows(), a.ncols()); - let raw: Vec = a.iter().copied().collect(); - Array2::from_shape_vec((rows, cols), raw) - .expect("shape/data mismatch converting nd16→nd17 Array2") -} - // ─── sprs ↔ faer sparse conversion ─────────────────────────────────────────── /// Convert a sprs `CsMat` (CSR or CSC) to a faer `SparseColMat`, @@ -154,11 +119,10 @@ pub fn lobpcg_sinv_solve( .column_mut(0) .assign(&sqrt_deg.mapv(|x| x / sqrt_deg_norm)); } - let x_init = to_nd16_array2(x_init_17); // Run LOBPCG with M⁻¹ operator — finds k largest eigenvalues of M⁻¹, // i.e. the k smallest eigenvalues of L (REQ-SINV-003). - let result = lobpcg( + let outcome = nd16_bridge::lobpcg( |x: nd16::ArrayView2| -> nd16::Array2 { let x17 = from_nd16_view2(x); let mut rhs = nd17_view_to_faer(x17.view()); @@ -166,27 +130,21 @@ pub fn lobpcg_sinv_solve( chol.solve_in_place(&mut rhs); faer_to_nd17_nd16(&rhs) }, - x_init, - |_: nd16::ArrayViewMut2| {}, - None, + x_init_17, SINV_LINFA_TOL as f32, (n * 5).min(300), Order::Largest, ); - // Extract result; accept partially-converged results if all residuals are small. - let extract = |r: linfa_linalg::lobpcg::Lobpcg| -> EigenResult { - (from_nd16_array1(r.eigvals), from_nd16_array2(r.eigvecs)) - }; - - let result_opt = match result { - Ok(r) => Some(extract(r)), - Err((_, Some(r))) - if r.rnorm + // Accept partially-converged results if all residuals are small. + let result_opt = match outcome { + LobpcgOutcome::Converged(eigenpairs) => Some(eigenpairs), + LobpcgOutcome::Partial { eigenpairs, rnorm } + if rnorm .iter() .all(|&norm| norm < SINV_LOBPCG_QUALITY_THRESHOLD) => { - Some(extract(r)) + Some(eigenpairs) } _ => None, }; diff --git a/tests/determinism_threads.rs b/tests/determinism_threads.rs new file mode 100644 index 0000000..3f46188 --- /dev/null +++ b/tests/determinism_threads.rs @@ -0,0 +1,82 @@ +//! Thread configuration: a sequential and a four-thread dense solve agree within a stated +//! tolerance. +//! +//! The test changes faer's process-wide parallelism setting, so this binary holds exactly +//! one test. + +#[path = "common/fixtures.rs"] +mod fixtures; + +use faer::Par; +use spectral_init::sprs::{CsMatI, TriMatI}; +use spectral_init::{SpectralInitConfig, spectral_init}; + +/// Largest coordinate difference accepted between two thread configurations, on +/// coordinates scaled to a maximum magnitude of 10. +const THREAD_TOLERANCE: f32 = 1e-5; + +/// Restores faer's global parallelism when dropped, so the setting is put back even if +/// an assertion fails. +struct RestoreParallelism(Par); + +impl Drop for RestoreParallelism { + fn drop(&mut self) { + faer::set_global_parallelism(self.0); + } +} + +/// A connected 1500-node graph: a ring with chords of uneven weight. Large enough for +/// faer's dense eigensolver to split its work across threads, small enough to stay on +/// the dense path (n < 2000). +fn chorded_ring(n: usize) -> CsMatI { + let mut tri: TriMatI = TriMatI::new((n, n)); + for i in 0..n { + for step in [1usize, 2, 5, 17] { + let j = (i + step) % n; + let weight = 0.2 + 0.8 * (((i * 31 + step * 7) % 97) as f32 / 97.0); + tri.add_triplet(i, j, weight); + tri.add_triplet(j, i, weight); + } + } + tri.to_csr() +} + +#[test] +fn sequential_and_parallel_dense_solves_agree() { + let _restore = RestoreParallelism(faer::get_global_parallelism()); + + let graphs = [ + ( + "blobs_500", + fixtures::load_sparse_csr_f32_u32(&fixtures::fixture_path( + "blobs_500", + "step5a_pruned.npz", + )), + ), + ("chorded ring, n = 1500", chorded_ring(1500)), + ]; + let config = SpectralInitConfig::new(2).with_seed(42); + + for (name, graph) in &graphs { + assert!(graph.rows() < 2000, "{name} must take the dense path"); + + faer::set_global_parallelism(Par::Seq); + let sequential = spectral_init(graph.view(), None, &config) + .unwrap_or_else(|e| panic!("{name}, sequential: {e}")); + faer::set_global_parallelism(Par::rayon(4)); + let parallel = spectral_init(graph.view(), None, &config) + .unwrap_or_else(|e| panic!("{name}, four threads: {e}")); + + assert_eq!(sequential.dim(), parallel.dim()); + let max_abs_diff = sequential + .iter() + .zip(parallel.iter()) + .map(|(a, b)| (a - b).abs()) + .fold(0.0_f32, f32::max); + println!("{name}: max |sequential - four threads| = {max_abs_diff:e}"); + assert!( + max_abs_diff <= THREAD_TOLERANCE, + "{name}: thread configurations differ by {max_abs_diff:e} > {THREAD_TOLERANCE:e}" + ); + } +} diff --git a/tests/internals/simd.rs b/tests/internals/simd.rs index cb72785..e72386e 100644 --- a/tests/internals/simd.rs +++ b/tests/internals/simd.rs @@ -1,10 +1,18 @@ -//! Parity between the scalar and the SIMD solver paths. +//! SIMD soundness and parity: the AVX2 SpMV kernel agrees with the scalar one, the two +//! compute modes agree end to end, and the safe operator around the kernel refuses or +//! panics instead of reading out of bounds. #![cfg(target_arch = "x86_64")] -use crate::{fixtures, internals}; -use spectral_init::__internal::{SolverParams, normalize_signs, scale_and_add_noise}; -use spectral_init::ComputeMode; +use crate::{diagnostics, fixtures, internals}; +use ndarray::Array2; +use spectral_init::__internal::{ + CsrOperator, CsrOperatorSimd, LinearOperator, SolverParams, normalize_signs, + scale_and_add_noise, simd_index_fits, spmv_avx2_gather, spmv_csr, +}; +use spectral_init::sprs::CsMatI; +use spectral_init::{ComputeMode, SpectralInitConfig, spectral_init}; +use std::panic::{AssertUnwindSafe, catch_unwind}; const FIXTURES: &[&str] = &[ "blobs_50", @@ -18,11 +26,32 @@ const FIXTURES: &[&str] = &[ "blobs_5000", ]; +/// Largest |scalar − AVX2| accepted for one SpMV output element. The kernels differ in +/// summation order and in fused versus separate multiply-add; on the fixture Laplacians +/// (entries of magnitude at most 1, a few dozen per row) that amounts to a few units in +/// the last place of an O(1) sum. +const SPMV_MAX_ABS_DIFF: f64 = 1e-14; + +fn avx2_fma_available() -> bool { + is_x86_feature_detected!("avx2") && is_x86_feature_detected!("fma") +} + +fn fixture_laplacian(fixture: &str) -> CsMatI { + fixtures::load_sparse_csr(&fixtures::fixture_path(fixture, "comp_b_laplacian.npz")) +} + +/// A deterministic dense vector with entries in [-1, 1). +fn test_vector(n: usize) -> Vec { + (0..n) + .map(|i| ((i * 7919 + 13) % 2000) as f64 / 1000.0 - 1.0) + .collect() +} + /// `RustNative` (AVX2 SpMV) and `PythonCompat` (scalar SpMV) must produce the same scaled /// coordinates once the per-column sign is normalized. #[test] fn rust_native_and_python_compat_solver_outputs_agree() { - if !is_x86_feature_detected!("avx2") || !is_x86_feature_detected!("fma") { + if !avx2_fma_available() { eprintln!( "rust_native_and_python_compat_solver_outputs_agree: skipping — AVX2/FMA not \ available; ComputeMode::RustNative uses the scalar path, making the comparison vacuous" @@ -32,8 +61,7 @@ fn rust_native_and_python_compat_solver_outputs_agree() { let params = SolverParams::default(); for &fixture in FIXTURES { - let lap_path = fixtures::fixture_path(fixture, "comp_b_laplacian.npz"); - let laplacian = fixtures::load_sparse_csr(&lap_path); + let laplacian = fixture_laplacian(fixture); let ((_, mut eigvec_scalar), _) = internals::solve_with_unit_hint(&laplacian, 2, 42, ComputeMode::PythonCompat, ¶ms); @@ -62,3 +90,183 @@ fn rust_native_and_python_compat_solver_outputs_agree() { ); } } + +/// The AVX2 kernel and the scalar kernel compute the same product on every fixture +/// Laplacian, through the raw-slice entry and through the operator. +#[test] +fn avx2_spmv_matches_scalar_on_fixture_laplacians() { + if !avx2_fma_available() { + eprintln!( + "avx2_spmv_matches_scalar_on_fixture_laplacians: skipping — AVX2/FMA not available" + ); + return; + } + + let mut widest_row_with_tail = 0; + for &fixture in FIXTURES { + let laplacian = fixture_laplacian(fixture); + let n = laplacian.rows(); + widest_row_with_tail = laplacian + .outer_iterator() + .map(|row| row.nnz()) + .filter(|nnz| nnz % 4 != 0) + .fold(widest_row_with_tail, usize::max); + + let indptr = laplacian.proper_indptr(); + let x = test_vector(n); + let mut y_scalar = vec![0.0_f64; n]; + let mut y_avx2 = vec![0.0_f64; n]; + spmv_csr( + &indptr, + laplacian.indices(), + laplacian.data(), + &x, + &mut y_scalar, + ); + // SAFETY: AVX2 and FMA were detected above. `indptr` (zero-based), `indices` and + // `data` are the storage of a valid `n × n` CSR matrix: `indptr` has `n + 1` + // non-decreasing entries ending at the length of `indices` and `data`, and + // every column index is below `n`, the length of `x`, far below `i32::MAX`. + unsafe { + spmv_avx2_gather( + &indptr, + laplacian.indices(), + laplacian.data(), + &x, + &mut y_avx2, + ) + }; + + let x_block = Array2::from_shape_vec((n, 1), x).expect("n values"); + let mut y_operator = Array2::zeros((n, 1)); + CsrOperatorSimd::new(&laplacian) + .expect("a square CSR Laplacian on an AVX2 machine") + .apply(x_block.view(), &mut y_operator); + + for i in 0..n { + assert!( + (y_avx2[i] - y_scalar[i]).abs() <= SPMV_MAX_ABS_DIFF, + "{fixture} row {i}: avx2={}, scalar={}", + y_avx2[i], + y_scalar[i] + ); + assert_eq!( + y_operator[[i, 0]], + y_avx2[i], + "{fixture} row {i}: the operator must run the same kernel" + ); + } + } + // A row of nine or more non-zeros that is not a multiple of four runs the four-wide + // loop at least twice and then the scalar tail. + assert!( + widest_row_with_tail >= 9, + "no fixture row exercises both the vector loop and the scalar tail" + ); +} + +/// Both compute modes span the same embedding subspace through the public entry point. +#[test] +fn rust_native_and_python_compat_agree_end_to_end() { + for &fixture in FIXTURES { + let graph = fixtures::load_sparse_csr_f32_u32(&fixtures::fixture_path( + fixture, + "step5a_pruned.npz", + )); + let run = |mode| { + let config = SpectralInitConfig::new(2) + .with_seed(42) + .with_compute_mode(mode); + spectral_init(graph.view(), None, &config) + .unwrap_or_else(|e| panic!("{fixture} {mode:?}: {e}")) + .mapv(f64::from) + }; + let python_compat = run(ComputeMode::PythonCompat); + let rust_native = run(ComputeMode::RustNative); + let gram_det = diagnostics::subspace_gram_det(rust_native.view(), python_compat.view()); + assert!( + gram_det > 0.999, + "{fixture}: subspace Gram determinant {gram_det}" + ); + } +} + +#[test] +fn simd_operator_is_refused_for_non_square_or_csc_input() { + let rect = CsMatI::::new((2, 3), vec![0, 1, 2], vec![0, 2], vec![1.0, 1.0]); + assert!(CsrOperatorSimd::new(&rect).is_none(), "non-square"); + + let square = fixtures::ring_laplacian(8); + let csc = square.to_csc(); + assert!(csc.is_csc()); + assert!(CsrOperatorSimd::new(&csc).is_none(), "CSC storage"); + + assert_eq!( + CsrOperatorSimd::new(&square).is_some(), + avx2_fma_available(), + "a square CSR matrix is accepted exactly when the CPU has AVX2 and FMA" + ); +} + +#[test] +fn simd_index_fits_up_to_i32_max_columns() { + assert!(simd_index_fits(i32::MAX as usize)); + assert!(!simd_index_fits(i32::MAX as usize + 1)); +} + +/// `apply` must panic, not read out of bounds, when a vector is shorter than the matrix. +#[test] +fn simd_operator_apply_panics_on_mismatched_lengths() { + let laplacian = fixtures::ring_laplacian(16); + let Some(op) = CsrOperatorSimd::new(&laplacian) else { + eprintln!( + "simd_operator_apply_panics_on_mismatched_lengths: skipping — AVX2/FMA not available" + ); + return; + }; + assert_eq!(op.size(), 16); + + let short_x = Array2::::ones((15, 1)); + let mut y = Array2::::zeros((16, 1)); + let result = catch_unwind(AssertUnwindSafe(|| op.apply(short_x.view(), &mut y))); + assert!(result.is_err(), "apply accepted an x with too few rows"); + + let x = Array2::::ones((16, 1)); + let mut short_y = Array2::::zeros((15, 1)); + let result = catch_unwind(AssertUnwindSafe(|| op.apply(x.view(), &mut short_y))); + assert!(result.is_err(), "apply accepted a y with too few rows"); + + let mut long_y = Array2::::zeros((17, 1)); + let result = catch_unwind(AssertUnwindSafe(|| op.apply(x.view(), &mut long_y))); + assert!(result.is_err(), "apply accepted a y with too many rows"); + + // Matching lengths still work, and agree with the scalar operator. + let mut y_scalar = Array2::::zeros((16, 1)); + CsrOperator(&laplacian).apply(x.view(), &mut y_scalar); + op.apply(x.view(), &mut y); + for i in 0..16 { + assert!((y[[i, 0]] - y_scalar[[i, 0]]).abs() <= SPMV_MAX_ABS_DIFF); + } +} + +/// The raw-slice kernel entry checks nothing, so it has to be an `unsafe fn`: were it ever +/// made safe, the `unsafe` block below would be unused and this test would stop compiling. +#[deny(unused_unsafe)] +#[test] +fn raw_kernel_entry_is_an_unsafe_fn() { + if !avx2_fma_available() { + eprintln!("raw_kernel_entry_is_an_unsafe_fn: skipping — AVX2/FMA not available"); + return; + } + // One row of nine non-zeros: two four-wide steps and a scalar tail of one. + let indptr = [0usize, 9]; + let indices: Vec = (0..9).collect(); + let data = vec![1.0_f64; 9]; + let x: Vec = (1..=9).map(f64::from).collect(); + let mut y = [0.0_f64]; + // SAFETY: AVX2 and FMA were detected above; `indptr` has `y.len() + 1` non-decreasing + // entries ending at 9, the length of `indices` and `data`; every column index is + // below `x.len()` = 9. + unsafe { spmv_avx2_gather(&indptr, &indices, &data, &x, &mut y) }; + assert_eq!(y[0], 45.0); +} diff --git a/trustworthiness/tests/test_tw_profiler.rs b/trustworthiness/tests/test_tw_profiler.rs index 302617a..d2619f4 100644 --- a/trustworthiness/tests/test_tw_profiler.rs +++ b/trustworthiness/tests/test_tw_profiler.rs @@ -69,6 +69,8 @@ fn t_profiler_01_produces_valid_json() { let _ = std::fs::remove_dir_all(&tmp); } +// `--stderr-capture` redirects stderr with `dup2`, which exists on Unix only. +#[cfg(unix)] #[test] fn t_profiler_02_stderr_capture_writes_file() { let tmp = std::env::temp_dir().join(format!("tw_profiler_stderr_test_{}", std::process::id())); From a180a05248f91ad85bae71f2077ae95e3a13c271 Mon Sep 17 00:00:00 2001 From: Trecek Date: Wed, 11 Nov 2026 17:00:18 -0800 Subject: [PATCH 005/113] Phase 4: compiled umap-rs integration and optimizer-independent evidence Integration - `umap-rs` 0.4.5 becomes a dev-dependency; the library itself depends on no UMAP implementation. - `examples/umap_rs.rs`: synthetic data, brute-force k-NN, `Umap::learn_manifold`, `spectral_init` on `manifold.graph()`, then the `Optimizer`, with the default-epoch rule and the NaN marking of isolated vertices that `Umap::fit` performs. - `tests/public_api/umap_rs.rs`: on fixture data, the learned graph passes validation, the initialization is `(n, n_components)`, finite and in standard layout, both `Optimizer::new` and `Umap::fit` accept it, and a graph built with `symmetrize = false` is rejected as `NotSymmetric`. - Tolerance calibration: `umap-rs` graphs for `set_op_mix_ratio` 0.3, 0.5, 0.7 and 1.0 pass validation on all nine datasets (measured asymmetry at most 1.2e-7 relative; the tolerance stays 1e-6). Evidence - `eval/src/assess.rs` holds the accuracy and parity measurements against the umap-learn fixtures; `test_metrics_assess` and the new `init_evidence` binary share them. - `init_evidence` reports residuals, eigenvalue errors and subspace agreement on connected graphs, component counts and separation on disconnected ones, and trustworthiness of the raw initial coordinates for the spectral and for a uniform random initialization. Docs - `docs/umap-rs-integration.md`: the `Optimizer` sequence and the `fit` variant, what to know (`symmetrize`, mix ratio, `data`, rescaling, isolated vertices), umap-learn's edge pruning, the dated state of `umap-rs`, a zero-copy CSR recipe for other implementations, and the evidence tables. Its Rust snippets run as doctests, and the guide ships in the package. Co-Authored-By: Claude --- .github/package-allowlist.txt | 2 + Cargo.lock | 180 +++++++++++++++++++- Cargo.toml | 14 +- docs/umap-rs-integration.md | 268 ++++++++++++++++++++++++++++++ eval/Cargo.toml | 1 + eval/src/assess.rs | 255 ++++++++++++++++++++++++++++ eval/src/bin/init_evidence.rs | 137 +++++++++++++++ eval/src/lib.rs | 14 +- eval/tests/test_metrics_assess.rs | 207 +++++------------------ examples/umap_rs.rs | 154 +++++++++++++++++ src/lib.rs | 8 + src/validate.rs | 4 +- tests/public_api/main.rs | 1 + tests/public_api/umap_rs.rs | 164 ++++++++++++++++++ tests/public_api/validation.rs | 16 ++ 15 files changed, 1250 insertions(+), 175 deletions(-) create mode 100644 docs/umap-rs-integration.md create mode 100644 eval/src/assess.rs create mode 100644 eval/src/bin/init_evidence.rs create mode 100644 examples/umap_rs.rs create mode 100644 tests/public_api/umap_rs.rs diff --git a/.github/package-allowlist.txt b/.github/package-allowlist.txt index a7c1ca1..77ba027 100644 --- a/.github/package-allowlist.txt +++ b/.github/package-allowlist.txt @@ -5,9 +5,11 @@ Cargo.toml.orig LICENSE README.md docs/katex-header.html +docs/umap-rs-integration.md examples/basic.rs examples/compute_modes.rs examples/from_adjacency_list.rs +examples/umap_rs.rs src/components.rs src/config.rs src/error.rs diff --git a/Cargo.lock b/Cargo.lock index 73a2c28..b76ac05 100644 --- a/Cargo.lock +++ b/Cargo.lock @@ -264,6 +264,18 @@ version = "1.1.1" source = "registry+https://github.com/rust-lang/crates.io-index" checksum = "1c133bc6a41be0d194c306b5506d15e6feeea7b1d6604bd3f8310dfb2ca96486" +[[package]] +name = "console" +version = "0.16.6" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "e96a4956774c13c126a8b5af4daa79384f4d826534c95a02d76afb39e2ab64e3" +dependencies = [ + "encode_unicode", + "libc", + "unicode-width", + "windows-sys 0.61.2", +] + [[package]] name = "core_detect" version = "1.0.0" @@ -300,7 +312,7 @@ dependencies = [ "clap", "criterion-plot", "is-terminal", - "itertools", + "itertools 0.10.5", "num-traits", "once_cell", "oorandom", @@ -321,7 +333,7 @@ source = "registry+https://github.com/rust-lang/crates.io-index" checksum = "6b50826342786a51a89e2da3a28f1c32b06e387201bc2d19791f622c673706b1" dependencies = [ "cast", - "itertools", + "itertools 0.10.5", ] [[package]] @@ -386,6 +398,21 @@ version = "0.2.4" source = "registry+https://github.com/rust-lang/crates.io-index" checksum = "460fbee9c2c2f33933d720630a6a0bac33ba7053db5344fac858d4b8952d77d5" +[[package]] +name = "dashmap" +version = "6.2.1" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "e6361d5c062261c78a176addb82d4c821ae42bed6089de0e12603cd25de2059c" +dependencies = [ + "cfg-if", + "crossbeam-utils", + "hashbrown 0.14.5", + "lock_api", + "once_cell", + "parking_lot_core", + "rayon", +] + [[package]] name = "defer" version = "0.2.1" @@ -425,6 +452,12 @@ version = "1.19.0" source = "registry+https://github.com/rust-lang/crates.io-index" checksum = "0e9c71c2167ca323c882b99918929403426e2373ea17242ff5653e0d5e1058be" +[[package]] +name = "encode_unicode" +version = "1.0.0" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "34aa73646ffb006b8f5147f3dc182bd4bcb190227ce861fc4a4844bf8e3cb2c0" + [[package]] name = "enum-as-inner" version = "0.6.1" @@ -790,6 +823,12 @@ dependencies = [ "zerocopy", ] +[[package]] +name = "hashbrown" +version = "0.14.5" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "e5274423e17b7c9fc20b6e7e208532f9b19825d82dfd615708b70edd83df41f1" + [[package]] name = "hashbrown" version = "0.17.1" @@ -821,7 +860,20 @@ source = "registry+https://github.com/rust-lang/crates.io-index" checksum = "cc4e190f5d26ca7051642629da2c52fc03bde85a03197c99408dcd291734c855" dependencies = [ "equivalent", - "hashbrown", + "hashbrown 0.17.1", +] + +[[package]] +name = "indicatif" +version = "0.18.6" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "9433806cd6b4ec1aba79c021c7e4c58fb4c3b9977c085062e611ac929998fb0c" +dependencies = [ + "console", + "portable-atomic", + "unicode-width", + "unit-prefix", + "web-time", ] [[package]] @@ -855,6 +907,15 @@ dependencies = [ "either", ] +[[package]] +name = "itertools" +version = "0.14.0" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "2b192c782037fadd9cfa75548310488aabdbf3d2da73885b31bd0abd03351285" +dependencies = [ + "either", +] + [[package]] name = "itoa" version = "1.0.19" @@ -908,6 +969,15 @@ version = "0.12.1" source = "registry+https://github.com/rust-lang/crates.io-index" checksum = "32a66949e030da00e8c7d4434b251670a91556f4144941d37452769c25d58a53" +[[package]] +name = "lock_api" +version = "0.4.14" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "224399e74b87b5f3557511d98dff8b14089b3dadafcab6bb93eab67d3aace965" +dependencies = [ + "scopeguard", +] + [[package]] name = "log" version = "0.4.35" @@ -1051,6 +1121,7 @@ dependencies = [ "portable-atomic", "portable-atomic-util", "rawpointer", + "serde", ] [[package]] @@ -1168,6 +1239,19 @@ version = "11.1.5" source = "registry+https://github.com/rust-lang/crates.io-index" checksum = "d6790f58c7ff633d8771f42965289203411a5e5c68388703c06e14f24770b41e" +[[package]] +name = "parking_lot_core" +version = "0.9.12" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "2621685985a2ebf1c516881c026032ac7deafcda1a2c9b7850dc81e3dfcb64c1" +dependencies = [ + "cfg-if", + "libc", + "redox_syscall", + "smallvec", + "windows-link", +] + [[package]] name = "paste" version = "1.0.15" @@ -1565,6 +1649,15 @@ version = "0.5.5" source = "registry+https://github.com/rust-lang/crates.io-index" checksum = "03251193000f4bd3b042892be858ee50e8b3719f2b08e5833ac4353724632430" +[[package]] +name = "redox_syscall" +version = "0.5.18" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "ed2bf2547551a7053d6fdfafda3f938979645c44812fbfcda098faae3f1a362d" +dependencies = [ + "bitflags", +] + [[package]] name = "regex" version = "1.13.1" @@ -1640,6 +1733,12 @@ version = "1.0.1" source = "registry+https://github.com/rust-lang/crates.io-index" checksum = "e1cf6437eb19a8f4a6cc0f7dca544973b0b78843adbfeb3683d1a94a0024a294" +[[package]] +name = "scopeguard" +version = "1.2.0" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "94143f37725109f92c262ed2cf5e59bce7498c01bcc1502d7b9afe439a4e9f49" + [[package]] name = "seq-macro" version = "0.3.6" @@ -1741,6 +1840,7 @@ dependencies = [ "serde_json", "sprs", "thiserror 2.0.21", + "umap-rs", ] [[package]] @@ -1760,6 +1860,7 @@ dependencies = [ "serde_json", "spectral-init", "sprs", + "trustworthiness", ] [[package]] @@ -1787,6 +1888,7 @@ dependencies = [ "num-traits", "num_cpus", "rayon", + "serde", "smallvec", ] @@ -1959,9 +2061,21 @@ source = "registry+https://github.com/rust-lang/crates.io-index" checksum = "63e71662fa4b2a2c3a26f570f037eb95bb1f85397f3cd8076caed2f026a6d100" dependencies = [ "pin-project-lite", + "tracing-attributes", "tracing-core", ] +[[package]] +name = "tracing-attributes" +version = "0.1.31" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "7490cfa5ec963746568740651ac6781f701c9c5ea257c58e057f3ba8cf69e8da" +dependencies = [ + "proc-macro2", + "quote", + "syn 2.0.119", +] + [[package]] name = "tracing-core" version = "0.1.36" @@ -2015,12 +2129,50 @@ dependencies = [ "serde_json", ] +[[package]] +name = "typed-builder" +version = "0.21.2" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "fef81aec2ca29576f9f6ae8755108640d0a86dd3161b2e8bca6cfa554e98f77d" +dependencies = [ + "typed-builder-macro", +] + +[[package]] +name = "typed-builder-macro" +version = "0.21.2" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "1ecb9ecf7799210407c14a8cfdfe0173365780968dc57973ed082211958e0b18" +dependencies = [ + "proc-macro2", + "quote", + "syn 2.0.119", +] + [[package]] name = "ucd-trie" version = "0.1.7" source = "registry+https://github.com/rust-lang/crates.io-index" checksum = "2896d95c02a80c6d6a5d6e953d479f5ddf2dfdb6a244441010e373ac0fb88971" +[[package]] +name = "umap-rs" +version = "0.4.5" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "edf38efe1c61db7d7d53fca13c9654a9fa902460d3501f7809dff029e977d54e" +dependencies = [ + "dashmap", + "indicatif", + "itertools 0.14.0", + "ndarray 0.17.2", + "rand 0.9.5", + "rayon", + "serde", + "sprs", + "tracing", + "typed-builder", +] + [[package]] name = "unarray" version = "0.1.4" @@ -2033,6 +2185,18 @@ version = "1.0.27" source = "registry+https://github.com/rust-lang/crates.io-index" checksum = "a2c754d6c33795a1c324727428e5a7dedb5b06195f9890bdbcba760d3e246563" +[[package]] +name = "unicode-width" +version = "0.2.3" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "ca718471876992059f251e33aafc334346ada08042b7661dd1fe313a9bced557" + +[[package]] +name = "unit-prefix" +version = "0.5.2" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "81e544489bf3d8ef66c953931f56617f423cd4b5494be343d9b9d3dda037b9a3" + [[package]] name = "valuable" version = "0.1.1" @@ -2133,6 +2297,16 @@ dependencies = [ "wasm-bindgen", ] +[[package]] +name = "web-time" +version = "1.1.0" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "5a6580f308b1fad9207618087a65c04e7a10bc77e02c8e84e9b00dd4b12fa0bb" +dependencies = [ + "js-sys", + "wasm-bindgen", +] + [[package]] name = "winapi-util" version = "0.1.11" diff --git a/Cargo.toml b/Cargo.toml index e044600..da4ef34 100644 --- a/Cargo.toml +++ b/Cargo.toml @@ -9,7 +9,14 @@ readme = "README.md" rust-version = "1.88" keywords = ["umap", "spectral", "laplacian", "eigenvectors", "embedding"] categories = ["science", "mathematics", "algorithms"] -include = ["/src/**", "/examples/**", "/docs/katex-header.html", "/README.md", "/LICENSE"] +include = [ + "/src/**", + "/examples/**", + "/docs/katex-header.html", + "/docs/umap-rs-integration.md", + "/README.md", + "/LICENSE", +] [package.metadata.docs.rs] rustdoc-args = ["--html-in-header", "docs/katex-header.html"] @@ -51,6 +58,7 @@ approx = "0.5" serde_json = "1" humantime = "2" proptest = "1" +umap-rs = "0.4.5" # the integration the `umap_rs` example and test compile against [profile.dev.package."*"] opt-level = 2 @@ -83,3 +91,7 @@ path = "examples/compute_modes.rs" [[example]] name = "from_adjacency_list" path = "examples/from_adjacency_list.rs" + +[[example]] +name = "umap_rs" +path = "examples/umap_rs.rs" diff --git a/docs/umap-rs-integration.md b/docs/umap-rs-integration.md new file mode 100644 index 0000000..e5bb73c --- /dev/null +++ b/docs/umap-rs-integration.md @@ -0,0 +1,268 @@ +# Using spectral-init with umap-rs + +[`umap-rs`](https://crates.io/crates/umap-rs) optimizes a UMAP embedding and leaves the +starting coordinates to the caller. `spectral-init` computes the starting coordinates +umap-learn uses by default — the spectral layout of the fuzzy graph — from the graph +`umap-rs` itself builds. + +`spectral-init` does not depend on `umap-rs`. This guide is written against `umap-rs` +0.4.5, and every Rust snippet in it is compiled by this crate's test suite. A runnable +program is in [`examples/umap_rs.rs`](https://github.com/TalonT-Org/spectral-init/blob/main/examples/umap_rs.rs). + +## Dependencies + +```toml +[dependencies] +spectral-init = "0.1" +umap-rs = "0.4.5" +``` + +`umap-rs` is imported as `umap_rs`. Both crates use `ndarray` 0.17 and `sprs` 0.11, so +arrays and the graph pass between them without conversion. `spectral-init` re-exports the +two as `spectral_init::ndarray` and `spectral_init::sprs`. + +## The sequence + +1. Find the k nearest neighbours of every point, with any library. `umap-rs` takes them + as two `(n, n_neighbors)` arrays and needs `n > n_neighbors`. A row may list the point + itself; `umap-rs` skips that entry. +2. `Umap::learn_manifold` builds the fuzzy graph. +3. `spectral_init` computes the initial coordinates from `manifold.graph()`. +4. `Optimizer` runs the stochastic gradient descent from those coordinates. + +```rust +use spectral_init::ndarray::{Array2, ArrayView2}; +use spectral_init::{SpectralError, SpectralInitConfig, spectral_init}; +use umap_rs::{EuclideanMetric, Metric, Optimizer, Umap, UmapConfig}; + +/// Embeds `data` with `umap-rs`, starting from the spectral initialization. +fn embed( + data: ArrayView2<'_, f32>, + knn_indices: ArrayView2<'_, u32>, + knn_dists: ArrayView2<'_, f32>, + config: UmapConfig, + seed: u64, +) -> Result, SpectralError> { + let n = data.nrows(); + + // The fuzzy graph. + let manifold = Umap::new(config.clone()).learn_manifold(data, knn_indices, knn_dists); + + // The initial coordinates, for the same number of components as `config`. + let init_config = SpectralInitConfig::new(config.n_components).with_seed(seed); + let init = spectral_init(manifold.graph().view(), Some(data), &init_config)?; + + // The number of epochs `Umap::fit` would choose. + let epochs = config + .optimization + .n_epochs + .unwrap_or(if n <= 10_000 { 500 } else { 200 }); + + let metric = EuclideanMetric; + let mut optimizer = Optimizer::new(manifold, init, epochs, &config, metric.metric_type()); + optimizer.step_epochs(epochs, &metric); + let fitted = optimizer.into_fitted(config); + + // `Umap::fit` reports vertices without any edge as NaN; do the same here. + let isolated: Vec = fitted + .manifold() + .graph() + .outer_iterator() + .enumerate() + .filter(|(_, row)| row.data().iter().sum::() == 0.0) + .map(|(vertex, _)| vertex) + .collect(); + let mut embedding = fitted.into_embedding(); + for vertex in isolated { + embedding.row_mut(vertex).fill(f32::NAN); + } + Ok(embedding) +} +``` + +`Optimizer::new` does not check the shape of the initialization and reads it as one +contiguous slice. `spectral_init` always returns an `(n, n_components)` array in standard +(row-major) layout, which is what it needs. + +### The one-call variant + +`Umap::fit` takes the initialization and runs the optimizer itself. It builds the graph +internally, so the graph is constructed twice: once for the initialization and once +inside `fit`. Prefer the sequence above when graph construction is expensive. + +```rust +use spectral_init::ndarray::{Array2, ArrayView2}; +use spectral_init::{SpectralError, SpectralInitConfig, spectral_init}; +use umap_rs::{Umap, UmapConfig}; + +fn embed_with_fit( + data: ArrayView2<'_, f32>, + knn_indices: ArrayView2<'_, u32>, + knn_dists: ArrayView2<'_, f32>, + config: UmapConfig, + seed: u64, +) -> Result, SpectralError> { + let umap = Umap::new(config.clone()); + let manifold = umap.learn_manifold(data, knn_indices, knn_dists); + let init_config = SpectralInitConfig::new(config.n_components).with_seed(seed); + let init = spectral_init(manifold.graph().view(), Some(data), &init_config)?; + Ok(umap + .fit(data, knn_indices, knn_dists, init.view()) + .into_embedding()) +} +``` + +## What to know + +- **`symmetrize` must stay `true`.** With `GraphParams { symmetrize: false, .. }` the graph + is directed, and `spectral_init` returns `SpectralError::NotSymmetric`. +- **`set_op_mix_ratio`.** For ratios other than 0, 0.5 and 1, the single-precision + symmetrization in `umap-rs` can leave the two halves of an edge one rounding error + apart (1.2 × 10⁻⁷ relative). `spectral_init` accepts relative differences up to 10⁻⁶. +- **`data`.** Pass `Some(data)`. It is read only when the graph has more than + `2 · n_components` connected components, where it places the components relative to one + another; without it that case is `SpectralError::DataRequired`. +- **Rescaling.** `Optimizer::new` rescales every axis of the initialization to `[0, 10]`, + as umap-learn does before it optimizes. The optimizer therefore sees the relative + positions along each axis, not the absolute scale `spectral_init` returns. +- **Isolated vertices.** A vertex without edges is a connected component of its own and + gets coordinates like any other component. `umap-rs` never moves it, and `Umap::fit` + reports it as NaN. +- **Errors.** `spectral_init` returns a `SpectralError` for invalid input and for solver + failure; it does not panic. `umap-rs` panics on invalid input. +- **Reproducibility.** The seed in `SpectralInitConfig` fixes the initialization. The + optimizer of `umap-rs` draws from an unseeded generator, so two fits from the same + initialization differ. + +## Matching umap-learn's edge pruning + +Before it computes the spectral layout, umap-learn removes every edge lighter than the +heaviest edge divided by the number of epochs. `manifold.graph()` still holds those edges. +They carry little weight, so the initialization changes little, but the graph umap-learn +uses can be reproduced: + +```rust +use spectral_init::sprs::CsMatI; + +/// Zeroes the edges umap-learn prunes before its spectral layout. +fn prune_weak_edges( + graph: &CsMatI, + n_epochs: usize, +) -> CsMatI { + let default_epochs = if graph.rows() <= 10_000 { 500 } else { 200 }; + let epochs = if n_epochs > 10 { n_epochs } else { default_epochs }; + let max_weight = graph.data().iter().copied().fold(0.0_f32, f32::max); + let threshold = max_weight / epochs as f32; + graph.map(|&weight| if weight < threshold { 0.0 } else { weight }) +} +``` + +`spectral_init` treats stored zeros as absent edges, so the zeroed entries need not be +removed. With a `set_op_mix_ratio` other than 0, 0.5 or 1, an edge whose two halves +straddle the threshold is pruned on one side only and the result is rejected as +`NotSymmetric`. + +## State of umap-rs + +As of 2026-11-11: + +- 0.4.5, released on 2025-12-01, is the latest version; the repository has had no commit + since 2025-12-02. +- The optimizer differs from umap-learn's in two ways. Both are corrected by pull request + [#6](https://github.com/wilsonzlin/umap-rs/pull/6), which is open. + 1. The gradient denominators carry an extra factor of the squared distance: + `a·d²ᵇ·d² + 1` where umap-learn has `a·d²ᵇ + 1`. + 2. `Optimizer::step_epochs` optimizes against a copy of the embedding made at the start + of each call, where umap-learn updates one array in place. The result depends on how + the epochs are divided among calls. +- Issues [#7](https://github.com/wilsonzlin/umap-rs/issues/7) ("Weird ring 2D embedding") + and [#8](https://github.com/wilsonzlin/umap-rs/issues/8) ("Optimizer produces + structureless embeddings…") are open. + +Final embeddings from `umap-rs` 0.4.5 therefore say little about any initialization, and +the evidence below does not involve an optimizer. + +A fork of `umap-rs` that carries both optimizer fixes and builds spectral initialization +in is at . + +## Other UMAP implementations + +Any implementation that can expose its fuzzy graph as CSR arrays can use `spectral-init` +without copying the graph: + +```rust +use spectral_init::ndarray::Array2; +use spectral_init::sprs::CsMatViewI; +use spectral_init::{SpectralInitConfig, spectral_init}; + +/// Spectral initialization from borrowed CSR arrays of an `n × n` graph. +fn init_from_csr( + n: usize, + indptr: &[usize], + indices: &[u32], + weights: &[f32], + n_components: usize, +) -> Result, Box> { + // A view over the three slices. `try_new` checks the CSR structure: `indptr` has + // `n + 1` non-decreasing entries, and the column indices of each row are sorted + // and below `n`. + let graph = CsMatViewI::::try_new((n, n), indptr, indices, weights) + .map_err(|(_, _, _, error)| error)?; + Ok(spectral_init( + graph, + None, + &SpectralInitConfig::new(n_components), + )?) +} +``` + +The graph must be symmetric with finite, non-negative weights; CSC arrays work the same +way through `try_new_csc`. + +## Evidence + +Measured with `cargo run --release -p spectral-init-eval --bin init_evidence` on +2026-11-12 (UTC), with `spectral-init` 0.1.0 on x86_64 Linux, against reference data +generated by umap-learn 0.5.11 (the fixtures under `tests/fixtures/`). No UMAP optimizer +is involved. + +**Agreement with umap-learn on connected graphs.** The solver runs on umap-learn's +Laplacian. The residual is `‖L·v − λ·v‖ / ‖v‖`, the eigenvalue error is against +umap-learn's eigenvalues, and the Gram determinant compares the spans of the two sets of +non-trivial eigenvectors (1 means the same subspace). + +| Dataset | n | Solver | Max eigenpair residual | Max eigenvalue error | Subspace Gram determinant | +|---|---|---|---|---|---| +| blobs_connected_200 | 200 | Dense EVD | 1.3e-15 | 2.6e-17 | 1.000000000 | +| blobs_connected_2000 | 2000 | LOBPCG | 9.1e-6 | 6.6e-10 | 0.999999988 | +| circles_300 | 300 | Dense EVD | 1.2e-15 | 3.0e-12 | 1.000000000 | +| moons_200 | 200 | Dense EVD | 1.7e-10 | 2.4e-16 | 1.000000000 | +| near_dupes_100 | 100 | Dense EVD | 1.1e-15 | 4.2e-16 | 1.000000000 | + +**Disconnected graphs.** Both implementations find the same connected components. The +separation ratio is the smallest distance between component centroids over the largest +spread within a component. + +| Dataset | n | Components (umap-learn) | Components (spectral-init) | Separation ratio | +|---|---|---|---|---| +| blobs_50 | 50 | 3 | 3 | 1.90 | +| blobs_500 | 500 | 4 | 4 | 1.56 | +| blobs_5000 | 5000 | 2 | 2 | 1.88 | +| disconnected_200 | 200 | 4 | 4 | 1.58 | + +**Trustworthiness of the initial coordinates** (k = 15), before any optimization, for +the spectral initialization and for umap-learn's random one (uniform in [−10, 10]). Eight +of the nine datasets have two-dimensional input, where a two-dimensional layout can +preserve neighbourhoods exactly; `blobs_connected_2000` has ten input dimensions. + +| Dataset | n | Input dimensions | Spectral | Random (mean of 5 seeds) | +|---|---|---|---|---| +| blobs_50 | 50 | 2 | 0.8918 | 0.5535 | +| blobs_500 | 500 | 2 | 0.9714 | 0.5075 | +| blobs_5000 | 5000 | 2 | 0.9628 | 0.4998 | +| blobs_connected_200 | 200 | 2 | 0.9183 | 0.5140 | +| blobs_connected_2000 | 2000 | 10 | 0.8314 | 0.5000 | +| circles_300 | 300 | 2 | 0.8497 | 0.5134 | +| disconnected_200 | 200 | 2 | 0.9442 | 0.5218 | +| moons_200 | 200 | 2 | 0.9866 | 0.5194 | +| near_dupes_100 | 100 | 2 | 0.9130 | 0.5332 | diff --git a/eval/Cargo.toml b/eval/Cargo.toml index 764a361..c4cd7fa 100644 --- a/eval/Cargo.toml +++ b/eval/Cargo.toml @@ -12,6 +12,7 @@ publish = false [dependencies] spectral-init = { path = "..", features = ["__internal"] } +trustworthiness = { path = "../trustworthiness" } ndarray = "0.17" sprs = "0.11" faer = "0.24" diff --git a/eval/src/assess.rs b/eval/src/assess.rs new file mode 100644 index 0000000..257092c --- /dev/null +++ b/eval/src/assess.rs @@ -0,0 +1,255 @@ +//! Accuracy and parity measurements of the solver chain against the umap-learn reference +//! fixtures, shared by the assessment tests and the `init_evidence` binary. + +use crate::diagnostics::{ + DEGENERATE_GAP_THRESHOLD, check_eigenvalue_bounds, eigenvalue_abs_errors, + eigenvalue_condition_number, orthogonality_error, separation_ratio, sign_agnostic_max_error, + spectral_gap, subspace_gram_det_kd, +}; +use crate::fixtures; +use crate::internals::solve_with_unit_hint; +use ndarray::{Array1, Array2, s}; +use spectral_init::__internal::{ + DENSE_EVD_QUALITY_THRESHOLD, LOBPCG_QUALITY_THRESHOLD, RSVD_QUALITY_THRESHOLD, + SINV_LOBPCG_QUALITY_THRESHOLD, SolverLevel, SolverParams, embed_disconnected, find_components, + max_eigenpair_residual, select_eigenvectors, +}; +use spectral_init::ComputeMode; +use sprs::CsMatI; + +/// A reference fixture dataset under `tests/fixtures/`. +#[derive(Debug, Clone, Copy)] +pub struct Dataset { + pub name: &'static str, + /// Number of points. + pub n: usize, + /// Whether the fuzzy graph is connected. + pub connected: bool, + /// Number of connected components of the fuzzy graph. + pub n_graph_components: usize, +} + +/// The nine reference datasets. +pub const DATASETS: &[Dataset] = &[ + Dataset::new("blobs_50", 50, 3), + Dataset::new("blobs_500", 500, 4), + Dataset::new("blobs_5000", 5000, 2), + Dataset::new("blobs_connected_200", 200, 1), + Dataset::new("blobs_connected_2000", 2000, 1), + Dataset::new("circles_300", 300, 1), + Dataset::new("disconnected_200", 200, 4), + Dataset::new("moons_200", 200, 1), + Dataset::new("near_dupes_100", 100, 1), +]; + +impl Dataset { + const fn new(name: &'static str, n: usize, n_graph_components: usize) -> Self { + Self { + name, + n, + connected: n_graph_components == 1, + n_graph_components, + } + } + + /// Number of embedding dimensions the reference was computed for: one less than the + /// number of reference eigenvalues. + pub fn n_embedding_dims(&self) -> usize { + let eigenvalues = self.reference_eigenvalues(); + assert!( + !eigenvalues.is_empty(), + "{}: ref eigenvalues array is empty — fixture may be corrupt", + self.name + ); + eigenvalues.len() - 1 + } + + fn reference_eigenvalues(&self) -> Array1 { + fixtures::load_dense( + &fixtures::fixture_path(self.name, "comp_d_eigensolver.npz"), + "eigenvalues", + ) + } +} + +/// Residual threshold the chain applies at `level`. +pub fn residual_threshold(level: SolverLevel) -> f64 { + match level { + SolverLevel::DenseEvd | SolverLevel::ForcedDense => DENSE_EVD_QUALITY_THRESHOLD, + SolverLevel::Lobpcg | SolverLevel::LobpcgRegularized => LOBPCG_QUALITY_THRESHOLD, + SolverLevel::SinvLobpcg => SINV_LOBPCG_QUALITY_THRESHOLD, + SolverLevel::Rsvd => RSVD_QUALITY_THRESHOLD, + } +} + +/// Eigenpairs the solver chain computes for the reference Laplacian of a connected +/// dataset. +pub struct ReferenceSolve { + pub laplacian: CsMatI, + pub eigenvalues: Array1, + pub eigenvectors: Array2, + /// Level of the chain that produced the eigenpairs. + pub level: SolverLevel, + pub n_embedding_dims: usize, +} + +/// Runs the solver chain (seed 42, `PythonCompat`, default parameters) on the reference +/// Laplacian of `dataset`. +pub fn solve_reference_laplacian(dataset: &Dataset) -> ReferenceSolve { + let n_embedding_dims = dataset.n_embedding_dims(); + let laplacian = fixtures::load_sparse_csr(&fixtures::fixture_path( + dataset.name, + "comp_b_laplacian.npz", + )); + let ((eigenvalues, eigenvectors), report) = solve_with_unit_hint( + &laplacian, + n_embedding_dims, + 42, + ComputeMode::PythonCompat, + &SolverParams::default(), + ); + ReferenceSolve { + laplacian, + eigenvalues, + eigenvectors, + level: report.level, + n_embedding_dims, + } +} + +/// How well computed eigenpairs satisfy the eigenproblem. +pub struct Accuracy { + pub max_residual: f64, + pub orthogonality_error: f64, + /// Every eigenvalue lies in `[-bounds_tol, 2 + bounds_tol]`. + pub eigenvalues_in_range: bool, + pub eigenvalues_sorted: bool, + pub spectral_gap: f64, + /// `NaN` when the second eigenvalue is not positive. + pub condition_number: f64, +} + +pub fn measure_accuracy(solve: &ReferenceSolve, bounds_tol: f64) -> Accuracy { + let eigenvalues = &solve.eigenvalues; + let (eigenvalues_in_range, eigenvalues_sorted) = + check_eigenvalue_bounds(eigenvalues, bounds_tol); + Accuracy { + max_residual: max_eigenpair_residual(&solve.laplacian, eigenvalues, &solve.eigenvectors), + orthogonality_error: orthogonality_error(&solve.eigenvectors), + eigenvalues_in_range, + eigenvalues_sorted, + spectral_gap: spectral_gap(eigenvalues), + condition_number: if eigenvalues.len() > 1 && eigenvalues[1] > 0.0 { + eigenvalue_condition_number(eigenvalues) + } else { + f64::NAN + }, + } +} + +/// How closely computed eigenpairs match the umap-learn reference. +pub struct Parity { + pub max_eigenvalue_abs_error: f64, + /// Largest element difference of the scaled, pre-noise coordinates, up to the sign of + /// each column. + pub sign_agnostic_max_error: f64, + /// Gram determinant between the computed and the reference non-trivial eigenvectors: + /// 1 when they span the same subspace. + pub subspace_gram_det: f64, + /// Whether two reference eigenvalues are closer than `DEGENERATE_GAP_THRESHOLD`, in + /// which case only the subspace, not the individual vectors, is determined. + pub degenerate: bool, +} + +/// Scale eigenvectors to pre-noise f32 (matching Python's 10/max_abs expansion). +fn compute_pre_noise(selected: &Array2) -> Array2 { + let max_abs = selected.iter().map(|x| x.abs()).fold(0.0f64, f64::max); + if max_abs == 0.0 { + return Array2::::zeros(selected.raw_dim()); + } + let expansion = 10.0 / max_abs; + selected.mapv(|v| (v * expansion) as f32) +} + +pub fn measure_parity(dataset: &Dataset, solve: &ReferenceSolve) -> Parity { + let eigensolver_path = fixtures::fixture_path(dataset.name, "comp_d_eigensolver.npz"); + let ref_eigenvalues = dataset.reference_eigenvalues(); + let ref_eigenvectors: Array2 = fixtures::load_dense(&eigensolver_path, "eigenvectors"); + let ref_pre_noise: Array2 = fixtures::load_dense( + &fixtures::fixture_path(dataset.name, "comp_f_scaling.npz"), + "pre_noise", + ); + + let abs_errors = eigenvalue_abs_errors(&solve.eigenvalues, &ref_eigenvalues); + let max_eigenvalue_abs_error = abs_errors.iter().cloned().fold(0.0f64, f64::max); + + let selected = select_eigenvectors( + solve + .eigenvalues + .as_slice_memory_order() + .expect("eigenvalues contiguous"), + &solve.eigenvectors, + solve.n_embedding_dims, + ); + let sign_agnostic_max_error = + sign_agnostic_max_error(&compute_pre_noise(&selected), &ref_pre_noise); + + let evals_slice = ref_eigenvalues + .as_slice_memory_order() + .expect("ref eigenvalues contiguous"); + let degenerate = solve.n_embedding_dims >= 2 + && evals_slice[1..] + .windows(2) + .any(|w| w[1] - w[0] < DEGENERATE_GAP_THRESHOLD); + + Parity { + max_eigenvalue_abs_error, + sign_agnostic_max_error, + subspace_gram_det: subspace_gram_det_kd( + solve.eigenvectors.slice(s![.., 1..]), + ref_eigenvectors.slice(s![.., 1..]), + ), + degenerate, + } +} + +/// Layout of a disconnected dataset. +pub struct DisconnectedLayout { + /// Number of connected components found in the fuzzy graph. + pub n_graph_components: usize, + /// Smallest distance between component centroids over the largest spread within a + /// component, with components as labelled by umap-learn. + pub separation_ratio: f64, +} + +/// Embeds the pruned fuzzy graph of a disconnected dataset (seed 42, `PythonCompat`, no +/// data) and measures how well its components are separated. +pub fn measure_disconnected(dataset: &Dataset) -> DisconnectedLayout { + let graph = fixtures::load_sparse_csr_f32_u32(&fixtures::fixture_path( + dataset.name, + "step5a_pruned.npz", + )); + let (labels, n_graph_components) = find_components(graph.view()); + let embedding = embed_disconnected( + graph.view(), + &labels, + n_graph_components, + dataset.n_embedding_dims(), + 42, + None, + ComputeMode::PythonCompat, + &SolverParams::default(), + ) + .unwrap_or_else(|e| panic!("{}: embed_disconnected failed: {e}", dataset.name)); + + let reference_labels: Array1 = fixtures::load_dense( + &fixtures::fixture_path(dataset.name, "comp_c_components.npz"), + "labels", + ); + let reference_labels: Vec = reference_labels.iter().map(|&x| x as usize).collect(); + + DisconnectedLayout { + n_graph_components, + separation_ratio: separation_ratio(embedding.view(), &reference_labels), + } +} diff --git a/eval/src/bin/init_evidence.rs b/eval/src/bin/init_evidence.rs new file mode 100644 index 0000000..6414b60 --- /dev/null +++ b/eval/src/bin/init_evidence.rs @@ -0,0 +1,137 @@ +//! Optimizer-independent evidence for the spectral initialization. +//! +//! For every reference dataset under `tests/fixtures/` this prints, as Markdown: +//! +//! - agreement with the umap-learn reference: eigenpair residuals, eigenvalue errors and +//! the subspace Gram determinant on connected graphs; component count and separation on +//! disconnected ones; +//! - trustworthiness of the raw initial coordinates, for the spectral initialization and +//! for umap-learn's random one (uniform in [-10, 10]). +//! +//! Nothing here runs a UMAP optimizer. +//! +//! Run with: cargo run --release -p spectral-init-eval --bin init_evidence + +use ndarray::Array2; +use rand::rngs::StdRng; +use rand::{Rng, SeedableRng}; +use spectral_init::{SpectralInitConfig, spectral_init}; +use spectral_init_eval::assess::{ + DATASETS, Dataset, measure_accuracy, measure_disconnected, measure_parity, + solve_reference_laplacian, +}; +use spectral_init_eval::fixtures; +use trustworthiness::trustworthiness; + +/// Embedding dimensions and seed of the spectral initialization. +const N_COMPONENTS: usize = 2; +const SEED: u64 = 42; + +/// Neighbourhood size of the trustworthiness score: the `n_neighbors` the reference +/// graphs were built with. +const TRUST_K: usize = 15; + +/// Seeds the random baseline is averaged over. +const RANDOM_SEEDS: std::ops::Range = 0..5; + +/// umap-learn's random initialization: uniform in [-10, 10]. +fn random_init(n: usize, seed: u64) -> Array2 { + let mut rng = StdRng::seed_from_u64(seed); + Array2::from_shape_fn((n, N_COMPONENTS), |_| rng.random_range(-10.0..10.0)) +} + +/// Version of umap-learn that generated the reference fixtures of `dataset`. +fn reference_umap_version(dataset: &Dataset) -> String { + let meta_path = fixtures::fixture_path(dataset.name, "meta.json"); + let meta = std::fs::read_to_string(&meta_path) + .unwrap_or_else(|e| panic!("cannot read {meta_path:?}: {e}")); + let meta: serde_json::Value = + serde_json::from_str(&meta).unwrap_or_else(|e| panic!("cannot parse {meta_path:?}: {e}")); + meta["env"]["umap"] + .as_str() + .unwrap_or_else(|| panic!("{meta_path:?} names no umap-learn version")) + .to_string() +} + +fn main() { + let generated_at = humantime::format_rfc3339_seconds(std::time::SystemTime::now()); + println!("# Initialization evidence\n"); + println!( + "spectral-init {} · reference: umap-learn {} · generated {generated_at}\n", + env!("CARGO_PKG_VERSION"), + reference_umap_version(&DATASETS[0]), + ); + + println!("## Connected graphs: agreement with umap-learn\n"); + println!( + "| Dataset | n | Solver | Max eigenpair residual | Max eigenvalue error | Subspace Gram determinant |" + ); + println!("|---|---|---|---|---|---|"); + for dataset in DATASETS.iter().filter(|dataset| dataset.connected) { + let solve = solve_reference_laplacian(dataset); + let accuracy = measure_accuracy(&solve, 0.0); + let parity = measure_parity(dataset, &solve); + println!( + "| {} | {} | {} | {:.1e} | {:.1e} | {:.9} |", + dataset.name, + dataset.n, + solve.level.name(), + accuracy.max_residual, + parity.max_eigenvalue_abs_error, + parity.subspace_gram_det, + ); + } + + println!("\n## Disconnected graphs\n"); + println!( + "| Dataset | n | Components (umap-learn) | Components (spectral-init) | Separation ratio |" + ); + println!("|---|---|---|---|---|"); + for dataset in DATASETS.iter().filter(|dataset| !dataset.connected) { + let layout = measure_disconnected(dataset); + println!( + "| {} | {} | {} | {} | {:.2} |", + dataset.name, + dataset.n, + dataset.n_graph_components, + layout.n_graph_components, + layout.separation_ratio, + ); + } + + println!("\n## Trustworthiness of the initial coordinates (k = {TRUST_K})\n"); + println!( + "| Dataset | n | Input dimensions | Spectral | Random (mean of {} seeds) |", + RANDOM_SEEDS.end - RANDOM_SEEDS.start + ); + println!("|---|---|---|---|---|"); + let config = SpectralInitConfig::new(N_COMPONENTS).with_seed(SEED); + for dataset in DATASETS { + let data: Array2 = fixtures::load_dense( + &fixtures::fixture_path(dataset.name, "step0_raw_data.npz"), + "X", + ); + let graph = fixtures::load_sparse_csr_f32_u32(&fixtures::fixture_path( + dataset.name, + "step5a_pruned.npz", + )); + let data_f32 = data.mapv(|v| v as f32); + let init = spectral_init(graph.view(), Some(data_f32.view()), &config) + .unwrap_or_else(|e| panic!("{}: {e}", dataset.name)) + .mapv(f64::from); + + let spectral = trustworthiness(data.view(), init.view(), TRUST_K); + let random = RANDOM_SEEDS + .map(|seed| trustworthiness(data.view(), random_init(dataset.n, seed).view(), TRUST_K)) + .sum::() + / (RANDOM_SEEDS.end - RANDOM_SEEDS.start) as f64; + println!( + "| {} | {} | {} | {:.4} | {:.4} |", + dataset.name, + dataset.n, + data.ncols(), + spectral, + random, + ); + } +} diff --git a/eval/src/lib.rs b/eval/src/lib.rs index 185d040..b917698 100644 --- a/eval/src/lib.rs +++ b/eval/src/lib.rs @@ -1,8 +1,16 @@ //! Research harness for `spectral-init`. //! -//! Holds the report structures shared by the assessment tests in `tests/` and by -//! the tooling that reads their JSON output, and the locations the harness reads -//! from and writes to. +//! Holds the measurements and report structures shared by the assessment tests in +//! `tests/`, the `init_evidence` binary and the tooling that reads their JSON output, +//! and the locations the harness reads from and writes to. + +pub mod assess; +#[path = "../../tests/common/diagnostics.rs"] +pub mod diagnostics; +#[path = "../../tests/common/fixtures.rs"] +pub mod fixtures; +#[path = "../../tests/common/internals.rs"] +pub mod internals; use serde::{Deserialize, Serialize}; use std::path::{Path, PathBuf}; diff --git a/eval/tests/test_metrics_assess.rs b/eval/tests/test_metrics_assess.rs index 538447d..9f1e920 100644 --- a/eval/tests/test_metrics_assess.rs +++ b/eval/tests/test_metrics_assess.rs @@ -1,40 +1,12 @@ -#[path = "../../tests/common/diagnostics.rs"] -mod diagnostics; -#[path = "../../tests/common/fixtures.rs"] -mod fixtures; -#[path = "../../tests/common/internals.rs"] -mod internals; - -use diagnostics::{ - DEGENERATE_GAP_THRESHOLD, SUBSPACE_GRAM_DET_THRESHOLD, check_eigenvalue_bounds, - eigenvalue_abs_errors, eigenvalue_condition_number, orthogonality_error, separation_ratio, - sign_agnostic_max_error, spectral_gap, subspace_gram_det_kd, tolerance_margin, -}; -use internals::solve_with_unit_hint; -use ndarray::s; -use ndarray::{Array1, Array2}; use serde_json::json; -use spectral_init::__internal::{ - DENSE_EVD_QUALITY_THRESHOLD, LOBPCG_QUALITY_THRESHOLD, RSVD_QUALITY_THRESHOLD, - SINV_LOBPCG_QUALITY_THRESHOLD, SolverLevel, SolverParams, embed_disconnected, find_components, - max_eigenpair_residual, select_eigenvectors, +use spectral_init::__internal::SolverLevel; +use spectral_init_eval::assess::{ + DATASETS, Dataset, measure_accuracy, measure_disconnected, measure_parity, residual_threshold, + solve_reference_laplacian, }; -use spectral_init::ComputeMode; +use spectral_init_eval::diagnostics::{SUBSPACE_GRAM_DET_THRESHOLD, tolerance_margin}; use spectral_init_eval::{AssessmentReport, ExperimentMetrics, MetricResult, results_dir}; -/// (name, n, is_connected, expected_n_components) -const DATASETS: &[(&str, usize, bool, usize)] = &[ - ("blobs_50", 50, false, 3), - ("blobs_500", 500, false, 4), - ("blobs_5000", 5000, false, 2), - ("blobs_connected_200", 200, true, 1), - ("blobs_connected_2000", 2000, true, 1), - ("circles_300", 300, true, 1), - ("disconnected_200", 200, false, 4), - ("moons_200", 200, true, 1), - ("near_dupes_100", 100, true, 1), -]; - /// Orthogonality threshold: V^T V - I must be smaller than this. const ORTHO_THRESHOLD: f64 = 1e-8; @@ -46,35 +18,15 @@ const BOUNDS_TOL: f64 = f64::EPSILON * 4.0; // ~8.88e-16 const SIGN_ERROR_THRESHOLD: f64 = 5e-3; /// Dataset filter: SPECTRAL_DATASET env var narrows to a single fixture. -fn datasets_to_run() -> Vec<(&'static str, usize, bool, usize)> { +fn datasets_to_run() -> Vec { let filter = std::env::var("SPECTRAL_DATASET").ok(); DATASETS .iter() - .filter(|(name, ..)| filter.as_deref().is_none_or(|f| *name == f)) + .filter(|dataset| filter.as_deref().is_none_or(|f| dataset.name == f)) .copied() .collect() } -/// Per-solver residual threshold. -fn residual_threshold(level: SolverLevel) -> f64 { - match level { - SolverLevel::DenseEvd | SolverLevel::ForcedDense => DENSE_EVD_QUALITY_THRESHOLD, - SolverLevel::Lobpcg | SolverLevel::LobpcgRegularized => LOBPCG_QUALITY_THRESHOLD, - SolverLevel::SinvLobpcg => SINV_LOBPCG_QUALITY_THRESHOLD, - SolverLevel::Rsvd => RSVD_QUALITY_THRESHOLD, - } -} - -/// Scale eigenvectors to pre-noise f32 (matching Python's 10/max_abs expansion). -fn compute_pre_noise(selected: &Array2) -> Array2 { - let max_abs = selected.iter().map(|x| x.abs()).fold(0.0f64, f64::max); - if max_abs == 0.0 { - return Array2::::zeros(selected.raw_dim()); - } - let expansion = 10.0 / max_abs; - selected.mapv(|v| (v * expansion) as f32) -} - /// Section 4.5 metric entry with threshold gate. fn gated_entry(value: f64, threshold: f64, passed: bool) -> serde_json::Value { json!({ @@ -232,59 +184,31 @@ fn assess_accuracy() { let mut all_reports: Vec = Vec::new(); let mut solver_levels: Vec> = Vec::new(); - for (dataset, n, is_connected, expected_n_components) in &run_set { - let base = fixtures::fixture_path(dataset, ""); - - let ref_eigenvalues: Array1 = - fixtures::load_dense(&base.join("comp_d_eigensolver.npz"), "eigenvalues"); - assert!( - !ref_eigenvalues.is_empty(), - "{dataset}: ref eigenvalues array is empty — fixture may be corrupt" - ); - let n_components_dim = ref_eigenvalues.len() - 1; - - if !is_connected { - let graph = fixtures::load_sparse_csr_f32_u32(&base.join("step5a_pruned.npz")); - let (rust_labels, rust_n_components) = find_components(graph.view()); - - let embedding = embed_disconnected( - graph.view(), - &rust_labels, - rust_n_components, - n_components_dim, - 42, - None, - ComputeMode::PythonCompat, - &SolverParams::default(), - ) - .unwrap_or_else(|e| panic!("{dataset}: embed_disconnected failed: {e}")); - - let py_labels_i32: Array1 = - fixtures::load_dense(&base.join("comp_c_components.npz"), "labels"); - let labels: Vec = py_labels_i32.iter().map(|&x| x as usize).collect(); - - let sep = separation_ratio(embedding.view(), &labels); + for dataset in &run_set { + if !dataset.connected { + let layout = measure_disconnected(dataset); + let count_matches = layout.n_graph_components == dataset.n_graph_components; let metrics = vec![ MetricResult { name: "component_count_match".into(), dimension: 0, - value: (rust_n_components == *expected_n_components) as u8 as f64, + value: count_matches as u8 as f64, threshold: 1.0, - passed: rust_n_components == *expected_n_components, + passed: count_matches, }, MetricResult { name: "separation_ratio".into(), dimension: 0, - value: sep, + value: layout.separation_ratio, threshold: 0.0, passed: true, }, ]; all_reports.push(AssessmentReport { - dataset: dataset.to_string(), - n: *n, + dataset: dataset.name.to_string(), + n: dataset.n, metrics, }); solver_levels.push(None); @@ -292,25 +216,15 @@ fn assess_accuracy() { } // Connected dataset path - let laplacian = fixtures::load_sparse_csr(&base.join("comp_b_laplacian.npz")); - let ((eigenvalues, eigenvectors), solve_report) = solve_with_unit_hint( - &laplacian, - n_components_dim, - 42, - ComputeMode::PythonCompat, - &SolverParams::default(), - ); - let solver_level = solve_report.level; - - let residual = max_eigenpair_residual(&laplacian, &eigenvalues, &eigenvectors); - let ortho = orthogonality_error(&eigenvectors); - let (in_range, sorted) = check_eigenvalue_bounds(&eigenvalues, BOUNDS_TOL); - let gap = spectral_gap(&eigenvalues); - let cond = if eigenvalues.len() > 1 && eigenvalues[1] > 0.0 { - eigenvalue_condition_number(&eigenvalues) - } else { - f64::NAN - }; + let solve = solve_reference_laplacian(dataset); + let solver_level = solve.level; + let accuracy = measure_accuracy(&solve, BOUNDS_TOL); + + let residual = accuracy.max_residual; + let ortho = accuracy.orthogonality_error; + let (in_range, sorted) = (accuracy.eigenvalues_in_range, accuracy.eigenvalues_sorted); + let gap = accuracy.spectral_gap; + let cond = accuracy.condition_number; let resid_thr = residual_threshold(solver_level); let resid_margin = tolerance_margin(resid_thr, residual); let ortho_margin = tolerance_margin(ORTHO_THRESHOLD, ortho); @@ -375,8 +289,8 @@ fn assess_accuracy() { ]; all_reports.push(AssessmentReport { - dataset: dataset.to_string(), - n: *n, + dataset: dataset.name.to_string(), + n: dataset.n, metrics, }); solver_levels.push(Some(solver_level)); @@ -427,57 +341,16 @@ fn assess_parity() { let mut all_reports: Vec = Vec::new(); let mut solver_levels: Vec> = Vec::new(); - for (dataset, n, _, _) in run_set.iter().filter(|(_, _, is_conn, _)| *is_conn) { - let base = fixtures::fixture_path(dataset, ""); - - let laplacian = fixtures::load_sparse_csr(&base.join("comp_b_laplacian.npz")); - let ref_eigenvalues: Array1 = - fixtures::load_dense(&base.join("comp_d_eigensolver.npz"), "eigenvalues"); - let ref_eigenvectors: Array2 = - fixtures::load_dense(&base.join("comp_d_eigensolver.npz"), "eigenvectors"); - let ref_pre_noise: Array2 = - fixtures::load_dense(&base.join("comp_f_scaling.npz"), "pre_noise"); - - assert!( - !ref_eigenvalues.is_empty(), - "{dataset}: ref eigenvalues array is empty — fixture may be corrupt" - ); - let n_components_dim = ref_eigenvalues.len() - 1; - - let ((eigenvalues, eigenvectors), solve_report) = solve_with_unit_hint( - &laplacian, - n_components_dim, - 42, - ComputeMode::PythonCompat, - &SolverParams::default(), - ); - let solver_level = solve_report.level; - - let abs_errors: Array1 = eigenvalue_abs_errors(&eigenvalues, &ref_eigenvalues); - let max_abs_err = abs_errors.iter().cloned().fold(0.0f64, f64::max); - - let selected = select_eigenvectors( - eigenvalues - .as_slice_memory_order() - .expect("eigenvalues contiguous"), - &eigenvectors, - n_components_dim, - ); - let rust_pre_noise = compute_pre_noise(&selected); - let sign_err = sign_agnostic_max_error(&rust_pre_noise, &ref_pre_noise); - - let evals_slice = ref_eigenvalues - .as_slice_memory_order() - .expect("ref eigenvalues contiguous"); - let has_degenerate = n_components_dim >= 2 - && evals_slice[1..] - .windows(2) - .any(|w| w[1] - w[0] < DEGENERATE_GAP_THRESHOLD); - let gram = if has_degenerate { - subspace_gram_det_kd( - eigenvectors.slice(s![.., 1..]), - ref_eigenvectors.slice(s![.., 1..]), - ) + for dataset in run_set.iter().filter(|dataset| dataset.connected) { + let solve = solve_reference_laplacian(dataset); + let solver_level = solve.level; + let parity = measure_parity(dataset, &solve); + + let max_abs_err = parity.max_eigenvalue_abs_error; + let sign_err = parity.sign_agnostic_max_error; + // The subspace is compared only where individual eigenvectors are not determined. + let gram = if parity.degenerate { + parity.subspace_gram_det } else { f64::NAN }; @@ -520,8 +393,8 @@ fn assess_parity() { } all_reports.push(AssessmentReport { - dataset: dataset.to_string(), - n: *n, + dataset: dataset.name.to_string(), + n: dataset.n, metrics, }); solver_levels.push(Some(solver_level)); @@ -558,7 +431,7 @@ fn assess_parity() { let json_parsed: serde_json::Value = serde_json::from_str(&json_str).expect("json not valid"); let connected_count = datasets_to_run() .iter() - .filter(|(_, _, is_conn, _)| *is_conn) + .filter(|dataset| dataset.connected) .count(); assert_eq!( json_parsed["datasets"] diff --git a/examples/umap_rs.rs b/examples/umap_rs.rs new file mode 100644 index 0000000..563c7bc --- /dev/null +++ b/examples/umap_rs.rs @@ -0,0 +1,154 @@ +//! Spectral initialization for `umap-rs`. +//! +//! `umap-rs` leaves the initial coordinates to the caller. This example builds the fuzzy +//! graph with `umap-rs`, computes the spectral initialization from that graph, and hands +//! it to the `umap-rs` optimizer: +//! +//! 1. synthetic data and a brute-force k-nearest-neighbour search, +//! 2. `Umap::learn_manifold` — the fuzzy graph, +//! 3. `spectral_init` on `manifold.graph()`, +//! 4. `Optimizer` — stochastic gradient descent from the spectral coordinates. +//! +//! Run with: cargo run --example umap_rs + +use spectral_init::ndarray::{Array2, ArrayView2}; +use spectral_init::{SpectralInitConfig, spectral_init}; +use umap_rs::{EuclideanMetric, GraphParams, Metric, Optimizer, Umap, UmapConfig}; + +/// Three Gaussian-like blobs in five dimensions, `points_per_blob` points each, close +/// enough to one another that their neighbourhoods overlap. +fn blobs(points_per_blob: usize) -> Array2 { + const CENTERS: [[f32; 5]; 3] = [ + [0.0, 0.0, 0.0, 0.0, 0.0], + [3.0, 1.0, 0.0, 2.0, 0.0], + [0.0, 3.0, 2.0, 0.0, 1.0], + ]; + // A small linear congruential generator keeps the example free of extra crates. + let mut state: u32 = 12345; + let mut uniform = move || { + state = state.wrapping_mul(1_664_525).wrapping_add(1_013_904_223); + (state >> 8) as f32 / (1u32 << 24) as f32 + }; + Array2::from_shape_fn((CENTERS.len() * points_per_blob, 5), |(i, j)| { + // The sum of four uniform draws is bell-shaped with unit-order spread. + let jitter: f32 = (0..4).map(|_| uniform() - 0.5).sum(); + CENTERS[i / points_per_blob][j] + 1.5 * jitter + }) +} + +/// Exact k-nearest neighbours by Euclidean distance. +/// +/// Each row lists the point itself first (distance 0), as `umap-rs` expects from a k-NN +/// search over the data set; it skips that entry when it builds the graph. +fn brute_force_knn(data: ArrayView2<'_, f32>, n_neighbors: usize) -> (Array2, Array2) { + let n = data.nrows(); + let mut indices = Array2::::zeros((n, n_neighbors)); + let mut distances = Array2::::zeros((n, n_neighbors)); + for i in 0..n { + let mut neighbours: Vec<(f32, u32)> = (0..n) + .map(|j| { + let squared: f32 = data + .row(i) + .iter() + .zip(data.row(j)) + .map(|(a, b)| (a - b) * (a - b)) + .sum(); + (squared.sqrt(), j as u32) + }) + .collect(); + neighbours.sort_by(|a, b| a.0.total_cmp(&b.0).then(a.1.cmp(&b.1))); + for (slot, &(distance, index)) in neighbours.iter().take(n_neighbors).enumerate() { + indices[[i, slot]] = index; + distances[[i, slot]] = distance; + } + } + (indices, distances) +} + +fn main() -> Result<(), Box> { + let n_components = 2; + let n_neighbors = 15; + + let data = blobs(100); + let n = data.nrows(); + // `learn_manifold` panics unless both k-NN arrays are (n, n_neighbors) and + // n > n_neighbors. + let (knn_indices, knn_dists) = brute_force_knn(data.view(), n_neighbors); + + // The fuzzy graph. `symmetrize` must stay `true` (the default): spectral + // initialization needs a symmetric graph. + let umap_config = UmapConfig { + n_components, + graph: GraphParams { + n_neighbors, + ..Default::default() + }, + ..Default::default() + }; + let umap = Umap::new(umap_config.clone()); + let manifold = umap.learn_manifold(data.view(), knn_indices.view(), knn_dists.view()); + + // Spectral initialization from the graph. Both configurations name the same + // number of components. `data` is read only if the graph has more than + // `2 * n_components` connected components. + let init_config = SpectralInitConfig::new(n_components).with_seed(42); + let init = spectral_init(manifold.graph().view(), Some(data.view()), &init_config)?; + // `Optimizer::new` does not check the shape of the initialization. + assert_eq!(init.dim(), (n, n_components)); + + // The epoch count `Umap::fit` would choose. + let total_epochs = + umap_config + .optimization + .n_epochs + .unwrap_or(if n <= 10_000 { 500 } else { 200 }); + + let metric = EuclideanMetric; + let mut optimizer = Optimizer::new( + manifold, + init, + total_epochs, + &umap_config, + metric.metric_type(), + ); + optimizer.step_epochs(total_epochs, &metric); + let fitted = optimizer.into_fitted(umap_config); + + // Like `Umap::fit`, mark vertices without any edge as NaN: the optimizer never + // moves them. + let isolated: Vec = fitted + .manifold() + .graph() + .outer_iterator() + .enumerate() + .filter(|(_, row)| row.data().iter().sum::() == 0.0) + .map(|(vertex, _)| vertex) + .collect(); + let mut embedding = fitted.into_embedding(); + for &vertex in &isolated { + embedding.row_mut(vertex).fill(f32::NAN); + } + + println!( + "Embedded {n} points into {n_components} dimensions ({} isolated).", + isolated.len() + ); + for i in (0..n).step_by(n / 6) { + println!( + " point {i:3}: [{:8.4}, {:8.4}]", + embedding[[i, 0]], + embedding[[i, 1]] + ); + } + + assert_eq!(embedding.dim(), (n, n_components)); + for (i, row) in embedding.outer_iter().enumerate() { + if !isolated.contains(&i) { + assert!( + row.iter().all(|v| v.is_finite()), + "non-finite coordinates for point {i}" + ); + } + } + Ok(()) +} diff --git a/src/lib.rs b/src/lib.rs index 6609f46..a3dabae 100644 --- a/src/lib.rs +++ b/src/lib.rs @@ -152,6 +152,14 @@ pub mod __internal { }; } +/// The guides shipped with the crate, attached as documentation so that their Rust +/// snippets are compiled and run as doctests. +#[cfg(doctest)] +mod guides { + #[doc = include_str!("../docs/umap-rs-integration.md")] + struct UmapRsIntegration; +} + use ndarray::{Array2, ArrayView2}; use sprs::CsMatViewI; diff --git a/src/validate.rs b/src/validate.rs index 832d72e..e051501 100644 --- a/src/validate.rs +++ b/src/validate.rs @@ -6,7 +6,9 @@ use ndarray::ArrayView2; use sprs::CsMatViewI; /// Largest relative difference between `W[i,j]` and `W[j,i]` that still counts as -/// symmetric. Single-precision graphs built as `A + Aᵀ − A∘Aᵀ` agree to a few ULPs. +/// symmetric. A fuzzy union `A + Aᵀ − A∘Aᵀ` evaluated in single precision can leave the +/// two halves of an edge one rounding error apart (1.2e-7 relative); the tolerance +/// admits a few of those. const SYMMETRY_REL_TOL: f64 = 1e-6; /// Validates the inputs of `spectral_init` and returns the graph as a CSR view. diff --git a/tests/public_api/main.rs b/tests/public_api/main.rs index 90f5cb5..ae1f501 100644 --- a/tests/public_api/main.rs +++ b/tests/public_api/main.rs @@ -13,4 +13,5 @@ mod no_panic; mod npz_loading; mod pipeline; mod traits; +mod umap_rs; mod validation; diff --git a/tests/public_api/umap_rs.rs b/tests/public_api/umap_rs.rs new file mode 100644 index 0000000..b7d247d --- /dev/null +++ b/tests/public_api/umap_rs.rs @@ -0,0 +1,164 @@ +//! Integration with `umap-rs`: the graph it learns is a valid input, and the resulting +//! initialization is accepted by both of its fitting entry points. +//! +//! The optimizer of `umap-rs` draws from an unseeded generator, so nothing here asserts +//! the values of an optimized embedding. + +use crate::fixtures; +use spectral_init::ndarray::{Array2, ArrayView2}; +use spectral_init::sprs::CsMatI; +use spectral_init::{SpectralError, SpectralInitConfig, spectral_init}; +use umap_rs::{ + EuclideanMetric, GraphParams, LearnedManifold, Metric, OptimizationParams, Optimizer, Umap, + UmapConfig, +}; + +const N_COMPONENTS: usize = 2; + +/// Epochs the optimizer runs: enough to move every vertex, few enough to stay quick. +const EPOCHS: usize = 30; + +/// Raw data and k-nearest-neighbour arrays of a fixture dataset, in the types `umap-rs` +/// takes. +struct KnnFixture { + data: Array2, + knn_indices: Array2, + knn_dists: Array2, +} + +fn load_knn_fixture(dataset: &str) -> KnnFixture { + let data: Array2 = + fixtures::load_dense(&fixtures::fixture_path(dataset, "step0_raw_data.npz"), "X"); + let knn_path = fixtures::fixture_path(dataset, "step1_knn.npz"); + let knn_indices: Array2 = fixtures::load_dense(&knn_path, "knn_indices"); + let knn_dists: Array2 = fixtures::load_dense(&knn_path, "knn_dists"); + KnnFixture { + data: data.mapv(|v| v as f32), + knn_indices: knn_indices.mapv(|i| u32::try_from(i).expect("neighbour index is negative")), + knn_dists, + } +} + +fn umap_config(graph: GraphParams) -> UmapConfig { + UmapConfig { + n_components: N_COMPONENTS, + graph, + optimization: OptimizationParams { + n_epochs: Some(EPOCHS), + ..Default::default() + }, + ..Default::default() + } +} + +fn learn_manifold(fixture: &KnnFixture, config: &UmapConfig) -> LearnedManifold { + assert_eq!(fixture.knn_indices.ncols(), config.graph.n_neighbors); + Umap::new(config.clone()).learn_manifold( + fixture.data.view(), + fixture.knn_indices.view(), + fixture.knn_dists.view(), + ) +} + +/// The fuzzy graph `umap-rs` builds for a fixture dataset with the given +/// `set_op_mix_ratio`. +pub(crate) fn fuzzy_graph(dataset: &str, set_op_mix_ratio: f32) -> CsMatI { + let config = umap_config(GraphParams { + set_op_mix_ratio, + ..Default::default() + }); + learn_manifold(&load_knn_fixture(dataset), &config) + .graph() + .clone() +} + +/// Vertices without any edge: `umap-rs` never moves them and `Umap::fit` reports them +/// as NaN. +fn isolated_vertices(manifold: &LearnedManifold) -> Vec { + manifold + .graph() + .outer_iterator() + .enumerate() + .filter(|(_, row)| row.data().iter().sum::() == 0.0) + .map(|(vertex, _)| vertex) + .collect() +} + +fn assert_rows_finite(embedding: ArrayView2<'_, f32>, isolated: &[usize], context: &str) { + for (vertex, row) in embedding.outer_iter().enumerate() { + if !isolated.contains(&vertex) { + assert!( + row.iter().all(|v| v.is_finite()), + "{context}: non-finite coordinates for vertex {vertex}" + ); + } + } +} + +#[test] +fn spectral_init_feeds_both_umap_rs_entry_points() { + // A connected graph, a graph with several components, and a larger one. + for dataset in ["blobs_connected_200", "disconnected_200", "blobs_500"] { + let fixture = load_knn_fixture(dataset); + let n = fixture.data.nrows(); + let config = umap_config(GraphParams::default()); + let manifold = learn_manifold(&fixture, &config); + let isolated = isolated_vertices(&manifold); + + // The learned graph passes validation as it is. + let init_config = SpectralInitConfig::new(N_COMPONENTS).with_seed(42); + let init = spectral_init( + manifold.graph().view(), + Some(fixture.data.view()), + &init_config, + ) + .unwrap_or_else(|e| panic!("{dataset}: {e}")); + assert_eq!(init.dim(), (n, N_COMPONENTS), "{dataset}"); + assert!(init.iter().all(|v| v.is_finite()), "{dataset}"); + // `Optimizer::new` reads the initialization through `as_slice_mut`. + assert!(init.is_standard_layout(), "{dataset}"); + + // The checkpointing path: `Optimizer` on the manifold the graph came from. + let metric = EuclideanMetric; + let mut optimizer = Optimizer::new( + manifold, + init.clone(), + EPOCHS, + &config, + metric.metric_type(), + ); + optimizer.step_epochs(EPOCHS, &metric); + assert_eq!(optimizer.remaining_epochs(), 0); + let fitted = optimizer.into_fitted(config.clone()); + assert_eq!(fitted.embedding().dim(), (n, N_COMPONENTS)); + assert_rows_finite(fitted.embedding(), &isolated, dataset); + + // The one-call path, which builds the graph again. + let fitted = Umap::new(config).fit( + fixture.data.view(), + fixture.knn_indices.view(), + fixture.knn_dists.view(), + init.view(), + ); + assert_eq!(fitted.embedding().dim(), (n, N_COMPONENTS)); + assert_rows_finite(fitted.embedding(), &isolated, dataset); + } +} + +#[test] +fn graph_without_symmetrization_is_rejected() { + let fixture = load_knn_fixture("blobs_connected_200"); + let config = umap_config(GraphParams { + symmetrize: false, + ..Default::default() + }); + let manifold = learn_manifold(&fixture, &config); + assert_err!( + spectral_init( + manifold.graph().view(), + Some(fixture.data.view()), + &SpectralInitConfig::new(N_COMPONENTS), + ), + SpectralError::NotSymmetric { .. } + ); +} diff --git a/tests/public_api/validation.rs b/tests/public_api/validation.rs index 9945152..602fb1f 100644 --- a/tests/public_api/validation.rs +++ b/tests/public_api/validation.rs @@ -494,6 +494,22 @@ fn every_fixture_graph_passes_validation() { assert_eq!(count, 18); } +/// `umap-rs` symmetrizes its graph in single precision; for mix ratios other than 0, 0.5 +/// and 1 the two halves of an edge can differ by a rounding error. +#[test] +fn umap_rs_graphs_pass_validation_for_every_mix_ratio() { + for dataset in DATASETS { + for set_op_mix_ratio in [0.3, 0.5, 0.7, 1.0] { + let graph = crate::umap_rs::fuzzy_graph(dataset, set_op_mix_ratio); + assert_eq!( + validate_graph(&graph), + Ok(()), + "{dataset}, set_op_mix_ratio = {set_op_mix_ratio}" + ); + } + } +} + #[test] fn a_one_part_in_a_thousand_asymmetry_fails_validation() { for (name, graph) in fixture_graphs() { From c81f3e03940d6be253de54f1ef4c7c0f9402bde6 Mon Sep 17 00:00:00 2001 From: Trecek Date: Wed, 11 Nov 2026 17:14:17 -0800 Subject: [PATCH 006/113] Phase 5: documentation and legal README - States what the crate computes and for which inputs, with a compiled quick start through the re-exported `sprs`, the `umap-rs` snippet, both compute modes as they behave on every target, the solver chain and the dense memory budget, the full error table with a fallback `match`, platforms, the reproducibility contract, the semver policy, the two integration routes and acknowledgements. - Drops the quality overclaim, the stale performance table and the stale testing and requirements sections. Guides - `docs/user-guide.md` is rewritten against the real API: building the graph, configuration, disconnected graphs and `data`, every error variant, reproducibility and threads, performance notes. - README, user guide and integration guide are attached to the crate under `cfg(doctest)`, so every Rust snippet compiles and runs; both guides ship in the package. - Internal reports move from `docs/` to `research/reports/` (benchmark plan and report, implementation report, metric definitions), with their links and the report generator's output path updated. Source docs - Crate docs: accurate algorithm, compute-mode and parity statements; the `umap-rs` section names the API that exists. - Stale solver level labels corrected; tracker references removed from `src/` and `eval/benches/`; "bit-for-bit" and "exactly" claims replaced by what the tests verify. - `tests/README.md`: fixtures are tracked; loaders and datasets described as they are. KaTeX - Two of the three subresource-integrity hashes in `docs/katex-header.html` were wrong; all three now match the files, as checked against the CDN and the npm tarball. `.github/scripts/check-sri.sh` verifies them in the docs job. Project files - `CHANGELOG.md` (Keep a Changelog) with the 0.1.0 entry. - License `MIT OR Apache-2.0`: `LICENSE-MIT` (the former `LICENSE`) and `LICENSE-APACHE`. - `.github/CONTRIBUTING.md` and `.github/SECURITY.md`. - `CLAUDE.md`: six-level chain and dense budget, workspace test command, architecture, dependencies and report path as they are now. Co-Authored-By: Claude --- .github/CONTRIBUTING.md | 109 +++ .github/SECURITY.md | 30 + .github/package-allowlist.txt | 4 +- .github/scripts/check-sri.sh | 47 ++ .github/workflows/test.yml | 3 + CHANGELOG.md | 54 ++ CLAUDE.md | 60 +- Cargo.toml | 6 +- LICENSE-APACHE | 201 +++++ LICENSE => LICENSE-MIT | 0 README.md | 316 +++++--- docs/katex-header.html | 4 +- docs/user-guide.md | 700 ++++++++++-------- eval/benches/README.md | 13 +- eval/benches/spectral_bench.rs | 2 +- .../scripts/write_benchmark_report.py | 6 +- .../reports}/merfish-10k-benchmark-report.md | 8 +- .../reports}/merfish-umap-benchmark-plan.md | 0 {docs => research/reports}/metrics/README.md | 2 +- .../reports}/metrics/cluster-preservation.md | 0 .../reports}/metrics/global-structure.md | 0 .../reports}/metrics/spatial-correlation.md | 0 .../metrics/structure-preservation.md | 0 ...itialization-rust-implementation-report.md | 0 src/config.rs | 23 +- src/laplacian.rs | 5 +- src/lib.rs | 85 ++- src/solvers/lobpcg.rs | 41 +- src/solvers/rsvd.rs | 2 +- src/solvers/sinv.rs | 8 +- tests/README.md | 65 +- tests/internals/comp_f_lobpcg.rs | 4 +- 32 files changed, 1239 insertions(+), 559 deletions(-) create mode 100644 .github/CONTRIBUTING.md create mode 100644 .github/SECURITY.md create mode 100755 .github/scripts/check-sri.sh create mode 100644 CHANGELOG.md create mode 100644 LICENSE-APACHE rename LICENSE => LICENSE-MIT (100%) rename {docs => research/reports}/merfish-10k-benchmark-report.md (91%) rename {docs => research/reports}/merfish-umap-benchmark-plan.md (100%) rename {docs => research/reports}/metrics/README.md (92%) rename {docs => research/reports}/metrics/cluster-preservation.md (100%) rename {docs => research/reports}/metrics/global-structure.md (100%) rename {docs => research/reports}/metrics/spatial-correlation.md (100%) rename {docs => research/reports}/metrics/structure-preservation.md (100%) rename {docs => research/reports}/umap-spectral-initialization-rust-implementation-report.md (100%) diff --git a/.github/CONTRIBUTING.md b/.github/CONTRIBUTING.md new file mode 100644 index 0000000..de88ceb --- /dev/null +++ b/.github/CONTRIBUTING.md @@ -0,0 +1,109 @@ +# Contributing to spectral-init + +## Layout + +The repository is a Cargo workspace with three packages: + +| Package | Path | Published | Purpose | +|---------|------|-----------|---------| +| `spectral-init` | `.` | yes | The library: `src/`, `examples/`, `tests/` | +| `trustworthiness` | `trustworthiness/` | no | Embedding-quality metric and command-line tools | +| `spectral-init-eval` | `eval/` | no | Research harness: benchmarks, sweeps, exporters | + +`research/` holds experiment artifacts and is not built by Cargo. + +## Building and testing + +The minimum supported Rust version of the library is 1.88. `Cargo.lock` is tracked; pass +`--locked` so that a build never changes it. + +```sh +# The whole workspace, as CI runs it (needs cargo-nextest). +cargo nextest run --locked --workspace --all-features --profile ci + +# Doctests, including the snippets of README.md and docs/*.md. +cargo test --locked --workspace --doc +``` + +`cargo test` on its own runs only the library's default-feature tests. The tests of its +internals are in `tests/internals/` and need the hidden `__internal` feature, which +`--all-features` switches on. + +The `ci` profile leaves out a few slow tests; two of them run with `--profile slow`. + +## Checks + +A change has to pass the checks CI runs: + +```sh +cargo fmt --all --check + +# The build users compile, and the whole workspace. +cargo clippy --locked -p spectral-init --all-targets -- -D warnings +cargo clippy --locked --workspace --all-targets --all-features -- -D warnings + +# Rustdoc without warnings. +RUSTDOCFLAGS="-D warnings" cargo doc --locked --no-deps -p spectral-init + +# The library neither prints nor reads the environment; see the script for the rest. +.github/scripts/check-purity.sh + +# The packaged crate contains exactly the allow-listed files and passes its own tests. +.github/scripts/check-package.sh + +# The hashes in docs/katex-header.html match the files they refer to. +.github/scripts/check-sri.sh +``` + +`check-package.sh` compares `cargo package --list` with `.github/package-allowlist.txt`. +Add a line there when you add a file under `src/` or `examples/`, or change `include` in +`Cargo.toml`. + +### Public API + +The public API of the library is recorded in `.github/api-snapshot.txt` and checked by +`.github/scripts/check-api.sh`, which needs a nightly toolchain and +[`cargo-public-api`](https://crates.io/crates/cargo-public-api). The listing depends on +both versions; use the ones CI pins in `.github/workflows/`. After an intended change of +the API, run `.github/scripts/check-api.sh --update` and commit the snapshot. + +Everything under `spectral_init::__internal` is outside the public API. It exists for +the tests in `tests/internals/` and for `eval/`, and the `__internal` feature must not +change what the library computes. + +## The parity rule + +`ComputeMode::PythonCompat` is the reference-matching implementation: its results are +tested against values recorded from umap-learn. A change that could make results diverge +from umap-learn — a different summation order, a different solver path, a SIMD kernel — +belongs behind `ComputeMode::RustNative` and must leave the `PythonCompat` path as it +is. + +Numerical changes come with numerical tests: compare against the reference fixtures, up +to the sign of each eigenvector, and use residuals and subspace comparison where +eigenvalues nearly coincide. + +## Reference fixtures + +`tests/fixtures/` holds `.npz` files generated by umap-learn for nine datasets, and they +are tracked. `tests/README.md` describes their format and how to regenerate them: + +```sh +micromamba create -f tests/environment.yml +micromamba activate spectral-test +python tests/generate_fixtures.py --verify +``` + +Regenerate them only on purpose, for example for a new umap-learn version, and commit +the result together with `tests/fixtures/manifest.json`. + +## Unsafe code + +The only `unsafe` code of the library is the AVX2 kernel in `src/operator.rs`. Every +`unsafe` block needs a `// SAFETY:` comment, and every safe function that reaches one +has to enforce what the block relies on. The kernel's tests run under Miri in CI. + +## License + +The project is licensed under either of the Apache License, Version 2.0 +([LICENSE-APACHE](../LICENSE-APACHE)) or the MIT license ([LICENSE-MIT](../LICENSE-MIT)). diff --git a/.github/SECURITY.md b/.github/SECURITY.md new file mode 100644 index 0000000..9974d34 --- /dev/null +++ b/.github/SECURITY.md @@ -0,0 +1,30 @@ +# Security policy + +## Supported versions + +Security fixes are made for the latest released version of `spectral-init`. + +## Reporting a vulnerability + +Please report vulnerabilities privately through GitHub's private vulnerability +reporting: open the **Security** tab of the repository and choose **Report a +vulnerability**, or go to +. Do not open a +public issue for a suspected vulnerability. + +Include the version, the target and CPU, and an input that reproduces the problem if you +have one. + +## What counts + +`spectral-init` is a numerical library that takes a sparse graph and returns coordinates. +It does no I/O and reads no environment variables. The following are treated as security +problems: + +- undefined behaviour reachable through the safe public API, in particular through the + AVX2 kernel selected by `ComputeMode::RustNative`; +- a panic in `spectral_init` on any input, which the crate documents as impossible; +- a dense allocation larger than the configured dense memory budget. + +Long running times and large memory use within the documented budget on large inputs +are not vulnerabilities; neither are numerical differences from umap-learn. diff --git a/.github/package-allowlist.txt b/.github/package-allowlist.txt index 77ba027..52ca793 100644 --- a/.github/package-allowlist.txt +++ b/.github/package-allowlist.txt @@ -2,10 +2,12 @@ Cargo.lock Cargo.toml Cargo.toml.orig -LICENSE +LICENSE-APACHE +LICENSE-MIT README.md docs/katex-header.html docs/umap-rs-integration.md +docs/user-guide.md examples/basic.rs examples/compute_modes.rs examples/from_adjacency_list.rs diff --git a/.github/scripts/check-sri.sh b/.github/scripts/check-sri.sh new file mode 100755 index 0000000..d656e3d --- /dev/null +++ b/.github/scripts/check-sri.sh @@ -0,0 +1,47 @@ +#!/usr/bin/env bash +# Subresource-integrity gate for the KaTeX header that rustdoc embeds. +# +# Downloads every resource docs/katex-header.html loads with an `integrity` +# attribute, recomputes its sha384 digest and compares it with the attribute. +# A wrong digest makes the browser refuse the resource, and the formulas on +# docs.rs stay unrendered. +# +# Usage: .github/scripts/check-sri.sh +set -euo pipefail + +repo_root="$(cd "$(dirname "${BASH_SOURCE[0]}")/../.." && pwd)" +cd "$repo_root" + +header="docs/katex-header.html" +status=0 +checked=0 + +while IFS= read -r line; do + [[ "$line" =~ integrity=\"([^\"]+)\" ]] || continue + expected="${BASH_REMATCH[1]}" + if ! [[ "$line" =~ (href|src)=\"([^\"]+)\" ]]; then + echo "error: integrity attribute without a URL: ${line}" >&2 + exit 2 + fi + url="${BASH_REMATCH[2]}" + + digest="$(curl --fail --silent --show-error --location "$url" \ + | openssl dgst -sha384 -binary | openssl base64 -A)" + actual="sha384-${digest}" + checked=$((checked + 1)) + if [ "$actual" != "$expected" ]; then + echo "error: integrity mismatch for ${url}" >&2 + echo " in ${header}: ${expected}" >&2 + echo " computed: ${actual}" >&2 + status=1 + fi +done < "$header" + +if [ "$checked" -eq 0 ]; then + echo "error: ${header} has no integrity attributes" >&2 + exit 2 +fi +if [ "$status" -eq 0 ]; then + echo "SRI gate passed (${checked} resources)" +fi +exit "$status" diff --git a/.github/workflows/test.yml b/.github/workflows/test.yml index 2a4e37b..bc41439 100644 --- a/.github/workflows/test.yml +++ b/.github/workflows/test.yml @@ -158,6 +158,9 @@ jobs: - name: Run doctests run: cargo test --locked --workspace --doc + - name: KaTeX header integrity hashes + run: .github/scripts/check-sri.sh + msrv: name: msrv runs-on: ubuntu-latest diff --git a/CHANGELOG.md b/CHANGELOG.md new file mode 100644 index 0000000..92b0fc8 --- /dev/null +++ b/CHANGELOG.md @@ -0,0 +1,54 @@ +# Changelog + +All notable changes to this project are documented in this file. + +The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/), and +this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html). + +## [0.1.0] - Unreleased + +First release. + +### Added + +- `spectral_init(graph, data, &config)`: spectral initialization coordinates for a + symmetric, non-negative sparse graph, with the semantics of + `umap.spectral.spectral_layout` in umap-learn 0.5.x. The graph is a `sprs` view with + `f32` weights and `u32` indices in CSR or CSC storage; the result is an + `(n, n_components)` `Array2` in standard layout, scaled to a largest magnitude of + 10 with Gaussian noise of standard deviation 10⁻⁴. +- `SpectralInitConfig`: the number of embedding dimensions, the seed (default 0), the + compute mode (default `PythonCompat`) and the dense memory budget (default 4 GiB). +- `ComputeMode::PythonCompat`, which follows umap-learn's arithmetic, and + `ComputeMode::RustNative`, which sums degrees in double precision and uses an AVX2+FMA + sparse matrix-vector kernel on x86_64 CPUs that support it. +- `SpectralError`, with one variant per failure. The input is validated before any + computation: the graph must be square, symmetric (within a relative tolerance of 10⁻⁶) + and have finite, non-negative weights, with more nodes than embedding dimensions. + Stored zeros are absent edges; self-loops count towards degree and adjacency. +- A chain of six eigensolvers — dense eigendecomposition, LOBPCG, shift-and-invert + LOBPCG, regularized LOBPCG, randomized SVD and a final dense eigendecomposition — in + which every result has to pass a residual check. +- A dense memory budget. No solver allocates a dense matrix larger than the budget: the + first dense level and the randomized SVD are skipped when they would exceed it, and + the final dense level and the component layout return + `SpectralError::DenseBudgetExceeded`. The budget bounds each dense matrix individually, + not the peak memory of the process, and an allocation within the budget that the + system cannot satisfy aborts the process. +- Layout of disconnected graphs: every connected component is embedded on its own, and + the components are placed relative to one another. `data` is required only when the + graph has more than `2 · n_components` components. +- Re-exports of `sprs` and `ndarray`, whose types appear in the API. +- A reproducibility contract: for a fixed `Cargo.lock`, target, CPU feature set and + thread configuration the output is deterministic. Random numbers come from + `rand_chacha::ChaCha12Rng`. +- A user guide, a guide to using the crate with `umap-rs`, and four examples. + +### Notes + +- `spectral_init` does not panic on any input, and it never substitutes a random layout: + a failure of every solver is reported as `SpectralError::ConvergenceFailure`. +- The minimum supported Rust version is 1.88. +- The crate has no public Cargo features. + +[0.1.0]: https://github.com/TalonT-Org/spectral-init/releases/tag/v0.1.0 diff --git a/CLAUDE.md b/CLAUDE.md index 42f33a5..c1bb207 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -6,9 +6,9 @@ Mandatory instructions for AI-assisted development in this repository. A standalone Rust crate that implements spectral initialization for UMAP embeddings. It computes Laplacian eigenvectors of the fuzzy k-NN graph to provide globally-aware starting coordinates for SGD optimization — the key factor that makes Python UMAP produce superior embeddings compared to random or PCA initialization. -Designed to integrate with `umap-rs` (wilsonzlin) via its public `graph()` accessor, but usable by any Rust UMAP implementation that provides a sparse adjacency matrix. +Designed to integrate with `umap-rs` (wilsonzlin) via its public `LearnedManifold::graph()` accessor, but usable by any Rust UMAP implementation that provides a sparse adjacency matrix. -**Core algorithm:** Build the symmetric normalized Laplacian `L = I - D^{-1/2} W D^{-1/2}`, compute the smallest non-trivial eigenvectors via a solver escalation chain (dense EVD → LOBPCG → LOBPCG+regularization → randomized SVD → forced dense EVD), scale and add noise. No random fallback, ever. +**Core algorithm:** Build the symmetric normalized Laplacian `L = I - D^{-1/2} W D^{-1/2}`, compute the smallest non-trivial eigenvectors via a six-level solver escalation chain (dense EVD → LOBPCG → shift-invert LOBPCG → LOBPCG+regularization → randomized SVD → dense EVD for any size within the dense memory budget), scale and add noise. When no level produces an acceptable result within the budget, return an error. No random fallback, ever. ## **2. General Principles** @@ -43,7 +43,7 @@ Designed to integrate with `umap-rs` (wilsonzlin) via its public `graph()` acces ## **4. Testing Guidelines** - * **Run tests**: `cargo test` from the project root. + * **Run tests**: `cargo nextest run --workspace --all-features` from the project root. `cargo test` alone runs only the root package's default-feature tests. * **Always run tests at end of task** * **Add tests for new features** * **Follow existing test patterns** — avoid test code redundancy @@ -51,36 +51,58 @@ Designed to integrate with `umap-rs` (wilsonzlin) via its public `graph()` acces ## **5. Architecture** +The repository is a Cargo workspace. The root package is the published `spectral-init` crate; `trustworthiness/` and `eval/` are unpublished members. + ``` -src/ -├── lib.rs # Public API: spectral_init() +src/ # The published crate +├── lib.rs # Public API: spectral_init(); hidden `__internal` re-exports +├── config.rs # SpectralInitConfig, ComputeMode +├── error.rs # SpectralError +├── validate.rs # Boundary validation of config, graph and data ├── components.rs # Connected components (BFS on sparse graph) -├── laplacian.rs # Symmetric normalized Laplacian construction +├── laplacian.rs # Degrees and symmetric normalized Laplacian construction +├── operator.rs # LinearOperator; scalar and AVX2 sparse matrix-vector product +├── selection.rs # Selection of the non-trivial eigenvectors ├── solvers/ # Eigensolver implementations -│ ├── mod.rs # Solver escalation chain -│ ├── dense.rs # Dense EVD via faer (small n) -│ ├── lobpcg.rs # LOBPCG iterative solver -│ └── rsvd.rs # Randomized SVD via 2I-L trick +│ ├── mod.rs # Solver escalation chain, SolverParams, dense memory budget +│ ├── quality.rs # Residual thresholds and checks +│ ├── dense.rs # Dense EVD via faer (Levels 0 and 5) +│ ├── lobpcg.rs # LOBPCG iterative solver (Levels 1 and 3) +│ ├── sinv.rs # Shift-and-invert LOBPCG (Level 2) +│ ├── rsvd.rs # Randomized SVD via 2I-L trick (Level 4) +│ └── nd16_bridge.rs # The only user of linfa-linalg and ndarray 0.16 ├── multi_component.rs # Disconnected graph handling -└── scaling.rs # Coordinate scaling and noise +└── scaling.rs # Sign normalization, coordinate scaling and noise + +examples/ # Runnable examples, shipped with the crate +docs/ # User guide, umap-rs integration guide, KaTeX header tests/ +├── public_api/ # Tests of the public API (default features) +├── internals/ # Tests of internals (feature `__internal`) +├── common/ # Fixture loaders and diagnostics, shared with eval/ +├── determinism_threads.rs # Thread-configuration test (its own binary) ├── fixtures/ # Python-generated .npz reference data -└── integration/ # End-to-end tests against Python UMAP output +└── visual_eval/ # Python visual-evaluation tooling + +trustworthiness/ # Workspace member: embedding-quality metric and CLI +eval/ # Workspace member: research harness (benches, sweeps, exporters) +research/ # Experiment artifacts and reports temp/ # Temporary/working files (gitignored) ``` ## **6. Key Dependencies** - * `sprs` — Sparse matrices (CSR/CSC/COO), matches `umap-rs` internal format - * `ndarray` — Dense array operations - * `faer` — Dense linear algebra (eigendecomposition, QR) - * `linfa-linalg` — pure-Rust LOBPCG eigensolver (no LAPACK dependency) - * `rand` — RNG for reproducible initialization + * `sprs` — Sparse matrices (CSR/CSC/COO), matches `umap-rs` internal format; public dependency, re-exported + * `ndarray` — Dense array operations; public dependency, re-exported + * `faer` — Dense linear algebra (eigendecomposition, QR) and sparse Cholesky + * `linfa-linalg` — pure-Rust LOBPCG eigensolver (no LAPACK dependency), reached only through `src/solvers/nd16_bridge.rs` + * `rand`, `rand_chacha`, `rand_distr` — ChaCha12 RNG for reproducible initialization + * `thiserror`, `log` — error type and logging facade ## **7. Reference** - * Implementation report: see `docs/umap-spectral-initialization-rust-implementation-report.md` + * Implementation report: see `research/reports/umap-spectral-initialization-rust-implementation-report.md` * Python UMAP spectral source: `umap/spectral.py` in `lmcinnes/umap` - * Target integration: `umap-rs` by wilsonzlin (`CsMatI` graph format) + * Target integration: `umap-rs` by wilsonzlin (`LearnedManifold::graph()` returns `CsMatI`) diff --git a/Cargo.toml b/Cargo.toml index da4ef34..4e890a5 100644 --- a/Cargo.toml +++ b/Cargo.toml @@ -3,7 +3,7 @@ name = "spectral-init" version = "0.1.0" edition = "2024" description = "Spectral initialization for UMAP embeddings" -license = "MIT" +license = "MIT OR Apache-2.0" repository = "https://github.com/TalonT-Org/spectral-init" readme = "README.md" rust-version = "1.88" @@ -14,8 +14,10 @@ include = [ "/examples/**", "/docs/katex-header.html", "/docs/umap-rs-integration.md", + "/docs/user-guide.md", "/README.md", - "/LICENSE", + "/LICENSE-APACHE", + "/LICENSE-MIT", ] [package.metadata.docs.rs] diff --git a/LICENSE-APACHE b/LICENSE-APACHE new file mode 100644 index 0000000..16fe87b --- /dev/null +++ b/LICENSE-APACHE @@ -0,0 +1,201 @@ + Apache License + Version 2.0, January 2004 + http://www.apache.org/licenses/ + +TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION + +1. Definitions. + + "License" shall mean the terms and conditions for use, reproduction, + and distribution as defined by Sections 1 through 9 of this document. + + "Licensor" shall mean the copyright owner or entity authorized by + the copyright owner that is granting the License. + + "Legal Entity" shall mean the union of the acting entity and all + other entities that control, are controlled by, or are under common + control with that entity. For the purposes of this definition, + "control" means (i) the power, direct or indirect, to cause the + direction or management of such entity, whether by contract or + otherwise, or (ii) ownership of fifty percent (50%) or more of the + outstanding shares, or (iii) beneficial ownership of such entity. + + "You" (or "Your") shall mean an individual or Legal Entity + exercising permissions granted by this License. + + "Source" form shall mean the preferred form for making modifications, + including but not limited to software source code, documentation + source, and configuration files. + + "Object" form shall mean any form resulting from mechanical + transformation or translation of a Source form, including but + not limited to compiled object code, generated documentation, + and conversions to other media types. + + "Work" shall mean the work of authorship, whether in Source or + Object form, made available under the License, as indicated by a + copyright notice that is included in or attached to the work + (an example is provided in the Appendix below). + + "Derivative Works" shall mean any work, whether in Source or Object + form, that is based on (or derived from) the Work and for which the + editorial revisions, annotations, elaborations, or other modifications + represent, as a whole, an original work of authorship. For the purposes + of this License, Derivative Works shall not include works that remain + separable from, or merely link (or bind by name) to the interfaces of, + the Work and Derivative Works thereof. + + "Contribution" shall mean any work of authorship, including + the original version of the Work and any modifications or additions + to that Work or Derivative Works thereof, that is intentionally + submitted to Licensor for inclusion in the Work by the copyright owner + or by an individual or Legal Entity authorized to submit on behalf of + the copyright owner. For the purposes of this definition, "submitted" + means any form of electronic, verbal, or written communication sent + to the Licensor or its representatives, including but not limited to + communication on electronic mailing lists, source code control systems, + and issue tracking systems that are managed by, or on behalf of, the + Licensor for the purpose of discussing and improving the Work, but + excluding communication that is conspicuously marked or otherwise + designated in writing by the copyright owner as "Not a Contribution." + + "Contributor" shall mean Licensor and any individual or Legal Entity + on behalf of whom a Contribution has been received by Licensor and + subsequently incorporated within the Work. + +2. Grant of Copyright License. Subject to the terms and conditions of + this License, each Contributor hereby grants to You a perpetual, + worldwide, non-exclusive, no-charge, royalty-free, irrevocable + copyright license to reproduce, prepare Derivative Works of, + publicly display, publicly perform, sublicense, and distribute the + Work and such Derivative Works in Source or Object form. + +3. Grant of Patent License. Subject to the terms and conditions of + this License, each Contributor hereby grants to You a perpetual, + worldwide, non-exclusive, no-charge, royalty-free, irrevocable + (except as stated in this section) patent license to make, have made, + use, offer to sell, sell, import, and otherwise transfer the Work, + where such license applies only to those patent claims licensable + by such Contributor that are necessarily infringed by their + Contribution(s) alone or by combination of their Contribution(s) + with the Work to which such Contribution(s) was submitted. If You + institute patent litigation against any entity (including a + cross-claim or counterclaim in a lawsuit) alleging that the Work + or a Contribution incorporated within the Work constitutes direct + or contributory patent infringement, then any patent licenses + granted to You under this License for that Work shall terminate + as of the date such litigation is filed. + +4. Redistribution. You may reproduce and distribute copies of the + Work or Derivative Works thereof in any medium, with or without + modifications, and in Source or Object form, provided that You + meet the following conditions: + + (a) You must give any other recipients of the Work or + Derivative Works a copy of this License; and + + (b) You must cause any modified files to carry prominent notices + stating that You changed the files; and + + (c) You must retain, in the Source form of any Derivative Works + that You distribute, all copyright, patent, trademark, and + attribution notices from the Source form of the Work, + excluding those notices that do not pertain to any part of + the Derivative Works; and + + (d) If the Work includes a "NOTICE" text file as part of its + distribution, then any Derivative Works that You distribute must + include a readable copy of the attribution notices contained + within such NOTICE file, excluding those notices that do not + pertain to any part of the Derivative Works, in at least one + of the following places: within a NOTICE text file distributed + as part of the Derivative Works; within the Source form or + documentation, if provided along with the Derivative Works; or, + within a display generated by the Derivative Works, if and + wherever such third-party notices normally appear. The contents + of the NOTICE file are for informational purposes only and + do not modify the License. You may add Your own attribution + notices within Derivative Works that You distribute, alongside + or as an addendum to the NOTICE text from the Work, provided + that such additional attribution notices cannot be construed + as modifying the License. + + You may add Your own copyright statement to Your modifications and + may provide additional or different license terms and conditions + for use, reproduction, or distribution of Your modifications, or + for any such Derivative Works as a whole, provided Your use, + reproduction, and distribution of the Work otherwise complies with + the conditions stated in this License. + +5. Submission of Contributions. Unless You explicitly state otherwise, + any Contribution intentionally submitted for inclusion in the Work + by You to the Licensor shall be under the terms and conditions of + this License, without any additional terms or conditions. + Notwithstanding the above, nothing herein shall supersede or modify + the terms of any separate license agreement you may have executed + with Licensor regarding such Contributions. + +6. Trademarks. This License does not grant permission to use the trade + names, trademarks, service marks, or product names of the Licensor, + except as required for reasonable and customary use in describing the + origin of the Work and reproducing the content of the NOTICE file. + +7. Disclaimer of Warranty. Unless required by applicable law or + agreed to in writing, Licensor provides the Work (and each + Contributor provides its Contributions) on an "AS IS" BASIS, + WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or + implied, including, without limitation, any warranties or conditions + of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A + PARTICULAR PURPOSE. You are solely responsible for determining the + appropriateness of using or redistributing the Work and assume any + risks associated with Your exercise of permissions under this License. + +8. Limitation of Liability. In no event and under no legal theory, + whether in tort (including negligence), contract, or otherwise, + unless required by applicable law (such as deliberate and grossly + negligent acts) or agreed to in writing, shall any Contributor be + liable to You for damages, including any direct, indirect, special, + incidental, or consequential damages of any character arising as a + result of this License or out of the use or inability to use the + Work (including but not limited to damages for loss of goodwill, + work stoppage, computer failure or malfunction, or any and all + other commercial damages or losses), even if such Contributor + has been advised of the possibility of such damages. + +9. Accepting Warranty or Additional Liability. While redistributing + the Work or Derivative Works thereof, You may choose to offer, + and charge a fee for, acceptance of support, warranty, indemnity, + or other liability obligations and/or rights consistent with this + License. However, in accepting such obligations, You may act only + on Your own behalf and on Your sole responsibility, not on behalf + of any other Contributor, and only if You agree to indemnify, + defend, and hold each Contributor harmless for any liability + incurred by, or claims asserted against, such Contributor by reason + of your accepting any such warranty or additional liability. + +END OF TERMS AND CONDITIONS + +APPENDIX: How to apply the Apache License to your work. + + To apply the Apache License to your work, attach the following + boilerplate notice, with the fields enclosed by brackets "[]" + replaced with your own identifying information. (Don't include + the brackets!) The text should be enclosed in the appropriate + comment syntax for the file format. We also recommend that a + file or class name and description of purpose be included on the + same "printed page" as the copyright notice for easier + identification within third-party archives. + +Copyright [yyyy] [name of copyright owner] + +Licensed under the Apache License, Version 2.0 (the "License"); +you may not use this file except in compliance with the License. +You may obtain a copy of the License at + + http://www.apache.org/licenses/LICENSE-2.0 + +Unless required by applicable law or agreed to in writing, software +distributed under the License is distributed on an "AS IS" BASIS, +WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. +See the License for the specific language governing permissions and +limitations under the License. diff --git a/LICENSE b/LICENSE-MIT similarity index 100% rename from LICENSE rename to LICENSE-MIT diff --git a/README.md b/README.md index 1fe365f..786ee7d 100644 --- a/README.md +++ b/README.md @@ -5,163 +5,275 @@ [![crates.io](https://img.shields.io/crates/v/spectral-init)](https://crates.io/crates/spectral-init) [![docs.rs](https://img.shields.io/docsrs/spectral-init)](https://docs.rs/spectral-init) [![CI](https://github.com/TalonT-Org/spectral-init/actions/workflows/test.yml/badge.svg)](https://github.com/TalonT-Org/spectral-init/actions/workflows/test.yml) -[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE) +[![License: MIT OR Apache-2.0](https://img.shields.io/badge/license-MIT%20OR%20Apache--2.0-blue.svg)](#license) [![MSRV: 1.88](https://img.shields.io/badge/MSRV-1.88-blue)](https://blog.rust-lang.org/2025/06/26/Rust-1.88.0/) -[Docs](https://docs.rs/spectral-init) · [Crate](https://crates.io/crates/spectral-init) · [User Guide](docs/user-guide.md) +[API docs](https://docs.rs/spectral-init) · [User guide](docs/user-guide.md) · [Using it with umap-rs](docs/umap-rs-integration.md) · [Changelog](CHANGELOG.md) -## What is this? +## What it computes -Spectral initialization seeds UMAP's SGD optimization from Laplacian eigenvectors -instead of random coordinates, giving the optimizer a globally-aware starting point -that reflects the true topology of the data. This is the single factor responsible -for Python UMAP's embedding quality advantage over random-init implementations. +`spectral-init` computes the coordinates umap-learn starts from by default before it +optimizes an embedding: the spectral layout of the fuzzy k-nearest-neighbour graph. -This crate computes the symmetric normalized Laplacian +Given a symmetric sparse graph `W` with non-negative weights, it builds the symmetric +normalized Laplacian +```text +L = I − D^(−1/2) · W · D^(−1/2) D = diag(row sums of W) ``` -L = I - D^(-1/2) W D^(-1/2) -``` -of the fuzzy k-NN graph and returns its smallest non-trivial eigenvectors as -initial UMAP coordinates. It is designed to integrate with -[`umap-rs`](https://github.com/wilsonzlin/umap-rs) via its `graph()` accessor, and -is usable with any Rust UMAP implementation that provides a sparse adjacency matrix. +and returns, for every node, its entries in the eigenvectors of the `n_components` +smallest non-zero eigenvalues of `L`. The coordinates are scaled so that the largest +magnitude is 10, and Gaussian noise with standard deviation 10⁻⁴ is added. + +- **Input.** A `sprs` matrix view with `f32` weights and `u32` column indices, in CSR or + CSC storage. The matrix must be square and symmetric, with finite, non-negative + weights. Stored zeros are absent edges. Diagonal entries (self-loops) count towards + both degree and adjacency. +- **Output.** An `(n, n_components)` `ndarray::Array2` in standard (row-major) + layout. +- **Disconnected graphs.** Each connected component is embedded on its own, and the + components are then placed relative to one another, in the manner of umap-learn's + multi-component layout. +- **Semantics.** Those of `umap.spectral.spectral_layout` in umap-learn 0.5.x, which + umap-learn 0.6 keeps as its default layout. + +The crate computes initial coordinates and nothing else: it contains no nearest-neighbour +search, no graph construction and no optimizer, and it depends on no UMAP implementation. -## Quick Start +## Quick start ```sh cargo add spectral-init ``` ```rust -use spectral_init::{spectral_init, SpectralInitConfig}; -use sprs::{CsMatI, TriMatI}; - -fn main() -> Result<(), Box> { - // Build a small synthetic graph (replace with your real UMAP graph) - let n = 10usize; - let mut tri: TriMatI = TriMatI::new((n, n)); +use spectral_init::sprs::{CsMatI, TriMatI}; +use spectral_init::{SpectralError, SpectralInitConfig, spectral_init}; + +fn main() -> Result<(), SpectralError> { + // A ring of 10 nodes: every node is joined to its two neighbours. + // Replace this with the graph of your UMAP implementation. + let n = 10; + let mut triplets: TriMatI = TriMatI::new((n, n)); for i in 0..n { let next = (i + 1) % n; - tri.add_triplet(i, next, 1.0_f32); - tri.add_triplet(next, i, 1.0_f32); + triplets.add_triplet(i, next, 1.0); + triplets.add_triplet(next, i, 1.0); } - let graph: CsMatI = tri.to_csr(); + let graph: CsMatI = triplets.to_csr(); + + // Two embedding dimensions, seed 42. + let config = SpectralInitConfig::new(2).with_seed(42); + let coords = spectral_init(graph.view(), None, &config)?; - let embedding = spectral_init(&graph, 2, 42, None, SpectralInitConfig::default())?; - assert_eq!(embedding.shape(), &[n, 2]); + assert_eq!(coords.dim(), (n, 2)); Ok(()) } ``` -See [`examples/basic.rs`](examples/basic.rs) for the full runnable version. - -## Integration with umap-rs +`sprs` and `ndarray` are re-exported, so the snippet needs no other dependency. The +[`examples/`](examples/) directory has runnable programs: `basic`, `from_adjacency_list`, +`compute_modes` and `umap_rs`. -```rust -use spectral_init::{spectral_init, SpectralInitConfig}; - -let umap = umap_rs::Umap::fit(&data, umap_rs::UmapConfig::default())?; -let graph = umap.graph(); // &CsMatI -let init = spectral_init(graph, 2, 42, None, SpectralInitConfig::default())?; -// Pass `init` to your SGD optimizer as the initial embedding -``` +## Using it with a UMAP implementation -## Standalone Usage — Building the Input Graph +There are two routes. -If you are not using `umap-rs`, construct a `CsMatI` via `sprs::TriMatI`. -The matrix must be symmetric and non-negative. See -[`examples/from_adjacency_list.rs`](examples/from_adjacency_list.rs) for a complete example. +**Standalone.** Compute the coordinates with this crate and pass them to any UMAP +implementation that accepts an initial embedding. With +[`umap-rs`](https://crates.io/crates/umap-rs), the graph comes from `learn_manifold`: ```rust -let mut tri: TriMatI = TriMatI::new((n, n)); -for &(i, j, w) in &edges { - tri.add_triplet(i, j, w); - tri.add_triplet(j, i, w); // symmetrize +use spectral_init::ndarray::{Array2, ArrayView2}; +use spectral_init::{SpectralError, SpectralInitConfig, spectral_init}; +use umap_rs::{Umap, UmapConfig}; + +/// Initial coordinates for a `umap-rs` fit. +fn spectral_coordinates( + data: ArrayView2<'_, f32>, + knn_indices: ArrayView2<'_, u32>, + knn_dists: ArrayView2<'_, f32>, + config: &UmapConfig, + seed: u64, +) -> Result, SpectralError> { + let manifold = Umap::new(config.clone()).learn_manifold(data, knn_indices, knn_dists); + let init_config = SpectralInitConfig::new(config.n_components).with_seed(seed); + spectral_init(manifold.graph().view(), Some(data), &init_config) } -let graph: CsMatI = tri.to_csr(); ``` -## ComputeMode +The [integration guide](docs/umap-rs-integration.md) continues from here to the +optimizer and lists what to know about `umap-rs`. Implementations that keep their graph +as raw CSR arrays can lend them to `spectral_init` without copying; the guide shows how. -| Mode | Description | -|------|-------------| -| `PythonCompat` (default) | Matches Python UMAP's degree accumulation and solver path exactly; use when reproducibility against Python output is required. | -| `RustNative` | Enables AVX2+FMA SIMD degree accumulation on x86\_64; silently falls back on other platforms. Embeddings are subspace-equivalent to `PythonCompat`. | +**Built in.** A fork of `umap-rs` that builds spectral initialization in is at +. + +## Compute modes + +| Mode | Behaviour | +|------|-----------| +| `ComputeMode::PythonCompat` (default) | Follows umap-learn's arithmetic where it affects the result: degrees are accumulated in single precision in SciPy's order, and the iterative solvers use a scalar sparse matrix-vector product. The reference tests run in this mode. | +| `ComputeMode::RustNative` | Sums degrees in double precision on every target. On x86_64 CPUs with AVX2 and FMA, detected at run time, the iterative solvers use a SIMD sparse matrix-vector product. The result spans the same subspace as `PythonCompat` and differs from it by rounding. | ```rust -use spectral_init::{spectral_init, ComputeMode, SpectralInitConfig}; +use spectral_init::{ComputeMode, SpectralInitConfig}; -let mut config = SpectralInitConfig::default(); -config.compute_mode = ComputeMode::RustNative; -let embedding = spectral_init(&graph, 2, 42, None, config)?; +let config = SpectralInitConfig::new(2) + .with_seed(42) + .with_compute_mode(ComputeMode::RustNative); +assert_eq!(config.compute_mode(), ComputeMode::RustNative); ``` -See [`examples/compute_modes.rs`](examples/compute_modes.rs) for a side-by-side comparison. - -## Feature Flags +## Solvers and memory + +The eigenvectors come from a chain of six solvers. Each result is checked by its residual +`‖L·v − λ·v‖ / ‖v‖`, and a result that misses the threshold of its solver is discarded in +favour of the next solver. + +| Level | Solver | Used when | +|-------|--------|-----------| +| 0 | Dense eigendecomposition | fewer than 2000 nodes | +| 1 | LOBPCG | 2000 nodes or more, or level 0 was not accepted | +| 2 | Shift-and-invert LOBPCG (sparse Cholesky) | level 1 was not accepted | +| 3 | LOBPCG with a small diagonal shift | level 2 was not accepted | +| 4 | Randomized SVD | level 3 was not accepted | +| 5 | Dense eigendecomposition | level 4 was not accepted | + +There is no random fallback. If the last level fails its check, or needs a dense matrix +larger than the dense memory budget, `spectral_init` returns an error. + +The **dense memory budget** (`SpectralInitConfig::with_dense_memory_budget`, 4 GiB by +default) caps every dense matrix a solver allocates. A solver that would exceed it is +skipped. The budget bounds each dense matrix individually, not the peak memory of the +process: the dense levels hold a few matrices of that size at once. An allocation within +the budget that the system cannot satisfy aborts the process, as any Rust allocation +does. + +## Errors + +`spectral_init` does not panic on any input. Every failure is a `SpectralError`: + +| Variant | Meaning | +|---------|---------| +| `InvalidParameter { name, reason }` | `n_components` is 0. | +| `NotSquare { rows, cols }` | The graph matrix is not square. | +| `TooFewNodes { n, n_components }` | The graph does not have more nodes than `n_components`; this covers the empty graph. | +| `NonFiniteWeight { row, col }` | A weight is NaN or infinite. | +| `NegativeWeight { row, col }` | A weight is negative. | +| `NotSymmetric { row, col }` | An entry has no matching mirror entry. Relative differences up to 10⁻⁶ are tolerated. | +| `DegreeOverflow { node }` | The summed weights of a node overflow `f32`. | +| `DataShapeMismatch { expected_rows, actual_rows }` | `data` does not have one row per node. | +| `NonFiniteData { row, col }` | `data` contains NaN or an infinity. | +| `DataRequired { connected_components, n_components }` | The graph has more than `2 · n_components` connected components and `data` is `None`. | +| `DenseBudgetExceeded { required_bytes, budget_bytes }` | The iterative solvers were not accepted and the dense one needs more than the dense memory budget, or the graph has so many components that their affinity matrix exceeds it. | +| `ConvergenceFailure { n }` | No solver produced eigenvectors of acceptable quality. | +| `DegenerateEmbedding` | All computed coordinates are zero. | + +The first nine are found by validating the input before any computation, in the order +listed. The enum and its struct variants are `#[non_exhaustive]`: match them with `..` +and a wildcard arm. + +umap-learn falls back to a random layout when its spectral layout fails. This crate +reports the failure, and the caller decides what to substitute: -The crate has no public Cargo features. The `trustworthiness` and `tw_profiler` -embedding-quality tools are a separate workspace package, [`trustworthiness/`](trustworthiness/) -(`cargo build --release -p trustworthiness --features cli`). +```rust +use spectral_init::ndarray::Array2; +use spectral_init::sprs::CsMatViewI; +use spectral_init::{SpectralError, SpectralInitConfig, spectral_init}; + +/// Spectral coordinates, or the caller's own layout when the solvers give up. +fn initial_coordinates( + graph: CsMatViewI<'_, f32, u32, usize>, + config: &SpectralInitConfig, + fallback: impl FnOnce() -> Array2, +) -> Result, SpectralError> { + match spectral_init(graph, None, config) { + Ok(coords) => Ok(coords), + Err( + SpectralError::ConvergenceFailure { .. } + | SpectralError::DenseBudgetExceeded { .. } + | SpectralError::DegenerateEmbedding, + ) => Ok(fallback()), + // Anything else is a problem with the input: report it. + Err(other) => Err(other), + } +} +``` -## Performance +## Platforms -Benchmarks run on a 2000-node ring graph (4 neighbours per node): +- Pure Rust: no BLAS, LAPACK or C toolchain is needed. +- Every target has a scalar code path. On x86_64 the AVX2+FMA kernel of + `ComputeMode::RustNative` is selected by run-time detection; no compiler flags are + involved. +- CI runs the test suite on Linux (x86_64 and aarch64), macOS and Windows. +- Minimum supported Rust version: 1.88. -| Stage | Time | -|-------|------| -| Full pipeline (`spectral_init`) | ~223 ms | -| Laplacian construction | ~228 µs | -| LOBPCG solve (k=3) | ~306 ms | -| Randomized SVD (k=3) | ~286 ms | +## Reproducibility -> These are pre-optimization baselines on a regular ring graph. Real k-NN graphs -> have non-uniform degree distributions; expect 2–4× slower SpMV in practice. -> See [`eval/benches/README.md`](eval/benches/README.md) for methodology and inputs. +For a fixed `Cargo.lock`, target, CPU feature set and thread configuration, the output is +a deterministic function of the graph, the data and the configuration. Random numbers +come from the ChaCha12 generator (`rand_chacha::ChaCha12Rng`), seeded with +`SpectralInitConfig::with_seed`. -## Correctness +Results are not promised to agree bit for bit across targets, CPU feature sets or thread +counts; they agree to rounding. Measured on x86_64 with faer 0.24.4, one thread against +four changed no coordinate for a 500-node graph and changed coordinates by at most +1.2 × 10⁻¹⁰ for a 1500-node graph, on coordinates of magnitude up to 10. To pin the +thread configuration, call `faer::set_global_parallelism` before `spectral_init` or set +`RAYON_NUM_THREADS`. -Outputs are validated against Python UMAP reference fixtures stored as `.npz` files -in `tests/fixtures/`. Verification uses: +## Evidence -- **Residual checks**: `||L·v - λ·v|| / ||v|| < 0.005` for each eigenpair -- **Subspace comparison**: Gram determinant of `V_rust^T V_python` for near-degenerate eigenvalues -- **Sign-invariant matching**: eigenvectors are compared up to global sign flip +Every stage of the pipeline is tested against values recorded from umap-learn 0.5.11 on +nine reference datasets. On the connected reference graphs the computed eigenvectors span +the same subspace as umap-learn's (Gram determinant at least 0.99999998) with eigenpair +residuals of at most 9.1 × 10⁻⁶. On the disconnected ones both implementations find the +same components. The trustworthiness (k = 15) of the raw initial coordinates is between +0.83 and 0.99, against 0.50 to 0.55 for a uniform random initialization. The tables, the +method and the versions are in the +[integration guide](docs/umap-rs-integration.md#evidence). -See the [implementation report](docs/umap-spectral-initialization-rust-implementation-report.md) -for the full algorithmic design. +These figures describe the initialization. They are not a comparison of final UMAP +embeddings. -## Requirements +## Stability -- **MSRV:** Rust 1.88 -- **No LAPACK/BLAS dependency** — pure Rust via `linfa-linalg` (LOBPCG) and `faer` (dense EVD) -- **AVX2+FMA** is optional and only used when `ComputeMode::RustNative` is selected on x86\_64 -- Tested on Linux x86\_64; should work on any platform supported by the above crates +This is a 0.x release, and the API may change in 0.2. -## Testing +`sprs` 0.11 and `ndarray` 0.17 appear in the signature of `spectral_init` and are +re-exported; moving to a semver-incompatible release of either is a breaking release of +this crate. The crate has no public Cargo features. -Install [`cargo-nextest`](https://nexte.st/) if not already present: +## Repository -```sh -cargo install cargo-nextest -``` +The repository is a Cargo workspace. The root package is the published crate. +[`trustworthiness/`](trustworthiness/) is a standalone embedding-quality tool, +[`eval/`](eval/) is the research harness, and `research/` holds experiment reports; none +of these is part of the published crate. [CONTRIBUTING](.github/CONTRIBUTING.md) explains +how to build and test. -Run the whole workspace (the reference fixtures are committed; no generation step is needed): +The design of the algorithm is described in the +[implementation report](https://github.com/TalonT-Org/spectral-init/blob/research-baseline-pre-0.1/docs/umap-spectral-initialization-rust-implementation-report.md). -```sh -cargo nextest run --workspace --all-features -``` +## Acknowledgements -Run with CI profile: +The algorithm and its reference behaviour are those of +[umap-learn](https://github.com/lmcinnes/umap) by Leland McInnes and contributors +(McInnes, Healy and Melville, *UMAP: Uniform Manifold Approximation and Projection for +Dimension Reduction*, [arXiv:1802.03426](https://arxiv.org/abs/1802.03426)). The sign +convention for eigenvectors and the Laplacian of the component layout follow +[scikit-learn](https://scikit-learn.org/). The degree accumulation follows +[SciPy](https://scipy.org/)'s sparse matrix-vector product, and the reference +eigenvectors in the test fixtures were computed with SciPy. -```sh -cargo nextest run --workspace --all-features --profile ci -``` +## License -`cargo test` on its own runs only the published crate's default-feature tests. +Licensed under either of -## License +- Apache License, Version 2.0 ([LICENSE-APACHE](LICENSE-APACHE)) +- MIT license ([LICENSE-MIT](LICENSE-MIT)) -MIT — see [LICENSE](LICENSE). +at your option. diff --git a/docs/katex-header.html b/docs/katex-header.html index b5c38a8..7d86077 100644 --- a/docs/katex-header.html +++ b/docs/katex-header.html @@ -1,5 +1,5 @@ - - + +