Metadata-Version: 2.4
Name: mobiu-q
Version: 2.4.3
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.3)

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

[![PyPI version](https://badge.fury.io/py/mobiu-q.svg)](https://badge.fury.io/py/mobiu-q)
[![License](https://img.shields.io/badge/License-Proprietary-blue)](https://mobiu.ai)

**Mobiu-Q** is the first optimizer based on **Soft Algebra**, developed by Dr. Moshe Klein and Prof. Oded Maimon. 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 **LLM Fine-Tuning**.

---

## 🚀 What's New in v2.4.3

- **Comprehensive Benchmark Validation**: 17 problems tested with statistical significance
- **IBM FakeFez Validation**: +50.9% on VQE, +16.1% on QAOA with real noise models
- **LLM Soft Prompt Tuning**: Optimize soft prompts for language models

---

## 🏆 Benchmark Results (v2.4.3)

### Quantum Computing - IBM FakeFez (Real Noise Model)

| Problem | Improvement | p-value | Win Rate |
|---------|-------------|---------|----------|
| **VQE H2 Molecule** | **+50.9%** | 0.0334 | 5/5 ✅ |
| **QAOA MaxCut 5q** | **+16.1%** | 0.0029 | 9/10 ✅ |

### Quantum Chemistry (Simulation)

| Molecule | Improvement | Significant |
|----------|-------------|-------------|
| H2 | +46.6% | ✅ |
| LiH | +41.4% | ✅ |
| BeH2 | +37.8% | ✅ |
| He Atom | +51.2% | ✅ |
| H3+ Chain | +42.0% | ✅ |

### Condensed Matter Physics

| Model | Improvement | Significant |
|-------|-------------|-------------|
| Heisenberg XXZ | +20.8% | ✅ |
| Transverse Ising | +42.0% | ✅ |
| XY Model | +60.8% | ✅ |
| Ferromagnetic Ising | +45.1% | ✅ |
| Hubbard Dimer | +14.1% | ✅ |

### Classical Optimization

| Problem | Improvement |
|---------|-------------|
| Rosenbrock | +65.5% |

### QAOA (Simulation with noise=0.1)

| Problem | Improvement | Win Rate | p-value |
|---------|-------------|----------|---------|
| MaxCut 4 qubits | +27.2% | 7/10 | 0.0414 ✅ |
| MaxCut 5 qubits | +23.7% | 9/10 | 0.0036 ✅ |
| MaxCut p=3 | +15.6% | 9/10 | 0.0083 ✅ |

---

## 📦 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

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

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. 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

⚠️ **Optimizer names are case-sensitive!**

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

# Alternative optimizer - note exact case!
opt = MobiuQCore(method="qaoa", base_optimizer="NAdam")
```

Available optimizers (exact names):
- `Adam` (default) - Best overall performance
- `NAdam` - Strong on QAOA problems
- `AMSGrad` - Alternative for VQE
- `SGD` - Simple baseline
- `Momentum` - SGD with momentum
- `LAMB` - Large batch training

### 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, developed by Dr. Moshe Klein and Prof. Oded Maimon, uses 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*.

### SoftNumber Multiplication

The core of Soft Algebra uses nilpotent arithmetic (ε²=0):

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

This allows gradients to carry both magnitude and uncertainty information.

### 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",  # Case-sensitive! Adam, NAdam, AMSGrad, SGD, Momentum, LAMB
    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)
```

---

## 🔬 Scientific Foundation

Mobiu-Q is based on **Soft Algebra**, developed by:

- **Dr. Moshe Klein** - Mathematician, developer of Soft Logic and Soft Numbers
- **Prof. Oded Maimon** - Tel Aviv University, Industrial Engineering

The theoretical foundations combine:
- Nilpotent arithmetic (ε²=0)
- Cross-coupled dynamical systems
- Information-theoretic trust measures

---

## 📖 Citation

If you use Mobiu-Q in research:

```bibtex
@software{mobiu_q,
  title = {Mobiu-Q: Soft Algebra Optimizer for Stochastic Systems},
  author = {Angel, Ido and Klein, Moshe and Maimon, Oded},
  year = {2024},
  url = {https://mobiu.ai}
}
```

---

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