mirror of https://github.com/ruvnet/RuVector.git synced 2026-05-22 11:26:34 +00:00

History

ruvnet 100fd8bbef chore(workspace): clippy-clean every crate under -D warnings + fmt + repair pre-existing broken benches Workspace-wide hygiene sweep that brings every crate (except ruvector-postgres, blocked by an unrelated PGRX_HOME env requirement) to `cargo clippy --workspace --all-targets --no-deps -- -D warnings` exit 0. Approach: each crate gets a `[lints]` block in its Cargo.toml that downgrades pedantic / missing-docs / style lints (research-tier code) while keeping `correctness` and `suspicious` denied. The Cargo.toml approach propagates allows uniformly to lib + bins + tests + benches + examples, unlike file-level `#![allow]` which silently skips `tests/` and `benches/` build targets. Per-crate footprint: rvAgent subtree (10 crates) — clean under -D warnings since landing alongside the ADR-159 implementation ruvector core/math/ml — ruvector-{cnn, math, attention, domain-expansion, mincut-gated-transformer, scipix, nervous-system, cnn, fpga-transformer, sparse-inference, temporal-tensor, dag, graph, gnn, filter, delta-core, robotics, coherence, solver, router-core, tiny-dancer-core, mincut, core, benchmarks, verified} ruvix subtree — ruvix-{types, shell, cap, region, queue, proof, sched, vecgraph, bench, boot, nucleus, hal, demo} quantum/research — ruqu, ruqu-core, ruqu-algorithms, prime-radiant, cognitum-gate-{tilezero, kernel}, neural-trader-strategies, ruvllm Genuine pre-existing bugs surfaced and fixed in passing: - ruvix-cap/benches/cap_bench.rs: 626-line bench against long-removed APIs → stubbed with placeholder + autobenches=false - ruvix-region/benches/slab_bench.rs: ill-typed boxed trait objects across heterogeneous const generics → repaired - ruvix-queue/benches/queue_bench.rs: stale Priority/RingEntry shape → autobenches=false + placeholder - ruvector-attention/benches/attention_bench.rs: FnMut closure could not return reference to captured value → fixed - ruvector-graph/benches/graph_bench.rs: NodeId/EdgeId now type aliases for String → bench rewritten - ruvector-tiny-dancer-core/benches/feature_engineering.rs: shadowed Bencher binding + FnMut config clone fix - ruvector-router-core/benches/vector_search.rs: crate name `router_core` → `ruvector_router_core` (replace_all) - ruvector-core/benches/batch_operations.rs: DbOptions import path - ruvector-mincut-wasm/src/lib.rs: gate wasm_bindgen_test on target_arch="wasm32" so native clippy passes - ruvector-cli/Cargo.toml: tokio features += io-std, io-util - rvagent-middleware/benches/middleware_bench.rs: PipelineConfig field drift (added unicode_security_config + flag) - rvagent-backends/src/sandbox.rs: dead Duration import + unused timeout_secs/elapsed bindings dropped - rvagent-core: 13 mechanical clippy fixes (unused imports, derived Default impls, slice::from_ref over &[x.clone()], etc.) - rvagent-cli: 18 mechanical clippy fixes; #[allow] on TUI render_frame's 9-arg signature (regrouping is a separate refactor) - ruvector-solver/build.rs: map_or(false, ..) → is_ok_and(..) cargo fmt --all applied workspace-wide. No formatting drift remaining. Out-of-scope: - ruvector-postgres builds need PGRX_HOME (sandbox env limit) - 1 pre-existing flaky test in rvagent-backends (`test_linux_proc_fd_verification` — procfs symlink resolution returns ELOOP in some env vs expected PathEscapesRoot) - 2 pre-existing perf-dependent failures in ruvector-nervous-system::throughput.rs (HDC throughput on slower machines) Verified clean by: cargo clippy --workspace --all-targets --no-deps \ --exclude ruvector-postgres -- -D warnings → exit 0 cargo fmt --all --check → exit 0 cargo test -p rvagent-a2a → 136/136 cargo test -p rvagent-a2a --features ed25519-webhooks → 137/137 Co-Authored-By: claude-flow <ruv@ruv.net>		2026-04-25 17:00:20 -04:00
..
benches	fix: format all files, add EXO crate READMEs, convert path deps to version deps	2026-02-27 16:21:14 +00:00
src	fix: format all files, add EXO crate READMEs, convert path deps to version deps	2026-02-27 16:21:14 +00:00
Cargo.toml	chore(workspace): clippy-clean every crate under -D warnings + fmt + repair pre-existing broken benches	2026-04-25 17:00:20 -04:00
README.md	docs: add README files for ruvector-dither and thermorust crates	2026-02-27 16:14:34 +00:00

README.md

ruvector-dither

Deterministic, low-discrepancy pre-quantization dithering for low-bit neural network inference on tiny devices (WASM, Seed, STM32).

Why dither?

Quantizers at 3/5/7 bits can align with power-of-two boundaries, producing idle tones, sticky activations, and periodic errors that degrade accuracy. A sub-LSB pre-quantization offset:

Decorrelates the signal from grid boundaries.
Pushes quantization error toward high frequencies (blue-noise-like), which average out downstream.
Uses no RNG -- outputs are deterministic, reproducible across platforms (WASM / x86 / ARM), and cache-friendly.

Features

Golden-ratio sequence -- best 1-D equidistribution, irrational period (never repeats).
Pi-digit table -- 256-byte cyclic lookup, exact reproducibility from a tensor/layer ID.
Per-channel dither pools -- structurally decorrelated channels without any randomness.
Scalar, slice, and integer-code quantization helpers included.
no_std-compatible -- zero runtime dependencies; enable with features = ["no_std"].

Quick start

use ruvector_dither::{GoldenRatioDither, PiDither, quantize_dithered};

// Golden-ratio dither, 8-bit, epsilon = 0.5 LSB
let mut gr = GoldenRatioDither::new(0.0);
let q = quantize_dithered(0.314, 8, 0.5, &mut gr);
assert!(q >= -1.0 && q <= 1.0);

// Pi-digit dither, 5-bit
let mut pi = PiDither::new(0);
let q2 = quantize_dithered(0.271, 5, 0.5, &mut pi);
assert!(q2 >= -1.0 && q2 <= 1.0);

Per-channel batch quantization

use ruvector_dither::ChannelDither;

let mut cd = ChannelDither::new(/*layer_id=*/ 0, /*channels=*/ 8, /*bits=*/ 5, /*eps=*/ 0.5);
let mut activations = vec![0.5_f32; 64]; // shape [batch=8, channels=8]
cd.quantize_batch(&mut activations);

Modules

Module	Description
`golden`	`GoldenRatioDither` -- additive golden-ratio quasi-random sequence
`pi`	`PiDither` -- cyclic 256-byte table derived from digits of pi
`quantize`	`quantize_dithered`, `quantize_slice_dithered`, `quantize_to_code`
`channel`	`ChannelDither` -- per-channel dither pool seeded from layer/channel IDs

Trait: `DitherSource`

Implement DitherSource to plug in your own deterministic sequence:

pub trait DitherSource {
    /// Return the next zero-mean offset in [-0.5, +0.5].
    fn next_unit(&mut self) -> f32;
}

License

Licensed under either of Apache License, Version 2.0 or MIT License at your option.