API Reference

Complete reference for all ThalosForge classes and functions.

thalosforge.optimize()

Main entry point for all optimization tasks. Unified interface for all ThalosForge optimizers.

optimize(func, bounds, method='quantumjolt', max_evals=1000, constraints=None, n_objectives=1, seed=None, callback=None, options=None)

Parameters

Name	Type	Description
`func`	callable	Required. Objective function to minimize. Takes array x, returns scalar (or list for multi-objective).
`bounds`	list of tuples	Required. List of (min, max) bounds for each dimension.
`method`	str	Optional. Optimizer: 'quantumjolt', 'dss', or 'kestrel'. Default: 'quantumjolt'
`max_evals`	int	Optional. Maximum function evaluations. Default: 1000
`constraints`	list of dict	Optional. Constraint functions. Each dict: {'type': 'ineq'\|'eq', 'fun': callable}
`n_objectives`	int	Optional. Number of objectives for multi-objective. Default: 1
`seed`	int	Optional. Random seed for reproducibility. Not needed for DSS.
`callback`	callable	Optional. Called after each iteration: callback(xk, fk, iteration)
`options`	dict	Optional. Method-specific options. See individual optimizer docs.

Returns: OptimizationResult object containing solution and metadata.

Example

import thalosforge as tf
import numpy as np

def sphere(x):
    return np.sum(x**2)

result = tf.optimize(
    sphere,
    bounds=[(-5, 5)] * 10,
    method='quantumjolt',
    max_evals=1000
)

print(result.fun)   # Best objective value
print(result.x)     # Best solution vector
print(result.nfev)  # Number of evaluations used

OptimizationResult

Container for optimization results. Returned by optimize().

Attributes

Name	Type	Description
`x`	ndarray	Best solution found
`fun`	float	Objective value at best solution
`nfev`	int	Number of function evaluations
`nit`	int	Number of iterations
`success`	bool	Whether optimization converged
`message`	str	Termination message
`history`	list	Optimization trajectory (if recorded)
`pareto_front`	list	Pareto solutions (multi-objective only)

thalosforge.set_api_key()

Set API key for cloud features and premium support.

set_api_key(key)

import thalosforge as tf
tf.set_api_key("tf_live_abc123...")

class QuantumJolt

High-dimensional SPSA-based optimizer with adaptive learning rates.

QuantumJolt(dim, bounds, a=0.1, c=0.01, alpha=0.602, gamma=0.101, A=100)

Methods

Method	Description
`optimize(func, max_evals)`	Run optimization
`step(func)`	Single optimization step
`reset()`	Reset optimizer state
`get_best()`	Return current best solution

from thalosforge.optimizers import QuantumJolt

optimizer = QuantumJolt(
    dim=100,
    bounds=[(-5, 5)] * 100,
    a=0.1,
    c=0.01
)

result = optimizer.optimize(objective, max_evals=5000)

class SpiralSwarmDSS

Deterministic Spiral Search using Fibonacci lattice sampling.

SpiralSwarmDSS(dim, bounds, beta_adaptive=True, contraction_rate=0.618)

Methods

Method	Description
`optimize(func, max_evals)`	Run deterministic optimization
`step(func)`	Single spiral iteration
`get_trajectory()`	Return full search path

from thalosforge.optimizers import SpiralSwarmDSS

optimizer = SpiralSwarmDSS(
    dim=20,
    bounds=[(0, 10)] * 20,
    beta_adaptive=True
)

# 100% reproducible - no seed needed
result = optimizer.optimize(expensive_sim, max_evals=200)

class KestrelPro

Constrained and multi-objective optimizer.

KestrelPro(dim, bounds, n_objectives=1, population_size=50)

Methods

Method	Description
`optimize(func, max_evals, constraints)`	Run constrained optimization
`add_constraint(type, fun)`	Add constraint function
`get_pareto_front()`	Return Pareto-optimal solutions
`hypervolume()`	Calculate hypervolume indicator

class Saturna

Model calibration maintenance layer for ONNX models.

Saturna(model_path, lambda_blend=0.3, temperature=0.9)

Methods

Method	Description
`calibrate(X)`	Learn baseline distribution from data X
`predict(X)`	Run inference with drift correction
`predict_proba(X)`	Return probability predictions
`stability_index()`	Return calibration health score (0-1)
`status()`	Return JSON status summary
`reset()`	Clear calibration state

from thalosforge import Saturna

saturna = Saturna(
    model_path="model.onnx",
    lambda_blend=0.3,
    temperature=0.9
)

# Initial calibration
saturna.calibrate(X_train)

# Production inference
predictions = saturna.predict(X_new)

# Check health
if saturna.stability_index() < 0.8:
    print("Warning: Calibration degrading")

class DosageController

Robotic motion smoothing through gradual command injection.

DosageController(update_rate=100, strategy='adaptive')

Methods

Method	Description
`set_limits(max_velocity, max_acceleration, max_jerk)`	Configure safety limits
`dose(target)`	Generator yielding smooth command sequence
`emergency_stop()`	Trigger immediate safe stop
`detect_oscillation()`	Check for motion instability
`get_trajectory()`	Return planned trajectory

from thalosforge import DosageController

controller = DosageController(
    update_rate=100,
    strategy="scurve"
)

controller.set_limits(
    max_velocity=1.0,
    max_acceleration=2.0,
    max_jerk=5.0
)

# Smooth motion to target
for cmd in controller.dose([1.5, -0.3, 0.8]):
    robot.send(cmd)
    time.sleep(0.01)

thalosforge.benchmark()

Run standardized benchmarks comparing optimizers.

benchmark(methods, problems, n_runs=30, max_evals=1000)

import thalosforge as tf

results = tf.benchmark(
    methods=['quantumjolt', 'dss', 'scipy-de'],
    problems=['rastrigin', 'ackley', 'griewank'],
    n_runs=30,
    max_evals=5000
)

print(results.summary())
results.to_csv("benchmark_results.csv")

Test Functions

Standard optimization test functions included in ThalosForge.

from thalosforge.benchmarks import (
    rastrigin,
    ackley,
    griewank,
    rosenbrock,
    schwefel,
    levy,
    sphere
)

# All functions take ndarray, return scalar
x = np.zeros(10)
print(rastrigin(x))   # 0.0 (global minimum)
print(ackley(x))      # 0.0 (global minimum)

Function	Global Minimum	Bounds	Characteristics
`rastrigin`	0 at origin	[-5.12, 5.12]	Highly multimodal
`ackley`	0 at origin	[-5, 5]	Many local minima
`griewank`	0 at origin	[-600, 600]	Product term
`rosenbrock`	0 at ones	[-5, 10]	Narrow valley
`schwefel`	0 at 420.97	[-500, 500]	Deceptive
`levy`	0 at ones	[-10, 10]	Multimodal
`sphere`	0 at origin	[-5, 5]	Convex (easy)