# Mobiu-Q v3.2.1

**Soft Algebra for Optimization & Attention**

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

---

## Overview

Mobiu-Q is a framework built on **Soft Algebra** (nilpotent ε²=0) that provides:

1. **MobiuOptimizer** - Stable optimization in noisy environments
2. **MobiuAttention** 🧪 - O(N) linear attention for long sequences

Both share the same mathematical foundation but serve different purposes.

---

## Installation

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

---

## Quick Start

### MobiuOptimizer (Stable API)

```python
from mobiu_q import MobiuOptimizer
import torch

# Your license key (get one at https://app.mobiu.ai)
LICENSE_KEY = "your-license-key-here"

# Wrap any PyTorch optimizer
model = MyModel()
base_opt = torch.optim.Adam(model.parameters(), lr=0.0003)
opt = MobiuOptimizer(
    base_opt,
    license_key=LICENSE_KEY,
    method="adaptive",
    use_soft_algebra=True
)

for batch in dataloader:
    loss = criterion(model(batch))
    loss.backward()
    opt.step(loss.item())  # Pass loss for Soft Algebra

opt.end()  # Important: release resources
```

### 🆕 AUTO Mode - Don't Know Which Method to Use?

```python
from mobiu_q import MobiuOptimizer

# Let Mobiu-Q choose automatically!
opt = MobiuOptimizer(base_opt, license_key=LICENSE_KEY, method="auto")

for batch in dataloader:
    loss = criterion(model(batch))
    loss.backward()
    opt.step(loss.item())

print(f"Selected mode: {opt.current_mode}")  # boost, dampen, or off
opt.end()
```

**Results:** ~35% average improvement, 0% hurts across 7 domains!

---

## License Key

MobiuOptimizer requires a license key to access the cloud API:

```python
from mobiu_q import MobiuOptimizer

LICENSE_KEY = "your-license-key-here"

# PyTorch mode (pass optimizer)
opt = MobiuOptimizer(base_opt, license_key=LICENSE_KEY, method="adaptive")

# Quantum/NumPy mode (pass params array)
opt = MobiuOptimizer(params, license_key=LICENSE_KEY, method="standard")
```

**Get your key:** https://app.mobiu.ai

| Tier | API Calls | Price |
|------|-----------|-------|
| Free | 20/month | $0 |
| Pro | Unlimited | $19/month |

**Note:** MobiuAttention and AUTO mode run locally and do NOT require API calls for each step.

---

## Methods

| Method     | Use Case                                    | Default LR |
|------------|---------------------------------------------|------------|
| `auto` 🆕  | **Don't know? Use this!** Auto-selects best | 0.01       |
| `auto-safe` 🆕 | Safer auto with DecayBoost             | 0.01       |
| `standard` | Smooth landscapes, chemistry, physics       | 0.01       |
| `deep`     | Deep circuits, noisy hardware, complex opt  | 0.1        |
| `adaptive` | RL, LLM fine-tuning, high-variance problems | 0.0003     |

### 🆕 AUTO Mode Details

AUTO mode runs 3 virtual optimizers in parallel and picks the winner:

| Mode | Description | When It Wins |
|------|-------------|--------------|
| `boost` | Higher LR when making progress | Biased gradients (Federated, Imbalanced) |
| `dampen` | Lower LR when gradients noisy | High variance, oscillations |
| `off` | Standard Adam | Clean problems |

```python
# Maximum improvement (~35% avg)
opt = MobiuOptimizer(base_opt, method="auto")

# Safer, more conservative (~20% avg, fewer hurts)
opt = MobiuOptimizer(base_opt, method="auto-safe")
```

#### AUTO with Maximize (RL / Trading)

AUTO mode supports both minimization and maximization:

```python
# Loss minimization (default) - VQE, supervised learning
opt = MobiuOptimizer(base_opt, method="auto")
opt.step(loss.item())

# Reward maximization - RL, trading
opt = MobiuOptimizer(base_opt, method="auto", maximize=True)
opt.step(episode_return)
```

#### How AUTO Differs from Other Methods

| Feature | `standard`/`deep`/`adaptive` | `auto` |
|---------|------------------------------|--------|
| Uses Frustration Engine | ✅ Yes | ❌ No |
| Uses Cloud API | ✅ Yes | ❌ No (local) |
| Adapts LR | Fixed strategy | Picks best strategy |
| Extra latency | ~1ms per sync | Zero |

