[integer] Implement Burnikel-Ziegler fast recursive division algorithm for BigUInt (#103)

This PR implements the Burnikel-Ziegler fast recursive division
algorithm which significantly improves the performance of large-number
divisions (particularly when there are thousands of words). It achieves
a realized time complexity of O(n^1.585) (3x time when digits are
doubled) instead of the O(n^2) (4x time when digits are doubled).

## Major Division Algorithm Improvements

### 1. **Burnikel-Ziegler Algorithm Implementation**
- **New fast recursive division algorithm** for large numbers
- Added `floor_divide_burnikel_ziegler()` function with cutoff at 64
words
- Implemented supporting functions:
  - `floor_divide_two_by_one()`
  - `floor_divide_three_by_two()`
  - `floor_divide_three_by_two_uint32()`
  - `floor_divide_four_by_two_uint32()`

### 2. **Division Strategy Refactoring**
- **Renamed** `floor_divide_general()` → `floor_divide_school()`
- **Smart algorithm selection** in `floor_divide()`:
  - Small numbers (≤64 words): Use schoolbook division
  - Large numbers (>64 words): Use Burnikel-Ziegler algorithm
- **Extracted normalization logic** into
`calculate_normalization_factor()` helper function

## Benchmark and Testing Enhancements

### 3. **Extended Test Coverage**
- **Increased test range** from 2^16 to 2^18 words (262,144 words)
- **Added validation** to compare Mojo vs Python results
- **Reduced iterations** for large number tests (100 → 10)
- **Added new test cases** for extremely large divisions

### 4. **Improved Benchmarking**
- **Extended Python string limit** from 1M to 10M digits
- **Enhanced logging** with result validation
- **Better error handling** for mismatched results

## Code Quality Improvements

### 5. **Constructor Safety**
- **Fixed BigUInt constructor** to handle empty word lists
- **Added validation** to prevent zero-length word arrays

### 6. **Build Process**
- **Improved formatting command** to target specific directories
- **Better project organization**

## Performance Impact

The main achievement is **dramatically improved performance for large
number division**:
- **O(n²) → O(n^1.585)** complexity reduction using Burnikel-Ziegler
- **Automatic algorithm selection** based on input size
- **Maintains compatibility** with existing API

This is a significant algorithmic improvement that should provide
substantial speedups for large number operations while maintaining
correctness for all input sizes.

Author: forfudan

benches/biguint/bench_biguint_divide_complexity.mojo

@@ -1,6 +1,6 @@
 # ===----------------------------------------------------------------------=== #
 # Benchmark for BigUInt division time complexity analysis
-# Testing word sizes from 32 to 65536 words (powers of 2)
+# Testing word sizes from 32 to 2**18 words (powers of 2)
 # ===----------------------------------------------------------------------=== #
 
 from time import perf_counter_ns
@@ -157,7 +157,7 @@ fn main() raises:
     )
     log_print("", log_file)
 
-    # Test sizes: powers of 2 from 32 to 65536
+    # Test sizes: powers of 2 from 32 to 2**18 words
     var test_sizes = List[Int]()
     test_sizes.append(32)
     test_sizes.append(64)
@@ -171,6 +171,8 @@ fn main() raises:
     test_sizes.append(16384)
     test_sizes.append(32768)
     test_sizes.append(65536)
+    test_sizes.append(131072)  # 2^17
+    test_sizes.append(262144)  # 2^18
 
     # Test Case 1: Large / Small division (2n / n)
     log_print("=== TEST CASE 1: LARGE / SMALL DIVISION (2n / n) ===", log_file)
@@ -183,7 +185,7 @@ fn main() raises:
     for i in range(len(test_sizes)):
         var divisor_size = test_sizes[i]
         var dividend_size = divisor_size * 2
-        if dividend_size <= 65536:  # Stay within our limit
+        if dividend_size <= 2**18:  # Stay within our limit
             var avg_time = benchmark_divide_at_size(
                 dividend_size, divisor_size, 5, log_file
             )
@@ -206,7 +208,7 @@ fn main() raises:
     for i in range(len(test_sizes)):
         var divisor_size = test_sizes[i]
         var dividend_size = divisor_size * 4
