Metadata-Version: 2.4
Name: mobiu-q
Version: 2.5.3
Summary: Soft Algebra Optimizer for Quantum & Complex Optimization
Home-page: https://mobiu.ai
Author: Mobiu Technologies
Author-email: Mobiu Technologies <ai@mobiu.ai>
License: Proprietary
Project-URL: Homepage, https://app.mobiu.ai
Project-URL: Documentation, https://pypi.org/project/mobiu-q/
Keywords: quantum,optimization,VQE,QAOA,machine-learning
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Science/Research
Classifier: Topic :: Scientific/Engineering :: Physics
Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.8
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Requires-Python: >=3.8
Description-Content-Type: text/markdown
Requires-Dist: numpy>=1.21.0
Requires-Dist: requests>=2.25.0
Provides-Extra: dev
Requires-Dist: pytest>=7.0; extra == "dev"
Requires-Dist: pytest-cov; extra == "dev"
Provides-Extra: full
Requires-Dist: scipy>=1.7.0; extra == "full"
Requires-Dist: qiskit>=0.40.0; extra == "full"
Dynamic: author
Dynamic: home-page
Dynamic: requires-python

# 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**, **Materials Science**, and **FinTech**.

---

## 🚀 What's New in v2.5.3

- **LLM Fine-tuning Support**: +23.3% improvement on full fine-tuning, +97% on LoRA
- **Materials Science**: +98% on Bulk Modulus, +67% on Band Gap prediction
- **Noise Robustness**: +32.5% more robust to quantum hardware noise
- **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.

### 🔬 Materials Science (NEW)
| Task | Improvement | p-value | Win Rate |
|------|-------------|---------|----------|
| **Bulk Modulus (GPa)** | **+98.3%** | <0.001 | 100% |
| **Band Gap (eV)** | **+66.8%** | <0.001 | 100% |
| **Formation Energy** | **+26.9%** | <0.001 | 100% |

### 🤖 LLM Fine-tuning
| Task | Improvement | p-value | Win Rate |
|------|-------------|---------|----------|
| **LoRA r16 + Momentum** | **+97.6%** | <0.001 | 100% |
| **LoRA r32 + SGD** | **+90.2%** | <0.001 | 100% |
| **Full Fine-tuning** | **+23.3%** | 0.002 | 100% |
| **GPT-2 Medium (PPL)** | **+21.2%** | <0.001 | 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. Materials Science (NEW)

```python
from mobiu_q import MobiuQCore

opt = MobiuQCore(
    license_key="YOUR-KEY",
    method="standard",
    base_optimizer="adam"
)

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

opt.end()
```

### 2. LoRA Fine-tuning

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

for step in range(1000):
    loss = lora_forward(model, batch)
    gradient = compute_lora_gradients()
    
    params = opt.step(params, gradient, loss)

opt.end()
```

### 3. 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()
```

### 4. VQE (Quantum Chemistry)

```python
from mobiu_q import MobiuQCore, Demeasurement

opt = MobiuQCore(
    license_key="YOUR-KEY",
    method="standard"
)

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

opt.end()
```

### 5. QAOA (Noisy Hardware)

```python
opt = MobiuQCore(
    license_key="YOUR-KEY",
    method="deep",
    mode="hardware"
)

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, Materials | Trust Ratio + Gradient Warping |
| `deep` | QAOA, Noisy Hardware | Super-Equation Δ† for emergence detection |
| `adaptive` | RL, LLM, LoRA, 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 |

---

## 🛠️ Troubleshooting

If optimization is not improving or diverging, try these adjustments:

### 1. Switch Base Optimizer

Different optimizers work better for different problems:

| Problem Type | Recommended Optimizer |
|--------------|----------------------|
| LoRA / LLM | `momentum` (not SGD) |
| VQE / Chemistry | `adam` |
| QAOA | `nadam` |
| RL | `momentum` |
| Materials Science | `adam` |

```python
# If Adam isn't working, try Momentum:
opt = MobiuQCore(license_key="KEY", base_optimizer="momentum")

# If Momentum isn't working, try NAdam:
opt = MobiuQCore(license_key="KEY", base_optimizer="nadam")
```

### 2. Switch Method

| If This Fails | Try This |
|---------------|----------|
| `standard` | `adaptive` |
| `adaptive` | `deep` |
| `deep` | `standard` |

```python
# If standard isn't working for your problem:
opt = MobiuQCore(license_key="KEY", method="adaptive")
```

### 3. Switch Mode

For quantum problems, if `simulation` mode isn't working:

```python
# Try hardware mode (more aggressive noise filtering):
opt = MobiuQCore(license_key="KEY", mode="hardware")
```

### 4. Adjust Learning Rate

Soft Algebra works best with moderate learning rates:

| Scenario | Recommendation |
|----------|---------------|
| Diverging | Lower LR by 2-5x |
| No improvement | Increase LR by 2x |
| LoRA specifically | Use LR=0.01-0.03 |

### 5. Common Fixes by Domain

| Domain | Common Issue | Fix |
|--------|--------------|-----|
| **LoRA** | SGD + high LR diverges | Use `momentum` + LR=0.02 |
| **Drug Discovery** | BCE loss unstable | Use `adam` + `standard` method |
| **Small Batch LLM** | High variance | Increase batch size or use `deep` method |
| **Classification** | Cross-entropy issues | Use `adam` + lower LR |

---

## 🔬 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 |
| **Materials (Bulk Modulus)** | +98.3% | vs Adam |
| **LoRA (r16 Momentum)** | +97.6% | vs Momentum |
| **Materials (Band Gap)** | +66.8% | vs Adam |
| **Quantum (XY Model)** | +60.8% | vs Adam |
| **Noise Robustness** | +32.5% | vs Momentum |
| **QAOA MaxCut** | +27.2% | vs NAdam |
| **LLM Full Fine-tune** | +23.3% | 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.
