hypercomplex-engine 0.6.0__py3-none-any.whl → 0.6.0.1__py3-none-any.whl

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.
@@ -0,0 +1,28 @@
1
+ Metadata-Version: 2.4
2
+ Name: hypercomplex-engine
3
+ Version: 0.6.0.1
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
@@ -23,9 +23,9 @@ hypercomplex_engine/core/vectorized/vectorized_standard.py,sha256=yCV48LvwrMZxg8
23
23
  hypercomplex_engine/printer/__init__.py,sha256=6EZOUBYb9TDgfqrFpnIfPS1bbPFZ0dMX6RCPDZepL6M,129
24
24
  hypercomplex_engine/printer/cd_format.py,sha256=X_cotGumJlRMuJO5cbsnI8FA9Py12TGYftPlUdx-9xg,5731
25
25
  hypercomplex_engine/printer/cd_table_printer.py,sha256=Ny1g5osDwttI5I8-KV4DzhVhWp_7fP-R5lYyC9sEhKE,4973
26
- hypercomplex_engine-0.6.0.dist-info/licenses/LICENSE,sha256=WNHhf_5RCaeuKWyq_K39vmp9F28LxKsB4SpomwSZ2L0,11357
27
- hypercomplex_engine-0.6.0.dist-info/licenses/NOTICE,sha256=WRgJ9Hv74Vke3ByFbvR6sqdlinPx4rCWDc0-7Iyh9VI,745
28
- hypercomplex_engine-0.6.0.dist-info/METADATA,sha256=-xOkrkRP_H__kmTQ3BLBl_t8SghUkReStNVHtcweCaY,26289
29
- hypercomplex_engine-0.6.0.dist-info/WHEEL,sha256=YVMoNqKzERt-wjUZwJ33xBGAwnFl-4cqbYkTtWa4itE,91
30
- hypercomplex_engine-0.6.0.dist-info/top_level.txt,sha256=654ACRoo9vk38vKW7kVBfgD-IjIADgVmh75smmXBZ88,20
31
- hypercomplex_engine-0.6.0.dist-info/RECORD,,
26
+ hypercomplex_engine-0.6.0.1.dist-info/licenses/LICENSE,sha256=WNHhf_5RCaeuKWyq_K39vmp9F28LxKsB4SpomwSZ2L0,11357
27
+ hypercomplex_engine-0.6.0.1.dist-info/licenses/NOTICE,sha256=WRgJ9Hv74Vke3ByFbvR6sqdlinPx4rCWDc0-7Iyh9VI,745
28
+ hypercomplex_engine-0.6.0.1.dist-info/METADATA,sha256=hNBGpVXGfhOcNeSv08ojYUAcwJUccR8q6iaQmr0_RZY,1398
29
+ hypercomplex_engine-0.6.0.1.dist-info/WHEEL,sha256=YVMoNqKzERt-wjUZwJ33xBGAwnFl-4cqbYkTtWa4itE,91
30
+ hypercomplex_engine-0.6.0.1.dist-info/top_level.txt,sha256=654ACRoo9vk38vKW7kVBfgD-IjIADgVmh75smmXBZ88,20
31
+ hypercomplex_engine-0.6.0.1.dist-info/RECORD,,
@@ -1,1148 +0,0 @@
1
- Metadata-Version: 2.4
2
- Name: hypercomplex-engine
3
- Version: 0.6.0
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
- # hypercomplex-engine
31
-
32
- [![License: Apache 2.0](https://img.shields.io/badge/License-Apache%202.0-blue.svg)](https://www.apache.org/licenses/LICENSE-2.0)
33
- [![Python 3.10+](https://img.shields.io/badge/python-3.10+-blue.svg)](https://www.python.org/downloads/)
34
- [![GitHub Repo](https://img.shields.io/badge/GitHub-maher1719%2Fhypercomplex--engine-black?logo=github)](https://github.com/maher1719/hypercomplex-engine)
35
- [![PyPI version](https://img.shields.io/pypi/v/hypercomplex-engine.svg)](https://pypi.org/project/hypercomplex-engine/)
36
- [![Downloads](https://static.pepy.tech/badge/hypercomplex-engine)](https://pepy.tech/project/hypercomplex-engine)
37
-
38
-
39
- 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.
40
-
41
-
42
- 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).
43
-
44
- This library provides the computational substrate for high-dimensional hypercomplex algebra, featuring:
45
-
46
- - **Full multiplication table generation** for standard, split, and dual algebras.
47
- - **O(n) holographic** table-free recursive descent multiplication.
48
- - **O(1) fast bitwise** closed-form multiplication.
49
- - **Integer, graded, and LaTeX** notation formatting.
50
- - **CSV export** for tables (matrix and long formats).
51
- - A **simple facade API** for everyday use, and direct low-level classes for advanced physics/math engines.
52
-
53
- ---
54
-
55
- ## Scope and limitations
56
-
57
- 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)
58
-
59
-
60
- ## 📄 Publications & Preprints
61
-
62
- This library serves as the formal verification substrate and computational engine for the following mathematical preprints:
63
-
64
- **1. The Sign Structure of Cayley–Dickson and Split Algebras By Blocks**
65
- *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.*
66
- * 📊 **Figshare:** [10.6084/m9.figshare.33705022](https://doi.org/10.6084/m9.figshare.33705022)
67
- * 📦 **Zenodo:** [10.5281/zenodo.22051873](https://doi.org/10.5281/zenodo.22051873)
68
-
69
- ---
70
-
71
- ## Supported algebras
72
-
73
- | Kind | Description |
74
- |---|---|
75
- | `standard` | Ordinary Cayley–Dickson algebras: real, complex, quaternions, octonions, sedenions, ... |
76
- | `split` | Split Cayley–Dickson algebras: standard parent plus one split doubling at the top |
77
- | `dual` | Dual extension of a standard algebra, with ε² = 0 |
78
- | `dual_split` | Dual extension of a split algebra, with ε² = 0 |
79
-
80
- ---
81
-
82
- ## Installation
83
-
84
- Clone the repository:
85
-
86
- ```bash
87
- git clone https://github.com/maher1719/hypercomplex-engine.git
88
- cd hypercomplex-engine
89
- ```
90
- Install with pip:
91
-
92
- ```bash
93
- pip install hypercomplex-engine
94
- ```
95
-
96
- Install in editable mode:
97
-
98
- ```bash
99
- pip install -e .
100
- ```
101
-
102
- Run the tests:
103
-
104
- ```bash
105
- pytest -v
106
- ```
107
-
108
- ---
109
-
110
- # Basic Use
111
-
112
- The simplest way to use the library is through the top-level facade API.
113
-
114
- ```python
115
- from hypercomplex_engine import (
116
- build_table,
117
- multiply,
118
- format_element,
119
- print_table,
120
- export_csv,
121
- )
122
- ```
123
-
124
- ---
125
-
126
- ## Build a table
127
-
128
- ```python
129
- table = build_table("standard", 3)
130
- ```
131
-
132
- This builds the octonion multiplication table.
133
-
134
- Dimensions:
135
-
136
- ```text
137
- n = 0 -> real numbers, dimension 1
138
- n = 1 -> complex numbers, dimension 2
139
- n = 2 -> quaternions, dimension 4
140
- n = 3 -> octonions, dimension 8
141
- n = 4 -> sedenions, dimension 16
142
- ```
143
-
144
- ---
145
-
146
- ## Print a table
147
-
148
- ```python
149
- print_table(table, title="Octonions", mode="integer")
150
- ```
151
-
152
- Example output style:
153
-
154
- ```text
155
- e0 e1 e2 e3 e4 e5 e6 e7
156
- e0 | +e0 +e1 +e2 +e3 +e4 +e5 +e6 +e7
157
- e1 | +e1 -e0 +e3 -e2 +e5 -e4 -e7 +e6
158
- ...
159
- ```
160
-
161
- You can also use graded notation:
162
-
163
- ```python
164
- print_table(table, title="Octonions", mode="graded")
165
- ```
166
-
167
- Example:
168
-
169
- ```text
170
- 1 o1 o2 o3 o4 o5 o6 o7
171
- 1 | +1 +o1 +o2 +o3 +o4 +o5 +o6 +o7
172
- o1 | +o1 -1 ...
173
- ...
174
- ```
175
-
176
- ---
177
-
178
- ## Export a table to CSV
179
-
180
- Matrix-style CSV:
181
-
182
- ```python
183
- export_csv(
184
- "octonions_graded.csv",
185
- table,
186
- mode="graded",
187
- csv_mode="matrix",
188
- )
189
- ```
190
-
191
- Long-format CSV for data analysis:
192
-
193
- ```python
194
- export_csv(
195
- "octonions_long.csv",
196
- table,
197
- mode="integer",
198
- csv_mode="long",
199
- )
200
- ```
201
-
202
- The long format produces rows like:
203
-
204
- ```csv
205
- i,j,sign,index
206
- 0,0,1,0
207
- 0,1,1,1
208
- 1,0,1,1
209
- 1,1,-1,0
210
- ...
211
- ```
212
-
213
- ---
214
-
215
- ## Multiply two basis elements
216
-
217
- ```python
218
- result = multiply("standard", (1, 1), (1, 2))
219
-
220
- print(result)
221
- # (1, 3)
222
- ```
223
-
224
- This means:
225
-
226
- ```text
227
- e1 * e2 = +e3
228
- ```
229
-
230
- Format the result:
231
-
232
- ```python
233
- print(format_element(result, mode="integer"))
234
- # +e3
235
-
236
- print(format_element(result, mode="graded"))
237
- # +o12
238
-
239
- print(format_element(result, mode="latex"))
240
- # +e_{3}
241
- ```
242
-
243
- Note:
244
-
245
- ```text
246
- integer mode uses the basis index:
247
- e3
248
-
249
- graded mode uses the generator decomposition:
250
- index 3 = binary 011 = generators 1 and 2 = o12
251
- ```
252
-
253
- ---
254
-
255
- ## Split multiplication
256
-
257
- ```python
258
- result = multiply("split", (1, 1), (1, 1), dim=1)
259
-
260
- print(result)
261
- # (1, 0)
262
- ```
263
-
264
- In split-complex numbers:
265
-
266
- ```text
267
- e1² = +e0
268
- ```
269
-
270
- ---
271
-
272
- ## Dual multiplication
273
-
274
- ```python
275
- # eps*e0 represented as local tuple: (sign, local_index, eps_flag)
276
- eps_e0 = (1, 0, 1)
277
-
278
- result = multiply("dual", (1, 0), eps_e0, dim=1)
279
-
280
- print(result)
281
- # (1, 0, 1)
282
-
283
- print(format_element(result, mode="integer"))
284
- # +eps
285
- ```
286
-
287
- Nilpotency:
288
-
289
- ```python
290
- result = multiply("dual", eps_e0, eps_e0, dim=1)
291
-
292
- print(result)
293
- # (0, 0, 0)
294
- ```
295
-
296
- This means:
297
-
298
- ```text
299
- ε² = 0
300
- ```
301
-
302
- ---
303
-
304
- # Intermediate Use
305
-
306
- The facade API is enough for most users.
307
-
308
- For more control, you can choose the computation engine and work directly with tables or multipliers.
309
-
310
- ---
311
-
312
- ## Engines
313
-
314
- The `multiply` function supports two engines:
315
-
316
- ```python
317
- multiply(kind, a, b, dim=None, engine="fast")
318
- ```
319
-
320
- | Engine | Complexity | Description |
321
- |---|---:|---|
322
- | `"fast"` | O(1) | Bitwise closed-form sign evaluator |
323
- | `"holographic"` | O(n) | Recursive block descent |
324
-
325
- Example:
326
-
327
- ```python
328
- from hypercomplex_engine import multiply
329
-
330
- a = (1, 3)
331
- b = (1, 5)
332
-
333
- fast_result = multiply("standard", a, b, engine="fast")
334
- holo_result = multiply("standard", a, b, engine="holographic")
335
-
336
- assert fast_result == holo_result
337
- ```
338
-
339
- ---
340
-
341
- ## Algebra kinds
342
-
343
- ```python
344
- multiply("standard", a, b)
345
- multiply("split", a, b, dim=3)
346
- multiply("dual", a, b, dim=3)
347
- multiply("dual_split", a, b, dim=3)
348
- ```
349
-
350
- For `standard`, `dim` is not needed.
351
-
352
- For `split`, `dual` and `dual_split`, `dim` is required.
353
-
354
- ---
355
-
356
- ## Table builders directly
357
-
358
- ```python
359
- from hypercomplex_engine import (
360
- StandardTableBuilder,
361
- SplitTableBuilder,
362
- DualTableBuilder,
363
- )
364
-
365
- standard_builder = StandardTableBuilder()
366
- split_builder = SplitTableBuilder()
367
- dual_builder = DualTableBuilder()
368
-
369
- signs, indices = standard_builder.build(3)
370
- signs, indices = split_builder.build(3)
371
- signs, indices, eps = dual_builder.build(2, split=False)
372
- ```
373
-
374
- Return conventions:
375
-
376
- ```text
377
- standard:
378
- signs, indices
379
-
380
- split:
381
- signs, indices
382
-
383
- dual:
384
- signs, indices, eps
385
- ```
386
-
387
- For dual tables:
388
-
389
- - `signs[i, j]` is the sign.
390
- - `indices[i, j]` is the local base index.
391
- - `eps[i, j]` is the epsilon flag.
392
-
393
- ---
394
-
395
- ## Multipliers directly
396
-
397
- ```python
398
- from hypercomplex_engine import (
399
- StandardHolographic,
400
- SplitHolographic,
401
- DualHolographic,
402
- )
403
-
404
- holo = StandardHolographic()
405
- result = holo.multiply((1, 1), (1, 2))
406
-
407
- print(result)
408
- # (1, 3)
409
- ```
410
-
411
- Split:
412
-
413
- ```python
414
- split_holo = SplitHolographic()
415
- result = split_holo.multiply((1, 2), (1, 2), dim=2)
416
-
417
- print(result)
418
- # (1, 0)
419
- ```
420
-
421
- Dual:
422
-
423
- ```python
424
- dual_holo = DualHolographic(split=False)
425
-
426
- result = dual_holo.multiply((1, 0), (1, 2), dim=1)
427
-
428
- print(result)
429
- # (1, 0, 1)
430
- ```
431
-
432
- ---
433
-
434
- ## Fast O(1) multipliers directly
435
-
436
- ```python
437
- from hypercomplex_engine import (
438
- FastStandard,
439
- FastSplit,
440
- FastDual,
441
- )
442
-
443
- fast = FastStandard()
444
-
445
- result = fast.multiply((1, 1), (1, 2))
446
-
447
- print(result)
448
- # (1, 3)
449
- ```
450
-
451
- Split:
452
-
453
- ```python
454
- fast_split = FastSplit()
455
-
456
- result = fast_split.multiply((1, 2), (1, 2), dim=2)
457
-
458
- print(result)
459
- # (1, 0)
460
- ```
461
-
462
- Dual:
463
-
464
- ```python
465
- fast_dual = FastDual(split=False)
466
-
467
- result = fast_dual.multiply((1, 0), (1, 0, 1), dim=1)
468
-
469
- print(result)
470
- # (1, 0, 1)
471
- ```
472
-
473
- ---
474
-
475
- ## Formatting modes
476
-
477
- | Mode | Example |
478
- |---|---|
479
- | `"integer"` | `+e5` |
480
- | `"graded"` | `+o13` |
481
- | `"latex"` | `+e_{5}` |
482
- | `"latex_integer"` | `+e_{5}` |
483
- | `"latex_graded"` | `+o_{13}` |
484
-
485
- Example:
486
-
487
- ```python
488
- from hypercomplex_engine import format_element
489
-
490
- element = (-1, 5)
491
-
492
- print(format_element(element, mode="integer"))
493
- # -e5
494
-
495
- print(format_element(element, mode="graded"))
496
- # -o13
497
-
498
- print(format_element(element, mode="latex"))
499
- # -e_{5}
500
-
501
- print(format_element(element, mode="latex_integer"))
502
- # -e_{5}
503
-
504
- print(format_element(element, mode="latex_graded"))
505
- # -o_{13}
506
- ```
507
-
508
- ---
509
-
510
- # Advanced Use
511
-
512
- This section is for contributors, benchmarking, physics engines, and symbolic pipelines.
513
-
514
- ---
515
-
516
- ## Direct low-level imports
517
-
518
- If you prefer explicit imports:
519
-
520
- ```python
521
- from hypercomplex_engine.core.table_builder import (
522
- StandardTableBuilder,
523
- SplitTableBuilder,
524
- DualTableBuilder,
525
- )
526
-
527
- from hypercomplex_engine.core.holographic import (
528
- StandardHolographic,
529
- SplitHolographic,
530
- DualHolographic,
531
- )
532
-
533
- from hypercomplex_engine.core.fast import (
534
- FastStandard,
535
- FastSplit,
536
- FastDual,
537
- )
538
-
539
- from hypercomplex_engine.printer import (
540
- CDFormat,
541
- CDTablePrinter,
542
- )
543
- ```
544
-
545
- ---
546
-
547
- ## Cross-validating O(1) against the full table
548
-
549
- ```python
550
- from hypercomplex_engine import StandardTableBuilder, FastStandard
551
-
552
- builder = StandardTableBuilder()
553
- fast = FastStandard()
554
-
555
- n = 4
556
- signs, indices = builder.build(n)
557
-
558
- dim = 1 << n
559
-
560
- for i in range(dim):
561
- for j in range(dim):
562
- fast_sign, fast_idx = fast.multiply_indices(i, j)
563
-
564
- assert int(signs[i, j]) == fast_sign
565
- assert int(indices[i, j]) == fast_idx
566
- ```
567
-
568
- This proves that the O(1) evaluator agrees with the O(4^n) table builder.
569
-
570
- ---
571
-
572
- ## Cross-validating split O(1) against the split table
573
-
574
- ```python
575
- from hypercomplex_engine import SplitTableBuilder, FastSplit
576
-
577
- builder = SplitTableBuilder()
578
- fast = FastSplit()
579
-
580
- n = 4
581
- signs, indices = builder.build(n)
582
-
583
- dim = 1 << n
584
-
585
- for i in range(dim):
586
- for j in range(dim):
587
- fast_sign, fast_idx = fast.multiply_indices(i, j, dim=n)
588
-
589
- assert int(signs[i, j]) == fast_sign
590
- assert int(indices[i, j]) == fast_idx
591
- ```
592
-
593
- ---
594
-
595
- ## Dual local and global indices
596
-
597
- For dual multiplication, the total dimension is:
598
-
599
- ```text
600
- 2^(dim + 1)
601
- ```
602
-
603
- The epsilon bit is bit `dim`.
604
-
605
- Example for `dim=1`:
606
-
607
- ```text
608
- lower half: 0, 1 base elements
609
- upper half: 2, 3 epsilon elements
610
- ```
611
-
612
- The dual multipliers accept both:
613
-
614
- ```python
615
- # global index tuple
616
- (1, 2)
617
-
618
- # local tuple with epsilon flag
619
- (1, 0, 1)
620
- ```
621
-
622
- Both represent ε·e₀ when `dim=1`.
623
-
624
- The output convention is:
625
-
626
- ```python
627
- (sign, local_index, eps_flag)
628
- ```
629
-
630
- This makes formatting easy:
631
-
632
- ```python
633
- from hypercomplex_engine import format_element
634
-
635
- result = (1, 0, 1)
636
-
637
- print(format_element(result, mode="integer"))
638
- # +eps
639
-
640
- print(format_element(result, mode="latex"))
641
- # +\epsilon
642
- ```
643
-
644
- ---
645
-
646
- ## Using the fast engine in a physics loop
647
-
648
- For simulations, avoid building large tables. Use the fast engine directly.
649
-
650
- ```python
651
- from hypercomplex_engine import FastStandard
652
-
653
- fast = FastStandard()
654
-
655
- def basis_product(i: int, j: int):
656
- sign, index = fast.multiply((1, i), (1, j))
657
- return sign, index
658
-
659
- sign, index = basis_product(1, 2)
660
-
661
- print(sign, index)
662
- # 1 3
663
- ```
664
-
665
- For octonionic or higher-dimensional simulations, this avoids O(4^n) memory.
666
-
667
- ---
668
-
669
- ## Table size warning
670
-
671
- Full table generation grows as:
672
-
673
- ```text
674
- entries = 4^n
675
- ```
676
-
677
- where `n` is the dimension exponent.
678
-
679
- | n | Dimension | Entries |
680
- |---:|---:|---:|
681
- | 0 | 1 | 1 |
682
- | 1 | 2 | 4 |
683
- | 2 | 4 | 16 |
684
- | 3 | 8 | 64 |
685
- | 4 | 16 | 256 |
686
- | 5 | 32 | 1,024 |
687
- | 6 | 64 | 4,096 |
688
- | 8 | 256 | 65,536 |
689
- | 10 | 1,024 | 1,048,576 |
690
- | 12 | 4,096 | 16,777,216 |
691
-
692
- For large dimensions, prefer:
693
-
694
- ```python
695
- engine="fast"
696
- ```
697
-
698
- or:
699
-
700
- ```python
701
- engine="holographic"
702
- ```
703
-
704
- ---
705
-
706
- # API Reference
707
-
708
- ## Top-level functions
709
-
710
- ### `build_table(kind, n)`
711
-
712
- Builds a multiplication table.
713
-
714
- ```python
715
- table = build_table("standard", 3)
716
- ```
717
-
718
- Returns:
719
-
720
- ```text
721
- standard:
722
- (signs, indices)
723
-
724
- split:
725
- (signs, indices)
726
-
727
- dual:
728
- (signs, indices, eps)
729
-
730
- dual_split:
731
- (signs, indices, eps)
732
- ```
733
-
734
- ---
735
-
736
- ### `multiply(kind, a, b, dim=None, engine="fast")`
737
-
738
- Multiplies two basis elements.
739
-
740
- ```python
741
- result = multiply("standard", (1, 1), (1, 2))
742
- ```
743
-
744
- Returns:
745
-
746
- ```text
747
- standard:
748
- (sign, index)
749
-
750
- split:
751
- (sign, index)
752
-
753
- dual:
754
- (sign, local_index, eps_flag)
755
-
756
- dual_split:
757
- (sign, local_index, eps_flag)
758
- ```
759
-
760
- ---
761
-
762
- ### `format_element(element, mode="integer")`
763
-
764
- Formats a basis element tuple.
765
-
766
- ```python
767
- format_element((1, 3), mode="integer")
768
- # "+e3"
769
-
770
- format_element((1, 3), mode="graded")
771
- # "+o12"
772
- ```
773
-
774
- ---
775
-
776
- ### `print_table(table, title=None, limit=None, mode="integer")`
777
-
778
- Prints a table.
779
-
780
- ```python
781
- table = build_table("standard", 2)
782
- print_table(table, mode="graded")
783
- ```
784
-
785
- ---
786
-
787
- ### `export_csv(path, table, mode="integer", csv_mode="matrix")`
788
-
789
- Exports a table to CSV.
790
-
791
- ```python
792
- table = build_table("standard", 3)
793
-
794
- export_csv(
795
- "octonions.csv",
796
- table,
797
- mode="graded",
798
- csv_mode="matrix",
799
- )
800
- ```
801
-
802
- CSV modes:
803
-
804
- | `csv_mode` | Output |
805
- |---|---|
806
- | `"matrix"` | Spreadsheet-style grid |
807
- | `"long"` | One row per product |
808
-
809
- ---
810
-
811
- ## Algebra kinds
812
-
813
- | Kind | Meaning |
814
- |---|---|
815
- | `"standard"` | Ordinary Cayley–Dickson |
816
- | `"split"` | Split Cayley–Dickson |
817
- | `"dual"` | Dual extension of standard algebra |
818
- | `"dual_split"` | Dual extension of split algebra |
819
-
820
- Aliases:
821
-
822
- ```text
823
- standard: "std", "ordinary", "o"
824
- split: "s"
825
- dual: "d", "dual_standard"
826
- dual_split: "split_dual", "ds"
827
- ```
828
-
829
- ---
830
-
831
- ## Engines
832
-
833
- | Engine | Aliases | Complexity |
834
- |---|---|---:|
835
- | `"fast"` | `"o1"`, `"bitwise"`, `"constant"` | O(1) Word-RAM |
836
- | `"holographic"` | `"on"`, `"descent"` | O(n) |
837
-
838
- ---
839
-
840
- # Mathematical Background
841
-
842
- ## Basis product rule
843
-
844
- For standard and split Cayley–Dickson algebras:
845
-
846
- ```text
847
- e_i * e_j = sign(i, j) * e_{i XOR j}
848
- ```
849
-
850
- The index is always:
851
-
852
- ```text
853
- i XOR j
854
- ```
855
-
856
- The sign is determined by the OPMT block laws.
857
-
858
- ---
859
-
860
- ## Standard doubling formula
861
-
862
- ```text
863
- (a, b)(c, d) = (ac - d* b, da + b c*)
864
- ```
865
-
866
- with conjugation:
867
-
868
- ```text
869
- e0* = e0
870
- ek* = -ek for k > 0
871
- ```
872
-
873
- ---
874
-
875
- ## Split doubling formula
876
-
877
- ```text
878
- (a, b)(c, d) = (ac + d* b, da + b c*)
879
- ```
880
-
881
- The only difference from the standard construction is the sign of the `d* b` term.
882
-
883
- This causes Block d signs to invert relative to the standard algebra.
884
-
885
- ---
886
-
887
- ## Block decomposition
888
-
889
- Each multiplication table splits into four blocks:
890
-
891
- ```text
892
- [ a b ]
893
- [ c d ]
894
- ```
895
-
896
- where:
897
-
898
- ```text
899
- Block a: e_i * e_j
900
- Block b: e_i * (e_j ℓ)
901
- Block c: (e_i ℓ) * e_j
902
- Block d: (e_i ℓ) * (e_j ℓ)
903
- ```
904
-
905
- For standard algebras:
906
-
907
- ```text
908
- Block d interior sign = -σ_a
909
- ```
910
-
911
- For split algebras:
912
-
913
- ```text
914
- Block d interior sign = +σ_a
915
- ```
916
-
917
- ---
918
-
919
- ## Dual numbers
920
-
921
- Dual algebras adjoin ε such that:
922
-
923
- ```text
924
- ε² = 0
925
- ```
926
-
927
- Multiplication rules:
928
-
929
- ```text
930
- e_i * e_j = parent product
931
- e_i * (ε e_j) = ε (e_i e_j)
932
- (ε e_i) * e_j = ε (e_i e_j)
933
- (ε e_i) * (ε e_j) = 0
934
- ```
935
-
936
- ---
937
-
938
- # Complexity
939
-
940
- | Operation | Complexity | Memory |
941
- |---|---:|---:|
942
- | Full table generation | O(4^n) | O(4^n) |
943
- | Holographic multiplication | O(n) | O(1) |
944
- | Fast bitwise multiplication | O(1) Word-RAM | O(1) |
945
-
946
- For arbitrary-precision integers, the fast evaluator uses O(n) bit operations, where:
947
-
948
- ```text
949
- n = ceil(log2(max(i, j) + 1))
950
- ```
951
-
952
- ---
953
-
954
- # Testing
955
-
956
- Run all tests:
957
-
958
- ```bash
959
- pytest -v
960
- ```
961
-
962
- Run specific test files:
963
-
964
- ```bash
965
- pytest tests/test_mega_mother.py -v
966
- pytest tests/test_fast_mode.py -v
967
- ```
968
-
969
- The test suite validates:
970
-
971
- - Basis notation conversion.
972
- - Input validation.
973
- - Standard table generation.
974
- - Split table generation.
975
- - Dual table generation.
976
- - Holographic O(n) multiplication.
977
- - Fast O(1) multiplication.
978
- - Cross-validation between tables and multipliers.
979
- - Facade API behavior.
980
- - CSV export.
981
-
982
- ---
983
-
984
- # Repository Structure
985
-
986
- ```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
1026
- ```
1027
-
1028
- # Scope, strengths and limitations
1029
-
1030
- > **Status: 0.4.x, pre-1.0.** The API can still change. Read this section before building on the package.
1031
-
1032
- ## What this package is
1033
-
1034
- 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.
1035
-
1036
- ## Advantages
1037
-
1038
- - **One job, small surface.** About 2,000 lines, one dependency (NumPy), and multipliers that keep no per-call state.
1039
- - **Two interchangeable engines.**
1040
- - `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.
1041
- - `holographic` is an O(n) recursive descent, useful as a cross-check.
1042
- - **Works where tables cannot.** Only the two indices are needed, so indices hundreds of bits long are fine. Full tables need 4^n entries.
1043
- - **Cross-validated.** The test suite checks the table builders, the `fast` engine and the `holographic` engine against each other.
1044
- - **Strict about types.** `bool`, `float`, `str` and `list` inputs are rejected. Results are plain Python `int`s.
1045
- - **Tested on Python 3.10–3.14** and with NumPy 1.22 and newer.
1046
-
1047
- ## Input rules (0.4.x behavior)
1048
-
1049
- | Kind | Element form | `dim` | Index range |
1050
- |---|---|---|---|
1051
- | `standard` | `(sign, index)` | not used | any integer ≥ 0 (no upper bound, since there is no `dim` to check against) |
1052
- | `split` | `(sign, index)` | **required** | `0 ≤ index < 2**dim` |
1053
- | `dual`, `dual_split` | `(sign, global_index)` or `(sign, local_index, eps)` | **required** | global: `0 ≤ i < 2**(dim+1)`; local: `0 ≤ i < 2**dim` |
1054
-
1055
- - Elements must be **tuples**. Integers only, and NumPy integers are accepted.
1056
- - `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.
1057
- - 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`).
1058
- - **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.
1059
- - The dual result is always `(sign, local_index, eps)`, and `ε·ε` gives `(0, 0, 0)`.
1060
-
1061
- ## What the package cannot detect (your responsibility)
1062
-
1063
- Elements are plain tuples, so they do not remember which algebra produced them.
1064
-
1065
- - Feeding a result from one `dim` into an algebra of a different `dim` is not detected if the index happens to be in range.
1066
- - 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`.
1067
- - For `standard`, nothing tells you an index is "too big for the octonions".
1068
-
1069
- ## Not supported
1070
-
1071
- - **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.
1072
- - **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.
1073
- - **No addition, conjugation, norm, inverse, or division.**
1074
- - **`split` means one split doubling on top of a standard parent.** Other sign patterns are not offered.
1075
- - **`dual` and `dual_split`** extend a standard or split parent with a central `ε`, where `ε² = 0`.
1076
-
1077
- ## Algebra facts to keep in mind
1078
-
1079
- | n | Standard | Split |
1080
- |---|---|---|
1081
- | 1 | complex, commutative | split-complex, commutative, has zero divisors |
1082
- | 2 | quaternions, associative, **not commutative** | split-quaternions, associative, not commutative |
1083
- | 3 | octonions, alternative, **not associative** | split-octonions, alternative, not associative, has zero divisors |
1084
- | ≥ 4 | sedenions and beyond: **zero divisors**, no longer alternative | no longer alternative |
1085
-
1086
- ## Convention
1087
-
1088
- 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`.
1089
-
1090
- ## Direct low-level classes
1091
-
1092
- `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.
1093
-
1094
- ## Tables and memory
1095
-
1096
- Full tables have `4**n` entries. `build_table` refuses requests above a default memory budget (`max_bytes`, 256 MiB):
1097
-
1098
- - `standard` and `split` are allowed up to `n = 13`.
1099
- - `dual` and `dual_split` are allowed up to `n = 12`, since they are one doubling larger.
1100
-
1101
- 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 `ε·ε`.
1102
-
1103
- ## Stability and planned changes
1104
-
1105
- - Pin your dependency, for example `hypercomplex-engine>=0.4.1,<0.5`.
1106
- - *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.
1107
- - Do not treat the package as 1.0-stable until it has been used by futur a palnned package the vector-and-expression package.
1108
-
1109
- ---
1110
-
1111
- # Citation
1112
-
1113
- If you use this engine in your research, physics simulations, or geometric deep learning models, please cite the underlying theoretical preprints:
1114
-
1115
- ```bibtex
1116
- @article{ben abdessalem2026,
1117
- author = "maher ben abdessalem",
1118
- title = "{An O(1) Bitwise Evaluator for Cayley--Dickson Sign Structure: Ordinary, Split, Dual, and Tensor Constructions}",
1119
- year = "2026",
1120
- month = "9",
1121
- url = "https://figshare.com/articles/preprint/A_Proven_Sign_Law_for_Cayley-Dickson_Algebras_Ordinary_and_Split_Constructions/33705022",
1122
- doi = "10.6084/m9.figshare.33705022.v8"
1123
- }
1124
-
1125
- ```
1126
-
1127
-
1128
- ### Acknowledgments
1129
-
1130
- 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)).
1131
-
1132
-
1133
- ---
1134
-
1135
- ## References
1136
-
1137
- - Guangbin Ren and Xin Zhao, "The Explicit Twisted Group Algebra Structure of
1138
- the Cayley–Dickson Algebra," *Advances in Applied Clifford Algebras* 33,
1139
- Article 49 (2023). https://doi.org/10.1007/s00006-023-01296-6 ·
1140
- arXiv:2205.07986.
1141
-
1142
- # License
1143
-
1144
- Apache 2.0 License.
1145
-
1146
- See [`LICENSE`](LICENSE) for details.
1147
-
1148
- Copyright (c) 2026 Maher Ben Abdessalem