Documentation

Complete guide to ThalosForge optimization engines, MLOps tools, and robotics control systems.

Installation

Install ThalosForge using pip:

pip install thalosforge

For specific modules only:

# Optimization engines only
pip install thalosforge[optimization]

# MLOps (Saturna) only
pip install thalosforge[mlops]

# Robotics (Command Dosage) only
pip install thalosforge[robotics]

# Everything
pip install thalosforge[all]

Requirements

• Python 3.8 or higher
• NumPy 1.20+
• SciPy 1.7+ (for optimization)
• ONNX Runtime 1.10+ (for Saturna)

API Key

For cloud features and premium support, set your API key:

import thalosforge as tf
tf.set_api_key("your-api-key")

Quick Start

Here's a complete example optimizing the 100D Rastrigin function:

import numpy as np
import thalosforge as tf

# Define objective function
def rastrigin(x):
    A = 10
    return A * len(x) + np.sum(x**2 - A * np.cos(2 * np.pi * x))

# Set bounds (100 dimensions)
bounds = [(-5.12, 5.12)] * 100

# Optimize with QuantumJolt
result = tf.optimize(
    rastrigin,
    bounds=bounds,
    method='quantumjolt',
    max_evals=5000
)

print(f"Best value: {result.fun}")
print(f"Evaluations: {result.nfev}")
# Expected: Best value ≈ 0.0

Core Concepts

When to Use ThalosForge

ThalosForge excels on problems where standard tools fail:

• High-dimensional — 100+ decision variables
• Multimodal — Many local optima (non-convex)
• Expensive — Each function evaluation costs time/money
• Black-box — No gradient information available
• Noisy — Function evaluations have variance

The optimize() Function

All ThalosForge optimizers share a common interface:

result = tf.optimize(
    func,           # Objective function to minimize
    bounds,         # List of (min, max) tuples
    method,         # 'quantumjolt', 'dss', or 'kestrel'
    max_evals,      # Maximum function evaluations
    constraints,    # Optional: constraint functions
    seed,           # Optional: random seed
    callback        # Optional: progress callback
)

QuantumJolt

High-dimensional multimodal optimizer based on SPSA (Simultaneous Perturbation Stochastic Approximation) with adaptive learning rates.

Best For

• 100-1000+ dimension problems
• Hyperparameter optimization
• Neural network training
• Problems with many local optima

Usage

result = tf.optimize(
    objective,
    bounds=bounds,
    method='quantumjolt',
    max_evals=5000,
    options={
        'a': 0.1,        # Initial step size
        'c': 0.01,       # Perturbation size
        'alpha': 0.602,  # Step decay rate
        'gamma': 0.101,  # Perturbation decay rate
    }
)

Parameters

Benchmark Results

Spiral Swarm DSS

Deterministic Spiral Search optimizer using Fibonacci lattice sampling. 100% reproducible with zero hyperparameters.

Best For

• Expensive simulations (CFD, FEA)
• Regulatory compliance (audit trails)
• Reproducibility requirements
• Problems where randomness is unacceptable

Usage

result = tf.optimize(
    expensive_simulation,
    bounds=bounds,
    method='dss',
    max_evals=500,  # Works well with few evals
    options={
        'beta_adaptive': True,  # Auto-balance explore/exploit
    }
)

Key Feature: Determinism

Parameters

Kestrel Pro

Constrained and multi-objective optimizer supporting inequality constraints, equality constraints, and Pareto front generation.

Best For

• Engineering design with constraints
• Portfolio optimization
• Resource allocation
• Multi-objective trade-offs

Constrained Optimization

# G06 benchmark: constrained optimization
def objective(x):
    return (x[0] - 10)**3 + (x[1] - 20)**3

# Inequality constraints: g(x) <= 0
def g1(x):
    return -(x[0] - 5)**2 - (x[1] - 5)**2 + 100

def g2(x):
    return (x[0] - 6)**2 + (x[1] - 5)**2 - 82.81

result = tf.optimize(
    objective,
    bounds=[(13, 100), (0, 100)],
    method='kestrel',
    constraints=[
        {'type': 'ineq', 'fun': g1},
        {'type': 'ineq', 'fun': g2},
    ]
)
# Result: -6961.82 (optimal: -6961.81)

Multi-Objective Optimization

# Multi-objective: minimize both f1 and f2
def objectives(x):
    f1 = x[0]**2
    f2 = (x[0] - 2)**2
    return [f1, f2]

result = tf.optimize(
    objectives,
    bounds=[(-5, 5)],
    method='kestrel',
    n_objectives=2
)

# Returns Pareto front
for point in result.pareto_front:
    print(f"x={point.x}, f={point.fun}")

Saturna

Model calibration maintenance layer. Prevents drift and maintains accuracy WITHOUT retraining.

Best For

• Fraud detection models
• Medical diagnostic devices
• IoT sensor calibration
• Credit risk models

Usage

from thalosforge import Saturna

# Wrap any ONNX model
saturna = Saturna(
    model_path="fraud_detector.onnx",
    lambda_blend=0.3,
    temperature=0.9
)

# Calibrate on baseline data
saturna.calibrate(X_baseline)

# Predict with automatic drift correction
predictions = saturna.predict(X_new)

# Check calibration health
stability = saturna.stability_index()
print(f"Stability: {stability:.2f}")  # 0.97 = healthy

Parameters

How It Works

1. Calibrate: Learn baseline data distribution statistics
2. Monitor: Detect drift in incoming data
3. Modulate: Apply drift correction to maintain calibration
4. Predict: Return corrected predictions

Command Dosage Control

Eliminates jerkiness and oscillation in robotic motion through gradual command injection.

Best For

• Industrial assembly robots
• Collaborative robots (cobots)
• Precision handling
• Autonomous vehicles

Usage

from thalosforge import DosageController

# Initialize controller
controller = DosageController(
    update_rate=100,  # Hz
    strategy="adaptive"
)

# Set safety limits
controller.set_limits(
    max_velocity=1.0,
    max_acceleration=2.0,
    max_jerk=5.0
)

# Inject target command gradually
target = [1.5, -0.3, 0.8]
for step in controller.dose(target):
    robot.send_command(step)
    time.sleep(0.01)  # 100 Hz

Dosing Strategies

Parameters