# Mobiu-Q

[![PyPI version](https://badge.fury.io/py/mobiu-q.svg)](https://badge.fury.io/py/mobiu-q)
[![Win Rate](https://img.shields.io/badge/Win%20Rate-80%25-brightgreen)](https://mobiu.ai)
[![License](https://img.shields.io/badge/License-Proprietary-blue)](https://mobiu.ai)

**Mobiu-Q** wraps your existing optimizer with **Soft Algebra** to filter noise and improve convergence. Same API, better results.

Works across **Quantum Computing**, **Reinforcement Learning**, **LLM Fine-tuning**, and **FinTech**.

---

## 🚀 What's New in v2.5.2

- **LLM Fine-tuning Support**: New `method="adaptive"` with +23.3% improvement on full fine-tuning
- **Noise Robustness**: +32.5% more robust to quantum hardware noise
- **New Method Names**: `standard`, `deep`, `adaptive` (legacy names still supported)
- **Multi-Optimizer**: Choose from Adam, NAdam, AMSGrad, SGD, Momentum, LAMB

---

## 🏆 Benchmark Results (v2.5)

All benchmarks compare **Optimizer + Soft Algebra** vs **Optimizer alone**. Same learning rate, same seeds, fair A/B test.

### 🤖 LLM Fine-tuning (NEW)
| Task | Improvement | p-value | Win Rate |
|------|-------------|---------|----------|
| **Full Fine-tuning** | **+23.3%** | 0.002 | 100% |
| **Soft Prompt Tuning** | **+18.1%** | <0.05 | 100% |

### 🎮 Reinforcement Learning
| Environment | Improvement | p-value | Win Rate |
|-------------|-------------|---------|----------|
| **LunarLander-v3** | **+129.7%** | <0.001 | 96.7% |
| **MuJoCo InvertedPendulum** | **+118.6%** | 0.001 | 100% |
| **Crypto Trading** | **+10.9% profit** | 0.005 | 90% |

### 🧪 Quantum Chemistry (VQE)
| Problem | Improvement |
|---------|-------------|
| **XY Model** | **+60.8%** |
| **He Atom** | **+51.2%** |
| **H2 Molecule** | **+46.6%** |
| **H3+ Chain** | **+42.0%** |
| **LiH Molecule** | **+41.4%** |
| **BeH2 Molecule** | **+37.8%** |

### 🎯 QAOA (Combinatorial Optimization)
| Problem | Improvement | p-value |
|---------|-------------|---------|
| **MaxCut 4-qubit** | **+27.2%** | 0.04 |
| **MaxCut 5-qubit** | **+23.7%** | 0.004 |
| **MaxCut p=3** | **+15.6%** | 0.008 |

### 🛡️ Noise Robustness (IBM FakeBackend)
| Metric | Result |
|--------|--------|
| **Robustness Advantage** | **+32.5%** |
| **Win Rate (all noise levels)** | **80% (12/15)** |
| **IBM FakeFez VQE** | **+50.9%** (p=0.03) |

---

## 📦 Installation

```bash
pip install mobiu-q
```

---

## ⚡ Quick Start

### 1. LLM Fine-tuning (NEW)

```python
from mobiu_q import MobiuQCore

# Wrap your training loop
opt = MobiuQCore(
    license_key="YOUR-KEY",
    method="adaptive",      # Best for LLM/RL
    base_optimizer="momentum"
)

for epoch in range(num_epochs):
    loss = train_step(model, batch)
    gradient = compute_gradients()
    
    params = opt.step(params, gradient, loss)

opt.end()
```

### 2. Reinforcement Learning

```python
opt = MobiuQCore(
    license_key="YOUR-KEY",
    method="adaptive",
    base_optimizer="momentum"
)

for episode in range(1000):
    episode_return = run_episode(policy)
    gradient = compute_policy_gradient()
    
    policy_params = opt.step(policy_params, gradient, episode_return)

opt.end()
```

### 3. VQE (Quantum Chemistry)

```python
from mobiu_q import MobiuQCore, Demeasurement

opt = MobiuQCore(
    license_key="YOUR-KEY",
    method="standard"  # Best for VQE
)

for step in range(100):
    grad = Demeasurement.finite_difference(energy_fn, params)
    params = opt.step(params, grad, energy_fn(params))

opt.end()
```

### 4. QAOA (Noisy Hardware)

```python
opt = MobiuQCore(
    license_key="YOUR-KEY",
    method="deep",       # Best for QAOA
    mode="hardware"      # For quantum hardware / noisy simulation
)

for step in range(150):
    grad, energy = Demeasurement.spsa(energy_fn, params)
    params = opt.step(params, grad, energy)

opt.end()
```

---

## 🔧 Configuration

### Methods

| Method | Best For | Description |
|--------|----------|-------------|
| `standard` | VQE, Chemistry | Trust Ratio + Gradient Warping |
| `deep` | QAOA, Noisy Hardware | Super-Equation Δ† for emergence detection |
| `adaptive` | RL, LLM, Trading | Trust + Emergence + Warping combined |

### Base Optimizers

Choose from: `adam`, `momentum`, `sgd`, `nadam`, `amsgrad`, `lamb`

```python
opt = MobiuQCore(
    license_key="YOUR-KEY",
    method="adaptive",
    base_optimizer="momentum"  # Best for RL/LLM
)
```

### Modes

| Mode | Description |
|------|-------------|
| `simulation` | Clean quantum simulation (default) |
| `hardware` | Noisy quantum hardware |

---

## 🔬 How It Works

Mobiu-Q is based on **Soft Algebra**, a mathematical framework that extends real numbers with infinitesimal components using nilpotent arithmetic (ε²=0).

### Core SoftNumber Multiplication

```
(a, b) × (c, d) = (ad + bc, bd)
```

Where:
- `a` = potential (infinitesimal component)
- `b` = realization (real component)

### Evolution Law

```
S_{t+1} = (γ · S_t) · Δ_t + Δ_t
```

This allows gradients to carry both magnitude AND uncertainty information, enabling the optimizer to distinguish real improvement from noise artifacts.

### Key Formulas

- **Trust Ratio**: `trust = |real| / (|real| + |soft| + ε)`
- **Gradient Warping**: `g_eff = gradient × soft_factor`
- **Super-Equation Δ†**: For emergence detection in rugged landscapes

---

## 💰 Pricing

| Tier | Price | Runs |
|------|-------|------|
| **Free** | $0 | 20 runs/month |
| **Pro** | $19/month | Unlimited |

Get your license key at [app.mobiu.ai](https://app.mobiu.ai)

---

## 📊 Full Benchmark Summary

| Domain | Best Result | vs Optimizer |
|--------|-------------|--------------|
| **RL (LunarLander)** | +129.7% | vs Momentum |
| **RL (MuJoCo)** | +118.6% | vs Momentum |
| **Quantum (XY Model)** | +60.8% | vs Adam |
| **Quantum (He Atom)** | +51.2% | vs Adam |
| **Noise Robustness** | +32.5% | vs Momentum |
| **QAOA MaxCut** | +27.2% | vs NAdam |
| **LLM Full Fine-tune** | +23.3% | vs Momentum |
| **LLM Soft Prompts** | +18.1% | vs Momentum |
| **Crypto Trading** | +10.9% | vs Momentum |

**Overall Win Rate: 80%** across all benchmarks.

---

## 🧑‍🔬 Scientific Foundation

Developed by **Mobiu Technologies**, based on Soft Algebra theory by:
- **Dr. Moshe Klein** – Developer of Soft Logic and Soft Numbers
- **Prof. Oded Maimon** – Tel Aviv University, Industrial Engineering

---

## 📚 Links

- **Website**: [mobiu.ai](https://mobiu.ai)
- **App**: [app.mobiu.ai](https://app.mobiu.ai)
- **PyPI**: [pypi.org/project/mobiu-q](https://pypi.org/project/mobiu-q)

---

## 📄 License

Proprietary. See [LICENSE](LICENSE) for details.

© 2025 Mobiu Technologies. All rights reserved.