-        if dividend_size <= 65536:  # Stay within our limit
+        if dividend_size <= 2**18:  # Stay within our limit
             var avg_time = benchmark_divide_at_size(
                 dividend_size, divisor_size, 5, log_file
             )
@@ -274,7 +276,7 @@ fn main() raises:
     for i in range(len(test_sizes)):
         var divisor_size = test_sizes[i]
         var dividend_size = divisor_size * 4
-        if dividend_size <= 65536:  # Only show results within our limit
+        if dividend_size <= 2**18:  # Only show results within our limit
             var time_taken = very_large_small_results[i]
 
             if time_taken > 0.0:  # Only show valid results

benches/biguint/bench_biguint_truncate_divide.mojo

@@ -23,7 +23,7 @@ fn open_log_file() raises -> PythonObject:
     var python = Python.import_module("builtins")
     var datetime = Python.import_module("datetime")
     var pysys = Python.import_module("sys")
-    pysys.set_int_max_str_digits(1000000)
+    pysys.set_int_max_str_digits(10000000)
 
     # Create logs directory if it doesn't exist
     var log_dir = "./logs"
@@ -88,6 +88,15 @@ fn run_benchmark_truncate_divide(
         var mojo_result = mojo_dividend // mojo_divisor
         var py_result = py_dividend // py_divisor
 
+        if String(mojo_result) != String(py_result):
+            log_print(
+                "Error: Mojo and Python results do not match!",
+                log_file,
+            )
+            log_print("Mojo result:     " + String(mojo_result), log_file)
+            log_print("Python result:   " + String(py_result), log_file)
+            return  # Skip this benchmark case if results don't match
+
         # Display results for verification
         log_print("Mojo result:     " + String(mojo_result), log_file)
         log_print("Python result:   " + String(py_result), log_file)
@@ -155,6 +164,7 @@ fn main() raises:
         log_print("Could not retrieve system information", log_file)
 
     var iterations = 100
+    var iterations_large_numbers = 10
 
     # Define benchmark cases (all positive numbers for BigUInt)
     log_print(
@@ -492,20 +502,40 @@ fn main() raises:
 
     # Case 31: Division of large numbers
     run_benchmark_truncate_divide(
-        "Division of large numbers (1000 words vs 100 digits)",
+        "Division of large numbers (5000 words vs words digits)",
         "316227766_016824890_583648059_893174009_579947593" * 1000,
         "141421356_237309504_880168872_420969807_856967187" * 100,
-        3,
+        iterations_large_numbers,
         log_file,
         speedup_factors,
     )
 
     # Case 32: Division of large numbers
     run_benchmark_truncate_divide(
-        "Division of large numbers (10000 words vs 1234 digits)",
+        "Division of large numbers (50000 words vs 6170 words)",
         "316227766_016824890_583648059_893174009_579947593" * 10000,
         "141421356_237309504_880168872_420969807_856967187" * 1234,
-        3,
+        iterations_large_numbers,
+        log_file,
+        speedup_factors,
+    )
+
+    # Case 33: Division of large numbers
+    run_benchmark_truncate_divide(
+        "Division of large numbers (2**16 words vs 2**12 digits)",
+        "123456789" * 2**16,
+        "987654321" * 2**12,
+        iterations_large_numbers,
+        log_file,
+        speedup_factors,
+    )
+
+    # Case 34: Division of large numbers
+    run_benchmark_truncate_divide(
+        "Division of large numbers (2**18 words vs 2**14 digits)",
+        "123456789" * 2**18,
+        "987654321" * 2**14,
+        iterations_large_numbers,
         log_file,
         speedup_factors,
     )

pixi.toml

@@ -14,7 +14,7 @@ max = "==25.4"
 
 [tasks]
 # format the code
-format = "pixi run mojo format ./"
+format = "pixi run mojo format ./src && pixi run mojo format ./benches && pixi run mojo format ./tests && pixi run mojo format ./docs"
 
 # compile the package
 package_decimojo = "pixi run mojo package src/decimojo && cp decimojo.mojopkg tests/ && cp decimojo.mojopkg benches/ && rm decimojo.mojopkg"