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/.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/.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/.claude/skills/plan-experiment/SKILL.md b/.claude/skills/plan-experiment/SKILL.md index 84b0930..932f473 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`, `eval/src/` 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..d310f49 100644 --- a/.claude/skills/run-experiment/SKILL.md +++ b/.claude/skills/run-experiment/SKILL.md @@ -125,14 +125,15 @@ 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, so a relative path would resolve under `eval/`. The command writes two files +to `$WORKTREE_PATH/.autoskillit/temp/run-experiment/`: - `accuracy_metrics.json` — machine-readable metrics with per-metric pass/fail status - `accuracy_metrics.md` — human-readable summary table @@ -140,7 +141,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 +161,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..f1d072d 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`, +`eval/src/` 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/deny.toml b/.config/deny.toml new file mode 100644 index 0000000..e87b6ce --- /dev/null +++ b/.config/deny.toml @@ -0,0 +1,63 @@ +# cargo-deny configuration for the workspace. +# +# Run with: cargo deny --workspace --config .config/deny.toml check + +[graph] +all-features = true + +[advisories] +ignore = [ + # zip 6.0.0 reaches the workspace only through ndarray-npy, whose latest release + # (0.10.0) requires it. ndarray-npy is a dev-dependency of the library and a + # dependency of the unpublished `eval` and `trustworthiness` packages; it is not in + # the published crate's dependency tree (the deps workflow fails if it enters it). + # All four advisories concern + # `ZipArchive::extract` and the stream extraction API, which write archive entries + # to the file system. ndarray-npy only reads `.npy` members of `.npz` archives into + # memory, and the archives read here are this repository's own fixtures. + { id = "RUSTSEC-2026-0367", reason = "zip via ndarray-npy (dev/eval only): extraction to disk is not used" }, + { id = "RUSTSEC-2026-0368", reason = "zip via ndarray-npy (dev/eval only): extraction to disk is not used" }, + { id = "RUSTSEC-2026-0369", reason = "zip via ndarray-npy (dev/eval only): extraction to disk is not used" }, + { id = "RUSTSEC-2026-0429", reason = "zip via ndarray-npy (dev/eval only): extraction to disk is not used" }, + # `paste` is unmaintained; it has no known vulnerability. It is a procedural macro + # used at build time by gemm, which faer 0.24 depends on. + { id = "RUSTSEC-2024-0436", reason = "paste (unmaintained) is a build-time macro of faer's gemm dependency" }, +] + +[licenses] +# Dev-dependencies are checked too: they decide what the repository may contain. +include-dev = true +allow = [ + "MIT", + "Apache-2.0", + "Apache-2.0 WITH LLVM-exception", + "BSD-2-Clause", + # umap-rs, a dev-dependency of the library. + "BSD-3-Clause", + "Unicode-3.0", + "Zlib", +] +confidence-threshold = 0.8 + +[bans] +multiple-versions = "deny" +wildcards = "deny" +# The unpublished `eval` package depends on its sibling packages by path. +allow-wildcard-paths = true +skip-tree = [ + # linfa-linalg 0.2 is built on ndarray 0.16, rand 0.8 and thiserror 1, while the + # rest of the graph uses ndarray 0.17, rand 0.9 and thiserror 2. The library + # isolates it in src/solvers/nd16_bridge.rs. + { crate = "linfa-linalg@0.2", reason = "pins ndarray 0.16, rand 0.8 and thiserror 1" }, + # Support crates of faer 0.24 that lag behind faer's own dependencies. + { crate = "nano-gemm@0.2", reason = "faer support crate on equator 0.2" }, + { crate = "spindle@0.2", reason = "faer support crate on equator 0.4 and, through atomic-wait, windows-sys 0.42" }, + { crate = "interpol@0.2", reason = "build-time macro of faer's private-gemm-x86, on syn 1" }, + # The `alga` feature of sprs, which the published crate switches off; the + # unpublished `eval` package builds sprs with its default features. + { crate = "alga@0.9", reason = "optional sprs feature on approx 0.3 and num-complex 0.2" }, +] + +[sources] +unknown-registry = "deny" +unknown-git = "deny" diff --git a/.config/nextest.toml b/.config/nextest.toml index c2c1fd8..07fa520 100644 --- a/.config/nextest.toml +++ b/.config/nextest.toml @@ -10,7 +10,7 @@ status-level = "fail" final-status-level = "fail" success-output = "never" failure-output = "immediate-final" -default-filter = 'not (test(comp_d_rsvd_blobs_connected_2000) or test(test_level_3_rsvd_valid_on_large_path) or test(direction_a_2il_vs_direct_l) or test(direction_b_sweep) or test(direction_c_subspace))' +default-filter = 'not (test(comp_d_rsvd_blobs_connected_2000) or test(test_level_4_rsvd_valid_on_large_path) or test(direction_a_2il_vs_direct_l) or test(direction_b_sweep) or test(direction_c_subspace))' [profile.ci.junit] path = "junit.xml" @@ -22,12 +22,7 @@ slow-timeout = { period = "300s" } fail-fast = false 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) +default-filter = 'test(comp_d_rsvd_blobs_connected_2000) or test(test_level_4_rsvd_valid_on_large_path)' [profile.quiet] retries = 0 diff --git a/.github/CONTRIBUTING.md b/.github/CONTRIBUTING.md new file mode 100644 index 0000000..6d9b0e0 --- /dev/null +++ b/.github/CONTRIBUTING.md @@ -0,0 +1,114 @@ +# 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 + +# Advisories, licenses and duplicate versions (cargo-deny); unused dependencies +# (cargo-machete). +cargo deny --workspace --config .config/deny.toml check +cargo machete +``` + +`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/ISSUE_TEMPLATE/bug_report.yml b/.github/ISSUE_TEMPLATE/bug_report.yml index 5683bab..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 @@ -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/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/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/dependabot.yml b/.github/dependabot.yml new file mode 100644 index 0000000..97cb4e8 --- /dev/null +++ b/.github/dependabot.yml @@ -0,0 +1,11 @@ +version: 2 +updates: + - package-ecosystem: cargo + directory: / + schedule: + interval: weekly + + - package-ecosystem: github-actions + directory: / + schedule: + interval: weekly diff --git a/.github/package-allowlist.txt b/.github/package-allowlist.txt new file mode 100644 index 0000000..88e87b6 --- /dev/null +++ b/.github/package-allowlist.txt @@ -0,0 +1,32 @@ +.cargo_vcs_info.json +CHANGELOG.md +Cargo.lock +Cargo.toml +Cargo.toml.orig +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 +examples/umap_rs.rs +src/components.rs +src/config.rs +src/error.rs +src/laplacian.rs +src/lib.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/nd16_bridge.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-package.sh b/.github/scripts/check-package.sh new file mode 100755 index 0000000..c261501 --- /dev/null +++ b/.github/scripts/check-package.sh @@ -0,0 +1,62 @@ +#!/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 and doc tests and runs every example, 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 and runs its examples" +# 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 + cargo test --locked --doc + # `cargo test --examples` only builds examples; running them executes their checks. + for example in examples/*.rs; do + cargo run --locked --example "$(basename "$example" .rs)" + done +) + +echo "==> publish dry run" +cargo publish -p "$package" --dry-run --locked "$@" + +echo "package gate passed" diff --git a/.github/scripts/check-purity.sh b/.github/scripts/check-purity.sh new file mode 100755 index 0000000..c7c4212 --- /dev/null +++ b/.github/scripts/check-purity.sh @@ -0,0 +1,80 @@ +#!/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 file under the given paths whose name +# matches the glob in the variable `include` (default: Rust sources, '*.rs'). Files named +# in the space-separated variable `allowed` are exempt. Both variables are set per call. +forbid() { + local description="$1" pattern="$2" + shift 2 + local path hits file grep_status=0 + for path in "$@" ${allowed:-}; do + if [ ! -e "$path" ]; then + echo "error: ${path} does not exist" >&2 + exit 2 + fi + done + # grep exits 1 for "no match" and 2 for an error (bad pattern, unreadable file), + # which must not pass as "no match". + hits="$(grep -rnHE --include="${include:-*.rs}" -e "$pattern" "$@")" || grep_status=$? + if [ "$grep_status" -gt 1 ]; then + echo "error: grep failed with status ${grep_status} while checking: ${description}" >&2 + exit 2 + fi + 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 + fi +} + +forbid "the library must not print or read the environment (src/)" \ + 'print(ln)?!|dbg!|env::(var|args)|io::(stdout|stderr)|SPECTRAL_' \ + src + +forbid "random numbers come from the named generator ChaCha12Rng, not StdRng (src/)" \ + 'StdRng' \ + src + +allowed="src/solvers/nd16_bridge.rs" \ +forbid "the library reaches ndarray 0.16 and linfa-linalg only through src/solvers/nd16_bridge.rs (src/)" \ + 'ndarray16|linfa_linalg' \ + 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 + +include='Cargo.toml' \ +forbid "no package declares a 'testing' feature" \ + '^testing[[:space:]]*=' \ + Cargo.toml eval trustworthiness + +include='Cargo.toml' \ +forbid "only the trustworthiness package declares the 'cli' and 'profiling' features" \ + '^(cli|profiling)[[:space:]]*=' \ + Cargo.toml eval + +if [ "$status" -eq 0 ]; then + echo "purity gate passed" +fi +exit "$status" diff --git a/.github/scripts/check-sri.sh b/.github/scripts/check-sri.sh new file mode 100755 index 0000000..bafd813 --- /dev/null +++ b/.github/scripts/check-sri.sh @@ -0,0 +1,59 @@ +#!/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. A resource loaded without an `integrity` attribute, or +# not over https, fails the gate too: rustdoc puts the header into every docs.rs page. +# +# 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 + if ! [[ "$line" =~ integrity=\"([^\"]+)\" ]]; then + if [[ "$line" =~ (href|src)=\" ]]; then + echo "error: resource without an integrity attribute: ${line}" >&2 + status=1 + fi + continue + fi + 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]}" + if [[ "$url" != https://* ]]; then + echo "error: resource not loaded over https: ${url}" >&2 + status=1 + continue + fi + + 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: no resource in ${header} was verified against an integrity attribute" >&2 + exit 2 +fi +if [ "$status" -eq 0 ]; then + echo "SRI gate passed (${checked} resources)" +fi +exit "$status" diff --git a/.github/workflows/api.yml b/.github/workflows/api.yml new file mode 100644 index 0000000..433d288 --- /dev/null +++ b/.github/workflows/api.yml @@ -0,0 +1,41 @@ +name: Public API + +on: + push: + branches: [main] + pull_request: + branches: ["**"] + merge_group: + +permissions: + contents: read + +concurrency: + group: ${{ github.workflow }}-${{ github.ref }} + cancel-in-progress: ${{ github.event_name == 'pull_request' }} + +jobs: + public-api: + name: public API snapshot + runs-on: ubuntu-latest + timeout-minutes: 30 + + steps: + - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1 + + # The listing depends on the nightly toolchain and on the cargo-public-api + # version, so both are pinned. cargo-public-api uses the active toolchain when it + # is a nightly one. + - name: Install Rust nightly + uses: dtolnay/rust-toolchain@683b588c487a69d01f6c6ddf40f036ff682cc2c8 # master + with: + toolchain: nightly-2026-08-10 + + - name: Cache Rust build artifacts + uses: Swatinem/rust-cache@d1527c8f67ef9af357290475d4af4b0fab8f12e0 # v2.9.3 + + - name: Install cargo-public-api + run: cargo install --locked cargo-public-api --version 0.52.0 + + - name: Compare the public API with .github/api-snapshot.txt + run: .github/scripts/check-api.sh diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml new file mode 100644 index 0000000..c1fca29 --- /dev/null +++ b/.github/workflows/ci.yml @@ -0,0 +1,252 @@ +name: CI + +on: + push: + branches: ["**"] + pull_request: + branches: ["**"] + merge_group: + schedule: + # Mondays at 03:00 UTC; the scheduled run also runs the slow tests. + - cron: "0 3 * * 1" + +permissions: + contents: read + +concurrency: + group: ${{ github.workflow }}-${{ github.ref }} + cancel-in-progress: ${{ github.event_name == 'pull_request' }} + +jobs: + test: + name: test (${{ matrix.label }}) + runs-on: ${{ matrix.os }} + timeout-minutes: 45 + permissions: + contents: read + checks: write + pull-requests: write + 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@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1 + + - name: Install Rust stable + uses: dtolnay/rust-toolchain@683b588c487a69d01f6c6ddf40f036ff682cc2c8 # master + with: + 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@d1527c8f67ef9af357290475d4af4b0fab8f12e0 # v2.9.3 + with: + key: ${{ matrix.label }} + + - name: Install cargo-nextest + uses: taiki-e/install-action@cfdb7ed4ccc7c7dce37759eae89dc5674b469b39 # v2.90.3 + with: + tool: cargo-nextest + + - name: Run tests (CI profile) + run: cargo nextest run --locked --workspace --all-features --profile ci + + - name: Upload JUnit XML + uses: actions/upload-artifact@cf430e030ddbb5b0abf93d22962f4752f3646cd9 # v7.0.2 + if: always() + with: + name: junit-results-${{ matrix.label }} + path: target/nextest/ci/junit.xml + retention-days: 30 + + - name: Report test results + uses: mikepenz/action-junit-report@a16be3a69023e9bd7e748ede768b3282ea7b30ce # v6.7.1 + 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 }} + + slow: + name: slow tests + if: github.event_name == 'schedule' + runs-on: ubuntu-latest + timeout-minutes: 90 + + steps: + - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1 + + - name: Install Rust stable + uses: dtolnay/rust-toolchain@683b588c487a69d01f6c6ddf40f036ff682cc2c8 # master + with: + toolchain: stable + + - name: Cache Rust build artifacts + uses: Swatinem/rust-cache@d1527c8f67ef9af357290475d4af4b0fab8f12e0 # v2.9.3 + + - name: Install cargo-nextest + uses: taiki-e/install-action@cfdb7ed4ccc7c7dce37759eae89dc5674b469b39 # v2.90.3 + with: + tool: cargo-nextest + + - name: Run slow tests + run: cargo nextest run --locked --workspace --all-features --profile slow + + # The required check: one result for the whole test matrix. + nextest: + name: cargo nextest + runs-on: ubuntu-latest + needs: [test, slow] + if: always() + timeout-minutes: 5 + + steps: + - name: Every test job passed + env: + TEST_RESULT: ${{ needs.test.result }} + SLOW_RESULT: ${{ needs.slow.result }} + run: | + echo "test matrix: ${TEST_RESULT}; slow tests: ${SLOW_RESULT}" + if [ "$TEST_RESULT" != "success" ]; then + exit 1 + fi + # The slow tests run on the schedule only; a skipped job counts as passed. + if [ "$SLOW_RESULT" != "success" ] && [ "$SLOW_RESULT" != "skipped" ]; then + exit 1 + fi + + lint: + name: fmt + clippy + runs-on: ubuntu-latest + timeout-minutes: 30 + + steps: + - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1 + + - name: Install Rust stable + uses: dtolnay/rust-toolchain@683b588c487a69d01f6c6ddf40f036ff682cc2c8 # master + with: + toolchain: stable + components: rustfmt, clippy + + - name: Cache Rust build artifacts + uses: Swatinem/rust-cache@d1527c8f67ef9af357290475d4af4b0fab8f12e0 # v2.9.3 + + - name: Check formatting + run: cargo fmt --all --check + + - 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 + runs-on: ubuntu-latest + timeout-minutes: 30 + + steps: + - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1 + + - name: Install Rust stable + uses: dtolnay/rust-toolchain@683b588c487a69d01f6c6ddf40f036ff682cc2c8 # master + with: + toolchain: stable + + - name: Cache Rust build artifacts + uses: Swatinem/rust-cache@d1527c8f67ef9af357290475d4af4b0fab8f12e0 # v2.9.3 + + - name: Build rustdoc + run: cargo doc --locked --no-deps -p spectral-init + env: + RUSTDOCFLAGS: "-D warnings" + + - name: Run doctests + run: cargo test --locked --workspace --doc + + msrv: + name: msrv + runs-on: ubuntu-latest + timeout-minutes: 30 + + steps: + - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1 + + - 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@683b588c487a69d01f6c6ddf40f036ff682cc2c8 # master + with: + toolchain: ${{ steps.msrv.outputs.version }} + + - name: Cache Rust build artifacts + uses: Swatinem/rust-cache@d1527c8f67ef9af357290475d4af4b0fab8f12e0 # v2.9.3 + + - name: Check the library on the MSRV toolchain + run: cargo check --locked --lib -p spectral-init + + package: + name: package + runs-on: ubuntu-latest + timeout-minutes: 30 + + steps: + - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1 + + - name: Install Rust stable + uses: dtolnay/rust-toolchain@683b588c487a69d01f6c6ddf40f036ff682cc2c8 # master + with: + toolchain: stable + + - name: Cache Rust build artifacts + uses: Swatinem/rust-cache@d1527c8f67ef9af357290475d4af4b0fab8f12e0 # v2.9.3 + + - name: Package gate + run: .github/scripts/check-package.sh + + miri: + name: miri + runs-on: ubuntu-latest + timeout-minutes: 30 + + steps: + - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1 + + - name: Install Rust nightly with Miri + uses: dtolnay/rust-toolchain@683b588c487a69d01f6c6ddf40f036ff682cc2c8 # master + with: + toolchain: nightly-2026-08-10 + components: miri, rust-src + + - name: Cache Rust build artifacts + uses: Swatinem/rust-cache@d1527c8f67ef9af357290475d4af4b0fab8f12e0 # v2.9.3 + + - 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" diff --git a/.github/workflows/deps.yml b/.github/workflows/deps.yml new file mode 100644 index 0000000..cd5353d --- /dev/null +++ b/.github/workflows/deps.yml @@ -0,0 +1,71 @@ +name: Dependencies + +on: + push: + branches: [main] + pull_request: + branches: ["**"] + merge_group: + schedule: + # Mondays at 04:00 UTC: advisories appear without any change to the repository. + - cron: "0 4 * * 1" + +permissions: + contents: read + +concurrency: + group: ${{ github.workflow }}-${{ github.ref }} + cancel-in-progress: ${{ github.event_name == 'pull_request' }} + +jobs: + deny: + name: cargo deny + runs-on: ubuntu-latest + timeout-minutes: 15 + + steps: + - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1 + + - name: Install Rust stable + uses: dtolnay/rust-toolchain@683b588c487a69d01f6c6ddf40f036ff682cc2c8 # master + with: + toolchain: stable + + - name: Install cargo-deny + uses: taiki-e/install-action@cfdb7ed4ccc7c7dce37759eae89dc5674b469b39 # v2.90.3 + with: + tool: cargo-deny@0.20.2 + + - name: Advisories, licenses, bans and sources + run: cargo deny --workspace --config .config/deny.toml check + + # The zip advisory ignores in .config/deny.toml hold only while zip stays out of + # the published crate's dependency tree. + - name: The published crate does not depend on zip + run: | + tree="$(cargo tree --locked -p spectral-init --edges normal,build --prefix none --all-features)" + if grep -q '^zip ' <<< "$tree"; then + echo "::error::zip is in the published crate's dependency tree; the zip advisory ignores in .config/deny.toml assume it is not" + exit 1 + fi + + machete: + name: cargo machete + runs-on: ubuntu-latest + timeout-minutes: 15 + + steps: + - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1 + + - name: Install Rust stable + uses: dtolnay/rust-toolchain@683b588c487a69d01f6c6ddf40f036ff682cc2c8 # master + with: + toolchain: stable + + - name: Install cargo-machete + uses: taiki-e/install-action@cfdb7ed4ccc7c7dce37759eae89dc5674b469b39 # v2.90.3 + with: + tool: cargo-machete@0.9.2 + + - name: Unused dependencies + run: cargo machete diff --git a/.github/workflows/docs.yml b/.github/workflows/docs.yml new file mode 100644 index 0000000..6bddc18 --- /dev/null +++ b/.github/workflows/docs.yml @@ -0,0 +1,51 @@ +name: Docs + +on: + push: + branches: [main] + pull_request: + branches: ["**"] + merge_group: + +permissions: + contents: read + +concurrency: + group: ${{ github.workflow }}-${{ github.ref }} + cancel-in-progress: ${{ github.event_name == 'pull_request' }} + +jobs: + docs-rs: + name: docs.rs build + runs-on: ubuntu-latest + timeout-minutes: 30 + + steps: + - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1 + + # docs.rs builds with a nightly toolchain and the settings under + # [package.metadata.docs.rs]; cargo-docs-rs reproduces that build. + - name: Install Rust nightly + uses: dtolnay/rust-toolchain@683b588c487a69d01f6c6ddf40f036ff682cc2c8 # master + with: + toolchain: nightly-2026-08-10 + + - name: Cache Rust build artifacts + uses: Swatinem/rust-cache@d1527c8f67ef9af357290475d4af4b0fab8f12e0 # v2.9.3 + + - name: Install cargo-docs-rs + run: cargo install --locked cargo-docs-rs --version 1.0.4 + + - name: Build the documentation as docs.rs does + run: cargo docs-rs -p spectral-init + + sri: + name: KaTeX integrity hashes + runs-on: ubuntu-latest + timeout-minutes: 5 + + steps: + - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1 + + - name: Compare the hashes in docs/katex-header.html with the files + run: .github/scripts/check-sri.sh diff --git a/.github/workflows/slow-tests.yml b/.github/workflows/slow-tests.yml deleted file mode 100644 index 6e1ebf4..0000000 --- a/.github/workflows/slow-tests.yml +++ /dev/null @@ -1,33 +0,0 @@ -name: Slow Tests - -on: - workflow_dispatch: - schedule: - # Run weekly on Monday at 03:00 UTC - - cron: '0 3 * * 1' - -permissions: - checks: write - contents: read - -jobs: - slow-tests: - name: cargo nextest (slow profile) - 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: Install cargo-nextest - uses: taiki-e/install-action@v2 - with: - tool: cargo-nextest - - - name: Run slow tests - run: cargo nextest run --profile slow --features testing diff --git a/.github/workflows/test.yml b/.github/workflows/test.yml deleted file mode 100644 index 13bd0c9..0000000 --- a/.github/workflows/test.yml +++ /dev/null @@ -1,77 +0,0 @@ -name: Tests - -on: - push: - branches: ["**"] - pull_request: - branches: ["**"] - merge_group: - -permissions: - checks: write - contents: read - pull-requests: write - -jobs: - test: - name: cargo nextest - runs-on: ubuntu-latest - - env: - RUSTFLAGS: "-C target-cpu=x86-64-v3" - - 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: Install cargo-nextest - uses: taiki-e/install-action@v2 - with: - tool: cargo-nextest - - - name: Run tests (CI profile) - run: cargo nextest run --profile ci --features testing - - - name: Upload JUnit XML - uses: actions/upload-artifact@v4 - if: always() - with: - name: junit-results - path: target/nextest/ci/junit.xml - retention-days: 30 - - - name: Report test results - uses: mikepenz/action-junit-report@v6 - if: always() - with: - report_paths: target/nextest/ci/junit.xml - fail_on_failure: false - annotate_only: ${{ github.event.pull_request.head.repo.full_name != github.repository }} - - lint: - name: fmt + clippy - runs-on: ubuntu-latest - - steps: - - uses: actions/checkout@v4 - - - name: Install Rust stable - uses: dtolnay/rust-toolchain@stable - with: - components: rustfmt, clippy - - - name: Cache Rust build artifacts - uses: Swatinem/rust-cache@v2 - - - name: Check formatting - run: cargo fmt --check - - - name: Clippy - run: cargo clippy --all-features -- -D warnings -A missing_docs - env: - RUSTFLAGS: "-C target-cpu=x86-64-v3" 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/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.lock b/Cargo.lock new file mode 100644 index 0000000..d5de8c1 --- /dev/null +++ b/Cargo.lock @@ -0,0 +1,2468 @@ +# 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 = "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" +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 0.10.5", + "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 0.10.5", +] + +[[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 = "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" +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 = "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" +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.14.5" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "e5274423e17b7c9fc20b6e7e208532f9b19825d82dfd615708b70edd83df41f1" + +[[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 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]] +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 = "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" +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 = "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" +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", + "serde", +] + +[[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 = "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" +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 = "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" +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 = "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" +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", + "faer", + "humantime", + "linfa-linalg", + "log", + "ndarray 0.16.1", + "ndarray 0.17.2", + "ndarray-npy", + "proptest", + "rand 0.9.5", + "rand_chacha 0.9.0", + "rand_distr", + "serde_json", + "sprs", + "thiserror 2.0.21", + "umap-rs", +] + +[[package]] +name = "spectral-init-eval" +version = "0.1.0" +dependencies = [ + "criterion", + "faer", + "humantime", + "ndarray 0.17.2", + "ndarray-npy", + "rand 0.9.5", + "rand_distr", + "serde_json", + "spectral-init", + "sprs", + "trustworthiness", +] + +[[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", + "serde", + "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-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" +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 = "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 = "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" +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 = "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" +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 = "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" +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..7712826 100644 --- a/Cargo.toml +++ b/Cargo.toml @@ -3,215 +3,85 @@ 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" -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", + "/docs/umap-rs-integration.md", + "/docs/user-guide.md", + "/README.md", + "/CHANGELOG.md", + "/LICENSE-APACHE", + "/LICENSE-MIT", +] [package.metadata.docs.rs] -all-features = true 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 = [] + +[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] -serde = { version = "1", features = ["derive"], optional = true } -ndarray-npy = { version = "0.10", optional = true } -pico-args = { version = "0.5", optional = true } -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" -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" +umap-rs = "0.4.5" # the integration the `umap_rs` example and test compile against [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"] - -[[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"] - -[[bench]] -name = "dist_sq_bench" -harness = false +[profile.test.package.trustworthiness] +opt-level = 2 + +[profile.test.package.spectral-init-eval] +opt-level = 2 [[example]] name = "basic" @@ -224,3 +94,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/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 8ab7f2e..e694443 100644 --- a/README.md +++ b/README.md @@ -4,171 +4,276 @@ [![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) -[![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) +[![CI](https://github.com/TalonT-Org/spectral-init/actions/workflows/ci.yml/badge.svg)](https://github.com/TalonT-Org/spectral-init/actions/workflows/ci.yml) +[![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. -## Quick Start +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 ```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(); - let embedding = spectral_init(&graph, 2, 42, None, SpectralInitConfig::default())?; - assert_eq!(embedding.shape(), &[n, 2]); + // Two embedding dimensions, seed 42. + let config = SpectralInitConfig::new(2).with_seed(42); + let coords = spectral_init(graph.view(), None, &config)?; + + assert_eq!(coords.dim(), (n, 2)); Ok(()) } ``` -See [`examples/basic.rs`](examples/basic.rs) for the full runnable version. - -## Integration with umap-rs - -```rust -use spectral_init::{spectral_init, SpectralInitConfig}; +`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`. -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` with spectral initialization built in is at +. -```rust -use spectral_init::{spectral_init, ComputeMode, SpectralInitConfig}; +## Compute modes -let mut config = SpectralInitConfig::default(); -config.compute_mode = ComputeMode::RustNative; -let embedding = spectral_init(&graph, 2, 42, None, config)?; -``` +| 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. | -See [`examples/compute_modes.rs`](examples/compute_modes.rs) for a side-by-side comparison. +```rust +use spectral_init::{ComputeMode, SpectralInitConfig}; -## Feature Flags +let config = SpectralInitConfig::new(2) + .with_seed(42) + .with_compute_mode(ComputeMode::RustNative); +assert_eq!(config.compute_mode(), ComputeMode::RustNative); +``` -| 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. | +## 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: -## Performance +```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), + } +} +``` -Benchmarks run on a 2000-node ring graph (4 neighbours per node): +## Platforms -| Stage | Time | -|-------|------| -| Full pipeline (`spectral_init`) | ~223 ms | -| Laplacian construction | ~228 µs | -| LOBPCG solve (k=3) | ~306 ms | -| Randomized SVD (k=3) | ~286 ms | +- 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. -> 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. +## Reproducibility -## Correctness +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`. -Outputs are validated against Python UMAP reference fixtures stored as `.npz` files -in `tests/fixtures/`. Verification uses: +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`. -- **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 +## Evidence -See the [implementation report](docs/umap-spectral-initialization-rust-implementation-report.md) -for the full algorithmic design. +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). -## Requirements +These figures describe the initialization. They are not a comparison of final UMAP +embeddings. -- **MSRV:** Rust 1.85 -- **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 +## Stability -## Testing +This is a 0.x release, and the API may change in 0.2. -Install [`cargo-nextest`](https://nexte.st/) if not already present: +`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. -```sh -cargo install cargo-nextest -``` +## Repository -Run the test suite (synthetic tests only — no fixture generation required): +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. -```sh -cargo nextest run --features testing -``` +The design of the algorithm is described in the +[implementation report](https://github.com/TalonT-Org/spectral-init/blob/4e2251690e9d4d9ab36f200a84ec9c7adaba73a8/docs/umap-spectral-initialization-rust-implementation-report.md). -Run with CI profile: +## Acknowledgements -```sh -cargo nextest run --profile ci --features testing -``` +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. -Run fixture-dependent tests (requires Python fixture generation first): +## License -```sh -python tests/generate_fixtures.py -cargo nextest run --profile with-fixtures --run-ignored all --features testing -``` +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 @@ - - + +