Skip to content

feat: add full-loop fixed-factor Brunet APIs - #2

Open
LCGaoZzz wants to merge 1 commit into
omicverse:mainfrom
LCGaoZzz:agent/spatial-ecotyper-fixed-factor
Open

feat: add full-loop fixed-factor Brunet APIs#2
LCGaoZzz wants to merge 1 commit into
omicverse:mainfrom
LCGaoZzz:agent/spatial-ecotyper-fixed-factor

Conversation

@LCGaoZzz

@LCGaoZzz LCGaoZzz commented Aug 1, 2026

Copy link
Copy Markdown

Summary

Adds first-class full-loop fixed-factor Brunet/KL APIs for Spatial EcoTyper training and projection.

Root cause

The downstream LOOCV workflow previously crossed the Python/PyO3 boundary once per NMF iteration and rebuilt invariant transposes and sums repeatedly. A formal 20-repeat, 6-sample workflow performs many projection solves, so that call overhead and repeated setup dominated runtime and made thread budgeting difficult to attest.

Changes

  • add fixed_h_brunet and fixed_w_brunet public Python APIs;
  • execute the complete loop in one GIL-released Rust call;
  • cache fixed-factor transposes/sums and expose a scoped per-call Rayon thread budget;
  • preserve R NMF Brunet semantics: float64, epsilon floor every 10 iterations, connectivity checks, and strict stable > stopconv stopping (default first stop at iteration 420);
  • attest fixed-factor immutability with SHA-256 and return convergence/KL/runtime metrics;
  • fail closed for invalid factors and infinite KL, including V > 0 && WH == 0;
  • bump package version to 0.2.0 and add tests plus a reproducible benchmark.

Validation

  • cargo test --release --manifest-path rust/Cargo.toml --lib: 7 passed
  • python -m pytest tests -q: 26 passed
  • 420-iteration random-matrix comparison against the legacy single-step loop: elementwise identical with 1 and 4 threads
  • downstream live parity against R NMF 0.30.1: fixed-H/fixed-W at 1, 10, and connectivity-stopped iterations passed
  • benchmark, V=300x2000, rank=8, 420 iterations, 8 threads: fixed-W 4.01x; fixed-H 0.94x (projection is the repeated hot path)

Downstream integration: PrimorDecode/omicos-admin#454.

@LCGaoZzz
LCGaoZzz marked this pull request as ready for review August 2, 2026 04:27
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant