Metadata-Version: 2.4
Name: eb47ns
Version: 0.1.0
Summary: Ethiopian Base-47 Numeral System (EB47NS) with Direct Digit Arithmetic and Cryptographic Research Layer
Author-email: Ezra Destaw <ezradestaw@gmail.com>
License-Expression: MIT
Project-URL: Homepage, https://github.com/Ezradestaw/eb47
Project-URL: Repository, https://github.com/Ezradestaw/eb47
Project-URL: Issues, https://github.com/Ezradestaw/eb47/issues
Keywords: numeral-system,base-47,arithmetic,cryptography,galois-field
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Science/Research
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Programming Language :: Python :: 3.14
Classifier: Topic :: Scientific/Engineering :: Mathematics
Classifier: Topic :: Security :: Cryptography
Requires-Python: >=3.12
Description-Content-Type: text/markdown
Provides-Extra: dev
Requires-Dist: pytest>=8.0.0; extra == "dev"

# Ethiopian Base-47 Numeral System (EB47NS)

[![Python 3.12+](https://img.shields.io/badge/python-3.12+-blue.svg)](https://www.python.org/downloads/)
[![License: MIT](https://img.shields.io/badge/License-MIT-green.svg)](https://opensource.org/licenses/MIT)
[![Tests](https://img.shields.io/badge/tests-64%20passed-brightgreen.svg)]()

The **Ethiopian Base-47 Numeral System (EB47NS)** is an original positional numeral system with radix $R = 47$. Designed at the intersection of mathematics, programming-language design, and non-binary cryptography research, it provides:

* A fixed, ordered 47-symbol glyph alphabet.
* **Direct multi-digit sequence arithmetic** operating column-by-column on base-47 digit arrays rather than relying on native decimal integer conversions.
* An extensible architecture for defining, analyzing, and registering **custom mathematical operations**.
* A dedicated **cryptographic research layer** exploring Galois field $\mathbb{F}_{47}$ arithmetic, primitive roots, optimal differential S-boxes ($\delta = 2$), Cauchy MDS diffusion matrices, and toy Substitution-Permutation Networks (SPN).

---

> ### ⚠️ Critical Scientific & Cryptographic Distinction
>
> It is vital to clearly separate these four distinct concepts:
>
> $$\text{Numeral Representation} \centernot\implies \text{Arithmetic System} \centernot\implies \text{Mathematical Operation} \centernot\implies \text{Cryptographic Primitive}$$
>
> 1. **Base-47 Numeral Representation:** A change-of-basis alphabet encoding. **Base-47 representation itself is NOT encryption.** It contains zero secret key material and provides zero confidentiality.
> 2. **Base-47 Arithmetic System:** The classical commutative ring operations $(+, -, \times, //, \%, **)$ evaluated directly on radix-47 digit arrays.
> 3. **Experimental Mathematical Operations:** Non-standard algebraic mappings (such as carryless digit-sum $\oplus_{47}$ or quasigroup folds $\star_{47}$) studied for mathematical structure.
> 4. **Cryptographic Primitives:** Keyed, computationally hard transformations resistant to differential, linear, and algebraic cryptanalysis.

---

## The Base-47 Alphabet & Digit Mapping

Radix: **47**  
Alphabet: `0abcdefghijklmnopqrstuvwxyz123456789!$?BCDEFGHI`

| Value | Glyph | Category | Value | Glyph | Category | Value | Glyph | Category |
| :---: | :---: | :--- | :---: | :---: | :--- | :---: | :---: | :--- |
| **0** | `0` | Zero | **16** | `p` | Lowercase | **32** | `6` | Decimal digit |
| **1** | `a` | Lowercase | **17** | `q` | Lowercase | **33** | `7` | Decimal digit |
| **2** | `b` | Lowercase | **18** | `r` | Lowercase | **34** | `8` | Decimal digit |
| **3** | `c` | Lowercase | **19** | `s` | Lowercase | **35** | `9` | Decimal digit |
| **4** | `d` | Lowercase | **20** | `t` | Lowercase | **36** | `!` | Punctuation |
| **5** | `e` | Lowercase | **21** | `u` | Lowercase | **37** | `$` | Punctuation |
| **6** | `f` | Lowercase | **22** | `v` | Lowercase | **38** | `?` | Punctuation |
| **7** | `g` | Lowercase | **23** | `w` | Lowercase | **39** | `B` | Uppercase |
| **8** | `h` | Lowercase | **24** | `x` | Lowercase | **40** | `C` | Uppercase |
| **9** | `i` | Lowercase | **25** | `y` | Lowercase | **41** | `D` | Uppercase |
| **10** | `j` | Lowercase | **26** | `z` | Lowercase | **42** | `E` | Uppercase |
| **11** | `k` | Lowercase | **27** | `1` | Decimal digit | **43** | `F` | Uppercase |
| **12** | `l` | Lowercase | **28** | `2` | Decimal digit | **44** | `G` | Uppercase |
| **13** | `m` | Lowercase | **29** | `3` | Decimal digit | **45** | `H` | Uppercase |
| **14** | `n` | Lowercase | **30** | `4` | Decimal digit | **46** | `I` | Uppercase |
| **15** | `o` | Lowercase | **31** | `5` | Decimal digit | — | — | — |

*Note: Uppercase letters start strictly at `B` and end at `I`. Glyph `A` and `J`..`Z` do not exist in the alphabet.*

---

## Installation

Requires Python 3.12 or newer.

```bash
cd eb47
pip install -e .
```

---

## Quickstart & Core Usage

### 1. Basic Construction & Conversions

```python
from eb47ns import Base47, encode_int, decode_str

# Construct from string, int, or digit sequences
x = Base47("1a4")               # 27*47^2 + 1*47 + 4 = 59,720
y = Base47.from_int(12345)      # Encodes to "e15"
z = Base47.from_string("I")     # Value 46

print(x.to_int())               # 59720
print(y.to_string())            # 'e15'
print(x.digit_length())         # 3

# Explicit functional conversions
s = encode_int(2209)            # 47^2 -> 'a00'
n = decode_str("a00")           # 2209
```

### 2. Direct Base-47 Arithmetic

All arithmetic operations are computed **directly on digit arrays** using radix-47 column-by-column carries and borrows:

```python
x = Base47("1a4")  # 59,720
y = Base47("e15")  # 12,345

# Positional addition & subtraction
print(x + y)       # Base47('63n')     (72,065)
print(x - y)       # Base47('utI')     (47,375)

# Positional multiplication (convolution)
print(x * y)       # Base47('cjcHn$')  (737,243,400)

# Positional long division & modulo
q, r = divmod(x, y)
print(q)           # Base47('d')       (4)
print(r)           # Base47('d60')     (10,340)

# Binary square-and-multiply exponentiation
print(Base47("a0") ** 3)  # Base47('a000') (103,823)

# Comparison
print(x > y)       # True
```

---

## Custom Mathematical Operations

EB47NS provides an extensible framework for defining and formally analyzing new dyadic operations.

### Built-in Experimental Operations

1. **The Ethiopian Digit Nim-Sum ($\oplus_{47}$):**
   $$c_i = (a_i + b_i) \pmod{47}$$
   Direct analogue of binary XOR transposed to characteristic 47. Forms an infinite elementary abelian 47-group $\bigoplus_{i=0}^\infty (\mathbb{Z}/47\mathbb{Z})$.
2. **The Ethiopian Quasigroup Isotopic Fold ($\star_{47}$):**
   $$c_i = (2 a_i + 3 b_i + 1) \pmod{47}$$
   Forms a non-commutative, non-associative Latin-square quasigroup with unique right division.

```python
from eb47ns import Base47, custom_operation, carryless_add_op

a = Base47("1a")
b = Base47("b2")

# Apply carryless modular addition
res = custom_operation(a, b, op="carryless_addition")
print("Carryless Sum:", res)  # Base47('33')

# Inspect formal mathematical properties
analysis = carryless_add_op.analyze()
print(analysis.summary())
```

### Defining a Custom Operation

```python
from eb47ns import Base47Operation, OperationAnalysis, register_operation

class MyOperation(Base47Operation):
    @property
    def name(self) -> str: return "my_op"
    @property
    def symbol(self) -> str: return "⊙"
    @property
    def description(self) -> str: return "Digit product modulo 47"

    def execute(self, a: Base47, b: Base47) -> Base47:
        # Custom logic on digits...
        ...

    def analyze(self) -> OperationAnalysis:
        # Full 11-property formal algebraic characterization
        ...

register_operation(MyOperation())
```

---

## Cryptography Research Layer

Located in `eb47ns.crypto`, this layer provides rigorous tools for investigating algebraic cryptography over odd-characteristic fields:

* **Galois Field $\mathbb{F}_{47}$ (`FieldElement47`):** Complete field arithmetic with Fermat inversion ($x^{45} \pmod{47}$).
* **Primitive Roots:** Exact enumeration of all $\phi(46) = 22$ generators of $\mathbb{F}_{47}^*$ (canonical generator $g = 5$).
* **Inversion S-Box over $\mathbb{F}_{47}$:** Optimal non-linear permutation achieving Nyberg's bound for differential uniformity ($\delta = 2$):
  $$S(x) = (3 \cdot x^{45} + 7) \pmod{47}$$
* **Difference Distribution Table (DDT) & LAT:** Automated cryptanalysis evaluating differential uniformity and linear bias.
* **MDS Diffusion Layer:** $4 \times 4$ Cauchy matrix over $\mathbb{F}_{47}$ guaranteeing optimal branch number $B = 5$.
* **Toy SPN Cipher (`ToyBase47SPN`):** 4-round educational Substitution-Permutation Network operating directly on blocks of 4 Base-47 digits.

```python
from eb47ns.crypto import (
    FieldElement47,
    ToyBase47SPN,
    generate_inversion_sbox,
    analyze_sbox,
)

# Field operations
a = FieldElement47(25)
b = FieldElement47(10)
print("Product in F_47:", a * b)
print("Inverse of 25 in F_47:", a.inv())

# Analyze S-box
sbox = generate_inversion_sbox()
metrics = analyze_sbox(sbox)
print("Differential Uniformity delta:", metrics.differential_uniformity)  # 2 (Optimal)

# Toy SPN block cipher
spn = ToyBase47SPN(rounds=4)
pt = [1, 26, 35, 46]    # 4 Base-47 digits
key = [5, 12, 19, 38]   # 4 Base-47 digits
ct = spn.encrypt_block(pt, key)
recovered = spn.decrypt_block(ct, key)
assert recovered == pt
```

---

## Running the Automated Test Suite

The test suite contains 64 rigorous tests including property-based tests verifying invariance against Python's arbitrary-precision integers.

```bash
pytest -v
```

---

## Package Architecture

```text
eb47/
├── eb47ns/
│   ├── __init__.py           # Package public interface exports
│   ├── alphabet.py           # Alphabet specification and digit bijections
│   ├── arithmetic.py         # Direct digit-array arithmetic algorithms
│   ├── conversion.py         # Encoding, decoding, and byte transformations
│   ├── crypto.py             # Cryptographic research layer (F_47, S-box, MDS, SPN)
│   ├── errors.py             # Exception hierarchy
│   ├── number.py             # Base47 class and operator overloading
│   ├── operations.py         # Custom operations architecture and formal analysis
│   └── tests/
│       ├── __init__.py
│       ├── test_conversion.py
│       ├── test_arithmetic.py
│       ├── test_operations.py
│       ├── test_crypto.py
│       └── test_vectors.py
├── pyproject.toml            # Build metadata and pytest configuration
├── README.md                 # Project documentation and quickstart
└── specification.md          # 18-section formal reference specification
```

---

## License

This project is licensed under the MIT License.
