Metadata-Version: 2.4
Name: eb47ns
Version: 0.2.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-105%20passed-brightgreen.svg)]()

The **Ethiopian Base-47 Numeral System (EB47NS)** is an original, mathematically complete positional numeral system of prime radix $R = 47$. Designed at the intersection of number theory, abstract algebra, and non-binary cryptography research, it provides a comprehensive mathematical architecture organized into distinct layers:

```text
                               RADIX-47
                                  │
    ┌─────────────────────────────┼─────────────────────────────┐
    │                             │                             │
Representation               Arithmetic                   Number Theory
    │                             │                             │
 Alphabet & Bijections        + - × ÷ (Direct Digits)       GCD / LCM / ExtGCD
 Encoding / Decoding          % pow                         Modular Inv / Add / Mul
 Bytes Transformations        Successor / Predecessor       isqrt / Miller-Rabin Primes
    │                             │                             │
    └─────────────────────────────┼─────────────────────────────┘
                                  │
                       Algebraic Operations Layer
                                  │
             ┌────────────────────┴────────────────────┐
             │                                         │
       Dyadic Ring Operations                    Transformation Functions
             │                                         │
        ⊕_47  (Carryless Add)                     T(d) = (kd + c) mod 47
        ⊗_47  (Carryless Mul)                     Digit Rotation / Shifts
        ⋆_47  (Quasigroup Fold)                   46's Digit Complement
        ◇_47  (Quadratic Fold)                    Digit Sum / Parity / Histograms
             │                                         │
             └────────────────────┬────────────────────┘
                                  │
                  Polynomial Ring & Matrix Layer
                                  │
             ┌────────────────────┴────────────────────┐
             │                                         │
       Polynomials F_47[x]                       Matrices M_nxn(F_47)
             │                                         │
        Add / Sub / Mul / Div                     Add / Mul / Exponentiation
        Monic GCD / Evaluation                    Determinant / Trace
        Lagrange Interpolation                    Gauss-Jordan Inversion
             │                                         │
             └────────────────────┬────────────────────┘
                                  │
                      Cryptographic Research Layer
                                  │
                     Galois Field F_47 (Order 46)
                     Primitive Roots (phi(46) = 22)
                     Optimal S-box (delta = 2, Nyberg)
                     Cauchy MDS Matrix (Branch B = 5)
                     Toy 4-Round Base-47 SPN Block Cipher
```

---

