Metadata-Version: 2.4
Name: mobiu-q
Version: 2.4.2
Summary: Soft Algebra Optimizer for Quantum & Complex Optimization
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"

# Mobiu-Q (v2.4.2)

**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 | Best Optimizer |
|---------|-------------|----------------|
| Rosenbrock Valley | +75.8% | Adam+SA |
| Credit Risk (VaR) | +52.3% | Adam+SA |
| Portfolio Optimization | +51.7% | Adam+SA |
| Ackley Function | +86.3% | **AMSGrad+SA** |

---

## 📦 Installation

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

### Verify Installation

Download our test suite to verify everything works:

```bash
# Quick verification (7 tests, ~2 min)
python test_quickstart.py

# Full test suite (21 tests, ~15 min)  
pytest test_mobiu_q_customer.py -v

# Benchmark with statistics
python benchmark_mobiu_q.py --seeds 10
```

Test files available at: [github.com/mobiuai/mobiu-q/examples](https://github.com/mobiuai/mobiu-q/tree/main/examples)

---

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

For real quantum hardware, use `mode="hardware"` and SPSA:
```python
opt = MobiuQCore(license_key="YOUR-KEY", method="vqe", mode="hardware")

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

opt.end()
```

### 2. QAOA (Combinatorial Optimization)

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

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

opt.end()
```

For hardware: `mode="hardware"`

### 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` | Simulated VQE (you control noise) | 0.01 |
| `vqe` | `hardware` | Real quantum hardware / FakeBackend | 0.02 |
| `qaoa` | `simulation` | Simulated QAOA (you control noise) | 0.1 |
| `qaoa` | `hardware` | Real quantum hardware / FakeBackend | 0.1 |
| `rl` | (ignored) | Reinforcement learning | 0.0003 |

> **When to use `hardware` mode:** Use when running on real quantum devices (IBM, IonQ, etc.) 
> or Qiskit FakeBackends. The optimizer uses higher learning rate to compensate for hardware noise.

### 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** - Best for multimodal functions (Ackley: +86%)
- **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)
```

---

## 💡 Best Practices

### Simulation vs Hardware

**Simulation (clean analytical functions):**
```python
opt = MobiuQCore(method="vqe", mode="simulation")

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

**Hardware (Qiskit FakeBackend / real quantum device):**
```python
opt = MobiuQCore(method="vqe", mode="hardware")

for step in range(100):
    grad, energy = Demeasurement.spsa(run_circuit, params)
    params = opt.step(params, grad, energy)
```

The noise comes from the device - you don't add it yourself.

### Recommended Steps

| Problem Type | Recommended Steps |
|--------------|-------------------|
| VQE (2-4 params) | 60-100 |
| VQE (8+ params) | 150-200 |
| QAOA (p=2-5) | 150-200 |
| RL (LunarLander) | 500-1000 episodes |

### When Optimization Fails

1. **Check mode matches your environment:**
   - `mode="simulation"` → Clean simulation only (no added noise)
   - `mode="hardware"` → Real quantum hardware or noisy simulation (FakeBackend)
   - Using the wrong mode will give poor results!

2. **Try a different base optimizer:**
   - Before adjusting learning rate, try: `base_optimizer="NAdam"` or `"AMSGrad"`
   - Different optimizers work better for different problems
   - Mobiu-Q wraps these optimizers with Soft Algebra

3. **Don't mix methods with wrong problem types:**
   - Use `method="vqe"` for VQE/chemistry problems
   - Use `method="qaoa"` for QAOA/combinatorial problems
   - Mixing them (e.g., QAOA method for VQE problem) may not work well

4. **Verify your problem setup:**
   - Check Hamiltonian coefficients are correct
   - Verify ground state energy is computed correctly
   - Ensure ansatz can actually reach the ground state
   - Test with a simple grid search first

---

## 🔬 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.*