**Why no Frustration Engine in AUTO?**

They solve the same problem differently:
- **Frustration Engine**: Reactive - detects stagnation, then boosts LR ×3
- **AUTO**: Proactive - continuously picks the best LR strategy

Using both together could cause conflicts (both trying to adjust LR).

**Benchmark (7 domains, 30 seeds each):**

| Domain | AUTO | AUTO-Safe |
|--------|------|-----------|
| Federated Learning | +40.8% | +22.4% |
| Noisy Labels | +22.6% | +14.3% |
| Sim-to-Real | +28.0% | +16.9% |
| Imbalanced Data | +27.8% | +17.0% |
| Meta-Learning | +42.7% | +22.8% |
| GAN Training | +42.6% | +23.0% |
| Clean | +43.9% | +23.2% |
| **Hurts** | **0/210** | **0/210** |

---

## Benchmarks

### Reinforcement Learning & Trading

| Domain                  | Improvement | Win Rate | p-value |
|-------------------------|-------------|----------|---------|
| Crypto Trading          | **+56%** profit | 100% | <0.001  |
| LunarLander-v3          | +128%       | 97%      | <0.001  |
| MuJoCo InvertedPendulum | +111%       | 100%     | <0.001  |

### Quantum Computing

| Domain                  | Improvement | Win Rate | p-value |
|-------------------------|-------------|----------|---------|
| VQE H₂ (FakeFez)        | +52%        | 100%     | <0.001  |
| QAOA MaxCut             | +45%        | 95%      | <0.001  |

### Noisy & Distributed Learning

| Domain              | Improvement | Win Rate | p-value | Bias Source |
|---------------------|-------------|----------|---------|-------------|
| Federated Learning  | **+67%**    | 100%     | <0.001  | Non-IID client data |
| Imbalanced Data     | **+52%**    | 100%     | <0.001  | Majority class dominates |
| Sim-to-Real         | **+47%**    | 100%     | <0.001  | Simulator ≠ reality |
| Noisy Labels        | **+40%**    | 100%     | <0.001  | Systematic mislabeling |

---

## Monitoring Training

```python
opt = MobiuOptimizer(base_opt, license_key=LICENSE_KEY, method="adaptive")
# ... training ...

# Track metrics
print(opt.lr_history)      # Learning rates over time
print(opt.warp_history)    # Gradient warp factors
print(opt.current_mode)    # AUTO mode selection (if using auto)
```

---

## Maximize vs Minimize

By default, Mobiu-Q assumes you're **minimizing** (loss, energy). For RL/Trading where you **maximize** (reward, profit), set `maximize=True`:

```python
LICENSE_KEY = "your-license-key-here"

# Loss minimization (default) - for supervised learning, VQE
opt = MobiuOptimizer(base_opt, license_key=LICENSE_KEY, method="adaptive")
opt.step(loss.item())

# Reward maximization - for RL, trading
opt = MobiuOptimizer(base_opt, license_key=LICENSE_KEY, method="adaptive", maximize=True)
opt.step(episode_return)
```

---

## A/B Testing

```python
LICENSE_KEY = "your-license-key-here"

# Test with Soft Algebra
opt_on = MobiuOptimizer(base_opt, license_key=LICENSE_KEY, use_soft_algebra=True)

# Test without (baseline)
opt_off = MobiuOptimizer(base_opt, license_key=LICENSE_KEY, use_soft_algebra=False)
```

---

## Examples by Domain

### 🆕 AUTO Mode (Recommended for New Users)

```python
from mobiu_q import MobiuQCore
import numpy as np

LICENSE_KEY = "your-license-key-here"

# Don't know which method? Use AUTO!
params = np.random.randn(20)
opt = MobiuQCore(license_key=LICENSE_KEY, method="auto")

def energy_fn(p):
    return np.sum(p ** 2)  # Your loss function

for step in range(100):
    params = opt.step(params, energy_fn)
    
    if step % 20 == 0:
        print(f"Step {step}: energy={energy_fn(params):.4f}, mode={opt.current_mode}")

opt.end()
```

### Federated Learning

```python
import numpy as np
from mobiu_q import MobiuOptimizer

LICENSE_KEY = "your-license-key-here"

# Simulate federated aggregation with non-IID clients
class FederatedTrainer:
    def __init__(self, n_clients=10, non_iid_strength=0.5):
        self.n_clients = n_clients
        self.non_iid = non_iid_strength
        self.client_biases = [np.random.randn(dim) * non_iid_strength 
                             for _ in range(n_clients)]
    
    def aggregate_gradients(self, params, sampled_clients):
        grads = []
        for c in sampled_clients:
            local_grad = compute_gradient(params) + self.client_biases[c]
            grads.append(local_grad)
        return np.mean(grads, axis=0)

params = np.random.randn(100)
opt = MobiuOptimizer(
    params,
    license_key=LICENSE_KEY,
    method="standard",  # or "auto"!
    base_lr=0.01
)

for round in range(100):
    clients = np.random.choice(n_clients, size=5, replace=False)
    gradient = trainer.aggregate_gradients(params, clients)
    loss = compute_global_loss(params)
    params = opt.step(params, gradient, loss)

opt.end()
```

### Reinforcement Learning (REINFORCE)

```python
import torch
import gymnasium as gym
from mobiu_q import MobiuOptimizer

LICENSE_KEY = "your-license-key-here"

policy = torch.nn.Sequential(
    torch.nn.Linear(8, 64), torch.nn.Tanh(),
    torch.nn.Linear(64, 64), torch.nn.Tanh(),
    torch.nn.Linear(64, 4)
)

base_opt = torch.optim.Adam(policy.parameters(), lr=3e-4)
opt = MobiuOptimizer(
    base_opt,
    license_key=LICENSE_KEY,
    method="adaptive",
    maximize=True,
    sync_interval=50,
    verbose=True
)

env = gym.make("LunarLander-v3")

for episode in range(1000):
    state, _ = env.reset()
    log_probs, rewards = [], []
    
    done = False
    while not done:
        logits = policy(torch.FloatTensor(state))
        dist = torch.distributions.Categorical(logits=logits)
        action = dist.sample()
        log_probs.append(dist.log_prob(action))
        state, reward, terminated, truncated, _ = env.step(action.item())
        rewards.append(reward)
        done = terminated or truncated
    
    # REINFORCE update
    returns = []
    G = 0
    for r in reversed(rewards):
        G = r + 0.99 * G
        returns.insert(0, G)
    returns = torch.tensor(returns)
    returns = (returns - returns.mean()) / (returns.std() + 1e-8)
    
    loss = sum(-lp * G for lp, G in zip(log_probs, returns))
    
    opt.zero_grad()
    loss.backward()
    opt.step(sum(rewards))

opt.end()
```

### Quantum Chemistry (VQE with Qiskit)

```python
import numpy as np
from qiskit.circuit.library import EfficientSU2
from qiskit.quantum_info import SparsePauliOp
from qiskit_aer import AerSimulator
from qiskit.primitives import BackendEstimatorV2
from mobiu_q import MobiuOptimizer

LICENSE_KEY = "your-license-key-here"

hamiltonian = SparsePauliOp.from_list([
    ("II", -0.4804), ("ZZ", 0.3435), ("ZI", -0.4347),
    ("IZ", 0.5716), ("XX", 0.0910), ("YY", 0.0910)
])

backend = AerSimulator()
estimator = BackendEstimatorV2(backend=backend)
estimator.options.default_shots = 4096

ansatz = EfficientSU2(2, reps=2, entanglement="linear")
params = np.random.uniform(-0.3, 0.3, ansatz.num_parameters)

opt = MobiuOptimizer(
    params,
    license_key=LICENSE_KEY,
    method="standard",  # or "auto"!
    mode="hardware",
    use_soft_algebra=True
)

for step in range(100):
    delta = np.random.choice([-1, 1], size=len(params))
    shift = 0.1
    
    job = estimator.run([
        (ansatz, hamiltonian, params),
        (ansatz, hamiltonian, params + shift * delta),
        (ansatz, hamiltonian, params - shift * delta)
    ])
    results = job.result()
    
    energy = float(results[0].data.evs)
    grad = (float(results[1].data.evs) - float(results[2].data.evs)) / (2 * shift) * delta
    
    params = opt.step(params, grad, energy)

opt.end()
print(f"Final energy: {energy:.4f}")
```

---

## Base Optimizers

| Optimizer | Description | Best For |
|-----------|-------------|----------|
| `Adam` | Adaptive moments | Default, most cases |
| `AdamW` | Adam with weight decay | LLM, Transformers |
| `NAdam` | Adam with Nesterov | Alternative to Adam |
| `AMSGrad` | Adam with stability | Drug discovery |
| `SGD` | Simple gradient descent | QAOA, convex |
| `Momentum` | SGD with momentum | RL, LLM fine-tuning |
| `LAMB` | Layer-wise adaptive | Large batch |

---

## 🛠️ Troubleshooting

### 1. Don't Know Which Method to Use?

```python
# Just use AUTO!
opt = MobiuOptimizer(base_opt, method="auto")
```

### 2. Switch Base Optimizer

| Problem Type | Recommended |
|--------------|-------------|
| LoRA / LLM | `Momentum` or `AdamW` |
| VQE / Chemistry | `Adam` |
| QAOA | `NAdam` |
| RL / Trading | `Momentum` |
| Drug Discovery | `AMSGrad` |

### 3. Adjust Learning Rate

```python
# Try lower LR if diverging
base_opt = torch.optim.Adam(model.parameters(), lr=0.0001)

# Try higher LR if stuck
base_opt = torch.optim.Adam(model.parameters(), lr=0.001)
```

---

## MobiuAttention 🧪

### Why?

Standard Transformer attention is O(N²). MobiuAttention is **O(N)**.

| Seq Length | Transformer | MobiuAttention | Speedup |
|------------|-------------|----------------|---------|
| 2,048      | 21s         | 9s             | 2.3x    |
| 4,096      | 39s         | 10s            | 3.9x    |
| 8,192      | 42s         | 7s             | 6.0x    |
| 16,384     | **OOM** 💥  | 5s ✅          | ∞       |

### Usage

```python
from mobiu_q.experimental import MobiuBlock

# No license key needed - runs locally!
class LongContextLM(nn.Module):
    def __init__(self, vocab, d=512, h=8, layers=6):
        super().__init__()
        self.embed = nn.Embedding(vocab, d)
        self.blocks = nn.Sequential(*[MobiuBlock(d, h) for _ in range(layers)])
        self.head = nn.Linear(d, vocab)
    
    def forward(self, x):
        return self.head(self.blocks(self.embed(x)))

# Works with 16K+ tokens!
model = LongContextLM(50000)
x = torch.randint(0, 50000, (1, 16384))
out = model(x)  # No OOM!
```

---

## Full Examples

| File | Domain | Description |
|------|--------|-------------|
| `test_lunarlander_hybrid.py` | RL | LunarLander with REINFORCE |
| `test_mujoco_maximize.py` | RL | MuJoCo continuous control |
| `ppo_mobiu_test.py` | RL | PPO from scratch |
| `crypto_trading_benchmark.py` | Trading | Crypto with regime switching |
| `test_fakefez_h2.py` | VQE | H₂ molecule on FakeFez |
| `test_fakefez_qaoa.py` | QAOA | MaxCut optimization |
| `test_federated_fair.py` | FL | Federated learning |
| `test_noisy_labels_fair.py` | Noisy | Noisy labels |
| `test_sim_to_real_fair.py` | Robotics | Sim-to-real |
| `test_imbalanced_fair.py` | Classification | Imbalanced data |

---

## License

| Tier | API Calls | Price | Get Started |
|------|-----------|-------|-------------|
| Free | 20/month | $0 | [Sign up](https://app.mobiu.ai) |
| Pro | Unlimited | $19/month | [Get one](https://app.mobiu.ai) |

**Note:** MobiuAttention and AUTO mode run locally, no API calls required.

---

## Links

- [PyPI](https://pypi.org/project/mobiu-q/)
- [GitHub](https://github.com/mobiuai/mobiu-q/)

---

## Citation

```bibtex
@software{mobiu_q,
  title={Mobiu-Q: Soft Algebra for Optimization and Attention},
  author={Mobiu Technologies},
  year={2026},
  url={https://mobiu.ai}
}
```