Skip to content
Open
Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
113 commits
Select commit Hold shift + click to select a range
5e18c15
Phase 0: truthful baseline and release gates
Trecek Nov 11, 2026
d4dce6f
Phase 1: crate boundary — lean library, standalone tools as workspace…
Trecek Nov 11, 2026
71749f2
Phase 2: freeze a sound public API
Trecek Nov 12, 2026
6c52fa4
Phase 3: portability, unsafe hygiene and dependencies
Trecek Nov 12, 2026
a180a05
Phase 4: compiled umap-rs integration and optimizer-independent evidence
Trecek Nov 12, 2026
c81f3e0
Phase 5: documentation and legal
Trecek Nov 12, 2026
c5fa9ca
Phase 6: CI release gates
Trecek Nov 12, 2026
02e530e
fix(review): keep solver-internal tolerances with their solvers; test…
Trecek Nov 12, 2026
6fe2746
fix(review): log when an iterative level produces no result
Trecek Nov 12, 2026
e1ecb8c
fix(review): derive the per-level timing array length from SolverLevel
Trecek Nov 12, 2026
3d6a4be
fix(review): log the faer error when rSVD's projected eigenproblem fails
Trecek Nov 12, 2026
c0e6d68
fix(review): say why rsvd_solve returned None
Trecek Nov 12, 2026
f25cd65
fix(review): derive the rSVD budget test's sketch size from rsvd_k_sub
Trecek Nov 12, 2026
b5a4e9b
fix(review): drop the duplicate owned nd16→nd17 Array2 conversion
Trecek Nov 12, 2026
58a187f
fix(review): document what the LOBPCG outcomes mean and test Failed
Trecek Nov 12, 2026
1decd04
fix(review): drop per-item doc(hidden) inside the hidden __internal m…
Trecek Nov 12, 2026
4d1ade1
fix(review): list the quality re-exports in __internal explicitly
Trecek Nov 12, 2026
c87dbed
fix(review): drop the tautological clone assertion in the config sett…
Trecek Nov 12, 2026
22f8458
fix(review): restore the in-bounds expect in find_components' BFS
Trecek Nov 12, 2026
45687e0
fix(review): replace the unreachable missing-row skip in extract_subg…
Trecek Nov 12, 2026
d907e11
fix(review): fall back to scalar for non-C-contiguous x instead of pa…
Trecek Nov 12, 2026
8939780
fix(review): one scalar squared-distance helper for both distance steps
Trecek Nov 12, 2026
e2de2d2
fix(review): state the AVX2/FMA requirement in the kernels' Safety co…
Trecek Nov 12, 2026
50cf6a7
fix(review): test the seed contract on the sampled rows, not the metr…
Trecek Nov 12, 2026
ba4d5d6
fix(review): one brute-force trustworthiness oracle
Trecek Nov 12, 2026
4108001
fix(review): say that tw_profiler's step timings need the profiling f…
Trecek Nov 12, 2026
08035cc
fix(review): fix the garbled umap-rs fork sentence in README and guide
Trecek Nov 12, 2026
775f7c7
fix(review): link the umap-rs example relatively from the integration…
Trecek Nov 12, 2026
dc34b7a
fix(review): name one unambiguous output directory in the run-experim…
Trecek Nov 12, 2026
0d37687
fix(review): list eval/src/ among the canonical metric sources in the…
Trecek Nov 12, 2026
9394247
fix(review): scope the nd16-bridge purity rule's description to the l…
Trecek Nov 12, 2026
5af1d23
fix(review): make the purity gate check feature declarations in manif…
Trecek Nov 12, 2026
3f4ee5d
fix(review): enforce that zip stays out of the published crate's tree
Trecek Nov 12, 2026
c6d1f7f
fix(review): run every example in the unpacked crate in the package gate
Trecek Nov 12, 2026
e7ad65a
fix(review): reject non-contiguous labels in separation_ratio
Trecek Nov 12, 2026
595cf05
fix(review): check the CSR shape key in both fixture loaders
Trecek Nov 12, 2026
ebba455
fix(review): use the eval crate's shared modules instead of re-includ…
Trecek Nov 12, 2026
d83ebf1
fix(review): one shared epsilon-bridge Laplacian builder
Trecek Nov 12, 2026
d25b4d8
fix(review): use the shared path and ring Laplacian builders in adver…
Trecek Nov 12, 2026
1bdc320
fix(review): number the adversarial solver-level tests after the six-…
Trecek Nov 12, 2026
236c89f
fix(review): name the regularized-LOBPCG fixture tests _level3
Trecek Nov 12, 2026
39e755f
fix(review): use the shared residual helper in the rSVD fixture tests
Trecek Nov 12, 2026
634fd2a
fix(review): reach the rSVD fixture directory like every other module
Trecek Nov 12, 2026
df185f0
fix(review): read .npz references through the shared fixture loader
Trecek Nov 12, 2026
5f58cc6
fix(review): drop the all-datasets component sweep that re-ran the pe…
Trecek Nov 12, 2026
ceb4983
fix(review): measure the accuracy report's Rust scaling with the libr…
Trecek Nov 12, 2026
da5eb44
fix(review): drop the unreachable disconnected arm of the e2e residual
Trecek Nov 12, 2026
35c1769
fix(review): check degree vector lengths before the tolerance-margin …
Trecek Nov 12, 2026
890f030
fix(review): share descale_embedding between the e2e test binaries
Trecek Nov 12, 2026
9698916
fix(review): share validate_graph between the two test binaries
Trecek Nov 12, 2026
a50ffea
fix(review): allow one f32 ULP at the scaled magnitude in the mode pa…
Trecek Nov 12, 2026
437fe2e
fix(review): make the ring_2000 convergence test's skip visible
Trecek Nov 12, 2026
69511e1
fix(review): guard zero degrees when building the Laplacian in laplac…
Trecek Nov 12, 2026
2705531
fix(review): name the solver report binding _report in the property t…
Trecek Nov 12, 2026
6eb65c1
fix(review): rename the umap_rs test module so it no longer shadows t…
Trecek Nov 12, 2026
5559a99
fix(review): move the self-loop fixture section out of "How Rust Test…
Trecek Nov 12, 2026
7190616
fix(review): declare eval's bench- and test-only crates as dev-depend…
Trecek Nov 12, 2026
c13f4e2
fix(review): one max_subspace_angle, in the shared diagnostics module
Trecek Nov 12, 2026
c49fdf1
fix(review): drop the vestigial MetricResult.dimension field
Trecek Nov 12, 2026
ad06879
fix(review): name the fixture and oversampling in rSVD sweep panics
Trecek Nov 12, 2026
37cc84a
fix(review): name the solver configuration in nbiter sweep panics
Trecek Nov 12, 2026
75c6d98
fix(review): report every umap-learn version behind the evidence fixt…
Trecek Nov 12, 2026
ff93551
fix(review): describe how eval reaches the shared fixture loaders
Trecek Nov 12, 2026
bb30d4a
fix(review): pin the exact residuals in the quality.rs residual tests
Trecek Nov 12, 2026
5b706d7
fix(review): saturate the rSVD subspace size instead of overflowing it
Trecek Nov 12, 2026
dfc3071
fix(review): share one power-iteration basis between the two rSVD sol…
Trecek Nov 12, 2026
bdc1f42
fix(review): make the rSVD params test fail when the params are ignored
Trecek Nov 12, 2026
284575a
fix(review): log the linfa error when LOBPCG stops or fails
Trecek Nov 12, 2026
18a1fb9
fix(review): pin each solver level's exact name
Trecek Nov 12, 2026
4795430
fix(review): drop the debug_assert that repeats the warm-restart expect
Trecek Nov 12, 2026
567a70d
fix(review): drop the unreachable member-index debug_assert in extrac…
Trecek Nov 12, 2026
408fda9
fix(review): drop the vestigial #[doc(hidden)] markers in operator.rs
Trecek Nov 12, 2026
0a92bcf
fix(review): drop the vacuous self-exclusion loop from t_tw_10
Trecek Nov 12, 2026
7b6e550
fix(review): state the broadcast vector's lane order correctly
Trecek Nov 12, 2026
79fda95
fix(review): one shared proptest configuration for the property tests
Trecek Nov 12, 2026
c088e3e
fix(review): one shared list of the reference datasets
Trecek Nov 12, 2026
2b14dc5
fix(review): validate the fixture expansion factor wherever it is loaded
Trecek Nov 12, 2026
72f8112
fix(review): drop the unread eigenvalue fields from the accuracy report
Trecek Nov 12, 2026
1e4d016
fix(review): stop the accuracy report folding NaN metrics into perfec…
Trecek Nov 12, 2026
3d2e9a0
fix(review): bound separation_ratio's labels before allocating per co…
Trecek Nov 12, 2026
14f3eec
fix(review): drop test_max_abs_is_10, which repeated check_pre_noise_…
Trecek Nov 12, 2026
503780a
fix(review): name the rSVD-only gate profile in the escalation tests
Trecek Nov 12, 2026
f952903
fix(review): compare solver levels as SolverLevel, not raw u8 discrim…
Trecek Nov 12, 2026
882c1ef
fix(review): drop the unreachable small-graph skip in the sinv fixtur…
Trecek Nov 12, 2026
c88e1cb
fix(review): check the LOBPCG fixture size the tests already pass in
Trecek Nov 12, 2026
6b8f21e
fix(review): import the shared helpers in comp_d_rsvd like its siblin…
Trecek Nov 12, 2026
cf120fa
fix(review): drop the duplicate ring_2000 warm-restart test
Trecek Nov 12, 2026
a4a05c8
fix(review): correct the dataset count in the e2e residual section he…
Trecek Nov 12, 2026
9991cb8
fix(review): drop the faer-parallelism restore guard nothing can observe
Trecek Nov 12, 2026
390ef97
fix(review): share the first-edge edit between the two asymmetry tests
Trecek Nov 12, 2026
100d250
fix(review): fail the purity gate when grep itself fails
Trecek Nov 12, 2026
0bcc25c
fix(review): widen the purity gate to every print and environment API
Trecek Nov 12, 2026
2964eeb
fix(review): reject unprotected or non-https resources in the SRI gate
Trecek Nov 12, 2026
37512d1
fix(review): document research/reports/ in the research README
Trecek Nov 12, 2026
41baa2b
fix(review): call inv_perm the inverse σ-sort permutation again
Trecek Nov 12, 2026
44d5709
fix(review): give test_warm_restart_benefit a module doc and drop ext…
Trecek Nov 12, 2026
9655b9f
fix(review): fail the rSVD sweep on a malformed SPECTRAL_RSVD_OVERSAM…
Trecek Nov 12, 2026
5af6fa7
fix(review): compare eval solver levels as SolverLevel, not raw u8
Trecek Nov 12, 2026
9074406
fix(review): let results_dir() create the eval results directory
Trecek Nov 12, 2026
2698c7f
fix(review): drop the unused serde surface of the eval report structs
Trecek Nov 12, 2026
7ccb3bf
fix(review): one warm-up helper for the three LOBPCG benchmarks
Trecek Nov 12, 2026
c64cb12
fix(review): one helper prints SOLVER_LEVEL in the MERFISH export tests
Trecek Nov 12, 2026
63aee80
fix(review): compute the report's per-component residuals on the real…
Trecek Nov 12, 2026
1d47694
fix(review): gate the hidden AVX2 distance kernel behind a __bench fe…
Trecek Nov 12, 2026
945881b
fix(review): say where eval's #[path] modules come from
Trecek Nov 12, 2026
1d4dcb7
fix(review): pin the README's implementation-report link to its commit
Trecek Nov 12, 2026
1544c8e
fix(review): state the second ndarray that linfa-linalg brings into a…
Trecek Nov 12, 2026
364f836
fix(review): make the path_laplacian fixture symmetric and test it
Trecek Nov 12, 2026
44b743c
fix(review): replace the ignored ring_2000 convergence test with a ga…
Trecek Nov 12, 2026
71f5091
fix(review): measure the warm-restart benefit against production's ow…
Trecek Nov 12, 2026
07f678a
fix: iterate the per-level timings directly in the forced-dense escal…
Trecek Nov 12, 2026
23bc16c
fix: treat a panic inside linfa-linalg's LOBPCG as a failed run
Trecek Nov 12, 2026
c7829b8
fix: record lobpcg_solve's None as an escalation row in the warm-rest…
Trecek Nov 12, 2026
File filter

