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