mobiu-q 4.4.2

Soft Algebra Optimizer + O(N) Linear Attention + Streaming Anomaly Detection

Mobiu-Q v4.4.2

Soft Algebra for Optimization & Attention

---

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
3. MobiuSignal 🆕 - Trading signals using Soft Algebra
4. MobiuAD - Streaming anomaly detection
5. TrainGuard - Safe ML training monitor

---

Installation

pip install mobiu-q

---

Quick Start

MobiuOptimizer (Stable API)

from mobiu_q import MobiuOptimizer, MobiuAD, TrainGuard
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())
opt = MobiuOptimizer(
    base_opt,
    license_key=LICENSE_KEY,
    method="adaptive",  # LR auto-set to 0.0003
    use_soft_algebra=True
)

# Or with explicit LR:
opt = MobiuOptimizer(
    base_opt,
    license_key=LICENSE_KEY,
    method="standard",
    base_lr=0.001  # Override default LR
)

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

opt.end()  # Important: release resources

Monitoring Training

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 (new in v3.1.3)

MobiuAttention (🧪 Experimental)

from mobiu_q.experimental import MobiuAttention, MobiuBlock

# Drop-in replacement for nn.MultiheadAttention
# Note: MobiuAttention runs locally, no license key needed!
attn = MobiuAttention(d_model=512, num_heads=8)
out = attn(x)  # x: [batch, seq, dim]

# Or use complete block
block = MobiuBlock(d_model=512, num_heads=8)
out = block(x)

MobiuAD (🆕 NEW in v3.9.0)

from mobiu_q import MobiuAD, TrainGuard

LICENSE_KEY = "your-license-key-here"

# Streaming anomaly detection
detector = MobiuAD(license_key=LICENSE_KEY)
result = detector.detect(value)

# Training monitor (Q + AD combined)
guard = TrainGuard(license_key=LICENSE_KEY)
result = guard.step(loss, gradient, val_loss)

MobiuSignal (🆕 NEW in v3.10.0)

from mobiu_q.signal import MobiuSignal

# No license required - runs locally!
signal = MobiuSignal(lookback=20)

# Compute signal from prices
result = signal.compute(prices)
if result.is_strong:
    print(f"Strong {'📈' if result.is_bullish else '📉'} signal: {result.magnitude:.2f}")

# Backtest on historical data
backtest = signal.backtest(historical_prices, future_window=5)
print(f"Correlation: {backtest.correlation:.3f}")
print(f"Q4/Q1 Ratio: {backtest.q4_q1_ratio:.2f}x")

---

License Key

MobiuOptimizer requires a license key to access the cloud API:

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 runs locally and does NOT require a license key.

---

MobiuOptimizer

Methods

Method	Use Case	Default LR
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

Note: Default LR is auto-applied in PyTorch mode. Override with base_lr=... if needed.

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
RL Trading (MobiuSignal)	+168%	83%	<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 🆕

These domains have systematic gradient bias - exactly where Soft Algebra excels:

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

All tests: 10 seeds, same energy & gradient for both, only use_soft_algebra differs

Why Soft Algebra Works Here

In these domains, the gradient is systematically biased:

• Federated: Each client sees different data distribution
• Imbalanced: Gradient dominated by majority class
• Sim-to-Real: Simulator has wrong physics parameters
• Noisy Labels: Labels consistently confused (e.g., 3↔8)

Soft Algebra detects the gap between gradient direction and actual loss improvement, then corrects for it.

Maximize vs Minimize

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

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)

Use Case	maximize=	Example
Supervised Learning	False (default)	opt.step(loss.item())
VQE / QAOA	False (default)	opt.step(energy)
RL (policy gradient)	True	opt.step(episode_return)
Trading	True	opt.step(profit)

Why does this matter? Soft Algebra tracks the "direction of improvement". Using the wrong setting confuses the optimizer.

A/B Testing

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