> ### ⚠️ Critical Scientific & Cryptographic Distinction
>
> $$\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 ring operations $(+, -, \times, //, \%, **)$ evaluated directly on radix-47 digit arrays.
> 3. **Experimental Mathematical Operations:** Non-standard algebraic mappings (such as $\oplus_{47}, \otimes_{47}, \star_{47}, \diamond_{47}$) studied for mathematical structure.
> 4. **Cryptographic Primitives:** Keyed, computationally hard transformations resistant to differential, linear, and algebraic cryptanalysis.

---

## Alphabet & Positional Mapping

Radix: **47**  
Alphabet: `0abcdefghijklmnopqrstuvwxyz123456789!$?BCDEFGHI` (47 unique ASCII glyphs)

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

---

## Installation

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

---

## Mathematical Capabilities & API Guide

### 1. Fundamental Arithmetic (Direct Digit Evaluation)

All arithmetic operates **directly on little-endian Base-47 digit arrays** without converting to decimal big-integers:

```python
import eb47ns

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

# Operator overloading
print(x + y)                          # Base47('63n')     (72,065)
print(x - y)                          # Base47('utI')     (47,375)
print(x * y)                          # Base47('cjcHn$')  (737,243,400)
print(x // y)                         # Base47('d')       (4)
print(x % y)                          # Base47('d60')     (10,340)
print(eb47ns.Base47("a0") ** 3)       # Base47('a000')    (103,823)

# Functional API
print(eb47ns.add_47(x, y))            # Base47('63n')
print(eb47ns.mul_47(x, y))            # Base47('cjcHn$')
print(x.succ())                       # Base47('1a5')
print(x.pred())                       # Base47('1a3')
```

### 2. Number-Theoretic Operations

```python
import eb47ns

a = eb47ns.Base47(240)
b = eb47ns.Base47(46)

# GCD and LCM
print(eb47ns.gcd(a, b))               # Base47('b') (2)
print(eb47ns.lcm(12, 18))             # Base47('36')

# Extended GCD: a*x + b*y = gcd(a, b)
g, x, y = eb47ns.extended_gcd(a, b)
print(f"{a}*{x} + {b}*{y} = {g}")

# Modular Multiplicative Inverse
inv = eb47ns.modular_inverse(3, 47)
print("3^(-1) mod 47:", inv)          # Base47('p') (16)

# Integer Square Root (via Base-47 binary search)
print(eb47ns.isqrt(2209))             # Base47('a0') (47)

# Miller-Rabin Primality Testing
print(eb47ns.is_prime(47))            # True
print(eb47ns.is_prime(49))            # False
```

### 3. Digit-Level Manipulations & Radix Reduction

```python
import eb47ns

x = eb47ns.Base47("a7C!m")

# Radix reduction
print(eb47ns.radix_remainder(x))      # Least-significant digit (13, 'm')
print(eb47ns.radix_quotient(x))       # Drops lowest digit: Base47('a7C!')

# Rotations, Shifts, and Reversals
print(eb47ns.digit_reverse(x))        # Base47('m!C7a')
print(eb47ns.digit_rotate_left(x, 1)) # Base47('7C!ma')
print(eb47ns.digit_shift_left(x, 2))  # Base47('a7C!m00')

# Digit Statistics & Complements
print(eb47ns.digit_sum(x))            # Base47('b3') (sum of digit values)
print(eb47ns.digit_complement(x))     # 46's complement: Base47('Hmfj7')
print(eb47ns.digit_histogram(x))      # Digit count map
```

### 4. Algebraic Operations Architecture

Custom dyadic operations characterized across 11 formal algebraic properties:

* **$\oplus_{47}$ (Carryless Addition / Nim-Sum):** $(a \oplus b)_i = (a_i + b_i) \bmod 47$
* **$\otimes_{47}$ (Carryless Multiplication):** Polynomial convolution product in $\mathbb{F}_{47}[x]$
* **$\star_{47}$ (Quasigroup Fold):** $(2a_i + 3b_i + 1) \bmod 47$ (Latin square)
* **$\diamond_{47}$ (Quadratic Fold):** $(a_i^2 + 3b_i) \bmod 47$ (Non-linear mapping)

```python
import eb47ns

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

# Carryless operations
print("⊕_47:", eb47ns.custom_operation(a, b, op="carryless_addition"))
print("⊗_47:", eb47ns.custom_operation(a, b, op="carryless_multiplication"))
print("⋆_47:", eb47ns.custom_operation(a, b, op="quasigroup_fold"))
print("◇_47:", eb47ns.custom_operation(a, b, op="quadratic_fold"))

# Formal algebraic analysis inspection
print(eb47ns.carryless_mul_op.analyze().summary())
```

### 5. Polynomial Ring $\mathbb{F}_{47}[x]$

```python
from eb47ns import Polynomial47, poly_gcd, poly_interpolate

# P(x) = (x + 1)(x + 2) = 2 + 3x + x^2
p1 = Polynomial47([1, 1])
p2 = Polynomial47([2, 1])
prod = p1 * p2
print("Product:", prod)

# Euclidean polynomial division
q, r = divmod(prod, p1)
print("Quotient:", q, "Remainder:", r)

# Monic GCD
print("GCD:", poly_gcd(prod, p1))

# Lagrange Interpolation (Shamir Secret Sharing)
pts = [(1, 5), (2, 12), (3, 23)]
poly = poly_interpolate(pts)
print("Interpolated Poly:", poly)
```

### 6. Linear Algebra & Matrices over $\mathbb{F}_{47}$

```python
from eb47ns import Matrix47

m = Matrix47([
    [1, 2],
    [3, 4]
])

print("Determinant:", m.determinant()) # 45 (-2 mod 47)
inv = m.inverse()
print("Inverse:\n", inv)
print("m * inv == I:\n", m * inv)      # Identity matrix

# Diffusion vector product
print("m * [5, 10]:", m.vector_mul([5, 10]))
```

### 7. Random Generation & Prime Synthesis

```python
import eb47ns

# Random 5-digit Base47 numeral
print(eb47ns.random_base47(5))

# Random stream of Base47 digits
print(eb47ns.random_digits(10))

# Cryptographic probable prime in Base-47
prime = eb47ns.random_prime(digit_length=4)
print("Random Base-47 Prime:", prime, "IsPrime:", eb47ns.is_prime(prime))
```

### 8. Cryptography Research Layer

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

# Prime field F_47 operations
f = FieldElement47(25)
print("F_47 Inverse:", f.inv())

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

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

---

## Test Suite

All 105 automated tests pass:

```bash
pytest -v
```

---

## License

MIT License. Authored by Ezra Destaw.
