Speed up the portable 4x4 inverse, adjugate and quaternion multiply

[ctreffs]

Optimizations chosen by the benchmarks from #75. Only FirebladeMath's own implementations are changed.

Changes

• 4x4 adjugate, determinant and portable inverse now share one Laplace expansion by 2×2 minors, a new internal adjugateAndDeterminant helper. It computes 12 shared sub-determinants once and builds the result directly from columns.
  • Previously, inverse computed a full adjugate (about 48 2×2 minors, many of them duplicates) plus a separate full determinant.
  • It also wrote 16 single elements through the switch-based subscript.
  • adjugate is FirebladeMath's own code on every platform. determinant and inverse change only on the portable path; with simd they still forward to simd_determinant and simd_inverse.
• Portable quaternion multiply: the Hamilton product is now four 4-wide multiply-adds instead of 16 scalar multiplies.

Benchmark results

M1 Max, Swift 6.4, p50 over 3 runs each. Allocations stay at 0 everywhere.

Benchmark	Before	After
Mat4x4f.inverse (portable)	21 ns	15 ns
Mat4x4f.adjugate (simd and portable)	17 ns	15 ns
Quat4f.multiply (portable)	13 ns	10 ns

The benchmark harness itself costs about 5 ns per matrix and 3 ns per quaternion; I measured that with temporary pass-through benchmarks. Subtracting it, the portable inverse's own computation went from ~16 to ~10 ns (−37%), the portable quaternion multiply from ~10 to ~7 ns, and the adjugate is now on par with Apple's simd.

Tried and discarded: a fully vectorized adjugate (three 4-wide multiply-adds per column) measured slower, 16/17 ns. The scalar form is already vectorized well by the compiler.

Unchanged and not worth pursuing: Quat4f.actNormalize is 27 ns on both paths and dominated by normalize's square root and division. The other benchmarks are already on par with simd.

Compatibility with older compilers

Swift 6.1 and 6.2 (the Linux and Windows CI jobs, and macOS 6.1) couldn't type-check the long generic determinant sum or the vectorized quaternion product in reasonable time. Every intermediate is now explicitly typed and split into short sub-expressions, following the approach from #59. Grouping the quaternion product as (term0 + term1) + (term2 - term3) also shortened its dependency chain, which is where the extra speed in the table comes from.

Tests

• New PortableVsSIMDTests: simd as the reference. It compares the portable 4×4 inverse, determinant and adjugate and quaternion multiply (Float and Double) against Apple's simd, which is exactly what FirebladeMath calls when the simd trait is on.
  • Inputs: 256 pseudo-random matrices and quaternion pairs, plus identity, diagonal, permutation, rotation + translation, small and large scales, singular matrices (determinant only) and the quaternion basis.
  • Adjugate reference: simd has no adjugate, so the reference is inverse · determinant.
  • Tolerances: about 10× the worst rounding difference measured, e.g. Double inverse 5e−13 and Float inverse 2e−4.
  • Where it runs: only when simd is importable but the trait is off. So the macOS CI job now runs the tests a second time with --disable-default-traits.
• New Matrix4x4CofactorTests: compares against an independent cofactor expansion on 32 matrices, plus a singular matrix.
• New QuaternionMultiplicationTests: compares against an independent scalar Hamilton product on 64 pairs, plus the basis rules (i·j = k, j·i = −k, i² = −1) and |p·q| = |p|·|q|.
• Mutation testing: I injected 22 deliberate single-point bugs into the changed code, one at a time: sign flips, swapped factors or lanes, a transposed result, a wrong determinant term, and a missing reciprocal in inverse.
  • The full suite catches all 22.
  • PortableVsSIMDTests alone also catches all 22.
  • Before these tests, three Quat4d bugs went unnoticed, because the old Quat4d tests only multiplied identity by i.
• Results: 311 tests pass with simd and 319 without. Both check-inlinable configurations pass, and lint is clean.

The same simd comparison for all other functions that have both implementations (108 in total) will come in a separate PR.

https://claude.ai/code/session_011WSUtoLptjea3s3iC5wTNC