Federated Learning 🆕

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
        # Each client has biased local data
        self.client_biases = [np.random.randn(dim) * non_iid_strength 
                             for _ in range(n_clients)]
    
    def aggregate_gradients(self, params, sampled_clients):
        """Aggregate gradients from subset of clients (FedAvg style)"""
        grads = []
        for c in sampled_clients:
            # Each client's gradient is biased by their local data
            local_grad = compute_gradient(params) + self.client_biases[c]
            grads.append(local_grad)
        return np.mean(grads, axis=0)

# Mobiu-Q handles the systematic bias from non-IID aggregation
params = np.random.randn(100)
opt = MobiuOptimizer(
    params,
    license_key=LICENSE_KEY,
    method="standard",
    base_lr=0.01
)

for round in range(100):
    # Sample random clients (realistic FL scenario)
    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()

Imbalanced Data Classification 🆕

import torch
from mobiu_q import MobiuOptimizer

LICENSE_KEY = "your-license-key-here"

# Dataset with 90% class 0, 10% class 1 (fraud detection, medical diagnosis)
train_loader = create_imbalanced_loader(imbalance_ratio=0.9)

model = FraudDetector()
base_opt = torch.optim.Adam(model.parameters(), lr=0.001)
opt = MobiuOptimizer(
    base_opt,
    license_key=LICENSE_KEY,
    method="standard"
)

for batch in train_loader:
    # Gradient dominated by majority class
    loss = criterion(model(batch))
    loss.backward()
    
    # Soft Algebra corrects for class imbalance bias
    opt.step(loss.item())

opt.end()

Sim-to-Real Robotics 🆕

import torch
from mobiu_q import MobiuOptimizer

LICENSE_KEY = "your-license-key-here"

# Policy trained in simulator, deployed in real world
policy = RobotPolicy()
base_opt = torch.optim.Adam(policy.parameters(), lr=0.0003)
opt = MobiuOptimizer(
    base_opt,
    license_key=LICENSE_KEY,
    method="adaptive",
    maximize=True
)

for episode in range(1000):
    # Gradient from SIMULATOR (biased - wrong friction, mass, etc.)
    sim_loss = run_simulator_episode(policy)
    sim_loss.backward()
    
    # Periodically evaluate in REAL environment
    if episode % 10 == 0:
        real_reward = run_real_episode(policy)
    
    # Soft Algebra uses real reward to correct simulator bias
    opt.step(real_reward)

opt.end()

Noisy Labels 🆕

import torch
from mobiu_q import MobiuOptimizer

LICENSE_KEY = "your-license-key-here"

# Dataset with systematic label noise (crowdsourced, OCR errors)
# e.g., "3" often mislabeled as "8", "cat" confused with "dog"
train_loader = create_noisy_label_loader(noise_rate=0.3)

model = Classifier()
base_opt = torch.optim.Adam(model.parameters(), lr=0.001)
opt = MobiuOptimizer(
    base_opt,
    license_key=LICENSE_KEY,
    method="standard"
)

for batch_x, noisy_labels in train_loader:
    # Gradient points toward WRONG targets due to label noise
    loss = criterion(model(batch_x), noisy_labels)
    loss.backward()
    
    # Validate on clean held-out set
    clean_loss = evaluate_clean(model)
    
    # Soft Algebra detects mismatch and corrects
    opt.step(clean_loss)

opt.end()

Reinforcement Learning (REINFORCE)

import torch
import torch.nn.functional as F
import gymnasium as gym
from mobiu_q import MobiuOptimizer

LICENSE_KEY = "your-license-key-here"

# Simple policy network
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)
)

# Wrap optimizer with maximize=True for RL
base_opt = torch.optim.Adam(policy.parameters(), lr=3e-4)
opt = MobiuOptimizer(
    base_opt,
    license_key=LICENSE_KEY,
    method="adaptive",
    maximize=True,       # Important: RL maximizes reward!
    sync_interval=50,    # Sync with cloud every 50 steps
    verbose=True
)

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

for episode in range(1000):
    state, _ = env.reset()
    log_probs, rewards = [], []
    
    # Collect episode
    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))  # Pass episode return for Soft Algebra

opt.end()

