hypercomplex-engine 0.6.0.1__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.7/PKG-INFO +1220 -0
- hypercomplex_engine-0.7/README.md +1191 -0
- {hypercomplex_engine-0.6.0.1 → hypercomplex_engine-0.7}/hypercomplex_engine/__init__.py +12 -2
- {hypercomplex_engine-0.6.0.1 → 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.7/hypercomplex_engine.egg-info/PKG-INFO +1220 -0
- {hypercomplex_engine-0.6.0.1 → hypercomplex_engine-0.7}/hypercomplex_engine.egg-info/SOURCES.txt +7 -0
- {hypercomplex_engine-0.6.0.1 → 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.1/PKG-INFO +0 -28
- hypercomplex_engine-0.6.0.1/hypercomplex_engine.egg-info/PKG-INFO +0 -28
- {hypercomplex_engine-0.6.0.1 → hypercomplex_engine-0.7}/LICENSE +0 -0
- {hypercomplex_engine-0.6.0.1 → hypercomplex_engine-0.7}/NOTICE +0 -0
- {hypercomplex_engine-0.6.0.1 → hypercomplex_engine-0.7}/hypercomplex_engine/core/basis_element.py +0 -0
- {hypercomplex_engine-0.6.0.1 → hypercomplex_engine-0.7}/hypercomplex_engine/core/basis_notation.py +0 -0
- {hypercomplex_engine-0.6.0.1 → hypercomplex_engine-0.7}/hypercomplex_engine/core/fast/__init__.py +0 -0
- {hypercomplex_engine-0.6.0.1 → hypercomplex_engine-0.7}/hypercomplex_engine/core/fast/bit_utils.py +0 -0
- {hypercomplex_engine-0.6.0.1 → hypercomplex_engine-0.7}/hypercomplex_engine/core/fast/fast_dual.py +0 -0
- {hypercomplex_engine-0.6.0.1 → hypercomplex_engine-0.7}/hypercomplex_engine/core/fast/fast_split.py +0 -0
- {hypercomplex_engine-0.6.0.1 → hypercomplex_engine-0.7}/hypercomplex_engine/core/fast/fast_standard.py +0 -0
- {hypercomplex_engine-0.6.0.1 → hypercomplex_engine-0.7}/hypercomplex_engine/core/holographic/__init__.py +0 -0
- {hypercomplex_engine-0.6.0.1 → hypercomplex_engine-0.7}/hypercomplex_engine/core/holographic/dual.py +0 -0
- {hypercomplex_engine-0.6.0.1 → hypercomplex_engine-0.7}/hypercomplex_engine/core/holographic/split.py +0 -0
- {hypercomplex_engine-0.6.0.1 → hypercomplex_engine-0.7}/hypercomplex_engine/core/holographic/standard.py +0 -0
- {hypercomplex_engine-0.6.0.1 → hypercomplex_engine-0.7}/hypercomplex_engine/core/table_builder/__init__.py +0 -0
- {hypercomplex_engine-0.6.0.1 → hypercomplex_engine-0.7}/hypercomplex_engine/core/table_builder/common.py +0 -0
- {hypercomplex_engine-0.6.0.1 → hypercomplex_engine-0.7}/hypercomplex_engine/core/table_builder/dual.py +0 -0
- {hypercomplex_engine-0.6.0.1 → hypercomplex_engine-0.7}/hypercomplex_engine/core/table_builder/split.py +0 -0
- {hypercomplex_engine-0.6.0.1 → hypercomplex_engine-0.7}/hypercomplex_engine/core/table_builder/standard.py +0 -0
- {hypercomplex_engine-0.6.0.1 → hypercomplex_engine-0.7}/hypercomplex_engine/core/validation.py +0 -0
- {hypercomplex_engine-0.6.0.1 → hypercomplex_engine-0.7}/hypercomplex_engine/core/vectorized/__init__.py +0 -0
- {hypercomplex_engine-0.6.0.1 → hypercomplex_engine-0.7}/hypercomplex_engine/core/vectorized/vectorized_standard.py +0 -0
- {hypercomplex_engine-0.6.0.1 → hypercomplex_engine-0.7}/hypercomplex_engine/facade.py +0 -0
- {hypercomplex_engine-0.6.0.1 → hypercomplex_engine-0.7}/hypercomplex_engine/printer/__init__.py +0 -0
- {hypercomplex_engine-0.6.0.1 → hypercomplex_engine-0.7}/hypercomplex_engine/printer/cd_format.py +0 -0
- {hypercomplex_engine-0.6.0.1 → hypercomplex_engine-0.7}/hypercomplex_engine/printer/cd_table_printer.py +0 -0
- {hypercomplex_engine-0.6.0.1 → hypercomplex_engine-0.7}/hypercomplex_engine.egg-info/dependency_links.txt +0 -0
- {hypercomplex_engine-0.6.0.1 → hypercomplex_engine-0.7}/hypercomplex_engine.egg-info/requires.txt +0 -0
- {hypercomplex_engine-0.6.0.1 → hypercomplex_engine-0.7}/hypercomplex_engine.egg-info/top_level.txt +0 -0
- {hypercomplex_engine-0.6.0.1 → hypercomplex_engine-0.7}/setup.cfg +0 -0
- {hypercomplex_engine-0.6.0.1 → hypercomplex_engine-0.7}/tests/test_dual_tuple_regression.py +0 -0
- {hypercomplex_engine-0.6.0.1 → hypercomplex_engine-0.7}/tests/test_fast_mode.py +0 -0
- {hypercomplex_engine-0.6.0.1 → hypercomplex_engine-0.7}/tests/test_fixes_0_4.py +0 -0
- {hypercomplex_engine-0.6.0.1 → hypercomplex_engine-0.7}/tests/test_mega_mother.py +0 -0
- {hypercomplex_engine-0.6.0.1 → hypercomplex_engine-0.7}/tests/test_split_dim.py +0 -0
- {hypercomplex_engine-0.6.0.1 → hypercomplex_engine-0.7}/tests/test_strict_dual_3tuple.py +0 -0
- {hypercomplex_engine-0.6.0.1 → hypercomplex_engine-0.7}/tests/test_vectorized_extended.py +0 -0
- {hypercomplex_engine-0.6.0.1 → hypercomplex_engine-0.7}/tests/test_vectorized_standard.py +0 -0
|
@@ -0,0 +1,1220 @@
|
|
|
1
|
+
Metadata-Version: 2.4
|
|
2
|
+
Name: hypercomplex-engine
|
|
3
|
+
Version: 0.7
|
|
4
|
+
Summary: Fast O(1)/O(n) multiplication engine for arbitrary dimensions and table generator for ordinary, split, and dual Cayley-Dickson algebras.
|
|
5
|
+
Author-email: Maher Ben Abdessalem <ba.maher94@gmail.com>
|
|
6
|
+
License-Expression: Apache-2.0
|
|
7
|
+
Project-URL: Homepage, https://github.com/maher1719/hypercomplex-engine
|
|
8
|
+
Project-URL: Repository, https://github.com/maher1719/hypercomplex-engine
|
|
9
|
+
Project-URL: Preprint: Sign Structure, https://doi.org/10.6084/m9.figshare.33705022
|
|
10
|
+
Keywords: hypercomplex,cayley-dickson,quaternions,octonions,split-algebra,math,physics,geometry,sedenions
|
|
11
|
+
Classifier: Development Status :: 4 - Beta
|
|
12
|
+
Classifier: Intended Audience :: Developers
|
|
13
|
+
Classifier: Intended Audience :: Science/Research
|
|
14
|
+
Classifier: Topic :: Scientific/Engineering :: Mathematics
|
|
15
|
+
Classifier: Topic :: Scientific/Engineering :: Physics
|
|
16
|
+
Classifier: Programming Language :: Python :: 3.10
|
|
17
|
+
Classifier: Programming Language :: Python :: 3.11
|
|
18
|
+
Classifier: Programming Language :: Python :: 3.12
|
|
19
|
+
Classifier: Programming Language :: Python :: 3.13
|
|
20
|
+
Classifier: Programming Language :: Python :: 3.14
|
|
21
|
+
Classifier: Programming Language :: Python :: 3.15
|
|
22
|
+
Classifier: Operating System :: OS Independent
|
|
23
|
+
Requires-Python: >=3.10
|
|
24
|
+
Description-Content-Type: text/markdown
|
|
25
|
+
License-File: LICENSE
|
|
26
|
+
License-File: NOTICE
|
|
27
|
+
Requires-Dist: numpy>=1.22.0
|
|
28
|
+
Dynamic: license-file
|
|
29
|
+
|
|
30
|
+
<p align="center">
|
|
31
|
+
<img src="asset/logo.jpeg" alt="Project Banner" width="100%">
|
|
32
|
+
</p>
|
|
33
|
+
|
|
34
|
+
# hypercomplex-engine
|
|
35
|
+
|
|
36
|
+
|
|
37
|
+
[](https://www.apache.org/licenses/LICENSE-2.0)
|
|
38
|
+
[](https://www.python.org/downloads/)
|
|
39
|
+
[](https://github.com/maher1719/hypercomplex-engine)
|
|
40
|
+
[](https://pypi.org/project/hypercomplex-engine/)
|
|
41
|
+
[](https://pepy.tech/project/hypercomplex-engine)
|
|
42
|
+
|
|
43
|
+
|
|
44
|
+
Fast, cross validated multiplication and table generation for Cayley–Dickson algebras multiplication up to **one million digit** two elements index tested for O(1)/O(n) and depend on RAM allocation up to 2^13 or more for table builder.
|
|
45
|
+
|
|
46
|
+
|
|
47
|
+
For more info please visit All benchamrks in [BENCHMARKS.md](https://github.com/maher1719/hypercomplex-engine/blob/main/BENCHMARKS.md) and Jupyter Notebook used in [examples/benchmark/benchmark.ipynb](https://github.com/maher1719/hypercomplex-engine/blob/main/examples/benchmark/benchmark.ipynb) (note speed time may vary depend on your hardware).
|
|
48
|
+
|
|
49
|
+
This library provides the computational substrate for high-dimensional hypercomplex algebra, featuring:
|
|
50
|
+
|
|
51
|
+
- **Full multiplication table generation** for standard, split, and dual algebras.
|
|
52
|
+
- **O(n) holographic** table-free recursive descent multiplication.
|
|
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.
|
|
59
|
+
- **Integer, graded, and LaTeX** notation formatting.
|
|
60
|
+
- **CSV export** for tables (matrix and long formats).
|
|
61
|
+
- A **simple facade API** for everyday use, and direct low-level classes for advanced physics/math engines.
|
|
62
|
+
|
|
63
|
+
|
|
64
|
+
---
|
|
65
|
+
|
|
66
|
+
## Scope and limitations
|
|
67
|
+
|
|
68
|
+
If you build upon this package, please read fully [Go to Scope, Strengths, and Limitations](#scope-strengths-and-limitations) below for more information or check [Scope, Strengths, and Limitations file](https://github.com/maher1719/hypercomplex-engine/blob/main/README_scope_and_limitations.md#scope-strengths-and-limitations)
|
|
69
|
+
|
|
70
|
+
|
|
71
|
+
## 📄 Publications & Preprints
|
|
72
|
+
|
|
73
|
+
This library serves as the formal verification substrate and computational engine for the following mathematical preprints:
|
|
74
|
+
|
|
75
|
+
**1. The Sign Structure of Cayley–Dickson and Split Algebras By Blocks**
|
|
76
|
+
*Proves the OPMT (Ordered-Pair Multiplication Table) sign laws, block decomposition, and the O(1) closed-form sign evaluator implemented in the `fast` engine of this library.*
|
|
77
|
+
* 📊 **Figshare:** [10.6084/m9.figshare.33705022](https://doi.org/10.6084/m9.figshare.33705022)
|
|
78
|
+
* 📦 **Zenodo:** [10.5281/zenodo.22051873](https://doi.org/10.5281/zenodo.22051873)
|
|
79
|
+
|
|
80
|
+
---
|
|
81
|
+
|
|
82
|
+
## Supported algebras
|
|
83
|
+
|
|
84
|
+
| Kind | Description |
|
|
85
|
+
|---|---|
|
|
86
|
+
| `standard` | Ordinary Cayley–Dickson algebras: real, complex, quaternions, octonions, sedenions, ... |
|
|
87
|
+
| `split` | Split Cayley–Dickson algebras: standard parent plus one split doubling at the top |
|
|
88
|
+
| `dual` | Dual extension of a standard algebra, with ε² = 0 |
|
|
89
|
+
| `dual_split` | Dual extension of a split algebra, with ε² = 0 |
|
|
90
|
+
|
|
91
|
+
---
|
|
92
|
+
|
|
93
|
+
## Installation
|
|
94
|
+
|
|
95
|
+
Clone the repository:
|
|
96
|
+
|
|
97
|
+
```bash
|
|
98
|
+
git clone https://github.com/maher1719/hypercomplex-engine.git
|
|
99
|
+
cd hypercomplex-engine
|
|
100
|
+
```
|
|
101
|
+
Install with pip:
|
|
102
|
+
|
|
103
|
+
```bash
|
|
104
|
+
pip install hypercomplex-engine
|
|
105
|
+
```
|
|
106
|
+
|
|
107
|
+
Install in editable mode:
|
|
108
|
+
|
|
109
|
+
```bash
|
|
110
|
+
pip install -e .
|
|
111
|
+
```
|
|
112
|
+
|
|
113
|
+
Run the tests:
|
|
114
|
+
|
|
115
|
+
```bash
|
|
116
|
+
pytest -v
|
|
117
|
+
```
|
|
118
|
+
|
|
119
|
+
---
|
|
120
|
+
|
|
121
|
+
# Basic Use
|
|
122
|
+
|
|
123
|
+
The simplest way to use the library is through the top-level facade API.
|
|
124
|
+
|
|
125
|
+
```python
|
|
126
|
+
from hypercomplex_engine import (
|
|
127
|
+
build_table,
|
|
128
|
+
multiply,
|
|
129
|
+
format_element,
|
|
130
|
+
print_table,
|
|
131
|
+
export_csv,
|
|
132
|
+
)
|
|
133
|
+
```
|
|
134
|
+
|
|
135
|
+
---
|
|
136
|
+
|
|
137
|
+
## Build a table
|
|
138
|
+
|
|
139
|
+
```python
|
|
140
|
+
table = build_table("standard", 3)
|
|
141
|
+
```
|
|
142
|
+
|
|
143
|
+
This builds the octonion multiplication table.
|
|
144
|
+
|
|
145
|
+
Dimensions:
|
|
146
|
+
|
|
147
|
+
```text
|
|
148
|
+
n = 0 -> real numbers, dimension 1
|
|
149
|
+
n = 1 -> complex numbers, dimension 2
|
|
150
|
+
n = 2 -> quaternions, dimension 4
|
|
151
|
+
n = 3 -> octonions, dimension 8
|
|
152
|
+
n = 4 -> sedenions, dimension 16
|
|
153
|
+
```
|
|
154
|
+
|
|
155
|
+
---
|
|
156
|
+
|
|
157
|
+
## Print a table
|
|
158
|
+
|
|
159
|
+
```python
|
|
160
|
+
print_table(table, title="Octonions", mode="integer")
|
|
161
|
+
```
|
|
162
|
+
|
|
163
|
+
Example output style:
|
|
164
|
+
|
|
165
|
+
```text
|
|
166
|
+
e0 e1 e2 e3 e4 e5 e6 e7
|
|
167
|
+
e0 | +e0 +e1 +e2 +e3 +e4 +e5 +e6 +e7
|
|
168
|
+
e1 | +e1 -e0 +e3 -e2 +e5 -e4 -e7 +e6
|
|
169
|
+
...
|
|
170
|
+
```
|
|
171
|
+
|
|
172
|
+
You can also use graded notation:
|
|
173
|
+
|
|
174
|
+
```python
|
|
175
|
+
print_table(table, title="Octonions", mode="graded")
|
|
176
|
+
```
|
|
177
|
+
|
|
178
|
+
Example:
|
|
179
|
+
|
|
180
|
+
```text
|
|
181
|
+
1 o1 o2 o3 o4 o5 o6 o7
|
|
182
|
+
1 | +1 +o1 +o2 +o3 +o4 +o5 +o6 +o7
|
|
183
|
+
o1 | +o1 -1 ...
|
|
184
|
+
...
|
|
185
|
+
```
|
|
186
|
+
|
|
187
|
+
---
|
|
188
|
+
|
|
189
|
+
## Export a table to CSV
|
|
190
|
+
|
|
191
|
+
Matrix-style CSV:
|
|
192
|
+
|
|
193
|
+
```python
|
|
194
|
+
export_csv(
|
|
195
|
+
"octonions_graded.csv",
|
|
196
|
+
table,
|
|
197
|
+
mode="graded",
|
|
198
|
+
csv_mode="matrix",
|
|
199
|
+
)
|
|
200
|
+
```
|
|
201
|
+
|
|
202
|
+
Long-format CSV for data analysis:
|
|
203
|
+
|
|
204
|
+
```python
|
|
205
|
+
export_csv(
|
|
206
|
+
"octonions_long.csv",
|
|
207
|
+
table,
|
|
208
|
+
mode="integer",
|
|
209
|
+
csv_mode="long",
|
|
210
|
+
)
|
|
211
|
+
```
|
|
212
|
+
|
|
213
|
+
The long format produces rows like:
|
|
214
|
+
|
|
215
|
+
```csv
|
|
216
|
+
i,j,sign,index
|
|
217
|
+
0,0,1,0
|
|
218
|
+
0,1,1,1
|
|
219
|
+
1,0,1,1
|
|
220
|
+
1,1,-1,0
|
|
221
|
+
...
|
|
222
|
+
```
|
|
223
|
+
|
|
224
|
+
---
|
|
225
|
+
|
|
226
|
+
## Multiply two basis elements
|
|
227
|
+
|
|
228
|
+
```python
|
|
229
|
+
result = multiply("standard", (1, 1), (1, 2))
|
|
230
|
+
|
|
231
|
+
print(result)
|
|
232
|
+
# (1, 3)
|
|
233
|
+
```
|
|
234
|
+
|
|
235
|
+
This means:
|
|
236
|
+
|
|
237
|
+
```text
|
|
238
|
+
e1 * e2 = +e3
|
|
239
|
+
```
|
|
240
|
+
|
|
241
|
+
Format the result:
|
|
242
|
+
|
|
243
|
+
```python
|
|
244
|
+
print(format_element(result, mode="integer"))
|
|
245
|
+
# +e3
|
|
246
|
+
|
|
247
|
+
print(format_element(result, mode="graded"))
|
|
248
|
+
# +o12
|
|
249
|
+
|
|
250
|
+
print(format_element(result, mode="latex"))
|
|
251
|
+
# +e_{3}
|
|
252
|
+
```
|
|
253
|
+
|
|
254
|
+
Note:
|
|
255
|
+
|
|
256
|
+
```text
|
|
257
|
+
integer mode uses the basis index:
|
|
258
|
+
e3
|
|
259
|
+
|
|
260
|
+
graded mode uses the generator decomposition:
|
|
261
|
+
index 3 = binary 011 = generators 1 and 2 = o12
|
|
262
|
+
```
|
|
263
|
+
|
|
264
|
+
---
|
|
265
|
+
|
|
266
|
+
## Split multiplication
|
|
267
|
+
|
|
268
|
+
```python
|
|
269
|
+
result = multiply("split", (1, 1), (1, 1), dim=1)
|
|
270
|
+
|
|
271
|
+
print(result)
|
|
272
|
+
# (1, 0)
|
|
273
|
+
```
|
|
274
|
+
|
|
275
|
+
In split-complex numbers:
|
|
276
|
+
|
|
277
|
+
```text
|
|
278
|
+
e1² = +e0
|
|
279
|
+
```
|
|
280
|
+
|
|
281
|
+
---
|
|
282
|
+
|
|
283
|
+
## Dual multiplication
|
|
284
|
+
|
|
285
|
+
```python
|
|
286
|
+
# eps*e0 represented as local tuple: (sign, local_index, eps_flag)
|
|
287
|
+
eps_e0 = (1, 0, 1)
|
|
288
|
+
|
|
289
|
+
result = multiply("dual", (1, 0), eps_e0, dim=1)
|
|
290
|
+
|
|
291
|
+
print(result)
|
|
292
|
+
# (1, 0, 1)
|
|
293
|
+
|
|
294
|
+
print(format_element(result, mode="integer"))
|
|
295
|
+
# +eps
|
|
296
|
+
```
|
|
297
|
+
|
|
298
|
+
Nilpotency:
|
|
299
|
+
|
|
300
|
+
```python
|
|
301
|
+
result = multiply("dual", eps_e0, eps_e0, dim=1)
|
|
302
|
+
|
|
303
|
+
print(result)
|
|
304
|
+
# (0, 0, 0)
|
|
305
|
+
```
|
|
306
|
+
|
|
307
|
+
This means:
|
|
308
|
+
|
|
309
|
+
```text
|
|
310
|
+
ε² = 0
|
|
311
|
+
```
|
|
312
|
+
|
|
313
|
+
---
|
|
314
|
+
|
|
315
|
+
# Intermediate Use
|
|
316
|
+
|
|
317
|
+
The facade API is enough for most users.
|
|
318
|
+
|
|
319
|
+
For more control, you can choose the computation engine and work directly with tables or multipliers.
|
|
320
|
+
|
|
321
|
+
---
|
|
322
|
+
|
|
323
|
+
## Engines
|
|
324
|
+
|
|
325
|
+
The `multiply` function supports two engines:
|
|
326
|
+
|
|
327
|
+
```python
|
|
328
|
+
multiply(kind, a, b, dim=None, engine="fast")
|
|
329
|
+
```
|
|
330
|
+
|
|
331
|
+
| Engine | Complexity | Description |
|
|
332
|
+
|---|---:|---|
|
|
333
|
+
| `"fast"` | O(1) | Bitwise closed-form sign evaluator |
|
|
334
|
+
| `"holographic"` | O(n) | Recursive block descent |
|
|
335
|
+
|
|
336
|
+
Example:
|
|
337
|
+
|
|
338
|
+
```python
|
|
339
|
+
from hypercomplex_engine import multiply
|
|
340
|
+
|
|
341
|
+
a = (1, 3)
|
|
342
|
+
b = (1, 5)
|
|
343
|
+
|
|
344
|
+
fast_result = multiply("standard", a, b, engine="fast")
|
|
345
|
+
holo_result = multiply("standard", a, b, engine="holographic")
|
|
346
|
+
|
|
347
|
+
assert fast_result == holo_result
|
|
348
|
+
```
|
|
349
|
+
|
|
350
|
+
---
|
|
351
|
+
|
|
352
|
+
## Algebra kinds
|
|
353
|
+
|
|
354
|
+
```python
|
|
355
|
+
multiply("standard", a, b)
|
|
356
|
+
multiply("split", a, b, dim=3)
|
|
357
|
+
multiply("dual", a, b, dim=3)
|
|
358
|
+
multiply("dual_split", a, b, dim=3)
|
|
359
|
+
```
|
|
360
|
+
|
|
361
|
+
For `standard`, `dim` is not needed.
|
|
362
|
+
|
|
363
|
+
For `split`, `dual` and `dual_split`, `dim` is required.
|
|
364
|
+
|
|
365
|
+
---
|
|
366
|
+
|
|
367
|
+
## Table builders directly
|
|
368
|
+
|
|
369
|
+
```python
|
|
370
|
+
from hypercomplex_engine import (
|
|
371
|
+
StandardTableBuilder,
|
|
372
|
+
SplitTableBuilder,
|
|
373
|
+
DualTableBuilder,
|
|
374
|
+
)
|
|
375
|
+
|
|
376
|
+
standard_builder = StandardTableBuilder()
|
|
377
|
+
split_builder = SplitTableBuilder()
|
|
378
|
+
dual_builder = DualTableBuilder()
|
|
379
|
+
|
|
380
|
+
signs, indices = standard_builder.build(3)
|
|
381
|
+
signs, indices = split_builder.build(3)
|
|
382
|
+
signs, indices, eps = dual_builder.build(2, split=False)
|
|
383
|
+
```
|
|
384
|
+
|
|
385
|
+
Return conventions:
|
|
386
|
+
|
|
387
|
+
```text
|
|
388
|
+
standard:
|
|
389
|
+
signs, indices
|
|
390
|
+
|
|
391
|
+
split:
|
|
392
|
+
signs, indices
|
|
393
|
+
|
|
394
|
+
dual:
|
|
395
|
+
signs, indices, eps
|
|
396
|
+
```
|
|
397
|
+
|
|
398
|
+
For dual tables:
|
|
399
|
+
|
|
400
|
+
- `signs[i, j]` is the sign.
|
|
401
|
+
- `indices[i, j]` is the local base index.
|
|
402
|
+
- `eps[i, j]` is the epsilon flag.
|
|
403
|
+
|
|
404
|
+
---
|
|
405
|
+
|
|
406
|
+
## Multipliers directly
|
|
407
|
+
|
|
408
|
+
```python
|
|
409
|
+
from hypercomplex_engine import (
|
|
410
|
+
StandardHolographic,
|
|
411
|
+
SplitHolographic,
|
|
412
|
+
DualHolographic,
|
|
413
|
+
)
|
|
414
|
+
|
|
415
|
+
holo = StandardHolographic()
|
|
416
|
+
result = holo.multiply((1, 1), (1, 2))
|
|
417
|
+
|
|
418
|
+
print(result)
|
|
419
|
+
# (1, 3)
|
|
420
|
+
```
|
|
421
|
+
|
|
422
|
+
Split:
|
|
423
|
+
|
|
424
|
+
```python
|
|
425
|
+
split_holo = SplitHolographic()
|
|
426
|
+
result = split_holo.multiply((1, 2), (1, 2), dim=2)
|
|
427
|
+
|
|
428
|
+
print(result)
|
|
429
|
+
# (1, 0)
|
|
430
|
+
```
|
|
431
|
+
|
|
432
|
+
Dual:
|
|
433
|
+
|
|
434
|
+
```python
|
|
435
|
+
dual_holo = DualHolographic(split=False)
|
|
436
|
+
|
|
437
|
+
result = dual_holo.multiply((1, 0), (1, 2), dim=1)
|
|
438
|
+
|
|
439
|
+
print(result)
|
|
440
|
+
# (1, 0, 1)
|
|
441
|
+
```
|
|
442
|
+
|
|
443
|
+
---
|
|
444
|
+
|
|
445
|
+
## Fast O(1) multipliers directly
|
|
446
|
+
|
|
447
|
+
```python
|
|
448
|
+
from hypercomplex_engine import (
|
|
449
|
+
FastStandard,
|
|
450
|
+
FastSplit,
|
|
451
|
+
FastDual,
|
|
452
|
+
)
|
|
453
|
+
|
|
454
|
+
fast = FastStandard()
|
|
455
|
+
|
|
456
|
+
result = fast.multiply((1, 1), (1, 2))
|
|
457
|
+
|
|
458
|
+
print(result)
|
|
459
|
+
# (1, 3)
|
|
460
|
+
```
|
|
461
|
+
|
|
462
|
+
Split:
|
|
463
|
+
|
|
464
|
+
```python
|
|
465
|
+
fast_split = FastSplit()
|
|
466
|
+
|
|
467
|
+
result = fast_split.multiply((1, 2), (1, 2), dim=2)
|
|
468
|
+
|
|
469
|
+
print(result)
|
|
470
|
+
# (1, 0)
|
|
471
|
+
```
|
|
472
|
+
|
|
473
|
+
Dual:
|
|
474
|
+
|
|
475
|
+
```python
|
|
476
|
+
fast_dual = FastDual(split=False)
|
|
477
|
+
|
|
478
|
+
result = fast_dual.multiply((1, 0), (1, 0, 1), dim=1)
|
|
479
|
+
|
|
480
|
+
print(result)
|
|
481
|
+
# (1, 0, 1)
|
|
482
|
+
```
|
|
483
|
+
|
|
484
|
+
---
|
|
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
|
+
|
|
528
|
+
## Formatting modes
|
|
529
|
+
|
|
530
|
+
| Mode | Example |
|
|
531
|
+
|---|---|
|
|
532
|
+
| `"integer"` | `+e5` |
|
|
533
|
+
| `"graded"` | `+o13` |
|
|
534
|
+
| `"latex"` | `+e_{5}` |
|
|
535
|
+
| `"latex_integer"` | `+e_{5}` |
|
|
536
|
+
| `"latex_graded"` | `+o_{13}` |
|
|
537
|
+
|
|
538
|
+
Example:
|
|
539
|
+
|
|
540
|
+
```python
|
|
541
|
+
from hypercomplex_engine import format_element
|
|
542
|
+
|
|
543
|
+
element = (-1, 5)
|
|
544
|
+
|
|
545
|
+
print(format_element(element, mode="integer"))
|
|
546
|
+
# -e5
|
|
547
|
+
|
|
548
|
+
print(format_element(element, mode="graded"))
|
|
549
|
+
# -o13
|
|
550
|
+
|
|
551
|
+
print(format_element(element, mode="latex"))
|
|
552
|
+
# -e_{5}
|
|
553
|
+
|
|
554
|
+
print(format_element(element, mode="latex_integer"))
|
|
555
|
+
# -e_{5}
|
|
556
|
+
|
|
557
|
+
print(format_element(element, mode="latex_graded"))
|
|
558
|
+
# -o_{13}
|
|
559
|
+
```
|
|
560
|
+
|
|
561
|
+
---
|
|
562
|
+
|
|
563
|
+
# Advanced Use
|
|
564
|
+
|
|
565
|
+
This section is for contributors, benchmarking, physics engines, and symbolic pipelines.
|
|
566
|
+
|
|
567
|
+
---
|
|
568
|
+
|
|
569
|
+
## Direct low-level imports
|
|
570
|
+
|
|
571
|
+
If you prefer explicit imports:
|
|
572
|
+
|
|
573
|
+
```python
|
|
574
|
+
from hypercomplex_engine.core.table_builder import (
|
|
575
|
+
StandardTableBuilder,
|
|
576
|
+
SplitTableBuilder,
|
|
577
|
+
DualTableBuilder,
|
|
578
|
+
)
|
|
579
|
+
|
|
580
|
+
from hypercomplex_engine.core.holographic import (
|
|
581
|
+
StandardHolographic,
|
|
582
|
+
SplitHolographic,
|
|
583
|
+
DualHolographic,
|
|
584
|
+
)
|
|
585
|
+
|
|
586
|
+
from hypercomplex_engine.core.fast import (
|
|
587
|
+
FastStandard,
|
|
588
|
+
FastSplit,
|
|
589
|
+
FastDual,
|
|
590
|
+
)
|
|
591
|
+
|
|
592
|
+
from hypercomplex_engine.printer import (
|
|
593
|
+
CDFormat,
|
|
594
|
+
CDTablePrinter,
|
|
595
|
+
)
|
|
596
|
+
```
|
|
597
|
+
|
|
598
|
+
---
|
|
599
|
+
|
|
600
|
+
## Cross-validating O(1) against the full table
|
|
601
|
+
|
|
602
|
+
```python
|
|
603
|
+
from hypercomplex_engine import StandardTableBuilder, FastStandard
|
|
604
|
+
|
|
605
|
+
builder = StandardTableBuilder()
|
|
606
|
+
fast = FastStandard()
|
|
607
|
+
|
|
608
|
+
n = 4
|
|
609
|
+
signs, indices = builder.build(n)
|
|
610
|
+
|
|
611
|
+
dim = 1 << n
|
|
612
|
+
|
|
613
|
+
for i in range(dim):
|
|
614
|
+
for j in range(dim):
|
|
615
|
+
fast_sign, fast_idx = fast.multiply_indices(i, j)
|
|
616
|
+
|
|
617
|
+
assert int(signs[i, j]) == fast_sign
|
|
618
|
+
assert int(indices[i, j]) == fast_idx
|
|
619
|
+
```
|
|
620
|
+
|
|
621
|
+
This proves that the O(1) evaluator agrees with the O(4^n) table builder.
|
|
622
|
+
|
|
623
|
+
---
|
|
624
|
+
|
|
625
|
+
## Cross-validating split O(1) against the split table
|
|
626
|
+
|
|
627
|
+
```python
|
|
628
|
+
from hypercomplex_engine import SplitTableBuilder, FastSplit
|
|
629
|
+
|
|
630
|
+
builder = SplitTableBuilder()
|
|
631
|
+
fast = FastSplit()
|
|
632
|
+
|
|
633
|
+
n = 4
|
|
634
|
+
signs, indices = builder.build(n)
|
|
635
|
+
|
|
636
|
+
dim = 1 << n
|
|
637
|
+
|
|
638
|
+
for i in range(dim):
|
|
639
|
+
for j in range(dim):
|
|
640
|
+
fast_sign, fast_idx = fast.multiply_indices(i, j, dim=n)
|
|
641
|
+
|
|
642
|
+
assert int(signs[i, j]) == fast_sign
|
|
643
|
+
assert int(indices[i, j]) == fast_idx
|
|
644
|
+
```
|
|
645
|
+
|
|
646
|
+
---
|
|
647
|
+
|
|
648
|
+
## Dual local and global indices
|
|
649
|
+
|
|
650
|
+
For dual multiplication, the total dimension is:
|
|
651
|
+
|
|
652
|
+
```text
|
|
653
|
+
2^(dim + 1)
|
|
654
|
+
```
|
|
655
|
+
|
|
656
|
+
The epsilon bit is bit `dim`.
|
|
657
|
+
|
|
658
|
+
Example for `dim=1`:
|
|
659
|
+
|
|
660
|
+
```text
|
|
661
|
+
lower half: 0, 1 base elements
|
|
662
|
+
upper half: 2, 3 epsilon elements
|
|
663
|
+
```
|
|
664
|
+
|
|
665
|
+
The dual multipliers accept both:
|
|
666
|
+
|
|
667
|
+
```python
|
|
668
|
+
# global index tuple
|
|
669
|
+
(1, 2)
|
|
670
|
+
|
|
671
|
+
# local tuple with epsilon flag
|
|
672
|
+
(1, 0, 1)
|
|
673
|
+
```
|
|
674
|
+
|
|
675
|
+
Both represent ε·e₀ when `dim=1`.
|
|
676
|
+
|
|
677
|
+
The output convention is:
|
|
678
|
+
|
|
679
|
+
```python
|
|
680
|
+
(sign, local_index, eps_flag)
|
|
681
|
+
```
|
|
682
|
+
|
|
683
|
+
This makes formatting easy:
|
|
684
|
+
|
|
685
|
+
```python
|
|
686
|
+
from hypercomplex_engine import format_element
|
|
687
|
+
|
|
688
|
+
result = (1, 0, 1)
|
|
689
|
+
|
|
690
|
+
print(format_element(result, mode="integer"))
|
|
691
|
+
# +eps
|
|
692
|
+
|
|
693
|
+
print(format_element(result, mode="latex"))
|
|
694
|
+
# +\epsilon
|
|
695
|
+
```
|
|
696
|
+
|
|
697
|
+
---
|
|
698
|
+
|
|
699
|
+
## Using the fast engine in a physics loop
|
|
700
|
+
|
|
701
|
+
For simulations, avoid building large tables. Use the fast engine directly.
|
|
702
|
+
|
|
703
|
+
```python
|
|
704
|
+
from hypercomplex_engine import FastStandard
|
|
705
|
+
|
|
706
|
+
fast = FastStandard()
|
|
707
|
+
|
|
708
|
+
def basis_product(i: int, j: int):
|
|
709
|
+
sign, index = fast.multiply((1, i), (1, j))
|
|
710
|
+
return sign, index
|
|
711
|
+
|
|
712
|
+
sign, index = basis_product(1, 2)
|
|
713
|
+
|
|
714
|
+
print(sign, index)
|
|
715
|
+
# 1 3
|
|
716
|
+
```
|
|
717
|
+
|
|
718
|
+
For octonionic or higher-dimensional simulations, this avoids O(4^n) memory.
|
|
719
|
+
|
|
720
|
+
---
|
|
721
|
+
|
|
722
|
+
## Table size warning
|
|
723
|
+
|
|
724
|
+
Full table generation grows as:
|
|
725
|
+
|
|
726
|
+
```text
|
|
727
|
+
entries = 4^n
|
|
728
|
+
```
|
|
729
|
+
|
|
730
|
+
where `n` is the dimension exponent.
|
|
731
|
+
|
|
732
|
+
| n | Dimension | Entries |
|
|
733
|
+
|---:|---:|---:|
|
|
734
|
+
| 0 | 1 | 1 |
|
|
735
|
+
| 1 | 2 | 4 |
|
|
736
|
+
| 2 | 4 | 16 |
|
|
737
|
+
| 3 | 8 | 64 |
|
|
738
|
+
| 4 | 16 | 256 |
|
|
739
|
+
| 5 | 32 | 1,024 |
|
|
740
|
+
| 6 | 64 | 4,096 |
|
|
741
|
+
| 8 | 256 | 65,536 |
|
|
742
|
+
| 10 | 1,024 | 1,048,576 |
|
|
743
|
+
| 12 | 4,096 | 16,777,216 |
|
|
744
|
+
|
|
745
|
+
For large dimensions, prefer:
|
|
746
|
+
|
|
747
|
+
```python
|
|
748
|
+
engine="fast"
|
|
749
|
+
```
|
|
750
|
+
|
|
751
|
+
or:
|
|
752
|
+
|
|
753
|
+
```python
|
|
754
|
+
engine="holographic"
|
|
755
|
+
```
|
|
756
|
+
|
|
757
|
+
---
|
|
758
|
+
|
|
759
|
+
# API Reference
|
|
760
|
+
|
|
761
|
+
## Top-level functions
|
|
762
|
+
|
|
763
|
+
### `build_table(kind, n)`
|
|
764
|
+
|
|
765
|
+
Builds a multiplication table.
|
|
766
|
+
|
|
767
|
+
```python
|
|
768
|
+
table = build_table("standard", 3)
|
|
769
|
+
```
|
|
770
|
+
|
|
771
|
+
Returns:
|
|
772
|
+
|
|
773
|
+
```text
|
|
774
|
+
standard:
|
|
775
|
+
(signs, indices)
|
|
776
|
+
|
|
777
|
+
split:
|
|
778
|
+
(signs, indices)
|
|
779
|
+
|
|
780
|
+
dual:
|
|
781
|
+
(signs, indices, eps)
|
|
782
|
+
|
|
783
|
+
dual_split:
|
|
784
|
+
(signs, indices, eps)
|
|
785
|
+
```
|
|
786
|
+
|
|
787
|
+
---
|
|
788
|
+
|
|
789
|
+
### `multiply(kind, a, b, dim=None, engine="fast")`
|
|
790
|
+
|
|
791
|
+
Multiplies two basis elements.
|
|
792
|
+
|
|
793
|
+
```python
|
|
794
|
+
result = multiply("standard", (1, 1), (1, 2))
|
|
795
|
+
```
|
|
796
|
+
|
|
797
|
+
Returns:
|
|
798
|
+
|
|
799
|
+
```text
|
|
800
|
+
standard:
|
|
801
|
+
(sign, index)
|
|
802
|
+
|
|
803
|
+
split:
|
|
804
|
+
(sign, index)
|
|
805
|
+
|
|
806
|
+
dual:
|
|
807
|
+
(sign, local_index, eps_flag)
|
|
808
|
+
|
|
809
|
+
dual_split:
|
|
810
|
+
(sign, local_index, eps_flag)
|
|
811
|
+
```
|
|
812
|
+
|
|
813
|
+
---
|
|
814
|
+
|
|
815
|
+
### `format_element(element, mode="integer")`
|
|
816
|
+
|
|
817
|
+
Formats a basis element tuple.
|
|
818
|
+
|
|
819
|
+
```python
|
|
820
|
+
format_element((1, 3), mode="integer")
|
|
821
|
+
# "+e3"
|
|
822
|
+
|
|
823
|
+
format_element((1, 3), mode="graded")
|
|
824
|
+
# "+o12"
|
|
825
|
+
```
|
|
826
|
+
|
|
827
|
+
---
|
|
828
|
+
|
|
829
|
+
### `print_table(table, title=None, limit=None, mode="integer")`
|
|
830
|
+
|
|
831
|
+
Prints a table.
|
|
832
|
+
|
|
833
|
+
```python
|
|
834
|
+
table = build_table("standard", 2)
|
|
835
|
+
print_table(table, mode="graded")
|
|
836
|
+
```
|
|
837
|
+
|
|
838
|
+
---
|
|
839
|
+
|
|
840
|
+
### `export_csv(path, table, mode="integer", csv_mode="matrix")`
|
|
841
|
+
|
|
842
|
+
Exports a table to CSV.
|
|
843
|
+
|
|
844
|
+
```python
|
|
845
|
+
table = build_table("standard", 3)
|
|
846
|
+
|
|
847
|
+
export_csv(
|
|
848
|
+
"octonions.csv",
|
|
849
|
+
table,
|
|
850
|
+
mode="graded",
|
|
851
|
+
csv_mode="matrix",
|
|
852
|
+
)
|
|
853
|
+
```
|
|
854
|
+
|
|
855
|
+
CSV modes:
|
|
856
|
+
|
|
857
|
+
| `csv_mode` | Output |
|
|
858
|
+
|---|---|
|
|
859
|
+
| `"matrix"` | Spreadsheet-style grid |
|
|
860
|
+
| `"long"` | One row per product |
|
|
861
|
+
|
|
862
|
+
---
|
|
863
|
+
|
|
864
|
+
## Algebra kinds
|
|
865
|
+
|
|
866
|
+
| Kind | Meaning |
|
|
867
|
+
|---|---|
|
|
868
|
+
| `"standard"` | Ordinary Cayley–Dickson |
|
|
869
|
+
| `"split"` | Split Cayley–Dickson |
|
|
870
|
+
| `"dual"` | Dual extension of standard algebra |
|
|
871
|
+
| `"dual_split"` | Dual extension of split algebra |
|
|
872
|
+
|
|
873
|
+
Aliases:
|
|
874
|
+
|
|
875
|
+
```text
|
|
876
|
+
standard: "std", "ordinary", "o"
|
|
877
|
+
split: "s"
|
|
878
|
+
dual: "d", "dual_standard"
|
|
879
|
+
dual_split: "split_dual", "ds"
|
|
880
|
+
```
|
|
881
|
+
|
|
882
|
+
---
|
|
883
|
+
|
|
884
|
+
## Engines
|
|
885
|
+
|
|
886
|
+
| Engine | Aliases | Complexity |
|
|
887
|
+
|---|---|---:|
|
|
888
|
+
| `"fast"` | `"o1"`, `"bitwise"`, `"constant"` | O(1) Word-RAM |
|
|
889
|
+
| `"holographic"` | `"on"`, `"descent"` | O(n) |
|
|
890
|
+
|
|
891
|
+
---
|
|
892
|
+
|
|
893
|
+
# Mathematical Background
|
|
894
|
+
|
|
895
|
+
## Basis product rule
|
|
896
|
+
|
|
897
|
+
For standard and split Cayley–Dickson algebras:
|
|
898
|
+
|
|
899
|
+
```text
|
|
900
|
+
e_i * e_j = sign(i, j) * e_{i XOR j}
|
|
901
|
+
```
|
|
902
|
+
|
|
903
|
+
The index is always:
|
|
904
|
+
|
|
905
|
+
```text
|
|
906
|
+
i XOR j
|
|
907
|
+
```
|
|
908
|
+
|
|
909
|
+
The sign is determined by the OPMT block laws.
|
|
910
|
+
|
|
911
|
+
---
|
|
912
|
+
|
|
913
|
+
## Standard doubling formula
|
|
914
|
+
|
|
915
|
+
```text
|
|
916
|
+
(a, b)(c, d) = (ac - d* b, da + b c*)
|
|
917
|
+
```
|
|
918
|
+
|
|
919
|
+
with conjugation:
|
|
920
|
+
|
|
921
|
+
```text
|
|
922
|
+
e0* = e0
|
|
923
|
+
ek* = -ek for k > 0
|
|
924
|
+
```
|
|
925
|
+
|
|
926
|
+
---
|
|
927
|
+
|
|
928
|
+
## Split doubling formula
|
|
929
|
+
|
|
930
|
+
```text
|
|
931
|
+
(a, b)(c, d) = (ac + d* b, da + b c*)
|
|
932
|
+
```
|
|
933
|
+
|
|
934
|
+
The only difference from the standard construction is the sign of the `d* b` term.
|
|
935
|
+
|
|
936
|
+
This causes Block d signs to invert relative to the standard algebra.
|
|
937
|
+
|
|
938
|
+
---
|
|
939
|
+
|
|
940
|
+
## Block decomposition
|
|
941
|
+
|
|
942
|
+
Each multiplication table splits into four blocks:
|
|
943
|
+
|
|
944
|
+
```text
|
|
945
|
+
[ a b ]
|
|
946
|
+
[ c d ]
|
|
947
|
+
```
|
|
948
|
+
|
|
949
|
+
where:
|
|
950
|
+
|
|
951
|
+
```text
|
|
952
|
+
Block a: e_i * e_j
|
|
953
|
+
Block b: e_i * (e_j ℓ)
|
|
954
|
+
Block c: (e_i ℓ) * e_j
|
|
955
|
+
Block d: (e_i ℓ) * (e_j ℓ)
|
|
956
|
+
```
|
|
957
|
+
|
|
958
|
+
For standard algebras:
|
|
959
|
+
|
|
960
|
+
```text
|
|
961
|
+
Block d interior sign = -σ_a
|
|
962
|
+
```
|
|
963
|
+
|
|
964
|
+
For split algebras:
|
|
965
|
+
|
|
966
|
+
```text
|
|
967
|
+
Block d interior sign = +σ_a
|
|
968
|
+
```
|
|
969
|
+
|
|
970
|
+
---
|
|
971
|
+
|
|
972
|
+
## Dual numbers
|
|
973
|
+
|
|
974
|
+
Dual algebras adjoin ε such that:
|
|
975
|
+
|
|
976
|
+
```text
|
|
977
|
+
ε² = 0
|
|
978
|
+
```
|
|
979
|
+
|
|
980
|
+
Multiplication rules:
|
|
981
|
+
|
|
982
|
+
```text
|
|
983
|
+
e_i * e_j = parent product
|
|
984
|
+
e_i * (ε e_j) = ε (e_i e_j)
|
|
985
|
+
(ε e_i) * e_j = ε (e_i e_j)
|
|
986
|
+
(ε e_i) * (ε e_j) = 0
|
|
987
|
+
```
|
|
988
|
+
|
|
989
|
+
---
|
|
990
|
+
|
|
991
|
+
# Complexity
|
|
992
|
+
|
|
993
|
+
| Operation | Complexity | Memory |
|
|
994
|
+
|---|---:|---:|
|
|
995
|
+
| Full table generation | O(4^n) | O(4^n) |
|
|
996
|
+
| Holographic multiplication | O(n) | O(1) |
|
|
997
|
+
| Fast bitwise multiplication | O(1) Word-RAM | O(1) |
|
|
998
|
+
|
|
999
|
+
For arbitrary-precision integers, the fast evaluator uses O(n) bit operations, where:
|
|
1000
|
+
|
|
1001
|
+
```text
|
|
1002
|
+
n = ceil(log2(max(i, j) + 1))
|
|
1003
|
+
```
|
|
1004
|
+
|
|
1005
|
+
---
|
|
1006
|
+
|
|
1007
|
+
# Testing
|
|
1008
|
+
|
|
1009
|
+
Run all tests:
|
|
1010
|
+
|
|
1011
|
+
```bash
|
|
1012
|
+
pytest -v
|
|
1013
|
+
```
|
|
1014
|
+
|
|
1015
|
+
Run specific test files:
|
|
1016
|
+
|
|
1017
|
+
```bash
|
|
1018
|
+
pytest tests/test_mega_mother.py -v
|
|
1019
|
+
pytest tests/test_fast_mode.py -v
|
|
1020
|
+
```
|
|
1021
|
+
|
|
1022
|
+
The test suite validates:
|
|
1023
|
+
|
|
1024
|
+
- Basis notation conversion.
|
|
1025
|
+
- Input validation.
|
|
1026
|
+
- Standard table generation.
|
|
1027
|
+
- Split table generation.
|
|
1028
|
+
- Dual table generation.
|
|
1029
|
+
- Holographic O(n) multiplication.
|
|
1030
|
+
- Fast O(1) multiplication.
|
|
1031
|
+
- Cross-validation between tables and multipliers.
|
|
1032
|
+
- Facade API behavior.
|
|
1033
|
+
- CSV export.
|
|
1034
|
+
|
|
1035
|
+
---
|
|
1036
|
+
|
|
1037
|
+
# Repository Structure
|
|
1038
|
+
|
|
1039
|
+
```text
|
|
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
|
|
1081
|
+
```
|
|
1082
|
+
|
|
1083
|
+
# Scope, strengths and limitations
|
|
1084
|
+
|
|
1085
|
+
|
|
1086
|
+
## What this package is
|
|
1087
|
+
|
|
1088
|
+
It computes the product of two **signed basis elements** of a Cayley–Dickson algebra: `±e_i × ±e_j → ±e_k` (or zero in dual algebras). It is a low-level component, a sign and index calculator, not a number type. There are no coefficients, no sums, and no vectors.
|
|
1089
|
+
|
|
1090
|
+
## Advantages
|
|
1091
|
+
|
|
1092
|
+
- **One job, small surface.** About 2,000 lines, one dependency (NumPy), and multipliers that keep no per-call state.
|
|
1093
|
+
- **Two interchangeable engines.**
|
|
1094
|
+
- `fast` is a closed-form bitwise evaluator. It does constant work per call for word-sized indices, and cost grows only with bit length for arbitrary-precision indices.
|
|
1095
|
+
- `holographic` is an O(n) recursive descent, useful as a cross-check.
|
|
1096
|
+
- **Works where tables cannot.** Only the two indices are needed, so indices hundreds of bits long are fine. Full tables need 4^n entries.
|
|
1097
|
+
- **Cross-validated.** The test suite checks the table builders, the `fast` engine and the `holographic` engine against each other.
|
|
1098
|
+
- **Strict about types.** `bool`, `float`, `str` and `list` inputs are rejected. Results are plain Python `int`s.
|
|
1099
|
+
- **Tested on Python 3.10–3.14** and with NumPy 1.22 and newer.
|
|
1100
|
+
|
|
1101
|
+
## Input rules (0.4.x behavior)
|
|
1102
|
+
|
|
1103
|
+
| Kind | Element form | `dim` | Index range |
|
|
1104
|
+
|---|---|---|---|
|
|
1105
|
+
| `standard` | `(sign, index)` | not used | any integer ≥ 0 (no upper bound, since there is no `dim` to check against) |
|
|
1106
|
+
| `split` | `(sign, index)` | **required** | `0 ≤ index < 2**dim` |
|
|
1107
|
+
| `dual`, `dual_split` | `(sign, global_index)` or `(sign, local_index, eps)` | **required** | global: `0 ≤ i < 2**(dim+1)`; local: `0 ≤ i < 2**dim` |
|
|
1108
|
+
|
|
1109
|
+
- Elements must be **tuples**. Integers only, and NumPy integers are accepted.
|
|
1110
|
+
- `sign` should be `-1` or `+1`. Note: `multiply` currently also accepts `0` as a formal zero and returns zero. **Do not rely on this**; it may be removed.
|
|
1111
|
+
- Dual elements have two spellings of the same thing. At `dim=3`, `(1, 9)` and `(1, 1, 1)` both mean `+ε·e1` (global index `8 + 1`).
|
|
1112
|
+
- **Known looseness:** at `dim=3`, `(1, 9, 1)` and even `(1, 9, 0)` are also accepted and read as `+ε·e1`. The second one contradicts itself, so don't rely on it.
|
|
1113
|
+
- The dual result is always `(sign, local_index, eps)`, and `ε·ε` gives `(0, 0, 0)`.
|
|
1114
|
+
|
|
1115
|
+
## What the package cannot detect (your responsibility)
|
|
1116
|
+
|
|
1117
|
+
Elements are plain tuples, so they do not remember which algebra produced them.
|
|
1118
|
+
|
|
1119
|
+
- Feeding a result from one `dim` into an algebra of a different `dim` is not detected if the index happens to be in range.
|
|
1120
|
+
- Mixing `standard` and `split` elements is not detected. The same tuple means different things: `e2·e2` is `-1` in the standard algebra, `+1` in `split` with `dim=2`, and `-1` in `split` with `dim>=3`.
|
|
1121
|
+
- For `standard`, nothing tells you an index is "too big for the octonions".
|
|
1122
|
+
|
|
1123
|
+
## Not supported
|
|
1124
|
+
|
|
1125
|
+
- **No chain multiplication and no expressions.** `multiply` is strictly binary. You can pass a result into the next call yourself, but you choose the bracketing. From `n=3` (octonions) upward multiplication is **not associative**, so `(ab)c` and `a(bc)` can differ in sign.
|
|
1126
|
+
- **No coefficients, sums, vectors, arrays, or parsing** of expressions like `e1+e2+e12`. This is planned for a separate package built on top of this one.
|
|
1127
|
+
- **No addition, conjugation, norm, inverse, or division.**
|
|
1128
|
+
- **`split` means one split doubling on top of a standard parent.** Other sign patterns are not offered.
|
|
1129
|
+
- **`dual` and `dual_split`** extend a standard or split parent with a central `ε`, where `ε² = 0`.
|
|
1130
|
+
|
|
1131
|
+
## Algebra facts to keep in mind
|
|
1132
|
+
|
|
1133
|
+
| n | Standard | Split |
|
|
1134
|
+
|---|---|---|
|
|
1135
|
+
| 1 | complex, commutative | split-complex, commutative, has zero divisors |
|
|
1136
|
+
| 2 | quaternions, associative, **not commutative** | split-quaternions, associative, not commutative |
|
|
1137
|
+
| 3 | octonions, alternative, **not associative** | split-octonions, alternative, not associative, has zero divisors |
|
|
1138
|
+
| ≥ 4 | sedenions and beyond: **zero divisors**, no longer alternative | no longer alternative |
|
|
1139
|
+
|
|
1140
|
+
## Convention
|
|
1141
|
+
|
|
1142
|
+
Products follow the standard doubling `(a, b)(c, d) = (ac − d*b, da + bc*)` (split algebras flip the sign of the `d*b` term at the top level). Other conventions give isomorphic algebras with **different tables**, so comparing against another source may show sign differences after relabeling. For example, here `e1·e2 = e3` and `e1·e6 = −e7`.
|
|
1143
|
+
|
|
1144
|
+
## Direct low-level classes
|
|
1145
|
+
|
|
1146
|
+
`FastStandard`, `FastSplit`, `FastDual`, `StandardHolographic`, `SplitHolographic` and `DualHolographic` are exported, but they validate **differently** from each other and from `multiply`. For example, `FastSplit` accepts a zero element while the other three reject it. Their `multiply_indices` methods do only minimal checks. **Prefer `multiply`.** These classes are not a stable API and are expected to become internal.
|
|
1147
|
+
|
|
1148
|
+
## Tables and memory
|
|
1149
|
+
|
|
1150
|
+
Full tables have `4**n` entries. `build_table` refuses requests above a default memory budget (`max_bytes`, 256 MiB):
|
|
1151
|
+
|
|
1152
|
+
- `standard` and `split` are allowed up to `n = 13`.
|
|
1153
|
+
- `dual` and `dual_split` are allowed up to `n = 12`, since they are one doubling larger.
|
|
1154
|
+
|
|
1155
|
+
Use `estimate_table_bytes(kind, n)` to check a size, and pass a larger `max_bytes` (or `None`) if you really mean it. In dual tables, `sign == 0` marks `ε·ε`.
|
|
1156
|
+
|
|
1157
|
+
## Stability and planned changes
|
|
1158
|
+
|
|
1159
|
+
- Pin your dependency, for example `hypercomplex-engine>=0.4.1,<0.5`.
|
|
1160
|
+
- *Planned for 0.5.0, subject to change:* stricter inputs (no zero elements, one dual form), and low-level classes made internal. Breaking changes will be listed in the release notes.
|
|
1161
|
+
- Do not treat the package as 1.0-stable until it has been used by futur a palnned package the vector-and-expression package.
|
|
1162
|
+
|
|
1163
|
+
---
|
|
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
|
+
|
|
1183
|
+
# Citation
|
|
1184
|
+
|
|
1185
|
+
If you use this engine in your research, physics simulations, or geometric deep learning models, please cite the underlying theoretical preprints:
|
|
1186
|
+
|
|
1187
|
+
```bibtex
|
|
1188
|
+
@article{ben abdessalem2026,
|
|
1189
|
+
author = "maher ben abdessalem",
|
|
1190
|
+
title = "{An O(1) Bitwise Evaluator for Cayley--Dickson Sign Structure: Ordinary, Split, Dual, and Tensor Constructions}",
|
|
1191
|
+
year = "2026",
|
|
1192
|
+
month = "9",
|
|
1193
|
+
url = "https://figshare.com/articles/preprint/A_Proven_Sign_Law_for_Cayley-Dickson_Algebras_Ordinary_and_Split_Constructions/33705022",
|
|
1194
|
+
doi = "10.6084/m9.figshare.33705022.v8"
|
|
1195
|
+
}
|
|
1196
|
+
|
|
1197
|
+
```
|
|
1198
|
+
|
|
1199
|
+
|
|
1200
|
+
### Acknowledgments
|
|
1201
|
+
|
|
1202
|
+
The author gratefully acknowledges **Prof. Derek Abbott**, **Dr. James M. Chappell**, and PhD candidate **Greg P. Wilmot** from the University of Adelaide, Australia, for the opportunity of collaboration and a deeper study of hypercomplex numbers. Special thanks go to **Greg P. Wilmot** for his work on the structure of Cayley-Dickson algebras and for acknowledging the author's contribution to his paper, *"Structure of the Cayley-Dickson algebras"* ([arXiv:2505.11747](https://arxiv.org)).
|
|
1203
|
+
|
|
1204
|
+
|
|
1205
|
+
---
|
|
1206
|
+
|
|
1207
|
+
## References
|
|
1208
|
+
|
|
1209
|
+
- Guangbin Ren and Xin Zhao, "The Explicit Twisted Group Algebra Structure of
|
|
1210
|
+
the Cayley–Dickson Algebra," *Advances in Applied Clifford Algebras* 33,
|
|
1211
|
+
Article 49 (2023). https://doi.org/10.1007/s00006-023-01296-6 ·
|
|
1212
|
+
arXiv:2205.07986.
|
|
1213
|
+
|
|
1214
|
+
# License
|
|
1215
|
+
|
|
1216
|
+
Apache 2.0 License.
|
|
1217
|
+
|
|
1218
|
+
See [`LICENSE`](LICENSE) for details.
|
|
1219
|
+
|
|
1220
|
+
Copyright (c) 2026 Maher Ben Abdessalem
|