docs: document Karatsuba attempt and why schoolbook is kept for 8 limbs

Karatsuba multiplication (splitting 8 limbs into 4+4 halves for 48 inner
products instead of 64) was implemented and tested but reverted because
the overhead of extra additions, carry propagation, and 5 temporary array
allocations per call negates the product-count savings at only 8 limbs.
The crossover point where Karatsuba beats schoolbook is typically ~32+
limbs on hardware with fast multiply.

https://claude.ai/code/session_01BhU63WUe9AhikZxRdw3Lpg
This commit is contained in:
Claude
2026-04-05 18:55:17 +00:00
parent 1f885accb1
commit 0e3c2fcda5
@@ -139,6 +139,10 @@ internal object U256 {
* Uses the standard O(n²) algorithm with 8×8 = 64 inner Long multiplications.
* Each partial product is at most 32×32 = 64 bits, which fits in a signed Long
* with room for carry accumulation.
*
* Note: Karatsuba (splitting into 4-limb halves for 48 products) was attempted
* but the overhead of extra additions, carry propagation, and 5 temporary array
* allocations per call negates the product-count savings at only 8 limbs.
*/
fun mulWide(
out: IntArray,