Quantum Chemistry (VQE with Qiskit)

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"

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

# Setup
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)

# Optimizer (NumPy mode - auto-delegates to MobiuQCore)
opt = MobiuOptimizer(
    params,
    license_key=LICENSE_KEY,
    method="standard",
    mode="hardware",        # Use hardware mode for noisy backends
    use_soft_algebra=True
)

# VQE loop with SPSA gradient
for step in range(100):
    # SPSA gradient estimation (2 circuit evaluations)
    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
    
    # Update params via Mobiu-Q
    params = opt.step(params, grad, energy)
    
    if step % 20 == 0:
        print(f"Step {step}: energy = {energy:.4f}")

opt.end()
print(f"Final energy: {energy:.4f}")  # Should approach -1.85

Combinatorial Optimization (QAOA)

import numpy as np
from qiskit import QuantumCircuit
from qiskit_aer import AerSimulator
from mobiu_q import MobiuOptimizer

LICENSE_KEY = "your-license-key-here"

# MaxCut graph
edges = [(0, 1), (1, 2), (2, 3), (3, 0), (0, 2)]
n_qubits = 4
p = 2  # QAOA layers

def qaoa_circuit(params):
    gammas, betas = params[:p], params[p:]
    qc = QuantumCircuit(n_qubits)
    qc.h(range(n_qubits))
    for layer in range(p):
        for i, j in edges:
            qc.rzz(2 * gammas[layer], i, j)
        for i in range(n_qubits):
            qc.rx(2 * betas[layer], i)
    qc.measure_all()
    return qc

def evaluate(params, shots=1024):
    qc = qaoa_circuit(params)
    counts = AerSimulator().run(qc, shots=shots).result().get_counts()
    cost = 0
    for bitstring, count in counts.items():
        for i, j in edges:
            if bitstring[-(i+1)] != bitstring[-(j+1)]:
                cost += count
    return -cost / shots  # Negative for minimization

# Optimizer
params = np.random.uniform(-np.pi, np.pi, 2 * p)
opt = MobiuOptimizer(
    params,
    license_key=LICENSE_KEY,
    method="deep",
    mode="simulation"
)

for step in range(100):
    # SPSA gradient
    delta = np.random.choice([-1, 1], size=len(params))
    shift = 0.1
    e_plus = evaluate(params + shift * delta)
    e_minus = evaluate(params - shift * delta)
    energy = evaluate(params)
    grad = (e_plus - e_minus) / (2 * shift) * delta
    
    params = opt.step(params, grad, energy)
    
    if step % 20 == 0:
        print(f"Step {step}: MaxCut = {-energy:.2f}")

opt.end()
print(f"Final MaxCut value: {-energy:.2f}")

Trading / Finance

import torch
import numpy as np
from mobiu_q import MobiuOptimizer

LICENSE_KEY = "your-license-key-here"

# Simple trading policy: state → action probabilities
policy = torch.nn.Sequential(
    torch.nn.Linear(20, 64), torch.nn.ReLU(),
    torch.nn.Linear(64, 32), torch.nn.ReLU(),
    torch.nn.Linear(32, 3)  # Hold, Buy, Sell
)

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

# Training loop
for episode in range(500):
    state = get_market_state()  # Your market data
    log_probs, rewards = [], []
    
    for step in range(episode_length):
        logits = policy(torch.FloatTensor(state))
        dist = torch.distributions.Categorical(logits=logits)
        action = dist.sample()
        log_probs.append(dist.log_prob(action))
        
        state, reward = execute_trade(action.item())  # Your trading logic
        rewards.append(reward)
    
    # Policy gradient update
    returns = compute_returns(rewards, gamma=0.99)
    loss = sum(-lp * G for lp, G in zip(log_probs, returns))
    
    opt.zero_grad()
    loss.backward()
    opt.step(sum(rewards))  # Pass episode profit

opt.end()

Tip: For even better results, use MobiuSignal features as your state representation. See the MobiuSignal section for integration example.

---

Stable-Baselines3 (PPO, SAC, etc.)

SB3 calls optimizer.step() internally without arguments. Use set_metric() to provide the reward:

import gymnasium as gym
import numpy as np
from stable_baselines3 import PPO
from stable_baselines3.common.callbacks import BaseCallback
from mobiu_q import MobiuOptimizer

LICENSE_KEY = "your-license-key-here"

class MobiuSB3Callback(BaseCallback):
    """Callback that integrates Mobiu-Q with SB3."""
    
    def __init__(self, method="adaptive", use_soft_algebra=True, verbose=0):
        super().__init__(verbose=verbose)
        self.method = method
        self.use_soft_algebra = use_soft_algebra
        self._mobiu = None
        self._ep_returns = []
    
    def _on_training_start(self):
        base_opt = self.model.policy.optimizer
        self._mobiu = MobiuOptimizer(
            base_opt,
            license_key=LICENSE_KEY,
            method=self.method,
            use_soft_algebra=self.use_soft_algebra,
            maximize=True,
            sync_interval=50,
            verbose=True
        )
        # Replace SB3's optimizer
        self.model.policy.optimizer = self._mobiu
    
    def _on_step(self):
        for info in self.locals.get("infos", []):
            if "episode" in info:
                ep_return = info["episode"]["r"]
                self._ep_returns.append(ep_return)
                # Update metric with rolling average
                recent = self._ep_returns[-4:]
                self._mobiu.set_metric(np.mean(recent))
        return True
    
    def _on_training_end(self):
        if self._mobiu:
            self._mobiu.end()


# Usage
env = gym.make("LunarLander-v3")
model = PPO("MlpPolicy", env, learning_rate=3e-4, verbose=0)
model.learn(total_timesteps=200_000, callback=MobiuSB3Callback())

---

MobiuSignal 🆕

Trading signal generator using the same Soft Algebra potential/realized framework.

Validated Results (3,080 days BTC/USDT)

Metric	Result
Spearman correlation	+0.222 (p<0.0001)
Q4/Q1 ratio	1.83x larger moves
Precision lift	1.18x vs random

Mathematical Framework

Potential (aₜ) = σₜ/μₜ × scale    # Normalized volatility
Realized (bₜ)  = (Pₜ - Pₜ₋₁)/Pₜ₋₁  # Price change
Magnitude      = √(aₜ² + bₜ²)      # Signal strength

Usage

from mobiu_q.signal import MobiuSignal, SignalResult

# Basic usage
signal = MobiuSignal(lookback=20, vol_scale=100)
result = signal.compute(prices)

print(f"Potential: {result.potential:.3f}")
print(f"Realized: {result.realized:.3f}%")
print(f"Magnitude: {result.magnitude:.3f}")
print(f"Direction: {result.direction}")  # +1, -1, or 0
print(f"Quartile: Q{result.quartile}")   # 1-4 (4=strongest)

# Check signal strength
if result.is_strong:  # Top quartile
    if result.is_bullish:
        print("🚀 Strong bullish signal!")
    else:
        print("🔻 Strong bearish signal!")

Streaming Mode

signal = MobiuSignal(lookback=20)

for price in live_price_stream:
    result = signal.update(price)
    if result and result.is_strong:
        execute_trade(result.direction)

Backtesting

from mobiu_q.signal import MobiuSignal, backtest_signal

# Full backtest
signal = MobiuSignal(lookback=20)
result = signal.backtest(prices, future_window=5)

print(f"Total signals: {result.total_signals}")
print(f"Strong signals: {result.strong_signals}")
print(f"Correlation: {result.correlation:.3f} (p={result.correlation_pvalue:.4f})")
print(f"Q4/Q1 Ratio: {result.q4_q1_ratio:.2f}x")
print(f"Precision Lift: {result.precision_lift:.2f}x")

# Quick backtest
result = backtest_signal(prices, lookback=20, future_window=5)

Series Analysis

signal = MobiuSignal(lookback=20)
results = signal.compute_series(prices)

# Find all strong signals
strong = [r for r in results if r.is_strong]
print(f"Found {len(strong)} strong signals out of {len(results)}")

When to Use

Scenario	Recommendation
Day trading	lookback=10-20
Swing trading	lookback=20-50
High volatility	Lower vol_scale
Low volatility	Higher vol_scale

Note: MobiuSignal runs 100% locally - no API calls, no license key needed.

---

Integration with MobiuOptimizer (RL Trading)

Combine MobiuSignal features with MobiuOptimizer for RL-based trading:

from mobiu_q import MobiuOptimizer
from mobiu_q.signal import MobiuSignal
import torch
import torch.nn as nn

LICENSE_KEY = "your-license-key-here"

# Policy uses MobiuSignal features as state
class TradingPolicy(nn.Module):
    def __init__(self):
        super().__init__()
        self.net = nn.Sequential(
            nn.Linear(5, 64), nn.Tanh(),
            nn.Linear(64, 64), nn.Tanh(),
            nn.Linear(64, 3)  # Hold, Buy, Sell
        )
    
    def forward(self, signal_features):
        # signal_features: [potential, realized, magnitude, position, pnl]
        return self.net(signal_features)

# Setup
signal = MobiuSignal(lookback=20)
policy = TradingPolicy()
base_opt = torch.optim.Adam(policy.parameters(), lr=3e-4)
opt = MobiuOptimizer(
    base_opt,
    license_key=LICENSE_KEY,
    method="adaptive",
    maximize=True,  # Maximize profit!
    use_soft_algebra=True
)

# Training loop
for episode in range(500):
    signal.reset()
    # ... collect episode using signal.update(price) for state ...
    # ... REINFORCE update ...
    opt.step(episode_profit)

opt.end()

Validated Results (30 seeds, 500 episodes, regime switching):

Metric	Adam	Mobiu	Δ
Final PnL	-4.7	+3.2	+168.7%
Win Rate	-	83.3%	25/30 seeds
p-value	-	-	0.000012

Adam lost money on average; Mobiu turned it profitable.

See examples/rl_trading_mobiu_benchmark.py for full implementation.

---

Base Optimizers

PyTorch Mode

Use any PyTorch optimizer — Mobiu-Q wraps it with Soft Algebra. Your optimizer always runs; Mobiu-Q enhances it via adaptive learning rate and gradient warping:

# Any of these work — your optimizer actually runs:
base_opt = torch.optim.Adam(model.parameters(), lr=0.0003)
base_opt = torch.optim.AdamW(model.parameters(), lr=0.0003)
base_opt = torch.optim.SGD(model.parameters(), lr=0.02, momentum=0.9)
base_opt = torch.optim.NAdam(model.parameters(), lr=0.001)

# Even custom/external optimizers:
from muon import Muon
base_opt = Muon(model.parameters(), lr=0.02, momentum=0.95)

# Wrap with Mobiu-Q — your optimizer runs, SA enhances it:
opt = MobiuOptimizer(base_opt, license_key=LICENSE_KEY, method="adaptive")

Quantum/NumPy Mode

Server-side optimization with Adam + Soft Algebra. You provide params, gradient, and energy; Mobiu-Q returns optimized params:

opt = MobiuOptimizer(params, license_key=LICENSE_KEY, method="deep", mode="hardware")
params = opt.step(params, grad, energy)

---

🛠️ Troubleshooting

If optimization is not improving or diverging, try these adjustments:

1. Switch Base Optimizer (PyTorch mode)

Note: These recommendations apply to PyTorch mode where your optimizer runs directly. In Quantum/NumPy mode, the server handles optimization internally.

Different optimizers work better for different problems:

Problem Type	Recommended Optimizer
LoRA / LLM	torch.optim.SGD with momentum
VQE / Chemistry	torch.optim.Adam
QAOA	torch.optim.NAdam
RL / Trading	torch.optim.SGD with momentum
Drug Discovery	torch.optim.Adam(amsgrad=True)
Large Batch	LAMB (from apex or custom)
Federated Learning	torch.optim.Adam
Imbalanced Data	torch.optim.Adam
Sim-to-Real	torch.optim.Adam + adaptive
Noisy Labels	torch.optim.Adam

LICENSE_KEY = "your-license-key-here"

# PyTorch: If Adam isn't working, try Momentum:
base_opt = torch.optim.SGD(model.parameters(), lr=0.02, momentum=0.9)
opt = MobiuOptimizer(base_opt, license_key=LICENSE_KEY, method="adaptive")

2. Switch Method

If This Fails	Try This
standard	adaptive
adaptive	deep
deep	standard

# If standard isn't working for your problem:
opt = MobiuOptimizer(base_opt, license_key=LICENSE_KEY, method="adaptive")

3. Switch Mode (Quantum only)

If This Fails	Try This
simulation	hardware

opt = MobiuOptimizer(params, license_key=LICENSE_KEY, method="standard", mode="hardware")

4. Adjust Learning Rate

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

5. Common Fixes by Domain

Domain	Common Issue	Fix
LoRA	SGD + high LR diverges	Use torch.optim.SGD(momentum=0.9) + LR=0.02
Drug Discovery	BCE loss unstable	Use torch.optim.Adam(amsgrad=True) + standard
Crypto/RL	High variance	Use torch.optim.SGD(momentum=0.9) + adaptive
QAOA	Local minima	Use torch.optim.NAdam + deep method
Federated	Non-IID variance	Use torch.optim.Adam + standard + LR=0.01
Imbalanced	Majority bias	Use torch.optim.Adam + standard + LR=0.01

---

Custom / External Optimizers

Mobiu-Q wraps any optimizer with a PyTorch-compatible interface:

# Example: Muon optimizer (https://github.com/KellerJordan/Muon)
from muon import Muon

base_opt = Muon(model.parameters(), lr=0.02, momentum=0.95)
opt = MobiuOptimizer(base_opt, license_key=LICENSE_KEY, method="adaptive")

# Example: LAMB from apex
from apex.optimizers import FusedLAMB

base_opt = FusedLAMB(model.parameters(), lr=0.001)
opt = MobiuOptimizer(base_opt, license_key=LICENSE_KEY, method="standard")

# Example: Adafactor from transformers
from transformers import Adafactor

base_opt = Adafactor(model.parameters(), lr=1e-3, relative_step=False)
opt = MobiuOptimizer(base_opt, license_key=LICENSE_KEY, method="adaptive")

Requirements: The optimizer must have:

• .step() method
• .zero_grad() method
• .param_groups attribute

Most modern optimizers meet these requirements.

---

MobiuAttention 🧪

Why?

Standard Transformer attention is O(N²) in sequence length. MobiuAttention is O(N).

Seq Length	Transformer	MobiuAttention	Speedup	Memory Saving
4,096	16.9ms	16.4ms	~1x	~Equal
8,192	75.3ms	33.8ms	2.2x ✅	50% ✅
16,384	OOM 💥	Works	∞	∞

Tested on T4 GPU, batch=2, d_model=128

Quality (Same as Transformer)

Benchmark	Transformer	MobiuAttention
Shakespeare PPL	12.3	12.2 ✅
ListOps Accuracy	81%	82%
Needle-in-Haystack	100%	100%

Usage

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!

When to Use MobiuAttention

Scenario	Recommendation
GPU + seq > 4K	✅ Use MobiuAttention - 2x faster, 50% less memory
GPU + seq < 4K	Standard Transformer is fine
Apple Silicon (MPS)	Equal quality, Transformer slightly faster
Very long context (>8K)	✅ MobiuAttention only option - Transformer OOMs

Key insight: MobiuAttention maintains the same quality (PPL) while enabling longer contexts that would otherwise cause out-of-memory errors.

Note: MobiuAttention runs 100% locally - no API calls, no license key needed. It's included in the mobiu-q package but operates independently of the cloud service.

⚠️ Combining MobiuAttention with MobiuOptimizer

Based on our testing, combining both products may cause interference:

Configuration	PPL	Result
Standard + Adam	11.86	Baseline
Standard + MobiuOptimizer	3.85	✅ Best! (+67.5%)
MobiuAttention + Adam	11.05	Good (+6.8%)
MobiuAttention + MobiuOptimizer	9.84	⚠️ Interference (+17%)

Recommendation:

• For best quality: Use MobiuOptimizer alone (Standard Attention)
• For long context (>4K tokens): Use MobiuAttention alone
• Don't combine unless you've tested on your specific use case

Verified Performance (Fair A/B Test)

Shakespeare Language Modeling:

Configuration	PPL	Improvement
Adam (baseline)	11.86	-
MobiuOptimizer (adaptive)	3.85	+67.5% ✅

Same API, same hyperparameters, only use_soft_algebra differs

Key Insight: Soft Algebra provides real value - not just adaptive LR!

⚠️ Experimental Status

• Functional and tested
• API may change in future versions
• Feedback welcome!

---

🛡️ Anomaly Detection (NEW in v3.9.0)

Mobiu-Q now includes anomaly detection using the same Soft Algebra mathematics as the optimizer.

MobiuAD - Streaming Detector

Detect anomalies in real-time data streams:

from mobiu_q import MobiuAD

LICENSE_KEY = "your-license-key-here"

detector = MobiuAD(license_key=LICENSE_KEY, method="deep")

for value in data_stream:
    result = detector.detect(value)
    if result.is_anomaly:
        print(f"⚠️ Anomaly! Δ†={result.delta_dagger:.4f}")

Detection Methods

Method	Use Case	Best For
standard	Trust Ratio based	Simple anomalies
deep	Super-Equation Δ†	Behavioral changes (recommended)
transition	Regime detection	Pattern shifts

TrainGuard - Safe ML Training

Combines MobiuOptimizer + MobiuAD to monitor training health:

from mobiu_q import TrainGuard

LICENSE_KEY = "your-license-key-here"

guard = TrainGuard(license_key=LICENSE_KEY)

for epoch in range(100):
    loss = train_epoch(model)
    val_loss = evaluate(model)
    gradient = get_gradient_norm(model)
    
    result = guard.step(
        loss=loss,
        gradient=gradient,
        val_loss=val_loss
    )
    
    # Apply optimized gradient
    apply_gradient(result.adjusted_gradient)
    
    # Check for training issues
    if result.alert:
        if result.alert_type == 'GRADIENT_EXPLOSION':
            print("💥 Gradient explosion detected!")
            reduce_lr()
        elif result.alert_type == 'OVERFITTING':
            print("📈 Overfitting detected!")
            apply_regularization()
        elif result.alert_type == 'LOSS_SPIKE':
            print("⚡ Loss spike detected!")
            restore_checkpoint()

guard.end()

TrainGuard Alerts

Alert Type	Trigger	Suggested Action
GRADIENT_EXPLOSION	Gradient norm spike	Reduce LR, clip gradients
OVERFITTING	Val loss ↑ while train loss ↓	Early stop, regularize
LOSS_SPIKE	Sudden loss increase	Restore checkpoint
PLATEAU	No improvement	Increase LR, change optimizer

Batch Detection

from mobiu_q import MobiuAD

LICENSE_KEY = "your-license-key-here"

detector = MobiuAD(license_key=LICENSE_KEY)

# Detect anomalies in batch
results = detector.detect_batch(data_array)
print(f"Found {results.total_anomalies} anomalies at indices: {results.anomaly_indices}")

MobiuAD vs PyOD

Feature	MobiuAD	PyOD
Type	Streaming	Batch
Detects	Behavioral changes	Statistical outliers
Real-time	✅ Yes	❌ No
Early warning	✅ Yes	❌ No
Pattern changes	✅ Excellent	⚠️ Limited
Value outliers	⚠️ Good	✅ Excellent

Use MobiuAD when:

• Real-time streaming detection needed
• Detecting behavioral/pattern changes
• Early warning before anomalies manifest
• Monitoring ML training (TrainGuard)

Use PyOD when:

• Batch analysis of static data
• Detecting statistical outliers
• Value-based anomaly detection

Enhanced Detection (PyOD + Soft Algebra)

Combine both approaches for maximum coverage:

from mobiu_q.detection import MobiuADEnhanced

# Requires: pip install pyod
detector = MobiuADEnhanced(base_detector="IForest")
results = detector.detect_batch(data)

---

How It Works

Soft Algebra

Both optimizer and attention use the nilpotent property ε²=0:

SoftNumber multiplication: (a,b) × (c,d) = (ad + bc, bd)

This enables tracking both "potential" and "realized" components.

In Optimization

lr_t = base_lr × (1 + soft_component)

Soft Algebra adapts learning rate based on loss landscape curvature.

In Attention

S(t) = γ·S(t-1) + k_t ⊗ v_t  # O(N) state update

Instead of O(N²) pairwise attention, we track state with O(N) complexity.

In Anomaly Detection

Δ† = |a_t + i·b_t|  # Super-Equation score

Soft Algebra tracks behavioral patterns and detects deviations.

In Signal Generation

a_t = volatility / mean_price    # Potential: what COULD happen
b_t = price_change               # Realized: what DID happen
signal = √(a² + b²)              # Interaction magnitude

Soft Algebra detects when high potential meets significant realization.

---

Full Examples

For complete working examples with benchmarking, see the examples/ folder:

Quantum Chemistry (VQE)

File	Description
test_fakefez_h2_customer.py	H₂ molecule on FakeFez
test_lih_customer.py	LiH molecule
test_h2o_customer.py	H₂O molecule
test_beh2_customer.py	BeH₂ molecule
test_h4_customer.py	H₄ chain
test_heh_customer.py	HeH⁺ molecule

Condensed Matter Physics

File	Description
test_heisenberg_xxz.py	Heisenberg XXZ model
test_transverse_ising.py	Transverse field Ising model
test_xy_model.py	XY model
test_ferro_ising.py	Ferromagnetic Ising
test_antiferro_heisenberg.py	Antiferromagnetic Heisenberg

Advanced Quantum

File	Description
test_hubbard_dimer.py	Hubbard dimer
test_ssh_model.py	SSH model (topological)
test_kitaev_chain.py	Kitaev chain

QAOA

File	Description
test_fakefez_qaoa_new.py	MaxCut on FakeFez
test_fakefez_qaoa_mis_new.py	Max Independent Set on FakeFez

Classical Optimization

File	Description
test_sphere.py	Sphere function
test_ackley.py	Ackley function
test_beale.py	Beale function
test_rosenbrok.py	Rosenbrock function

Finance

File	Description
test_portfolio.py	Portfolio optimization
test_credit_risk.py	Credit risk assessment
test_option_pricing.py	Option pricing
crypto_trading_customer.py	Crypto trading with regime switching

Reinforcement Learning

File	Description
test_lunarlander_customer.py	LunarLander with REINFORCE
test_mujoco_customer.py	MuJoCo continuous control
ppo_mobiu_test_customer.py	PPO from scratch
atari_breakout_customer.py	Atari Breakout
rl_trading_customer.py	RL Trading with MobiuSignal

Machine Learning Benchmarks

File	Description
test_federated_customer.py	Federated learning
test_noisy_labels_customer.py	Noisy labels
test_sim_to_real_customer.py	Sim-to-real transfer
test_imbalanced_customer.py	Imbalanced classification

Utilities & Demos

File	Description
double_mobiu_customer.py	Fair A/B: Soft Algebra ON vs OFF
ad_test_trainguard.py	TrainGuard monitoring demo
ad_poc_demo.py	Anomaly detection POC
benchmark_behavioral_customer.py	Behavioral anomaly detection
example_signal_customer.py	MobiuSignal demo
blackbox_spsa_customer.py	Blackbox SPSA optimization
antenna_customer.py	Antenna design optimization

---

License

Tier	API Calls	Price	Get Started
Free	20/month	$0	Sign up
Pro	Unlimited	$19/month	Get one

Note: MobiuAttention & MobiuSignal run locally, no API calls required.

---

Links

• PyPI
• GitHub

---

Citation

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