# Mobiu-Q (v2.4)

**Universal Physics-Aware Optimizer for Stochastic Systems**

[![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-100%25-brightgreen)](https://mobiu.ai)
[![License](https://img.shields.io/badge/License-Proprietary-blue)](https://mobiu.ai)

**Mobiu-Q** is the first optimizer based on **Soft Algebra**. By mathematically decomposing gradients into *Potential* ($a_t$) and *Realization* ($b_t$), it filters out noise in real-time.

Works across **Quantum Computing**, **Reinforcement Learning**, **FinTech**, and **Complex Engineering**.

---

## 🚀 What's New in v2.4

- **Reinforcement Learning Support**: New `method="rl"` with +129% improvement on LunarLander
- **Multi-Optimizer**: Choose from Adam, NAdam, AMSGrad, SGD, Momentum, LAMB
- **MuJoCo Robotics**: +118% improvement on continuous control tasks
- **Crypto Trading**: +10.9% profit improvement in high-volatility environments

---

## 🏆 Benchmark Results (v2.4)

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

### Quantum Computing
| Problem | Improvement | p-value | Win Rate |
|---------|-------------|---------|----------|
| **VQE H2 (IBM FakeFez)** | **+53.1%** | 0.001 | 100% |
| **QAOA MaxCut** | **+21.5%** | <0.05 | 85% |

### Classical Optimization
| Problem | Improvement |
|---------|-------------|
| Rosenbrock Valley | +75.8% |
| Credit Risk (VaR) | +52.3% |
| Portfolio Optimization | +51.7% |

---

## 📦 Installation

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

---

## ⚡ Quick Start

### 1. VQE (Quantum Chemistry)

```python
from mobiu_q import MobiuQCore, Demeasurement

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

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

opt.end()
```

### 2. QAOA (Combinatorial Optimization)

```python
opt = MobiuQCore(
    license_key="YOUR-KEY",
    method="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()
```

### 3. Reinforcement Learning (NEW in v2.4)

```python
opt = MobiuQCore(license_key="YOUR-KEY", method="rl")

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

opt.end()
```

### 4. Multi-Seed Experiments (1 billing session)

```python
opt = MobiuQCore(license_key="YOUR-KEY")

for seed in range(10):
    opt.new_run()  # Resets state, keeps session open
    params = init_params(seed)
    # ... optimization loop ...

opt.end()  # All 10 seeds count as 1 run
```

---

## 🎛️ Configuration

### Methods and Modes

| Method | Mode | Use Case | Default LR |
|--------|------|----------|------------|
| `vqe` | `simulation` | Chemistry, physics (clean) | 0.01 |
| `vqe` | `hardware` | VQE on quantum hardware | 0.02 |
| `qaoa` | `simulation` | Combinatorial (simulator) | 0.1 |
| `qaoa` | `hardware` | QAOA on quantum hardware | 0.1 |
| `rl` | (ignored) | Reinforcement learning | 0.0003 |

### Optimizers (NEW in v2.4)

Default: **Adam** (recommended - works best across all methods)

```python
# Use default (Adam)
opt = MobiuQCore(method="vqe")

# Try alternative optimizer
opt = MobiuQCore(method="qaoa", base_optimizer="NAdam")
```

Available optimizers:
- **Adam** (default) - Best overall performance
- **NAdam** - Strong on QAOA problems
- **AMSGrad** - May outperform on VQE simulation
- **LAMB** - High improvement potential, less stable
- **SGD** / **Momentum** - Simple baselines

### Disable Soft Algebra

For A/B testing against plain optimizers:

```python
# Plain Adam (no Soft Algebra)
opt = MobiuQCore(method="vqe", use_soft_algebra=False)
```

---

## 🧠 How It Works

### The Core Innovation: "Noise Hallucination" Prevention

Standard optimizers (Adam, SGD) assume lower objective values always indicate better solutions. In noisy environments—like NISQ processors or stochastic RL—this fails. Optimizers "tunnel" into noise, creating **Noise Hallucinations**.

**The Solution:** Soft Algebra cross-coupled state evolution:

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

Where:
- `a_t` (Potential): Curvature signal from energy history
- `b_t` (Realized): Actual improvement achieved
- `Δ†` (Super-Equation): Emergence detection for QAOA/RL

A parameter update is only committed if the *Potential Field* is validated by *Realized Improvement*.

### Method-Specific Logic

| Method | Primary Mechanism | Best For |
|--------|-------------------|----------|
| VQE | Trust Ratio + Gradient Warping | Smooth energy landscapes |
| QAOA | Super-Equation Δ† | Rugged, multimodal landscapes |
| RL | Trust + Emergence + Warping | High-variance, sparse rewards |

---

## 📊 When to Use Mobiu-Q

✅ **Use Mobiu-Q when:**
- High noise/variance (quantum hardware, RL, stochastic finance)
- Rugged landscapes with many local minima
- Expensive function evaluations
- Standard optimizers diverge or get stuck

❌ **Skip Mobiu-Q when:**
- Clean, convex problems (vanilla SGD is fine)
- Deterministic, low-noise environments
- Very low variance settings

---

## 🔑 Pricing

| Tier | Runs/Month | Features |
|------|------------|----------|
| **Free** | 20 | Testing & students |
| **Pro** | Unlimited | Priority processing, all features |

**[Get your License Key](https://app.mobiu.ai)**

---

## 📚 API Reference

### MobiuQCore

```python
MobiuQCore(
    license_key: str,           # Your license key
    method: str = "vqe",        # "vqe", "qaoa", or "rl"
    mode: str = "simulation",   # "simulation" or "hardware"
    base_lr: float = None,      # Learning rate (auto if None)
    base_optimizer: str = "Adam",  # Optimizer choice
    use_soft_algebra: bool = True, # Enable/disable SA
    offline_fallback: bool = True  # Fallback to local Adam
)
```

**Methods:**
- `step(params, gradient, energy)` → Updated params
- `new_run()` → Reset for new seed (same session)
- `end()` → End session (counts usage)
- `check_usage()` → Get remaining runs

### Demeasurement

```python
# For VQE (smooth landscapes)
grad = Demeasurement.finite_difference(energy_fn, params)
grad = Demeasurement.parameter_shift(circuit_fn, params)

# For QAOA/hardware (noisy)
grad, energy = Demeasurement.spsa(energy_fn, params)
```

---

## 🔬 Citation

If you use Mobiu-Q in research:

```bibtex
@software{mobiu_q,
  title = {Mobiu-Q: Soft Algebra Optimizer for Stochastic Systems},
  author = {Mobiu Technologies},
  year = {2024},
  url = {https://mobiu.ai}
}
```

---

*Proprietary technology. All rights reserved by Mobiu Technologies.*
