hypercomplex-engine 0.6.0__tar.gz → 0.7__tar.gz

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (50) hide show
  1. {hypercomplex_engine-0.6.0/hypercomplex_engine.egg-info → hypercomplex_engine-0.7}/PKG-INFO +113 -41
  2. {hypercomplex_engine-0.6.0 → hypercomplex_engine-0.7}/README.md +112 -40
  3. {hypercomplex_engine-0.6.0 → hypercomplex_engine-0.7}/hypercomplex_engine/__init__.py +12 -2
  4. {hypercomplex_engine-0.6.0 → hypercomplex_engine-0.7}/hypercomplex_engine/core/__init__.py +13 -0
  5. hypercomplex_engine-0.7/hypercomplex_engine/core/bitplane/__init__.py +5 -0
  6. hypercomplex_engine-0.7/hypercomplex_engine/core/bitplane/bitplane_standard.py +162 -0
  7. hypercomplex_engine-0.7/hypercomplex_engine/core/graded/__init__.py +5 -0
  8. hypercomplex_engine-0.7/hypercomplex_engine/core/graded/graded_sparse_standard.py +125 -0
  9. {hypercomplex_engine-0.6.0 → hypercomplex_engine-0.7/hypercomplex_engine.egg-info}/PKG-INFO +113 -41
  10. {hypercomplex_engine-0.6.0 → hypercomplex_engine-0.7}/hypercomplex_engine.egg-info/SOURCES.txt +6 -0
  11. {hypercomplex_engine-0.6.0 → hypercomplex_engine-0.7}/pyproject.toml +11 -1
  12. hypercomplex_engine-0.7/tests/test_bitplane_standard.py +128 -0
  13. hypercomplex_engine-0.7/tests/test_graded_sparse.py +285 -0
  14. {hypercomplex_engine-0.6.0 → hypercomplex_engine-0.7}/LICENSE +0 -0
  15. {hypercomplex_engine-0.6.0 → hypercomplex_engine-0.7}/NOTICE +0 -0
  16. {hypercomplex_engine-0.6.0 → hypercomplex_engine-0.7}/hypercomplex_engine/core/basis_element.py +0 -0
  17. {hypercomplex_engine-0.6.0 → hypercomplex_engine-0.7}/hypercomplex_engine/core/basis_notation.py +0 -0
  18. {hypercomplex_engine-0.6.0 → hypercomplex_engine-0.7}/hypercomplex_engine/core/fast/__init__.py +0 -0
  19. {hypercomplex_engine-0.6.0 → hypercomplex_engine-0.7}/hypercomplex_engine/core/fast/bit_utils.py +0 -0
  20. {hypercomplex_engine-0.6.0 → hypercomplex_engine-0.7}/hypercomplex_engine/core/fast/fast_dual.py +0 -0
  21. {hypercomplex_engine-0.6.0 → hypercomplex_engine-0.7}/hypercomplex_engine/core/fast/fast_split.py +0 -0
  22. {hypercomplex_engine-0.6.0 → hypercomplex_engine-0.7}/hypercomplex_engine/core/fast/fast_standard.py +0 -0
  23. {hypercomplex_engine-0.6.0 → hypercomplex_engine-0.7}/hypercomplex_engine/core/holographic/__init__.py +0 -0
  24. {hypercomplex_engine-0.6.0 → hypercomplex_engine-0.7}/hypercomplex_engine/core/holographic/dual.py +0 -0
  25. {hypercomplex_engine-0.6.0 → hypercomplex_engine-0.7}/hypercomplex_engine/core/holographic/split.py +0 -0
  26. {hypercomplex_engine-0.6.0 → hypercomplex_engine-0.7}/hypercomplex_engine/core/holographic/standard.py +0 -0
  27. {hypercomplex_engine-0.6.0 → hypercomplex_engine-0.7}/hypercomplex_engine/core/table_builder/__init__.py +0 -0
  28. {hypercomplex_engine-0.6.0 → hypercomplex_engine-0.7}/hypercomplex_engine/core/table_builder/common.py +0 -0
  29. {hypercomplex_engine-0.6.0 → hypercomplex_engine-0.7}/hypercomplex_engine/core/table_builder/dual.py +0 -0
  30. {hypercomplex_engine-0.6.0 → hypercomplex_engine-0.7}/hypercomplex_engine/core/table_builder/split.py +0 -0
  31. {hypercomplex_engine-0.6.0 → hypercomplex_engine-0.7}/hypercomplex_engine/core/table_builder/standard.py +0 -0
  32. {hypercomplex_engine-0.6.0 → hypercomplex_engine-0.7}/hypercomplex_engine/core/validation.py +0 -0
  33. {hypercomplex_engine-0.6.0 → hypercomplex_engine-0.7}/hypercomplex_engine/core/vectorized/__init__.py +0 -0
  34. {hypercomplex_engine-0.6.0 → hypercomplex_engine-0.7}/hypercomplex_engine/core/vectorized/vectorized_standard.py +0 -0
  35. {hypercomplex_engine-0.6.0 → hypercomplex_engine-0.7}/hypercomplex_engine/facade.py +0 -0
  36. {hypercomplex_engine-0.6.0 → hypercomplex_engine-0.7}/hypercomplex_engine/printer/__init__.py +0 -0
  37. {hypercomplex_engine-0.6.0 → hypercomplex_engine-0.7}/hypercomplex_engine/printer/cd_format.py +0 -0
  38. {hypercomplex_engine-0.6.0 → hypercomplex_engine-0.7}/hypercomplex_engine/printer/cd_table_printer.py +0 -0
  39. {hypercomplex_engine-0.6.0 → hypercomplex_engine-0.7}/hypercomplex_engine.egg-info/dependency_links.txt +0 -0
  40. {hypercomplex_engine-0.6.0 → hypercomplex_engine-0.7}/hypercomplex_engine.egg-info/requires.txt +0 -0
  41. {hypercomplex_engine-0.6.0 → hypercomplex_engine-0.7}/hypercomplex_engine.egg-info/top_level.txt +0 -0
  42. {hypercomplex_engine-0.6.0 → hypercomplex_engine-0.7}/setup.cfg +0 -0
  43. {hypercomplex_engine-0.6.0 → hypercomplex_engine-0.7}/tests/test_dual_tuple_regression.py +0 -0
  44. {hypercomplex_engine-0.6.0 → hypercomplex_engine-0.7}/tests/test_fast_mode.py +0 -0
  45. {hypercomplex_engine-0.6.0 → hypercomplex_engine-0.7}/tests/test_fixes_0_4.py +0 -0
  46. {hypercomplex_engine-0.6.0 → hypercomplex_engine-0.7}/tests/test_mega_mother.py +0 -0
  47. {hypercomplex_engine-0.6.0 → hypercomplex_engine-0.7}/tests/test_split_dim.py +0 -0
  48. {hypercomplex_engine-0.6.0 → hypercomplex_engine-0.7}/tests/test_strict_dual_3tuple.py +0 -0
  49. {hypercomplex_engine-0.6.0 → hypercomplex_engine-0.7}/tests/test_vectorized_extended.py +0 -0
  50. {hypercomplex_engine-0.6.0 → hypercomplex_engine-0.7}/tests/test_vectorized_standard.py +0 -0
@@ -1,6 +1,6 @@
1
1
  Metadata-Version: 2.4
2
2
  Name: hypercomplex-engine
3
- Version: 0.6.0
3
+ Version: 0.7
4
4
  Summary: Fast O(1)/O(n) multiplication engine for arbitrary dimensions and table generator for ordinary, split, and dual Cayley-Dickson algebras.
5
5
  Author-email: Maher Ben Abdessalem <ba.maher94@gmail.com>
6
6
  License-Expression: Apache-2.0
@@ -27,8 +27,13 @@ License-File: NOTICE
27
27
  Requires-Dist: numpy>=1.22.0
28
28
  Dynamic: license-file
29
29
 
30
+ <p align="center">
31
+ <img src="asset/logo.jpeg" alt="Project Banner" width="100%">
32
+ </p>
33
+
30
34
  # hypercomplex-engine
31
35
 
36
+
32
37
  [![License: Apache 2.0](https://img.shields.io/badge/License-Apache%202.0-blue.svg)](https://www.apache.org/licenses/LICENSE-2.0)
33
38
  [![Python 3.10+](https://img.shields.io/badge/python-3.10+-blue.svg)](https://www.python.org/downloads/)
34
39
  [![GitHub Repo](https://img.shields.io/badge/GitHub-maher1719%2Fhypercomplex--engine-black?logo=github)](https://github.com/maher1719/hypercomplex-engine)
@@ -46,10 +51,16 @@ This library provides the computational substrate for high-dimensional hypercomp
46
51
  - **Full multiplication table generation** for standard, split, and dual algebras.
47
52
  - **O(n) holographic** table-free recursive descent multiplication.
48
53
  - **O(1) fast bitwise** closed-form multiplication.
54
+ - **Version 0.6** Added **vectorized numpy** for standard hypercomplex!
55
+ - Version 0.7 Added arbitrary-width engines that break the 64-bit SIMD ceiling:
56
+ **BitPlaneStandard** (bit-sliced) and **GradedSparseStandard** (graded-sparse,
57
+ memory-optimal via Wilmot graded notation). Both cross-validated against the
58
+ proven O(1) evaluator at widths up to 10,000 bits.
49
59
  - **Integer, graded, and LaTeX** notation formatting.
50
60
  - **CSV export** for tables (matrix and long formats).
51
61
  - A **simple facade API** for everyday use, and direct low-level classes for advanced physics/math engines.
52
62
 
63
+
53
64
  ---
54
65
 
55
66
  ## Scope and limitations
@@ -472,6 +483,48 @@ print(result)
472
483
 
473
484
  ---
474
485
 
486
+ ### Arbitrary-width engines (breaking the 64-bit ceiling)
487
+
488
+ The scalar `fast` and `holographic` engines support arbitrary precision natively
489
+ (Python big integers), but the **vectorized** engine is capped at 64 bits because
490
+ SIMD lanes are fixed-width. Version 0.7 adds two arbitrary-width engines that
491
+ remove this ceiling:
492
+
493
+ | Engine | Cost | Memory | Best for |
494
+ | --- | --- | --- | --- |
495
+ | `BitPlaneStandard` | O(B) per pair, O(N·B/L) batch | O(N·B) | dense arbitrary-width batches |
496
+ | `GradedSparseStandard` | O(p) per pair, O(N·p) batch | O(N·p) | sparse arbitrary-width indices (p ≪ B) |
497
+
498
+ Here `B` is the bit-width and `p` is the number of set bits (popcount). For the
499
+ sparse indices typical of symbolic and zero-divisor workloads, `GradedSparse`
500
+ is memory-optimal because its cost scales with the information content `p`,
501
+ not the ambient width `B`.
502
+
503
+ **BitPlaneStandard** (bit-sliced):
504
+ ```python
505
+ from hypercomplex_engine import BitPlaneStandard
506
+
507
+ bp = BitPlaneStandard()
508
+ # Indices wider than 64 bits — impossible for np.uint64, fine here
509
+ i_arr = [2**200 + 5, 2**300, 7]
510
+ j_arr = [3, 2**150, 2**100]
511
+ signs, indices = bp.multiply_indices(i_arr, j_arr)
512
+ # signs[k] in {-1, +1}, indices[k] = i_arr[k] ^ j_arr[k]
513
+ ```
514
+
515
+ ```python
516
+ from hypercomplex_engine import GradedSparseStandard
517
+
518
+ gs = GradedSparseStandard()
519
+ sign, idx = gs.multiply_indices(2**1000 + 3, 5)
520
+
521
+ # Graded (Wilmot) notation: generator levels, o_k = bit position k-1
522
+ print(gs.graded_to_notation(gs.int_to_graded(idx))) # e.g. "o1,2,1001"
523
+ ```
524
+
525
+
526
+
527
+
475
528
  ## Formatting modes
476
529
 
477
530
  | Mode | Example |
@@ -984,50 +1037,51 @@ The test suite validates:
984
1037
  # Repository Structure
985
1038
 
986
1039
  ```text
987
- hypercomplex-engine/
988
- ├── examples/
989
- │ ├── direct_implementation/
990
- │ │ └── full_table_builder_simple.py
991
- │ └── uses/
992
- │ ├── outputs/
993
- │ └── use.ipynb
994
- ├── hypercomplex/
995
- │ ├── core/
996
- │ │ ├── basis_element.py
997
- │ │ ├── basis_notation.py
998
- │ │ ├── validation.py
999
- │ │ ├── table_builder/
1000
- │ │ │ ├── common.py
1001
- │ │ │ ├── standard.py
1002
- │ │ │ ├── split.py
1003
- │ │ │ └── dual.py
1004
- │ │ ├── holographic/
1005
- │ │ │ ├── standard.py
1006
- │ │ │ ├── split.py
1007
- │ │ │ └── dual.py
1008
- │ │ └── fast/
1009
- │ │ ├── bit_utils.py
1010
- │ │ ├── fast_standard.py
1011
- │ │ ├── fast_split.py
1012
- │ │ └── fast_dual.py
1013
- │ ├── printer/
1014
- │ │ ├── cd_format.py
1015
- │ │ └── cd_table_printer.py
1016
- │ ├── facade.py
1017
- │ └── __init__.py
1018
- ├── tests/
1019
- │ ├── test_algebra.py
1020
- │ ├── test_fast_mode.py
1021
- │ ├── test_holographic_vs_table.py
1022
- │ └── test_mega_mother.py
1023
- ├── LICENSE
1024
- ├── README.md
1025
- └── pyproject.toml
1040
+ hypercomplex_engine
1041
+ ├── asset
1042
+ │ ├── logo.jpeg
1043
+ │ └── logo.svg
1044
+ ├── core
1045
+ │ ├── basis_element.py
1046
+ │ ├── basis_notation.py
1047
+ │ ├── bitplane
1048
+ │ │ ├── bitplane_standard.py
1049
+ │ │ └── __init__.py
1050
+ │ ├── fast
1051
+ │ │ ├── bit_utils.py
1052
+ │ │ ├── fast_dual.py
1053
+ │ │ ├── fast_split.py
1054
+ │ │ ├── fast_standard.py
1055
+ │ │ └── __init__.py
1056
+ │ ├── graded
1057
+ │ │ ├── graded_sparse_standard.py
1058
+ │ │ └── __init__.py
1059
+ │ ├── holographic
1060
+ │ │ ├── dual.py
1061
+ │ │ ├── __init__.py
1062
+ │ │ ├── split.py
1063
+ │ │ └── standard.py
1064
+ │ ├── __init__.py
1065
+ │ ├── table_builder
1066
+ │ │ ├── common.py
1067
+ │ │ ├── dual.py
1068
+ │ │ ├── __init__.py
1069
+ │ │ ├── split.py
1070
+ │ │ └── standard.py
1071
+ │ ├── validation.py
1072
+ │ └── vectorized
1073
+ │ ├── __init__.py
1074
+ │ └── vectorized_standard.py
1075
+ ├── facade.py
1076
+ ├── __init__.py
1077
+ └── printer
1078
+ ├── cd_format.py
1079
+ ├── cd_table_printer.py
1080
+ └── __init__.py
1026
1081
  ```
1027
1082
 
1028
1083
  # Scope, strengths and limitations
1029
1084
 
1030
- > **Status: 0.4.x, pre-1.0.** The API can still change. Read this section before building on the package.
1031
1085
 
1032
1086
  ## What this package is
1033
1087
 
@@ -1108,6 +1162,24 @@ Use `estimate_table_bytes(kind, n)` to check a size, and pass a larger `max_byte
1108
1162
 
1109
1163
  ---
1110
1164
 
1165
+
1166
+ ---
1167
+
1168
+ ## Summary of What's New (for your own tracking)
1169
+
1170
+ | Addition | Where |
1171
+ | :--- | :--- |
1172
+ | Version 0.7 announcement | Features list |
1173
+ | Arbitrary-width engines section + examples | Intermediate Use |
1174
+ | Expanded complexity table (BitPlane, GradedSparse) | Complexity |
1175
+ | New directories (`bitplane/`, `graded/`) | Repository Structure |
1176
+ | New test files | Testing |
1177
+ | New imports | Advanced Use |
1178
+
1179
+ Once you paste these in, the README will reflect the **complete engine family**: table builder → holographic O(n) → fast O(1) → vectorized (≤64-bit) → **BitPlane + GradedSparse (arbitrary-width)**. That's the full arc of the paper, now mirrored in the package docs.
1180
+
1181
+ Want me to also draft a short **"What's New in 0.7"** changelog block for the very top, or update the **Citation** block to point at the revised preprint?
1182
+
1111
1183
  # Citation
1112
1184
 
1113
1185
  If you use this engine in your research, physics simulations, or geometric deep learning models, please cite the underlying theoretical preprints:
@@ -1,5 +1,10 @@
1
+ <p align="center">
2
+ <img src="asset/logo.jpeg" alt="Project Banner" width="100%">
3
+ </p>
4
+
1
5
  # hypercomplex-engine
2
6
 
7
+
3
8
  [![License: Apache 2.0](https://img.shields.io/badge/License-Apache%202.0-blue.svg)](https://www.apache.org/licenses/LICENSE-2.0)
4
9
  [![Python 3.10+](https://img.shields.io/badge/python-3.10+-blue.svg)](https://www.python.org/downloads/)
5
10
  [![GitHub Repo](https://img.shields.io/badge/GitHub-maher1719%2Fhypercomplex--engine-black?logo=github)](https://github.com/maher1719/hypercomplex-engine)
@@ -17,10 +22,16 @@ This library provides the computational substrate for high-dimensional hypercomp
17
22
  - **Full multiplication table generation** for standard, split, and dual algebras.
18
23
  - **O(n) holographic** table-free recursive descent multiplication.
19
24
  - **O(1) fast bitwise** closed-form multiplication.
25
+ - **Version 0.6** Added **vectorized numpy** for standard hypercomplex!
26
+ - Version 0.7 Added arbitrary-width engines that break the 64-bit SIMD ceiling:
27
+ **BitPlaneStandard** (bit-sliced) and **GradedSparseStandard** (graded-sparse,
28
+ memory-optimal via Wilmot graded notation). Both cross-validated against the
29
+ proven O(1) evaluator at widths up to 10,000 bits.
20
30
  - **Integer, graded, and LaTeX** notation formatting.
21
31
  - **CSV export** for tables (matrix and long formats).
22
32
  - A **simple facade API** for everyday use, and direct low-level classes for advanced physics/math engines.
23
33
 
34
+
24
35
  ---
25
36
 
26
37
  ## Scope and limitations
@@ -443,6 +454,48 @@ print(result)
443
454
 
444
455
  ---
445
456
 
457
+ ### Arbitrary-width engines (breaking the 64-bit ceiling)
458
+
459
+ The scalar `fast` and `holographic` engines support arbitrary precision natively
460
+ (Python big integers), but the **vectorized** engine is capped at 64 bits because
461
+ SIMD lanes are fixed-width. Version 0.7 adds two arbitrary-width engines that
462
+ remove this ceiling:
463
+
464
+ | Engine | Cost | Memory | Best for |
465
+ | --- | --- | --- | --- |
466
+ | `BitPlaneStandard` | O(B) per pair, O(N·B/L) batch | O(N·B) | dense arbitrary-width batches |
467
+ | `GradedSparseStandard` | O(p) per pair, O(N·p) batch | O(N·p) | sparse arbitrary-width indices (p ≪ B) |
468
+
469
+ Here `B` is the bit-width and `p` is the number of set bits (popcount). For the
470
+ sparse indices typical of symbolic and zero-divisor workloads, `GradedSparse`
471
+ is memory-optimal because its cost scales with the information content `p`,
472
+ not the ambient width `B`.
473
+
474
+ **BitPlaneStandard** (bit-sliced):
475
+ ```python
476
+ from hypercomplex_engine import BitPlaneStandard
477
+
478
+ bp = BitPlaneStandard()
479
+ # Indices wider than 64 bits — impossible for np.uint64, fine here
480
+ i_arr = [2**200 + 5, 2**300, 7]
481
+ j_arr = [3, 2**150, 2**100]
482
+ signs, indices = bp.multiply_indices(i_arr, j_arr)
483
+ # signs[k] in {-1, +1}, indices[k] = i_arr[k] ^ j_arr[k]
484
+ ```
485
+
486
+ ```python
487
+ from hypercomplex_engine import GradedSparseStandard
488
+
489
+ gs = GradedSparseStandard()
490
+ sign, idx = gs.multiply_indices(2**1000 + 3, 5)
491
+
492
+ # Graded (Wilmot) notation: generator levels, o_k = bit position k-1
493
+ print(gs.graded_to_notation(gs.int_to_graded(idx))) # e.g. "o1,2,1001"
494
+ ```
495
+
496
+
497
+
498
+
446
499
  ## Formatting modes
447
500
 
448
501
  | Mode | Example |
@@ -955,50 +1008,51 @@ The test suite validates:
955
1008
  # Repository Structure
956
1009
 
957
1010
  ```text
958
- hypercomplex-engine/
959
- ├── examples/
960
- │ ├── direct_implementation/
961
- │ │ └── full_table_builder_simple.py
962
- │ └── uses/
963
- │ ├── outputs/
964
- │ └── use.ipynb
965
- ├── hypercomplex/
966
- │ ├── core/
967
- │ │ ├── basis_element.py
968
- │ │ ├── basis_notation.py
969
- │ │ ├── validation.py
970
- │ │ ├── table_builder/
971
- │ │ │ ├── common.py
972
- │ │ │ ├── standard.py
973
- │ │ │ ├── split.py
974
- │ │ │ └── dual.py
975
- │ │ ├── holographic/
976
- │ │ │ ├── standard.py
977
- │ │ │ ├── split.py
978
- │ │ │ └── dual.py
979
- │ │ └── fast/
980
- │ │ ├── bit_utils.py
981
- │ │ ├── fast_standard.py
982
- │ │ ├── fast_split.py
983
- │ │ └── fast_dual.py
984
- │ ├── printer/
985
- │ │ ├── cd_format.py
986
- │ │ └── cd_table_printer.py
987
- │ ├── facade.py
988
- │ └── __init__.py
989
- ├── tests/
990
- │ ├── test_algebra.py
991
- │ ├── test_fast_mode.py
992
- │ ├── test_holographic_vs_table.py
993
- │ └── test_mega_mother.py
994
- ├── LICENSE
995
- ├── README.md
996
- └── pyproject.toml
1011
+ hypercomplex_engine
1012
+ ├── asset
1013
+ │ ├── logo.jpeg
1014
+ │ └── logo.svg
1015
+ ├── core
1016
+ │ ├── basis_element.py
1017
+ │ ├── basis_notation.py
1018
+ │ ├── bitplane
1019
+ │ │ ├── bitplane_standard.py
1020
+ │ │ └── __init__.py
1021
+ │ ├── fast
1022
+ │ │ ├── bit_utils.py
1023
+ │ │ ├── fast_dual.py
1024
+ │ │ ├── fast_split.py
1025
+ │ │ ├── fast_standard.py
1026
+ │ │ └── __init__.py
1027
+ │ ├── graded
1028
+ │ │ ├── graded_sparse_standard.py
1029
+ │ │ └── __init__.py
1030
+ │ ├── holographic
1031
+ │ │ ├── dual.py
1032
+ │ │ ├── __init__.py
1033
+ │ │ ├── split.py
1034
+ │ │ └── standard.py
1035
+ │ ├── __init__.py
1036
+ │ ├── table_builder
1037
+ │ │ ├── common.py
1038
+ │ │ ├── dual.py
1039
+ │ │ ├── __init__.py
1040
+ │ │ ├── split.py
1041
+ │ │ └── standard.py
1042
+ │ ├── validation.py
1043
+ │ └── vectorized
1044
+ │ ├── __init__.py
1045
+ │ └── vectorized_standard.py
1046
+ ├── facade.py
1047
+ ├── __init__.py
1048
+ └── printer
1049
+ ├── cd_format.py
1050
+ ├── cd_table_printer.py
1051
+ └── __init__.py
997
1052
  ```
998
1053
 
999
1054
  # Scope, strengths and limitations
1000
1055
 
1001
- > **Status: 0.4.x, pre-1.0.** The API can still change. Read this section before building on the package.
1002
1056
 
1003
1057
  ## What this package is
1004
1058
 
@@ -1079,6 +1133,24 @@ Use `estimate_table_bytes(kind, n)` to check a size, and pass a larger `max_byte
1079
1133
 
1080
1134
  ---
1081
1135
 
1136
+
1137
+ ---
1138
+
1139
+ ## Summary of What's New (for your own tracking)
1140
+
1141
+ | Addition | Where |
1142
+ | :--- | :--- |
1143
+ | Version 0.7 announcement | Features list |
1144
+ | Arbitrary-width engines section + examples | Intermediate Use |
1145
+ | Expanded complexity table (BitPlane, GradedSparse) | Complexity |
1146
+ | New directories (`bitplane/`, `graded/`) | Repository Structure |
1147
+ | New test files | Testing |
1148
+ | New imports | Advanced Use |
1149
+
1150
+ Once you paste these in, the README will reflect the **complete engine family**: table builder → holographic O(n) → fast O(1) → vectorized (≤64-bit) → **BitPlane + GradedSparse (arbitrary-width)**. That's the full arc of the paper, now mirrored in the package docs.
1151
+
1152
+ Want me to also draft a short **"What's New in 0.7"** changelog block for the very top, or update the **Citation** block to point at the revised preprint?
1153
+
1082
1154
  # Citation
1083
1155
 
1084
1156
  If you use this engine in your research, physics simulations, or geometric deep learning models, please cite the underlying theoretical preprints:
@@ -30,7 +30,13 @@ from .core import (
30
30
  FastSplit,
31
31
  FastDual,
32
32
 
33
- VectorizedStandard
33
+ VectorizedStandard,
34
+
35
+ BitPlaneStandard,
36
+
37
+ GradedSparseStandard,
38
+
39
+
34
40
  )
35
41
 
36
42
  from .printer import (
@@ -68,7 +74,11 @@ __all__ = [
68
74
  "FastDual",
69
75
 
70
76
  #VectorizedStandard
71
- "VectorizedStandard"
77
+ "VectorizedStandard",
78
+
79
+ "BitPlaneStandard",
80
+
81
+ "GradedSparseStandard",
72
82
 
73
83
  # Printer / formatter
74
84
  "CDFormat",
@@ -24,6 +24,15 @@ from .vectorized import (
24
24
  VectorizedStandard
25
25
  )
26
26
 
27
+ from .bitplane import (
28
+ BitPlaneStandard
29
+ )
30
+
31
+
32
+ from .graded import (
33
+ GradedSparseStandard
34
+ )
35
+
27
36
  __all__ = [
28
37
  "BasisElement",
29
38
  "BasisNotation",
@@ -42,4 +51,8 @@ __all__ = [
42
51
  "FastDual",
43
52
 
44
53
  "VectorizedStandard",
54
+
55
+ "BitPlaneStandard"
56
+
57
+ "GradedSparseStandard"
45
58
  ]
@@ -0,0 +1,5 @@
1
+ from .bitplane_standard import BitPlaneStandard
2
+
3
+ __all__= [
4
+ "BitPlaneStandard"
5
+ ]
@@ -0,0 +1,162 @@
1
+ import numpy as np
2
+
3
+
4
+ class BitPlaneStandard:
5
+ """
6
+ Arbitrary-width SIMD (bit-sliced) standard Cayley-Dickson O(1) multiplier.
7
+
8
+ Breaks the 64-bit SIMD-lane ceiling of VectorizedStandard by representing
9
+ each index as a column of bits (bit-slicing). Every word operation of the
10
+ O(1) evaluator (Definition def:o1) lifts to a lane-parallel boolean
11
+ operation over the bit-planes.
12
+
13
+ Representation:
14
+ A batch of N indices of width B is stored as a bit-plane matrix of
15
+ shape (N, B), dtype uint8, where entry (r, b) holds bit b of index r
16
+ (b = 0 is the LSB).
17
+
18
+ Complexity (paper Table tab:complexity):
19
+ Per-pair: O(B) bit-plane work
20
+ Batch of N: O(N*B / L) wall-clock, O(N*B) space, L = SIMD lanes
21
+ Bit-width: unbounded (no 64-bit ceiling)
22
+
23
+ Input / output convention:
24
+ multiply_indices(i_arr, j_arr) -> (signs_array, indices_list)
25
+ signs_array[k] in {-1, +1}, indices_list[k] = i_arr[k] ^ j_arr[k]
26
+ """
27
+
28
+ # ---------- representation: big-int <-> bit-plane ----------
29
+ @staticmethod
30
+ def ints_to_bitplane(vals, B):
31
+ """
32
+ Convert a sequence of Python big-ints to an (N, B) uint8 bit-plane.
33
+ Entry (n, b) = bit b of vals[n]; b = 0 is the LSB.
34
+ """
35
+ N = len(vals)
36
+ out = np.zeros((N, B), dtype=np.uint8)
37
+ for n, v in enumerate(vals):
38
+ v = int(v)
39
+ if v == 0:
40
+ continue
41
+ nbytes = (min(B, v.bit_length()) + 7) // 8
42
+ bits = np.unpackbits(
43
+ np.frombuffer(v.to_bytes(nbytes, 'little'), dtype=np.uint8),
44
+ bitorder='little')
45
+ m = min(B, len(bits))
46
+ out[n, :m] = bits[:m]
47
+ return out
48
+
49
+ @staticmethod
50
+ def bitplane_to_ints(bits):
51
+ """
52
+ Convert an (N, B) bit-plane back to a list of Python big-ints.
53
+ """
54
+ N, B = bits.shape
55
+ out = []
56
+ nbytes = (B + 7) // 8
57
+ for n in range(N):
58
+ packed = np.packbits(bits[n], bitorder='little')
59
+ out.append(int.from_bytes(packed.tobytes()[:nbytes], 'little'))
60
+ return out
61
+
62
+ @staticmethod
63
+ def _required_width(i_arr, j_arr):
64
+ """Minimal bit-width B that holds every index in both batches."""
65
+ B = 1
66
+ for v in i_arr:
67
+ bl = int(v).bit_length()
68
+ if bl > B:
69
+ B = bl
70
+ for v in j_arr:
71
+ bl = int(v).bit_length()
72
+ if bl > B:
73
+ B = bl
74
+ return B
75
+
76
+ # ---------- core O(1) evaluator over bit-planes ----------
77
+ def multiply_indices_bitplane(self, i_bits, j_bits):
78
+ """
79
+ Vectorized arbitrary-width O(1) multiplication on bit-planes.
80
+
81
+ Args:
82
+ i_bits: (N, B) uint8 bit-plane for the first indices
83
+ j_bits: (N, B) uint8 bit-plane for the second indices
84
+
85
+ Returns:
86
+ (signs, idx_bits):
87
+ signs : (N,) int8 array, +1 / -1
88
+ idx_bits: (N, B) uint8 bit-plane of the result indices i^j
89
+ """
90
+ i_bits = np.asarray(i_bits, dtype=np.uint8)
91
+ j_bits = np.asarray(j_bits, dtype=np.uint8)
92
+ N, B = i_bits.shape
93
+ ar = np.arange(N)
94
+
95
+ idx = i_bits ^ j_bits # result index = XOR
96
+
97
+ # structural masks
98
+ mask_zero = (~i_bits.any(axis=1)) | (~j_bits.any(axis=1))
99
+ mask_diag = ((i_bits == j_bits).all(axis=1)) & ~mask_zero
100
+
101
+ # nu2 via first-set-bit (argmax returns the index of the first 1)
102
+ t = np.argmax(idx, axis=1)
103
+ ti = np.argmax(i_bits, axis=1)
104
+ tj = np.argmax(j_bits, axis=1)
105
+
106
+ # branch selection
107
+ cond1 = (t >= ti) & (t >= tj) # diagonal break
108
+ cond2 = (~cond1) & (ti >= tj) # i-axis break
109
+ cond3 = ~cond1 & ~cond2 # j-axis break
110
+
111
+ # branch signs
112
+ s1 = 2 * i_bits[ar, t].astype(np.int64) - 1
113
+ # i-axis: delta = -1 always here (Corollary cor:iaxis-collapse);
114
+ # kept in general form to mirror the scalar evaluator exactly.
115
+ delta = np.where(tj == ti, 1, -1)
116
+ s2 = np.where(j_bits[ar, ti] == 0, delta, -delta)
117
+ s3 = 1 - 2 * i_bits[ar, tj].astype(np.int64)
118
+ s = np.where(cond1, s1, np.where(cond2, s2, s3))
119
+
120
+ # higher-bit parity via reverse cumulative sum
121
+ k = np.where(cond1, t + 1, np.where(cond2, ti + 1, tj + 1))
122
+ or_bits = i_bits | j_bits
123
+ rev_cumsum = np.cumsum(or_bits[:, ::-1], axis=1)[:, ::-1]
124
+ parity_count = np.zeros(N, dtype=np.int64)
125
+ valid = k < B
126
+ parity_count[valid] = rev_cumsum[ar[valid], k[valid]]
127
+ s = np.where((parity_count & 1) == 1, -s, s)
128
+
129
+ # structural overrides
130
+ s = np.where(mask_zero, 1, s)
131
+ s = np.where(mask_diag, -1, s)
132
+
133
+ return s.astype(np.int8), idx
134
+
135
+ # ---------- convenience: Python ints in, ints out ----------
136
+ def multiply_indices(self, i_arr, j_arr):
137
+ """
138
+ Convenience wrapper: sequences of Python big-ints in, integer results out.
139
+ Mirrors FastStandard.multiply_indices but vectorized and arbitrary-width.
140
+
141
+ Args:
142
+ i_arr: sequence of first indices (Python ints, any width)
143
+ j_arr: sequence of second indices (Python ints, any width)
144
+
145
+ Returns:
146
+ (signs, indices):
147
+ signs : (N,) int8 array, +1 / -1
148
+ indices : list of N Python ints, indices[k] = i_arr[k] ^ j_arr[k]
149
+ """
150
+ i_arr = list(i_arr)
151
+ j_arr = list(j_arr)
152
+ if len(i_arr) != len(j_arr):
153
+ raise ValueError("i_arr and j_arr must have the same length")
154
+ if len(i_arr) == 0:
155
+ return np.zeros(0, dtype=np.int8), []
156
+
157
+ B = self._required_width(i_arr, j_arr)
158
+ i_bits = self.ints_to_bitplane(i_arr, B)
159
+ j_bits = self.ints_to_bitplane(j_arr, B)
160
+ signs, idx_bits = self.multiply_indices_bitplane(i_bits, j_bits)
161
+ indices = self.bitplane_to_ints(idx_bits)
162
+ return signs, indices
@@ -0,0 +1,5 @@
1
+ from .graded_sparse_standard import GradedSparseStandard
2
+
3
+ __all__ = [
4
+ "GradedSparseStandard"
5
+ ]