Update README.md

README.md

@@ -17,82 +17,144 @@ tags:
 pipeline_tag: feature-extraction
 ---
 
-# 🤖 Stupid-Equation-Solver (1st–4th Degree Polynomials)
+<div align="center">
 
-[English](#description) | [Polski](#opis) | [Русский](#описание)
+# 🤖 Stupid-Equation-Solver
+
+### Solving 1st–4th Degree Polynomials from Raw Text
+
+*No CAS. No symbolic engine. Just a neural network that learned algebra from scratch.*
+
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
+[![Params](https://img.shields.io/badge/Params-3.73M-blue.svg)]()
+[![Hardware](https://img.shields.io/badge/Trained%20on-Intel%20Arc%20A770-0071C5.svg)]()
+[![OS](https://img.shields.io/badge/OS-Arch%20Linux-1793D1.svg)]()
+
+[English](#-english) · [Polski](#-polski) · [Русский](#-русский)
+
+</div>
 
 ---
 
 ## 🇬🇧 English
 
-### Description
-A lightweight neural network designed to solve algebraic polynomial equations from **1st to 4th degree** (both complete and incomplete) directly from raw character text.
+### 📖 Description
 
-The model infers real roots without any external CAS/symbolic algebra engines—it learns polynomial factorization, discriminant calculation, sign switching, and roots extraction directly from ASCII strings.
+A lightweight neural network that solves algebraic polynomial equations of **1st to 4th degree** (both complete and incomplete) — directly from raw character text.
 
-### 📊 Architecture & Training
-* **Model Architecture:** 2-layer Bidirectional GRU (BiGRU) + Deep MLP regression head
-* **Parameters:** `embed_dim=64`, `hidden_dim=384`, `max_roots=4`
-* **Dataset:** Trained on over **1,000,000 synthetic equations** (random variable names $x, y, a, t, z...$, non-monic scales from -6 to +12, roots range $[-20, 20]$)
-* **Hardware Acceleration:** **Intel Arc A770 (16GB GDDR6)** on **Arch Linux** via PyTorch XPU (oneAPI / Level Zero backend)
-* **Loss Function:** Custom Masked MSE Loss (penalizes only valid real roots, masking out padding slots)
+The model infers **real roots without any external CAS or symbolic algebra engine**. It learned polynomial factorization, discriminant calculation, sign switching, and root extraction directly from ASCII strings.
+
+> 💡 *Think of it as a tiny neural calculator that reads equations like a human would — and just knows the answer.*
+
+### 🏗️ Architecture & Training
+
+| Property | Value |
+|---|---|
+| **Architecture** | 2-layer Bidirectional GRU (BiGRU) + Deep MLP regression head |
+| **Parameters** | `embed_dim=64`, `hidden_dim=384`, `max_roots=4` |
+| **Dataset** | 1,000,000+ synthetic equations |
+| **Variable names** | $x, y, a, t, z, \dots$ (randomized) |
+| **Coefficients** | Non-monic scales from −6 to +12 |
+| **Root range** | $[-20, 20]$ |
+| **Hardware** | Intel Arc A770 (16GB GDDR6) |
+| **OS** | Arch Linux |
+| **Backend** | PyTorch XPU (oneAPI / Level Zero) |
+| **Loss** | Custom Masked MSE (penalizes only valid real roots) |
 
 ### 🎯 Benchmark Results (100 Unseen Test Equations)
-* **Degree 1 (Linear):** MAE ≈ **0.33**
-* **Degree 2 (Quadratic):** MAE ≈ **0.27** *(Accurate on full quadratics and irrationals, e.g. $1 - \sqrt{2} \approx -0.41$)*
-* **Degree 3 (Cubic):** MAE ≈ **0.60**
-* **Degree 4 (Quartic):** MAE ≈ **1.17**
-* **Overall Mean Absolute Error (MAE):** **~0.69 – 0.75**
+
+| Degree | Type | MAE | Notes |
+|:---:|:---:|:---:|---|
+| **1** | Linear | **0.33** | Solid |
+| **2** | Quadratic | **0.27** | Handles irrationals, e.g. $1 - \sqrt{2} \approx -0.41$ |
+| **3** | Cubic | **0.60** | Reliable |
+| **4** | Quartic | **1.17** | Best effort |
+| — | **Overall** | **~0.69 – 0.75** | |
 
 ---
 
 ## 🇵🇱 Polski
 
-### Opis
-Neuronowy solver równań algebraicznych wielomianowych od **1. do 4. stopnia** (zarówno zupełnych, jak i niezupełnych) bezpośrednio z surowego tekstu znakowego.
+### 📖 Opis
 
-Model wyznacza pierwiastki rzeczywiste bez użycia zewnętrznych silników symbolicznych (CAS) — uczy się wyznaczania wyróżnika (delty), rozkładu na czynniki, reguły znaków i pierwiastkowania wprost z ciągów znaków ASCII.
+Lekki model neuronowy rozwiązujący równania algebraiczne wielomianowe od **1. do 4. stopnia** (zarówno zupełne, jak i niezupełne) bezpośrednio z surowego tekstu znakowego.
 
-### 📊 Architektura i Trening
-* **Architektura:** 2-warstwowy dwukierunkowy GRU (BiGRU) + głęboka regresyjna głowica MLP
-* **Wymiary:** `embed_dim=64`, `hidden_dim=384`, `max_roots=4`
-* **Zbiór danych:** Wytrenowany na ponad **1 000 000 syntetycznych równań** (losowe zmienne $x, y, a, t...$, współczynniki skalowania od -6 do +12, zakres pierwiastków $[-20, 20]$)
-* **Akceleracja sprzętowa:** **Intel Arc A770 (16GB)** pod **Arch Linux** z wykorzystaniem PyTorch XPU (Level Zero)
-* **Funkcja straty:** Masked MSE Loss (uwzględnia wyłącznie istniejące pierwiastki rzeczywiste)
+Model wyznacza **pierwiastki rzeczywiste bez użycia zewnętrznych silników symbolicznych (CAS)** — uczy się wyznaczania wyróżnika (delty), rozkładu na czynniki, reguły znaków i pierwiastkowania wprost z ciągów znaków ASCII.
 
-### 🎯 Wyniki testowe (Benchmark 100 równań)
-* **Stopień 1 (Liniowe):** MAE ≈ **0.33**
-* **Stopień 2 (Kwadratowe):** MAE ≈ **0.27** *(Wysoka precyzja na pierwiastkach niewymiernych, np. $1 - \sqrt{2} \approx -0.41$)*
-* **Stopień 3 (Sześcienne):** MAE ≈ **0.60**
-* **Stopień 4 (4. stopień):** MAE ≈ **1.17**
-* **Średni błąd bezwzględny (Ogólny MAE):** **~0.69 – 0.75**
+> 💡 *Wyobraź sobie mały neuronowy kalkulator, który czyta równania jak człowiek — i po prostu zna odpowiedź.*
+
+### 🏗️ Architektura i Trening
+
+| Właściwość | Wartość |
+|---|---|
+| **Architektura** | 2-warstwowy dwukierunkowy GRU (BiGRU) + głęboka regresyjna głowica MLP |
+| **Parametry** | `embed_dim=64`, `hidden_dim=384`, `max_roots=4` |
+| **Zbiór danych** | Ponad 1 000 000 syntetycznych równań |
+| **Nazwy zmiennych** | $x, y, a, t, z, \dots$ (losowe) |
+| **Współczynniki** | Skala od −6 do +12 |
+| **Zakres pierwiastków** | $[-20, 20]$ |
+| **Sprzęt** | Intel Arc A770 (16GB GDDR6) |
+| **System** | Arch Linux |
+| **Backend** | PyTorch XPU (oneAPI / Level Zero) |
+| **Funkcja straty** | Masked MSE (uwzględnia tylko istniejące pierwiastki) |
+
+### 🎯 Wyniki testowe (100 równań)
+
+| Stopień | Typ | MAE | Uwagi |
+|:---:|:---:|:---:|---|
+| **1** | Liniowe | **0.33** | Stabilnie |
+| **2** | Kwadratowe | **0.27** | Radzi sobie z niewymiernymi, np. $1 - \sqrt{2} \approx -0.41$ |
+| **3** | Sześcienne | **0.60** | Niezawodnie |
+| **4** | 4. stopnia | **1.17** | Zadowalająco |
+| — | **Ogólnie** | **~0.69 – 0.75** | |
 
 ---
 
 ## 🇷🇺 Русский
 
-### Описание
-Нейросетевой решатель алгебраических уравнений степеней **от 1 до 4** (полных и неполных) по сырому символьному тексту.
+### 📖 Описание
+
+Лёгкая нейросеть, решающая алгебраические полиномиальные уравнения **1–4 степени** (полные и неполные) прямо из сырого текста.
 
-Модель находит действительные корни полиномов без сторонних систем компьютерной алгебры (CAS) — она выучила формулы Виета, дискриминант, смену знаков и извлечение корней напрямую из строк ASCII.
+Модель находит **действительные корни без сторонних систем компьютерной алгебры (CAS)** — она выучила формулы Виета, дискриминант, смену знаков и извлечение корней напрямую из ASCII-строк.
 
-### 📊 Архитектура и Обучение
-* **Архитектура:** 2-слойная Двунаправленная GRU (BiGRU) + Полносвязная голова MLP
-* **Размерности:** `embed_dim=64`, `hidden_dim=384`, `max_roots=4`
-* **Датасет:** Обучена суммарно на более чем **1 000 000 синтетических уравнений** (различные переменные $x, y, a, t...$, коэффициенты от -6 до +12, диапазон корней $[-20, 20]$)
-* **Аппаратное ускорение:** **Intel Arc A770 (16GB)** под **Arch Linux** через PyTorch XPU (интерфейс Level Zero)
-* **Функция потерь:** Кастомный Masked MSE Loss (штрафует только за существующие действительные корни)
+> 💡 *Представьте крошечный нейронный калькулятор, который читает уравнение как человек — и просто знает ответ.*
 
-### 🎯 Метрики качества (Бенчмарк на 100 контрольных уравнениях)
-* **Степень 1 (Линейные):** MAE ≈ **0.33**
-* **Степень 2 (Квадратные):** MAE ≈ **0.27** *(Точное извлечение корней, включая иррациональные до сотых, например $1 - \sqrt{2} \approx -0.41$)*
-* **Степень 3 (Кубические):** MAE ≈ **0.60**
-* **Степень 4 (4-я степень):** MAE ≈ **1.17**
-* **Общая средняя ошибка (Overall MAE):** **~0.69 – 0.75**
+### 🏗️ Архитектура и обучение
+
+| Параметр | Значение |
+|---|---|
+| **Архитектура** | 2-слойная двунаправленная GRU (BiGRU) + полносвязная голова MLP |
+| **Размерности** | `embed_dim=64`, `hidden_dim=384`, `max_roots=4` |
+| **Датасет** | 1 000 000+ синтетических уравнений |
+| **Переменные** | $x, y, a, t, z, \dots$ (случайные) |
+| **Коэффициенты** | Нем��нические, от −6 до +12 |
+| **Диапазон корней** | $[-20, 20]$ |
+| **Железо** | Intel Arc A770 (16GB GDDR6) |
+| **ОС** | Arch Linux |
+| **Бэкенд** | PyTorch XPU (oneAPI / Level Zero) |
+| **Функция потерь** | Кастомный Masked MSE (штрафует только за существующие корни) |
+
+### 🎯 Метрики качества (бенчмарк на 100 уравнениях)
+
+| Степень | Тип | MAE | Заметки |
+|:---:|:---:|:---:|---|
+| **1** | Линейные | **0.33** | Стабильно |
+| **2** | Квадратные | **0.27** | Справляется с иррациональными, напр. $1 - \sqrt{2} \approx -0.41$ |
+| **3** | Кубические | **0.60** | Надёжно |
+| **4** | 4-й степени | **1.17** | На пределе |
+| — | **Общая** | **~0.69 – 0.75** | |
 
 ---
 
-## 💻 Quick Start / Szybki start / Быстрый запуск (ONNX Runtime)
+## 💻 Quick Start
+
+### Install dependencies
+
+```bash
+pip install onnxruntime numpy
+```
+### Solve equations in Python
 
 ```python
 import json
@@ -113,12 +175,12 @@ def solve(equation: str):
     equation = equation.strip()
     if "=" not in equation:
         equation += " = 0"
-        
+
     # Determine polynomial degree
-    if "^4" in equation: deg = 4
+    if "^4" in equation:   deg = 4
     elif "^3" in equation: deg = 3
     elif "^2" in equation: deg = 2
-    else: deg = 1
+    else:                  deg = 1
 
     tokens = [vocab.get(ch, 1) for ch in equation]
     tokens = tokens[:max_len] + [0] * max(0, max_len - len(tokens))
@@ -128,7 +190,40 @@ def solve(equation: str):
     return [round(float(r), 2) for r in preds[:deg]]
 
 # 3. Test examples
-print(solve("3x^2 - 4x - 15 = 0"))  # -> [2.96, -1.59] (Exact: 3.0, -1.67)
-print(solve("x^2 - 2x - 1 = 0"))      # -> [2.03, -0.41] (Exact: 2.41, -0.41)
-print(solve("x^2 - 16 = 0"))          # -> [3.85, -4.02] (Exact: 4.0, -4.0)
-print(solve("a^3 - 3a^2 + 2a = 0"))   # -> [2.09, 0.84, -0.14] (Exact: 2.0, 1.0, 0.0)
+print(solve("3x^2 - 4x - 15 = 0"))   # -> [2.96, -1.59]           (Exact: 3.0, -1.67)
+print(solve("x^2 - 2x - 1 = 0"))     # -> [2.03, -0.41]           (Exact: 2.41, -0.41)
+print(solve("x^2 - 16 = 0"))         # -> [3.85, -4.02]           (Exact: 4.0, -4.0)
+print(solve("a^3 - 3a^2 + 2a = 0"))  # -> [2.09, 0.84, -0.14]     (Exact: 2.0, 1.0, 0.0)
+```
+
+---
+
+⚠️ Limitations
+
+· Regression, not symbolic. Outputs are continuous approximations, not exact fractions. Values like 2.96 instead of 3.0 are expected.
+· Degree cap. Trained exclusively on 1st–4th degree polynomials. Fifth-degree and higher are out of scope for this version.
+· Real roots only. Complex roots are not modeled.
+· Root range. Best performance within $[-20, 20]$.
+· No repeat roots detection. Multiplicity is not reported — only the value.
+
+---
+
+🚀 Roadmap
+
+☐ v2: Token-classification head for exact integer roots
+☐ v2: Variable-length output (no fixed max_roots)
+☐ v3: Extend to 5th+ degree polynomials
+☐ v3: Complex root support
+
+---
+
+<div align="center">
+
+⚡ Part of XIV AI
+
+A startup from Poland, building AI models from scratch.
+
+License: MIT · Trained on: Intel Arc A770 · Framework: PyTorch XPU
+
+</div>
+```