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.
- {hypercomplex_engine-0.6.0/hypercomplex_engine.egg-info → hypercomplex_engine-0.7}/PKG-INFO +113 -41
- {hypercomplex_engine-0.6.0 → hypercomplex_engine-0.7}/README.md +112 -40
- {hypercomplex_engine-0.6.0 → hypercomplex_engine-0.7}/hypercomplex_engine/__init__.py +12 -2
- {hypercomplex_engine-0.6.0 → hypercomplex_engine-0.7}/hypercomplex_engine/core/__init__.py +13 -0
- hypercomplex_engine-0.7/hypercomplex_engine/core/bitplane/__init__.py +5 -0
- hypercomplex_engine-0.7/hypercomplex_engine/core/bitplane/bitplane_standard.py +162 -0
- hypercomplex_engine-0.7/hypercomplex_engine/core/graded/__init__.py +5 -0
- hypercomplex_engine-0.7/hypercomplex_engine/core/graded/graded_sparse_standard.py +125 -0
- {hypercomplex_engine-0.6.0 → hypercomplex_engine-0.7/hypercomplex_engine.egg-info}/PKG-INFO +113 -41
- {hypercomplex_engine-0.6.0 → hypercomplex_engine-0.7}/hypercomplex_engine.egg-info/SOURCES.txt +6 -0
- {hypercomplex_engine-0.6.0 → hypercomplex_engine-0.7}/pyproject.toml +11 -1
- hypercomplex_engine-0.7/tests/test_bitplane_standard.py +128 -0
- hypercomplex_engine-0.7/tests/test_graded_sparse.py +285 -0
- {hypercomplex_engine-0.6.0 → hypercomplex_engine-0.7}/LICENSE +0 -0
- {hypercomplex_engine-0.6.0 → hypercomplex_engine-0.7}/NOTICE +0 -0
- {hypercomplex_engine-0.6.0 → hypercomplex_engine-0.7}/hypercomplex_engine/core/basis_element.py +0 -0
- {hypercomplex_engine-0.6.0 → hypercomplex_engine-0.7}/hypercomplex_engine/core/basis_notation.py +0 -0
- {hypercomplex_engine-0.6.0 → hypercomplex_engine-0.7}/hypercomplex_engine/core/fast/__init__.py +0 -0
- {hypercomplex_engine-0.6.0 → hypercomplex_engine-0.7}/hypercomplex_engine/core/fast/bit_utils.py +0 -0
- {hypercomplex_engine-0.6.0 → hypercomplex_engine-0.7}/hypercomplex_engine/core/fast/fast_dual.py +0 -0
- {hypercomplex_engine-0.6.0 → hypercomplex_engine-0.7}/hypercomplex_engine/core/fast/fast_split.py +0 -0
- {hypercomplex_engine-0.6.0 → hypercomplex_engine-0.7}/hypercomplex_engine/core/fast/fast_standard.py +0 -0
- {hypercomplex_engine-0.6.0 → hypercomplex_engine-0.7}/hypercomplex_engine/core/holographic/__init__.py +0 -0
- {hypercomplex_engine-0.6.0 → hypercomplex_engine-0.7}/hypercomplex_engine/core/holographic/dual.py +0 -0
- {hypercomplex_engine-0.6.0 → hypercomplex_engine-0.7}/hypercomplex_engine/core/holographic/split.py +0 -0
- {hypercomplex_engine-0.6.0 → hypercomplex_engine-0.7}/hypercomplex_engine/core/holographic/standard.py +0 -0
- {hypercomplex_engine-0.6.0 → hypercomplex_engine-0.7}/hypercomplex_engine/core/table_builder/__init__.py +0 -0
- {hypercomplex_engine-0.6.0 → hypercomplex_engine-0.7}/hypercomplex_engine/core/table_builder/common.py +0 -0
- {hypercomplex_engine-0.6.0 → hypercomplex_engine-0.7}/hypercomplex_engine/core/table_builder/dual.py +0 -0
- {hypercomplex_engine-0.6.0 → hypercomplex_engine-0.7}/hypercomplex_engine/core/table_builder/split.py +0 -0
- {hypercomplex_engine-0.6.0 → hypercomplex_engine-0.7}/hypercomplex_engine/core/table_builder/standard.py +0 -0
- {hypercomplex_engine-0.6.0 → hypercomplex_engine-0.7}/hypercomplex_engine/core/validation.py +0 -0
- {hypercomplex_engine-0.6.0 → hypercomplex_engine-0.7}/hypercomplex_engine/core/vectorized/__init__.py +0 -0
- {hypercomplex_engine-0.6.0 → hypercomplex_engine-0.7}/hypercomplex_engine/core/vectorized/vectorized_standard.py +0 -0
- {hypercomplex_engine-0.6.0 → hypercomplex_engine-0.7}/hypercomplex_engine/facade.py +0 -0
- {hypercomplex_engine-0.6.0 → hypercomplex_engine-0.7}/hypercomplex_engine/printer/__init__.py +0 -0
- {hypercomplex_engine-0.6.0 → hypercomplex_engine-0.7}/hypercomplex_engine/printer/cd_format.py +0 -0
- {hypercomplex_engine-0.6.0 → hypercomplex_engine-0.7}/hypercomplex_engine/printer/cd_table_printer.py +0 -0
- {hypercomplex_engine-0.6.0 → hypercomplex_engine-0.7}/hypercomplex_engine.egg-info/dependency_links.txt +0 -0
- {hypercomplex_engine-0.6.0 → hypercomplex_engine-0.7}/hypercomplex_engine.egg-info/requires.txt +0 -0
- {hypercomplex_engine-0.6.0 → hypercomplex_engine-0.7}/hypercomplex_engine.egg-info/top_level.txt +0 -0
- {hypercomplex_engine-0.6.0 → hypercomplex_engine-0.7}/setup.cfg +0 -0
- {hypercomplex_engine-0.6.0 → hypercomplex_engine-0.7}/tests/test_dual_tuple_regression.py +0 -0
- {hypercomplex_engine-0.6.0 → hypercomplex_engine-0.7}/tests/test_fast_mode.py +0 -0
- {hypercomplex_engine-0.6.0 → hypercomplex_engine-0.7}/tests/test_fixes_0_4.py +0 -0
- {hypercomplex_engine-0.6.0 → hypercomplex_engine-0.7}/tests/test_mega_mother.py +0 -0
- {hypercomplex_engine-0.6.0 → hypercomplex_engine-0.7}/tests/test_split_dim.py +0 -0
- {hypercomplex_engine-0.6.0 → hypercomplex_engine-0.7}/tests/test_strict_dual_3tuple.py +0 -0
- {hypercomplex_engine-0.6.0 → hypercomplex_engine-0.7}/tests/test_vectorized_extended.py +0 -0
- {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.
|
|
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
|
[](https://www.apache.org/licenses/LICENSE-2.0)
|
|
33
38
|
[](https://www.python.org/downloads/)
|
|
34
39
|
[](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
|
-
|
|
988
|
-
├──
|
|
989
|
-
│ ├──
|
|
990
|
-
│
|
|
991
|
-
|
|
992
|
-
│
|
|
993
|
-
│
|
|
994
|
-
├──
|
|
995
|
-
│ ├──
|
|
996
|
-
│ │
|
|
997
|
-
│
|
|
998
|
-
│ │ ├──
|
|
999
|
-
│ │ ├──
|
|
1000
|
-
│ │
|
|
1001
|
-
│ │
|
|
1002
|
-
│ │
|
|
1003
|
-
│
|
|
1004
|
-
│ │ ├──
|
|
1005
|
-
│ │
|
|
1006
|
-
│
|
|
1007
|
-
│ │
|
|
1008
|
-
│ │
|
|
1009
|
-
│ │
|
|
1010
|
-
│ │
|
|
1011
|
-
│
|
|
1012
|
-
│
|
|
1013
|
-
│ ├──
|
|
1014
|
-
│ │ ├──
|
|
1015
|
-
│ │
|
|
1016
|
-
│ ├──
|
|
1017
|
-
│ └──
|
|
1018
|
-
├──
|
|
1019
|
-
│
|
|
1020
|
-
│
|
|
1021
|
-
│
|
|
1022
|
-
|
|
1023
|
-
├──
|
|
1024
|
-
|
|
1025
|
-
|
|
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
|
[](https://www.apache.org/licenses/LICENSE-2.0)
|
|
4
9
|
[](https://www.python.org/downloads/)
|
|
5
10
|
[](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
|
-
|
|
959
|
-
├──
|
|
960
|
-
│ ├──
|
|
961
|
-
│
|
|
962
|
-
|
|
963
|
-
│
|
|
964
|
-
│
|
|
965
|
-
├──
|
|
966
|
-
│ ├──
|
|
967
|
-
│ │
|
|
968
|
-
│
|
|
969
|
-
│ │ ├──
|
|
970
|
-
│ │ ├──
|
|
971
|
-
│ │
|
|
972
|
-
│ │
|
|
973
|
-
│ │
|
|
974
|
-
│
|
|
975
|
-
│ │ ├──
|
|
976
|
-
│ │
|
|
977
|
-
│
|
|
978
|
-
│ │
|
|
979
|
-
│ │
|
|
980
|
-
│ │
|
|
981
|
-
│ │
|
|
982
|
-
│
|
|
983
|
-
│
|
|
984
|
-
│ ├──
|
|
985
|
-
│ │ ├──
|
|
986
|
-
│ │
|
|
987
|
-
│ ├──
|
|
988
|
-
│ └──
|
|
989
|
-
├──
|
|
990
|
-
│
|
|
991
|
-
│
|
|
992
|
-
│
|
|
993
|
-
|
|
994
|
-
├──
|
|
995
|
-
|
|
996
|
-
|
|
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,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
|