Filter by extension

Filter by extension


Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
5 changes: 5 additions & 0 deletions .autoskillit/.gitignore
Original file line number Diff line number Diff line change
@@ -1 +1,6 @@
temp/
.secrets.yaml
.onboarded
sync_manifest.json
test-filter-manifest.yaml
validation-errors/
5 changes: 3 additions & 2 deletions .autoskillit/config.yaml
Original file line number Diff line number Diff line change
Expand Up @@ -13,7 +13,8 @@ test_check:
- cargo
- nextest
- run
- --locked
- --workspace
- --all-features
- --profile
- ci
- --features
- testing
2 changes: 0 additions & 2 deletions .cargo/config.toml

This file was deleted.

19 changes: 12 additions & 7 deletions .claude/skills/plan-experiment/SKILL.md
Original file line number Diff line number Diff line change
Expand Up @@ -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.

Expand Down Expand Up @@ -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.

Expand Down
14 changes: 8 additions & 6 deletions .claude/skills/run-experiment/SKILL.md
Original file line number Diff line number Diff line change
Expand Up @@ -125,22 +125,24 @@ 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

**If the experiment affects parity** (i.e., it involves `ComputeMode`, SIMD paths,
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:
Expand All @@ -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.

Expand Down
12 changes: 8 additions & 4 deletions .claude/skills/scope/SKILL.md
Original file line number Diff line number Diff line change
Expand Up @@ -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.
Expand Down Expand Up @@ -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.}
```
Expand Down
63 changes: 63 additions & 0 deletions .config/deny.toml
Original file line number Diff line number Diff line change
@@ -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"
9 changes: 2 additions & 7 deletions .config/nextest.toml
Original file line number Diff line number Diff line change
Expand Up @@ -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"
Expand All @@ -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
Expand Down
114 changes: 114 additions & 0 deletions .github/CONTRIBUTING.md
Original file line number Diff line number Diff line change
@@ -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)).
8 changes: 4 additions & 4 deletions .github/ISSUE_TEMPLATE/bug_report.yml
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand All @@ -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

Expand All @@ -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
Expand Down
30 changes: 30 additions & 0 deletions .github/SECURITY.md
Original file line number Diff line number Diff line change
@@ -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
<https://github.com/TalonT-Org/spectral-init/security/advisories/new>. 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.
Loading
Loading