hypercomplex-engine 0.4.1__tar.gz → 0.4.2.1__tar.gz

{hypercomplex_engine-0.4.1/hypercomplex_engine.egg-info → hypercomplex_engine-0.4.2.1}/PKG-INFO

@@ -1,7 +1,7 @@
 Metadata-Version: 2.4
 Name: hypercomplex-engine
-Version: 0.4.1
-Summary: Fast O(1)/O(n) multiplication engine and table generator for ordinary, split, and dual Cayley-Dickson algebras.
+Version: 0.4.2.1
+Summary: Fast O(1)/O(n) multiplication engine for arbitrary dimensions and table generator for ordinary, split, and dual Cayley-Dickson algebras.
 Author-email: Maher Ben Abdessalem <ba.maher94@gmail.com>
 License: MIT License
         
@@ -50,13 +50,15 @@ Dynamic: license-file
 
 [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
 [![Python 3.10+](https://img.shields.io/badge/python-3.10+-blue.svg)](https://www.python.org/downloads/)
-[![Tests](https://img.shields.io/badge/tests-62%20passed-success)](#)
 [![GitHub Repo](https://img.shields.io/badge/GitHub-maher1719%2Fhypercomplex--engine-black?logo=github)](https://github.com/maher1719/hypercomplex-engine)
-[![PyPI version](https://badge.fury.io/py/hypercomplex-engine.svg)](https://pypi.org/project/hypercomplex-engine/)
+[![PyPI version](https://img.shields.io/pypi/v/hypercomplex-engine.svg)](https://pypi.org/project/hypercomplex-engine/)
 [![Downloads](https://static.pepy.tech/badge/hypercomplex-engine)](https://pepy.tech/project/hypercomplex-engine)
 
 
-Fast, validated multiplication and table generation for Cayley–Dickson algebras.
+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.
+
+
+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).
 
 This library provides the computational substrate for high-dimensional hypercomplex algebra, featuring:
 
@@ -69,6 +71,11 @@ This library provides the computational substrate for high-dimensional hypercomp
 
 ---
 
+## Scope and limitations 
+
+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)
+
+
 ## 📄 Publications & Preprints
 
 This library serves as the formal verification substrate and computational engine for the following mathematical preprints:
@@ -1037,6 +1044,87 @@ hypercomplex-engine/
 └── pyproject.toml
 ```
 
+# Scope, strengths and limitations
+
+> **Status: 0.4.x, pre-1.0.** The API can still change. Read this section before building on the package.
+
+## What this package is
+
+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.
+
+## Advantages
+
+- **One job, small surface.** About 2,000 lines, one dependency (NumPy), and multipliers that keep no per-call state.
+- **Two interchangeable engines.**
+  - `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.
+  - `holographic` is an O(n) recursive descent, useful as a cross-check.
+- **Works where tables cannot.** Only the two indices are needed, so indices hundreds of bits long are fine. Full tables need 4^n entries.
+- **Cross-validated.** The test suite checks the table builders, the `fast` engine and the `holographic` engine against each other.
+- **Strict about types.** `bool`, `float`, `str` and `list` inputs are rejected. Results are plain Python `int`s.
+- **Tested on Python 3.10–3.14** and with NumPy 1.22 and newer.
+
+## Input rules (0.4.x behavior)
+
+| Kind | Element form | `dim` | Index range |
+|---|---|---|---|
+| `standard` | `(sign, index)` | not used | any integer ≥ 0 (no upper bound, since there is no `dim` to check against) |
+| `split` | `(sign, index)` | **required** | `0 ≤ index < 2**dim` |
+| `dual`, `dual_split` | `(sign, global_index)` or `(sign, local_index, eps)` | **required** | global: `0 ≤ i < 2**(dim+1)`; local: `0 ≤ i < 2**dim` |
+
+- Elements must be **tuples**. Integers only, and NumPy integers are accepted.
+- `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.
+- 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`).
+- **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.
+- The dual result is always `(sign, local_index, eps)`, and `ε·ε` gives `(0, 0, 0)`.
+
+## What the package cannot detect (your responsibility)
+
+Elements are plain tuples, so they do not remember which algebra produced them.
+
+- Feeding a result from one `dim` into an algebra of a different `dim` is not detected if the index happens to be in range.
+- 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`.
+- For `standard`, nothing tells you an index is "too big for the octonions".
+
+## Not supported
+
+- **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.
+- **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.
+- **No addition, conjugation, norm, inverse, or division.**
+- **`split` means one split doubling on top of a standard parent.** Other sign patterns are not offered.
+- **`dual` and `dual_split`** extend a standard or split parent with a central `ε`, where `ε² = 0`.
+
+## Algebra facts to keep in mind
+
+| n | Standard | Split |
+|---|---|---|
+| 1 | complex, commutative | split-complex, commutative, has zero divisors |
+| 2 | quaternions, associative, **not commutative** | split-quaternions, associative, not commutative |
+| 3 | octonions, alternative, **not associative** | split-octonions, alternative, not associative, has zero divisors |
+| ≥ 4 | sedenions and beyond: **zero divisors**, no longer alternative | no longer alternative |
+
+## Convention
+
+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`.
+
+## Direct low-level classes
+
+`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.
+
+## Tables and memory
+
+Full tables have `4**n` entries. `build_table` refuses requests above a default memory budget (`max_bytes`, 256 MiB):
+
+- `standard` and `split` are allowed up to `n = 13`.
+- `dual` and `dual_split` are allowed up to `n = 12`, since they are one doubling larger.
+
+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 `ε·ε`.
+
+## Stability and planned changes
+
+- Pin your dependency, for example `hypercomplex-engine>=0.4.1,<0.5`.
+- *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.
+- Do not treat the package as 1.0-stable until it has been used by futur a palnned package the vector-and-expression package.
+
 ---
 
 # Citation

{hypercomplex_engine-0.4.1 → hypercomplex_engine-0.4.2.1}/README.md

@@ -2,13 +2,15 @@
 
 [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
 [![Python 3.10+](https://img.shields.io/badge/python-3.10+-blue.svg)](https://www.python.org/downloads/)
-[![Tests](https://img.shields.io/badge/tests-62%20passed-success)](#)
 [![GitHub Repo](https://img.shields.io/badge/GitHub-maher1719%2Fhypercomplex--engine-black?logo=github)](https://github.com/maher1719/hypercomplex-engine)
-[![PyPI version](https://badge.fury.io/py/hypercomplex-engine.svg)](https://pypi.org/project/hypercomplex-engine/)
+[![PyPI version](https://img.shields.io/pypi/v/hypercomplex-engine.svg)](https://pypi.org/project/hypercomplex-engine/)
 [![Downloads](https://static.pepy.tech/badge/hypercomplex-engine)](https://pepy.tech/project/hypercomplex-engine)
 
 
-Fast, validated multiplication and table generation for Cayley–Dickson algebras.
+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.
+
+
+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).
 
 This library provides the computational substrate for high-dimensional hypercomplex algebra, featuring:
 
@@ -21,6 +23,11 @@ This library provides the computational substrate for high-dimensional hypercomp
 
 ---
 
+## Scope and limitations 
+
+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)
+
+
 ## 📄 Publications & Preprints
 
 This library serves as the formal verification substrate and computational engine for the following mathematical preprints:
@@ -989,6 +996,87 @@ hypercomplex-engine/
 └── pyproject.toml
 ```
 
+# Scope, strengths and limitations
+
+> **Status: 0.4.x, pre-1.0.** The API can still change. Read this section before building on the package.
+
+## What this package is
+
+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.
+
+## Advantages
+
+- **One job, small surface.** About 2,000 lines, one dependency (NumPy), and multipliers that keep no per-call state.
+- **Two interchangeable engines.**
+  - `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.
+  - `holographic` is an O(n) recursive descent, useful as a cross-check.
+- **Works where tables cannot.** Only the two indices are needed, so indices hundreds of bits long are fine. Full tables need 4^n entries.
+- **Cross-validated.** The test suite checks the table builders, the `fast` engine and the `holographic` engine against each other.
+- **Strict about types.** `bool`, `float`, `str` and `list` inputs are rejected. Results are plain Python `int`s.
+- **Tested on Python 3.10–3.14** and with NumPy 1.22 and newer.
+
+## Input rules (0.4.x behavior)
+
+| Kind | Element form | `dim` | Index range |
+|---|---|---|---|
+| `standard` | `(sign, index)` | not used | any integer ≥ 0 (no upper bound, since there is no `dim` to check against) |
+| `split` | `(sign, index)` | **required** | `0 ≤ index < 2**dim` |
+| `dual`, `dual_split` | `(sign, global_index)` or `(sign, local_index, eps)` | **required** | global: `0 ≤ i < 2**(dim+1)`; local: `0 ≤ i < 2**dim` |
+
+- Elements must be **tuples**. Integers only, and NumPy integers are accepted.
+- `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.
+- 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`).
+- **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.
+- The dual result is always `(sign, local_index, eps)`, and `ε·ε` gives `(0, 0, 0)`.
+
+## What the package cannot detect (your responsibility)
+
+Elements are plain tuples, so they do not remember which algebra produced them.
+
+- Feeding a result from one `dim` into an algebra of a different `dim` is not detected if the index happens to be in range.
+- 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`.
+- For `standard`, nothing tells you an index is "too big for the octonions".
+
+## Not supported
+
+- **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.
+- **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.
+- **No addition, conjugation, norm, inverse, or division.**
+- **`split` means one split doubling on top of a standard parent.** Other sign patterns are not offered.
+- **`dual` and `dual_split`** extend a standard or split parent with a central `ε`, where `ε² = 0`.
+
+## Algebra facts to keep in mind
+
+| n | Standard | Split |
+|---|---|---|
+| 1 | complex, commutative | split-complex, commutative, has zero divisors |
+| 2 | quaternions, associative, **not commutative** | split-quaternions, associative, not commutative |
+| 3 | octonions, alternative, **not associative** | split-octonions, alternative, not associative, has zero divisors |
+| ≥ 4 | sedenions and beyond: **zero divisors**, no longer alternative | no longer alternative |
+
+## Convention
+
+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`.
+
+## Direct low-level classes
+
+`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.
+
+## Tables and memory
+
+Full tables have `4**n` entries. `build_table` refuses requests above a default memory budget (`max_bytes`, 256 MiB):
+
+- `standard` and `split` are allowed up to `n = 13`.
+- `dual` and `dual_split` are allowed up to `n = 12`, since they are one doubling larger.
+
+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 `ε·ε`.
+
+## Stability and planned changes
+
+- Pin your dependency, for example `hypercomplex-engine>=0.4.1,<0.5`.
+- *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.
+- Do not treat the package as 1.0-stable until it has been used by futur a palnned package the vector-and-expression package.
+
 ---
 
 # Citation

{hypercomplex_engine-0.4.1 → hypercomplex_engine-0.4.2.1}/hypercomplex/core/fast/fast_standard.py

@@ -34,9 +34,6 @@ class FastStandard:
         s1, i = int(t1[0]), int(t1[1])
         s2, j = int(t2[0]), int(t2[1])
 
-        if s1 == 0 or s2 == 0:
-            return (0, 0)
-
         sign, idx = self.multiply_indices(i, j)
 
         return (s1 * s2 * sign, idx)

{hypercomplex_engine-0.4.1 → hypercomplex_engine-0.4.2.1}/hypercomplex/facade.py

@@ -267,8 +267,12 @@ def multiply(
         # Validate inputs before any early return, so malformed data always
         # raises ValidationError instead of leaking TypeError/IndexError.
     allow_eps = kind in ("dual", "dual_split")
-    Validation.basis_tuple(a, allow_zero=True, allow_eps=allow_eps)
-    Validation.basis_tuple(b, allow_zero=True, allow_eps=allow_eps)
+    if allow_eps:
+        Validation.basis_tuple(a, allow_zero=True, allow_eps=allow_eps)
+        Validation.basis_tuple(b, allow_zero=True, allow_eps=allow_eps)
+    else:
+        Validation.basis_tuple(a, allow_zero=False, allow_eps=False)
+        Validation.basis_tuple(b, allow_zero=False, allow_eps=False)
 
     # Zero propagation
     if int(a[0]) == 0 or int(b[0]) == 0:
@@ -354,7 +358,7 @@ def export_csv(
     Export a table built by build_table().
     """
     signs, indices, eps = _unpack_table(table)
-
+    
     return CDTablePrinter.export_csv(
         path,
         signs,

{hypercomplex_engine-0.4.1 → hypercomplex_engine-0.4.2.1}/hypercomplex/printer/cd_table_printer.py

@@ -1,4 +1,5 @@
 from .cd_format import CDFormat
+import logging
 
 
 class CDTablePrinter:
@@ -200,5 +201,7 @@ class CDTablePrinter:
                             line += f",{int(eps[i, j])}"
 
                         f.write(line + "\n")
+        logging.basicConfig(level=logging.INFO)
 
+        logging.info(f"Table successfully built {path} ")
         return path

{hypercomplex_engine-0.4.1 → hypercomplex_engine-0.4.2.1/hypercomplex_engine.egg-info}/PKG-INFO

@@ -1,7 +1,7 @@
 Metadata-Version: 2.4
 Name: hypercomplex-engine
-Version: 0.4.1
-Summary: Fast O(1)/O(n) multiplication engine and table generator for ordinary, split, and dual Cayley-Dickson algebras.
+Version: 0.4.2.1
+Summary: Fast O(1)/O(n) multiplication engine for arbitrary dimensions and table generator for ordinary, split, and dual Cayley-Dickson algebras.
 Author-email: Maher Ben Abdessalem <ba.maher94@gmail.com>
 License: MIT License
         
@@ -50,13 +50,15 @@ Dynamic: license-file
 
 [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
 [![Python 3.10+](https://img.shields.io/badge/python-3.10+-blue.svg)](https://www.python.org/downloads/)
-[![Tests](https://img.shields.io/badge/tests-62%20passed-success)](#)
 [![GitHub Repo](https://img.shields.io/badge/GitHub-maher1719%2Fhypercomplex--engine-black?logo=github)](https://github.com/maher1719/hypercomplex-engine)
-[![PyPI version](https://badge.fury.io/py/hypercomplex-engine.svg)](https://pypi.org/project/hypercomplex-engine/)
+[![PyPI version](https://img.shields.io/pypi/v/hypercomplex-engine.svg)](https://pypi.org/project/hypercomplex-engine/)
 [![Downloads](https://static.pepy.tech/badge/hypercomplex-engine)](https://pepy.tech/project/hypercomplex-engine)
 
 
-Fast, validated multiplication and table generation for Cayley–Dickson algebras.
+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.
+
+
+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).
 
 This library provides the computational substrate for high-dimensional hypercomplex algebra, featuring:
 
@@ -69,6 +71,11 @@ This library provides the computational substrate for high-dimensional hypercomp
 
 ---
 
+## Scope and limitations 
+
+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)
+
+
 ## 📄 Publications & Preprints
 
 This library serves as the formal verification substrate and computational engine for the following mathematical preprints:
@@ -1037,6 +1044,87 @@ hypercomplex-engine/
 └── pyproject.toml
 ```
 
+# Scope, strengths and limitations
+
+> **Status: 0.4.x, pre-1.0.** The API can still change. Read this section before building on the package.
+
+## What this package is
+
+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.
+
+## Advantages
+
+- **One job, small surface.** About 2,000 lines, one dependency (NumPy), and multipliers that keep no per-call state.
+- **Two interchangeable engines.**
+  - `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.
+  - `holographic` is an O(n) recursive descent, useful as a cross-check.
+- **Works where tables cannot.** Only the two indices are needed, so indices hundreds of bits long are fine. Full tables need 4^n entries.
+- **Cross-validated.** The test suite checks the table builders, the `fast` engine and the `holographic` engine against each other.
+- **Strict about types.** `bool`, `float`, `str` and `list` inputs are rejected. Results are plain Python `int`s.
+- **Tested on Python 3.10–3.14** and with NumPy 1.22 and newer.
+
+## Input rules (0.4.x behavior)
+
+| Kind | Element form | `dim` | Index range |
+|---|---|---|---|
+| `standard` | `(sign, index)` | not used | any integer ≥ 0 (no upper bound, since there is no `dim` to check against) |
+| `split` | `(sign, index)` | **required** | `0 ≤ index < 2**dim` |
+| `dual`, `dual_split` | `(sign, global_index)` or `(sign, local_index, eps)` | **required** | global: `0 ≤ i < 2**(dim+1)`; local: `0 ≤ i < 2**dim` |
+
+- Elements must be **tuples**. Integers only, and NumPy integers are accepted.
+- `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.
+- 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`).
+- **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.
+- The dual result is always `(sign, local_index, eps)`, and `ε·ε` gives `(0, 0, 0)`.
+
+## What the package cannot detect (your responsibility)
+
+Elements are plain tuples, so they do not remember which algebra produced them.
+
+- Feeding a result from one `dim` into an algebra of a different `dim` is not detected if the index happens to be in range.
+- 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`.
+- For `standard`, nothing tells you an index is "too big for the octonions".
+
+## Not supported
+
+- **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.
+- **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.
+- **No addition, conjugation, norm, inverse, or division.**
+- **`split` means one split doubling on top of a standard parent.** Other sign patterns are not offered.
+- **`dual` and `dual_split`** extend a standard or split parent with a central `ε`, where `ε² = 0`.
+
+## Algebra facts to keep in mind
+
+| n | Standard | Split |
+|---|---|---|
+| 1 | complex, commutative | split-complex, commutative, has zero divisors |
+| 2 | quaternions, associative, **not commutative** | split-quaternions, associative, not commutative |
+| 3 | octonions, alternative, **not associative** | split-octonions, alternative, not associative, has zero divisors |
+| ≥ 4 | sedenions and beyond: **zero divisors**, no longer alternative | no longer alternative |
+
+## Convention
+
+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`.
+
+## Direct low-level classes
+
+`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.
+
+## Tables and memory
+
+Full tables have `4**n` entries. `build_table` refuses requests above a default memory budget (`max_bytes`, 256 MiB):
+
+- `standard` and `split` are allowed up to `n = 13`.
+- `dual` and `dual_split` are allowed up to `n = 12`, since they are one doubling larger.
+
+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 `ε·ε`.
+
+## Stability and planned changes
+
+- Pin your dependency, for example `hypercomplex-engine>=0.4.1,<0.5`.
+- *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.
+- Do not treat the package as 1.0-stable until it has been used by futur a palnned package the vector-and-expression package.
+
 ---
 
 # Citation

{hypercomplex_engine-0.4.1 → hypercomplex_engine-0.4.2.1}/pyproject.toml

@@ -4,11 +4,11 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "hypercomplex-engine" 
-version = "0.4.1"
+version = "0.4.2.1"
 authors = [
   { name="Maher Ben Abdessalem", email="ba.maher94@gmail.com" },
 ]
-description = "Fast O(1)/O(n) multiplication engine and table generator for ordinary, split, and dual Cayley-Dickson algebras."
+description = "Fast O(1)/O(n) multiplication engine for arbitrary dimensions and table generator for ordinary, split, and dual Cayley-Dickson algebras."
 readme = "README.md"
 license = { file="LICENSE" }
 requires-python = ">=3.10"

{hypercomplex_engine-0.4.1 → hypercomplex_engine-0.4.2.1}/tests/test_dual_tuple_regression.py

@@ -73,8 +73,10 @@ def test_facade_dual_3tuple_promotion():
 def test_facade_zero_shapes():
     assert multiply("dual", (0, 2), (1, 3), dim=2) == (0, 0, 0)
     assert multiply("dual_split", (1, 2), (0, 3), dim=2) == (0, 0, 0)
-    assert multiply("standard", (0, 2), (1, 3), dim=2) == (0, 0)   # formal zero
-    assert multiply("split", (0, 2), (1, 3), dim=2) == (0, 0)
+    with pytest.raises((TypeError, ValueError)):
+        assert multiply("standard", (0, 2), (1, 3), dim=2) == (0, 0) 
+    with pytest.raises((TypeError, ValueError)):  # formal zero
+        assert multiply("split", (0, 2), (1, 3), dim=2) == (0, 0)
 
 
 def test_facade_malformed_raises_validation_error():