hypercomplex-engine 0.4.2.7__py3-none-any.whl → 0.5.0__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.
@@ -2,26 +2,15 @@ from ..validation import Validation
2
2
  from .fast_standard import FastStandard
3
3
  from .fast_split import FastSplit
4
4
 
5
-
6
5
  class FastDual:
7
6
  """
8
7
  Dual Cayley-Dickson O(1) multiplier.
9
8
 
10
- Input index convention:
11
- Total dual dimension is 2^(dim + 1).
12
- Bit `dim` marks the epsilon component.
13
-
14
- lower half: base elements
15
- upper half: epsilon * base elements
16
-
17
- Output:
9
+ STRICT 3-TUPLE INPUT:
18
10
  (sign, local_index, eps_flag)
19
-
20
- The output index is the local base index, so it can be formatted
21
- directly by CDFormat.
22
-
23
- Zero products are normalized to:
24
- (0, 0, 0)
11
+
12
+ local_index must be strictly < 2^dim.
13
+ eps_flag must be 0 or 1.
25
14
  """
26
15
 
27
16
  def __init__(self, split: bool = False):
@@ -29,160 +18,43 @@ class FastDual:
29
18
  self._standard = FastStandard()
30
19
  self._split = FastSplit() if self._split_mode else None
31
20
 
32
- # ==================================================================
33
- # Index helpers
34
- # ==================================================================
35
-
36
- @staticmethod
37
- def local_to_global(index: int, eps: int, dim: int) -> int:
38
- """
39
- Convert local dual representation to global index.
40
-
41
- local:
42
- index in [0, 2^dim - 1]
43
- eps = 0 or 1
44
-
45
- global:
46
- index in [0, 2^(dim+1) - 1]
47
- """
48
- dim = Validation.dimension(dim)
49
- index = int(index)
50
- eps = int(eps)
51
-
52
- half = 1 << dim
53
-
54
- if index < 0 or index >= half:
55
- raise ValueError(f"local index must be in [0, {half - 1}], got {index}")
56
-
57
- if eps:
58
- return index + half
59
-
60
- return index
61
-
62
- @staticmethod
63
- def global_to_local(global_index: int, dim: int) -> tuple:
64
- """
65
- Convert global dual index to:
66
- (local_index, eps_flag)
67
- """
68
- dim = Validation.dimension(dim)
69
- global_index = int(global_index)
70
-
71
- half = 1 << dim
72
- total = half << 1
73
-
74
- if global_index < 0 or global_index >= total:
75
- raise ValueError(f"global index must be in [0, {total - 1}], got {global_index}")
76
-
77
- return (global_index & (half - 1), 1 if global_index >= half else 0)
78
-
79
- # ==================================================================
80
- # Tuple input helper
81
- # ==================================================================
82
-
83
- def _extract_global(self, t: tuple, dim: int) -> tuple:
84
- """
85
- Accepts:
86
- (sign, global_index)
87
- (sign, local_index, eps_flag)
88
-
89
- Returns:
90
- (sign, global_index)
91
- """
92
- Validation.basis_tuple(t, allow_zero=True, allow_eps=True)
93
-
94
- sign = int(t[0])
95
- idx = int(t[1])
96
-
97
- if sign == 0:
98
- return (0, 0)
99
-
100
- half = 1 << Validation.dimension(dim)
101
-
102
- if len(t) >= 3:
103
- eps = int(t[2])
104
-
105
- # If the tuple carries an epsilon flag and the index is still
106
- # local, promote it to the global upper half.
107
- if eps == 1 and idx < half:
108
- idx += half
109
-
110
- return (sign, idx)
111
-
112
- # ==================================================================
113
- # Public API
114
- # ==================================================================
115
-
116
21
  def multiply(self, t1: tuple, t2: tuple, dim: int) -> tuple:
117
- """
118
- Multiply two dual basis element tuples.
119
-
120
- Accepted inputs:
121
- (sign, global_index)
122
- (sign, local_index, eps_flag)
123
-
124
- Returns:
125
- (final_sign, local_index, eps_flag)
126
- """
127
22
  dim = Validation.dimension(dim)
