mobiu-q 2.4.1__tar.gz

mobiu_q-2.4.1/PKG-INFO

@@ -0,0 +1,383 @@
+Metadata-Version: 2.4
+Name: mobiu-q
+Version: 2.4.1
+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.1)
+
+**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
+```
+
+### 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** - 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)
+```
+
+---
+
+## 💡 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.*