perf(matmath): hoist EPSILON out of invert_3x3's per-call path

[kalwalt]

Summary

bench/README.md carried matmath.invert_3x3 as an open finding: jsfeat faster in 10 of 10 samples, 1.18–1.40x, never flipping. Profiling attributed it entirely to the singular-matrix check that #120 added — a line original jsfeat does not have at all, so this was never porting drift.

Attribution

Isolating the two halves of return Math.abs(det) < JSFEAT_CONSTANTS.EPSILON ? 0 : 1;:

variant	ops/s
jsfeatNext as written	9.35M	—
drop Math.abs only	10.01M	+7%
hoist EPSILON to module scope only	13.36M	+43%
both	14.57M	+56%
jsfeat (no check at all)	12.47M	reference

The object property load dominates, not Math.abs. The surrounding arithmetic is only ~30 float operations, so one property read per call is not negligible — and with both fixed the standalone form is faster than jsfeat, which does no singular check at all.

The fix

EPSILON hoisted to a module-scope const, and Math.abs(det) < EPSILON replaced by the two-sided compare det < EPSILON && det > -EPSILON.

Semantics unchanged, edge cases included: NaN yields 1 under both forms (all NaN comparisons are false), -0 yields 0 under both. The 265 parity/property tests stay green, unchanged.

Result

Eight idle-machine runs after the fix:

1.03 / 2.20 / 1.01 / 1.09 / 1.15* / 1.14 / 1.09 / 1.04 (* = jsfeatNext faster)

Seven of eight sit at or below the ~1.15x noise floor, and the sign now flips — where before it was 10/10 jsfeat and never below 1.18. The 2.20 is a single outlier, reported rather than discarded.

The residual ~1.05x is method-dispatch overhead the standalone probe didn't have: the probe timed a plain function, the shipped path goes through jsfeatNext.matmath.invert_3x3.

Two things this investigation also established

A hypothesis was disproven, not confirmed. The same profiling session tested bench/README.md's long-standing YAPE hypothesis — that importing hessian_min_eigen_value across modules blocks V8 inlining. The profile shows 96.6% of yape06.detect's time in detect itself and ~0.6% in the helpers, and the two implementations' inner loops are character-for-character identical. The hypothesis does not hold; YAPE's cause is still unknown. (Not changed in this PR — flagging it so the README's wording gets revisited.)

A misattribution was caught. linalg.lu_solve — the finding #159 explicitly did not explain — also reads JSFEAT_CONSTANTS.EPSILON inside a loop, which looked like the same bug. It isn't: jsfeat's equivalent reads jsfeat.EPSILON, also a property load. Both sides pay the same cost there, so it explains nothing. lu_solve remains open.

Verification

npm test: 265 passed, unchanged. tsc --noEmit, prettier --check, license-check (93 files) all clean. Benches measured on an idle machine, warm-up discarded, eight samples.

Refs #86, #120.

🤖 Generated with Claude Code

[codecov]

Codecov Report

✅ All modified and coverable lines are covered by tests.

📢 Thoughts on this report? Let us know!

[Copilot]

Pull request overview

Optimizes matmath.invert_3x3 while preserving semantics and documents updated benchmark results.

Changes:

• Hoists EPSILON to module scope.
• Replaces Math.abs with an equivalent two-sided comparison.
• Updates profiling and post-fix benchmark documentation.

Reviewed changes

Copilot reviewed 2 out of 2 changed files in this pull request and generated 2 comments.

File	Summary
src/matmath/matmath.ts	Optimizes the determinant check; scope the performance claim to the local optimization.
bench/README.md	Documents benchmark results; remove stale pre-fix results and wording.

---

💡 Add a code-review agent skill or configure MCP servers for context-aware, tailored reviews. Learn more in the docs.