128
23
  Validation.basis_tuple(t1, allow_zero=True, allow_eps=True)
129
24
  Validation.basis_tuple(t2, allow_zero=True, allow_eps=True)
130
25
 
131
-
132
-
133
- s1, i = int(t1[0]), int(t1[1])
134
- s2, j = int(t2[0]), int(t2[1])
135
- i_eps_flag = int(t1[2]) if len(t1) == 3 else 0
136
- j_eps_flag = int(t2[2]) if len(t2) == 3 else 0
26
+ # STRICT 3-TUPLE UNPACKING
27
+ s1, i, i_eps = int(t1[0]), int(t1[1]), int(t1[2])
28
+ s2, j, j_eps = int(t2[0]), int(t2[1]), int(t2[2])
137
29
 
138
30
  if s1 == 0 or s2 == 0:
139
31
  return (0, 0, 0)
140
32
 
141
- sign, idx, eps = self.multiply_indices(i, j,dim,i_eps_flag,j_eps_flag)
142
-
33
+ sign, idx, eps = self.multiply_indices(i, j, dim, i_eps, j_eps)
143
34
  return (s1 * s2 * sign, idx, eps)
144
35
 
145
- def multiply_indices(self, i: int, j: int,dim:int, i_eps_flag=0 ,j_eps_flag=0) -> tuple:
146
- """
147
- Core dual O(1) multiplication using global indices.
148
-
149
- Returns:
150
- (sign, local_index, eps_flag)
151
- """
152
- i = int(i)
153
- j = int(j)
36
+ def multiply_indices(self, i: int, j: int, dim: int, i_eps_flag: int = 0, j_eps_flag: int = 0) -> tuple:
154
37
  dim = Validation.dimension(dim)
155
-
156
38
  half = 1 << dim
157
- total = half << 1
158
-
159
- if i < 0 or i >= total:
160
- raise ValueError(f"index must be in [0, {total - 1}] for dual dim={dim}, got {i}")
161
-
162
- if j < 0 or j >= total:
163
- raise ValueError(f"index must be in [0, {total - 1}] for dual dim={dim}, got {j}")
164
-
165
- i_eps = i >= half or i_eps_flag
166
- j_eps = j >= half or j_eps_flag
167
-
168
- i_loc = i & (half - 1)
169
- j_loc = j & (half - 1)
170
-
171
- # --------------------------------------------------------------
172
- # Epsilon nilpotency:
173
- # (epsilon e_i)(epsilon e_j) = 0
174
- # --------------------------------------------------------------
39
+
40
+ # STRICT LOCAL ENFORCEMENT: No more global overflow!
41
+ if i < 0 or i >= half:
42
+ raise ValueError(f"local index must be in [0, {half - 1}] for dual dim={dim}, got {i}")
43
+ if j < 0 or j >= half:
44
+ raise ValueError(f"local index must be in [0, {half - 1}] for dual dim={dim}, got {j}")
45
+
46
+ i_eps = bool(i_eps_flag)
47
+ j_eps = bool(j_eps_flag)
48
+
49
+ # Nilpotency: eps^2 = 0
175
50
  if i_eps and j_eps:
176
51
  return (0, 0, 0)
177
52
 
178
- # --------------------------------------------------------------
179
- # Base multiplication
180
- # --------------------------------------------------------------
53
+ # Base multiplication (parent algebra)
181
54
  if self._split_mode:
182
- base_sign, local_idx = self._split.multiply_indices(i_loc, j_loc, dim)
55
+ base_sign, local_idx = self._split.multiply_indices(i, j, dim)
183
56
  else:
184
- base_sign, local_idx = self._standard.multiply_indices(i_loc, j_loc)
57
+ base_sign, local_idx = self._standard.multiply_indices(i, j)
185
58
 
186
59
  eps_flag = 1 if (i_eps or j_eps) else 0
187
-
188
60
  return (base_sign, local_idx, eps_flag)
@@ -2,25 +2,10 @@ from ..validation import Validation
2
2
  from .standard import StandardHolographic
3
3
  from .split import SplitHolographic
4
4
 
5
-
6
5
  class DualHolographic:
7
6
  """
8
7
  Dual Cayley-Dickson holographic multiplier.
9
-
10
- Input index convention:
11
- The total dual dimension is 2^(dim + 1).
12
- Bit `dim` marks the epsilon component.
13
-
14
- lower half: 0 ... 2^dim - 1
15
- upper half: epsilon times lower half
16
-
17
- Output:
18
- (sign, local_index, eps_flag)
19
-
20
- Nilpotency:
21
- (epsilon e_i) * (epsilon e_j) = 0
22
- returned as the canonical zero (0, 0, 0), matching FastDual
23
- and DualTableBuilder
8
+ STRICT 3-TUPLE INPUT: (sign, local_index, eps_flag)
24
9
  """
25
10
 
26
11
  def __init__(self, split: bool = False):
@@ -29,62 +14,37 @@ class DualHolographic:
29
14
  self._split = SplitHolographic() if self._split_mode else None
30
15
 
31
16
  def multiply(self, t1: tuple, t2: tuple, dim: int) -> tuple:
32
- """
33
- Multiply two dual basis elements.
34
-
35
- t1, t2 may be:
36
- (sign, global_index)
37
- (sign, global_index, eps_flag)
38
-
39
- The epsilon component is determined by bit `dim` of global_index.
40
-
41
- Returns:
42
- (final_sign, local_index, eps_flag)
43
- """
44
17
  Validation.basis_tuple(t1, allow_zero=True, allow_eps=True)
45
18
  Validation.basis_tuple(t2, allow_zero=True, allow_eps=True)
46
-
47
19
  dim = Validation.dimension(dim)
48
20
 
49
- s1, i = int(t1[0]), int(t1[1])
50
- s2, j = int(t2[0]), int(t2[1])
51
- i_eps_flag = int(t1[2]) if len(t1) == 3 else 0
52
- j_eps_flag = int(t2[2]) if len(t2) == 3 else 0
53
- # Zero propagates.
21
+ # STRICT 3-TUPLE UNPACKING
22
+ s1, i, i_eps_flag = int(t1[0]), int(t1[1]), int(t1[2])
23
+ s2, j, j_eps_flag = int(t2[0]), int(t2[1]), int(t2[2])
24
+
54
25
  if s1 == 0 or s2 == 0:
55
26
  return (0, 0, 0)
56
27
 
57
- total_size = 1 << (dim + 1)
58
-
59
- if i < 0 or i >= total_size:
60
- raise ValueError(f"index must be in [0, {total_size - 1}] for dual dim={dim}, got {i}")
61
-
62
- if j < 0 or j >= total_size:
63
- raise ValueError(f"index must be in [0, {total_size - 1}] for dual dim={dim}, got {j}")
64
-
65
28
  half = 1 << dim
29
+
30
+ # STRICT LOCAL ENFORCEMENT
31
+ if i < 0 or i >= half:
32
+ raise ValueError(f"local index must be in [0, {half - 1}] for dual dim={dim}, got {i}")
33
+ if j < 0 or j >= half:
34
+ raise ValueError(f"local index must be in [0, {half - 1}] for dual dim={dim}, got {j}")
66
35
 
67
- i_eps = i >= half or i_eps_flag
68
- j_eps = j >= half or j_eps_flag
69
-
70
- i_loc = i & (half - 1)
71
- j_loc = j & (half - 1)
36
+ i_eps = bool(i_eps_flag)
37
+ j_eps = bool(j_eps_flag)
72
38
 
73
- # --------------------------------------------------------------
74
- # Epsilon nilpotency:
75
- # (epsilon e_i) * (epsilon e_j) = 0
76
- # --------------------------------------------------------------
39
+ # Nilpotency
77
40
  if i_eps and j_eps:
78
41
  return (0, 0, 0)
79
42
 
80
- # --------------------------------------------------------------
81
- # Base multiplication.
82
- # --------------------------------------------------------------
43
+ # Base multiplication
83
44
  if self._split_mode:
84
- base_sign, local_idx = self._split.multiply_indices(i_loc, j_loc, dim)
45
+ base_sign, local_idx = self._split.multiply_indices(i, j, dim)
85
46
  else:
86
- base_sign, local_idx = self._standard.multiply_indices(i_loc, j_loc)
47
+ base_sign, local_idx = self._standard.multiply_indices(i, j)
87
48
 
88
49
  eps_flag = 1 if (i_eps or j_eps) else 0
89
-
90
50
  return (s1 * s2 * base_sign, local_idx, eps_flag)
@@ -54,12 +54,12 @@ class Validation:
54
54
  if not isinstance(data, tuple):
55
55
  raise TypeError(f"Expected tuple, got {type(data).__name__}")
56
56
 
57
- if len(data) not in (2, 3):
58
- raise ValueError(f"Basis tuple must have length 2 or 3, got {len(data)}")
59
-
60
- if len(data) == 3 and not allow_eps:
61
- raise ValueError("3-tuple epsilon form is not allowed here")
62
-
57
+ if allow_eps:
58
+ if len(data) != 3:
59
+ raise ValueError(f"Dual basis tuple must have length 3 (sign, index, eps), got {len(data)}")
60
+ else:
61
+ if len(data) != 2:
62
+ raise ValueError(f"Standard/Split basis tuple must have length 2 (sign, index), got {len(data)}")
63
63
 
64
64
  sign = data[0]
65
65
  index = data[1]
@@ -126,33 +126,6 @@ def _unpack_table(table):
126
126
  )
127
127
 
128
128
 
129
- def _as_dual_global(t: tuple, dim: int) -> tuple:
130
- """
131
- Converts a dual input tuple into a global 2-tuple.
132
-
133
- Accepts:
134
- (sign, global_index)
135
- (sign, local_index, eps_flag)
136
-
137
- Returns:
138
- (sign, global_index)
139
- """
140
- sign = int(t[0])
141
- idx = int(t[1])
142
-
143
- if sign == 0:
144
- return (0, 0)
145
-
146
- half = 1 << Validation.dimension(dim)
147
-
148
- if len(t) >= 3:
149
- eps = int(t[2])
150
-
151
- if eps == 1 and idx < half:
152
- idx += half
153
-
154
- return (sign, idx)
155
-
156
129
 
157
130
  # ----------------------------------------------------------------------
158
131
  # Public simple API
@@ -280,11 +253,9 @@ def multiply(
280
253
  return (0, 0, 0)
281
254
  return (0, 0)
282
255
 
283
- # Dual inputs may be local 3-tuples: (sign, local_index, eps)
284
- if kind in ("dual", "dual_split"):
285
- a = _as_dual_global(a, dim)
286
- b = _as_dual_global(b, dim)
287
-
256
+ # Dual inputs are strictly local 3-tuples: (sign, local_index, eps_flag).
257
+ # We pass them directly to the engines. No global overflow conversion needed.
258
+
288
259
  # ------------------------------------------------------------------
289
260
  # O(1) engine
290
261
  # ------------------------------------------------------------------
@@ -1,6 +1,6 @@
1
1
  Metadata-Version: 2.4
2
2
  Name: hypercomplex-engine
3
- Version: 0.4.2.7
3
+ Version: 0.5.0
4
4
  Summary: Fast O(1)/O(n) multiplication engine for arbitrary dimensions and table generator for ordinary, split, and dual Cayley-Dickson algebras.
5
5
  Author-email: Maher Ben Abdessalem <ba.maher94@gmail.com>
6
6
  License-Expression: Apache-2.0
@@ -1123,6 +1123,7 @@ doi = "10.6084/m9.figshare.33705022.v8"
1123
1123
 
1124
1124
  ```
1125
1125
 
1126
+
1126
1127
  ### Acknowledgments
1127
1128
 
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)).
@@ -1,16 +1,16 @@
1
1
  hypercomplex_engine/__init__.py,sha256=pwDbzzCLFaSqD_rsNVmgdZhylolIcEkDBJFEVstLMYE,1247
2
- hypercomplex_engine/facade.py,sha256=-5mjJP2OGQC0m2_ZaGrkt5Zzty-Qvdz1FOsHMY4ctdE,9706
2
+ hypercomplex_engine/facade.py,sha256=Rw0GyrZJMs1fkdZzLwwjIdZAvid4XmDGJEM-G7fOG_k,9192
3
3
  hypercomplex_engine/core/__init__.py,sha256=7cD5SJFbAewuVMIvKnQ6tb7JwcmpGQktSvGbN5n8dIM,668
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
- hypercomplex_engine/core/validation.py,sha256=1ehTiV2fuV9ahGaGcDswWqUJMBzmGcYQ-3wY8lbrd7k,3174
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
8
  hypercomplex_engine/core/fast/bit_utils.py,sha256=aqBjPX2srWym6AjxZqTzt998-in_-5VAxNUiQXUFAVw,385
9
- hypercomplex_engine/core/fast/fast_dual.py,sha256=Y5JFtGunb9p9qezogqPBWJfjNdiijtXV1LsKJXEENqY,5540
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
12
12
  hypercomplex_engine/core/holographic/__init__.py,sha256=TGMyPs6dyeaQ9I--rFooBOrKzkex73IbwzQtL7Q0i04,200
13
- hypercomplex_engine/core/holographic/dual.py,sha256=1JdYDPpFk7u0yMswDOxRhhEUcg4CDxCu3Rk-a1rDImA,2898
13
+ hypercomplex_engine/core/holographic/dual.py,sha256=LyxA4zpr6fUlD-ZckLYQGH_FAu9Xf8FOGyYo6c_5kyk,1731
14
14
  hypercomplex_engine/core/holographic/split.py,sha256=kJXPXvw3rT8YieENor0hNTko4qBoXaKKb9n07UWhfQY,2864
15
15
  hypercomplex_engine/core/holographic/standard.py,sha256=nNgM0QxvWXVMlTenHdxKd63RvLOkF_xu1cB0f00EumA,3935
16
16
  hypercomplex_engine/core/table_builder/__init__.py,sha256=qkKJQ1S44hlSeNdW-Cc9REvbCeU2K646pkCalV9Sft4,206
@@ -21,9 +21,9 @@ hypercomplex_engine/core/table_builder/standard.py,sha256=3kyg4TLCG_LKhC8lT95hZB
21
21
  hypercomplex_engine/printer/__init__.py,sha256=6EZOUBYb9TDgfqrFpnIfPS1bbPFZ0dMX6RCPDZepL6M,129
22
22
  hypercomplex_engine/printer/cd_format.py,sha256=X_cotGumJlRMuJO5cbsnI8FA9Py12TGYftPlUdx-9xg,5731
23
23
  hypercomplex_engine/printer/cd_table_printer.py,sha256=Ny1g5osDwttI5I8-KV4DzhVhWp_7fP-R5lYyC9sEhKE,4973
24
- hypercomplex_engine-0.4.2.7.dist-info/licenses/LICENSE,sha256=WNHhf_5RCaeuKWyq_K39vmp9F28LxKsB4SpomwSZ2L0,11357
25
- hypercomplex_engine-0.4.2.7.dist-info/licenses/NOTICE,sha256=WRgJ9Hv74Vke3ByFbvR6sqdlinPx4rCWDc0-7Iyh9VI,745
26
- hypercomplex_engine-0.4.2.7.dist-info/METADATA,sha256=CPCm_GBbVCX8Xwr5y4YSal-zF4p7M-5aCGeHZESo6HA,26239
27
- hypercomplex_engine-0.4.2.7.dist-info/WHEEL,sha256=YVMoNqKzERt-wjUZwJ33xBGAwnFl-4cqbYkTtWa4itE,91
28
- hypercomplex_engine-0.4.2.7.dist-info/top_level.txt,sha256=654ACRoo9vk38vKW7kVBfgD-IjIADgVmh75smmXBZ88,20
29
- hypercomplex_engine-0.4.2.7.dist-info/RECORD,,
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,,