Metadata-Version: 2.4
Name: mobiu-q
Version: 1.0.4
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

**Mobiu-Q** is a next-generation optimizer built on *Soft Algebra* and *Demeasurement* theory, enabling stable and efficient optimization in quantum variational algorithms (VQE, QAOA).

### ✨ Features
- Soft Algebra update rule for stable convergence  
- SPSA Demeasurement for noisy hardware  
- Adaptive "Noisy Mode" presets
- **Validated on real quantum hardware (IBM)**

---

## 📦 Installation
```bash
pip install mobiu-q
```

## 🔑 License
```python
from mobiu_q import activate_license

activate_license("YOUR-LICENSE-KEY")
```
- **Free tier:** 5 runs/month
- **Pro tier:** Unlimited runs

---

## 🚀 Quick Start (Simulation)
Best for clean simulations or statevector backends.

```python
import numpy as np
from mobiu_q import MobiuQCore, Demeasurement, get_energy_function

energy_fn = get_energy_function("h2_molecule")

# Initialize in standard mode
opt = MobiuQCore(mode="standard") 

params = np.random.uniform(-np.pi, np.pi, 6)

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

opt.end()  # End session
```

## ⚡ Real Hardware / Shot Noise
When running on noisy quantum computers (IBM, IonQ) or simulators with shot noise:

```python
# Initialize in noisy mode (robust learning)
opt = MobiuQCore(mode="noisy") 

for step in range(100):
    # SPSA returns gradient AND energy estimate (saves 50% measurements)
    grad, E = Demeasurement.spsa(energy_fn, params, c_shift=0.1)
    params = opt.step(params, grad, E)

opt.end()
```

---

## 📊 Performance Results

### Clean Simulation
Tested on H2 molecule (6 params), 100 seeds:

| Optimizer | Gap to Ground State | Improvement |
|-----------|---------------------|-------------|
| Adam | 0.089 | - |
| **Mobiu-Q** | **0.034** | **+62%** ✅ |

### Shot Noise Simulation
Tested on Transverse Ising (4 qubits), 30 seeds:

| Shots | Adam Gap | Mobiu-Q Gap | Improvement | p-value |
|-------|----------|-------------|-------------|---------|
| 1000 | 1.63 | 1.48 | +9.2% | 0.002 ✅ |
| 500 | 1.65 | 1.49 | +9.8% | 0.002 ✅ |
| 50 | 2.00 | 1.82 | +9.2% | 0.009 ✅ |

### Real Quantum Hardware (IBM Fez)
H2 molecule optimization:

| Metric | Result |
|--------|--------|
| Initial gap | 0.22 |
| **Final gap** | **0.034** |
| Improvement | **85%** ✅ |

---

## 💡 Choosing the Right Mode

| Scenario | Mode | Gradient Method |
|----------|------|-----------------|
| Clean simulation (statevector) | `standard` | `finite_difference` |
| Shot noise simulation | `noisy` | `spsa` |
| Real quantum hardware | `noisy` | `spsa` |

### Mode Settings

| Mode | Learning Rate | Best For |
|------|---------------|----------|
| `standard` | 0.05 | Simulators (Qiskit Aer, PennyLane, Cirq) |
| `noisy` | 0.02 | Real hardware (IBM, IonQ, Rigetti) |

---

## 📚 Built-in Problems

```python
from mobiu_q import list_problems, get_energy_function, get_ground_state_energy

print(list_problems())
# ['h2_molecule', 'lih_molecule', 'transverse_ising', 'heisenberg_xxz', ...]

energy_fn = get_energy_function("h2_molecule")
E0 = get_ground_state_energy("h2_molecule")
```

---

## ⚙️ API Reference

### MobiuQCore

```python
MobiuQCore(
    license_key=None,       # Your license key (or use activate_license())
    mode="standard",        # 'standard' or 'noisy'
    base_lr=None,           # Custom learning rate (overrides mode)
    verbose=True            # Print session messages
)
```

**Methods:**
- `step(params, gradient, energy)` → updated params
- `end()` → close session

### Demeasurement

```python
# For clean simulations (2*N function calls)
grad = Demeasurement.finite_difference(fn, params)

# For noisy environments (only 2 function calls!)
grad, energy = Demeasurement.spsa(fn, params, c_shift=0.1)
```

---

## 🔥 Full Example: IBM Hardware

```python
from qiskit_ibm_runtime import QiskitRuntimeService, EstimatorV2
from mobiu_q import MobiuQCore, Demeasurement

service = QiskitRuntimeService(channel="ibm_quantum")
backend = service.least_busy(simulator=False, min_num_qubits=5)
estimator = EstimatorV2(mode=backend)

opt = MobiuQCore(mode="noisy")

for step in range(60):
    grad, energy = Demeasurement.spsa(
        lambda p: estimator.run([(circuit, observable)]).result()[0].data.evs.item(),
        params,
        c_shift=0.12
    )
    params = opt.step(params, grad, energy)

opt.end()
```

---

© Mobiu Technologies, 2025
