Qubots is a Python optimization framework that enables developers to build, share, and deploy optimization solutions. With its innovative AutoProblem and AutoOptimizer components, qubots transforms complex optimization challenges into modular, reusable components that integrate seamlessly with the Rastion platform for collaborative development and deployment.
Qubots is designed for environments where optimization problems need to be:
The framework centers around six core components that work together to provide a comprehensive optimization ecosystem:
AutoProblem and AutoOptimizerInstall qubots from PyPI:
pip install qubots
For domain-specific optimizations, install optional dependencies:
# For routing and scheduling
pip install qubots[routing]
# For continuous optimization
pip install qubots[continuous]
# For finance optimization
pip install qubots[finance]
# For energy optimization
pip install qubots[energy]
# For all features
pip install qubots[all]
For development and testing:
# Clone the repository
git clone https://github.com/Rastion/qubots.git
cd qubots
# Install in development mode
pip install -e .[dev]
The qubots framework is built around a modular architecture with the following core components:
AutoProblem & AutoOptimizer: Dynamic loading system for optimization components
Autoloading Functions: Intelligent discovery and execution system
Benchmark System: Comprehensive testing and evaluation framework
Cloud Execution: Scalable optimization infrastructure
Rastion Integration: Seamless platform connectivity
Leaderboard System: Performance tracking and comparison
Each qubots repository follows a standardized structure:
repository/
├── qubot.py # Main implementation file
├── config.json # Configuration and metadata
├── requirements.txt # Python dependencies (optional)
└── README.md # Documentation (optional)
Here's how to load problems and optimizers from repositories and run optimizations:
from qubots import AutoProblem, AutoOptimizer
# Load a problem from a repository
problem = AutoProblem.from_repo("ileo/demo-maxcut")
# Load an optimizer from a repository
optimizer = AutoOptimizer.from_repo("ileo/demo-ortools-maxcut-optimizer")
# Run optimization
result = optimizer.optimize(problem)
print(f"Best Solution: {result.best_solution}")
print(f"Best Value: {result.best_value}")
print(f"Runtime: {result.runtime_seconds:.3f} seconds")
print(f"Iterations: {result.iterations}")
You can override parameters when loading problems and optimizers:
from qubots import AutoProblem, AutoOptimizer
# Load problem with custom parameters
problem = AutoProblem.from_repo("ileo/demo-maxcut", override_params={
"n_vertices": 20,
"graph_type": "random",
"density": 0.3
})
# Load optimizer with custom parameters
optimizer = AutoOptimizer.from_repo("ileo/demo-ortools-maxcut-optimizer", override_params={
"time_limit": 60.0,
"num_search_workers": 4,
"log_search_progress": True
})
# Run optimization with callbacks
def progress_callback(iteration, best_value, current_value):
print(f"Iteration {iteration}: Best={best_value}, Current={current_value}")
def log_callback(level, message, source):
print(f"[{level.upper()}] {source}: {message}")
result = optimizer.optimize(
problem,
progress_callback=progress_callback,
log_callback=log_callback
)
Qubots integrates with the Rastion platform for collaborative optimization development:
The framework loads optimization components directly from Git repositories:
from qubots import AutoProblem, AutoOptimizer
# Load from public repositories
problem = AutoProblem.from_repo("username/problem-repo")
optimizer = AutoOptimizer.from_repo("username/optimizer-repo")
# Load from specific branches or revisions
problem = AutoProblem.from_repo("username/problem-repo", revision="v1.2.0")
optimizer = AutoOptimizer.from_repo("username/optimizer-repo", revision="development")
The framework automatically caches repositories for improved performance:
# Repositories are cached in ~/.cache/rastion_hub by default
# Subsequent loads are much faster
# Custom cache directory
problem = AutoProblem.from_repo(
"username/problem-repo",
cache_dir="./my_cache"
)
The qubots framework includes a comprehensive set of examples that demonstrate the core functionality and showcase different optimization problems and solvers. These examples are available in the examples/ directory and have been uploaded to the Rastion platform for easy access and testing.
maxcut_problem/): Graph partitioning optimization with configurable graph typesortools_maxcut_optimizer/): Integer programming solver using Google OR-Toolstsp/): Traveling Salesman Problem with TSPLIB format supporthighs_tsp_solver/): Linear programming solver using HiGHS for TSPvehicle_routing_problem/): Multi-vehicle routing with capacity constraintsgenetic_vrp_optimizer/): Evolutionary algorithm for VRP optimizationtsp_time_windows/): TSP variant with delivery time constraintstsp_capacity_constraints/): TSP with vehicle capacity limitationsAll examples can be tested locally using the autoloading functions. See the Examples README for detailed instructions on:
from qubots import AutoProblem, AutoOptimizer
# Load any example from the local examples directory
problem = AutoProblem.from_repo("examples/maxcut_problem")
optimizer = AutoOptimizer.from_repo("examples/ortools_maxcut_optimizer")
# Run optimization
result = optimizer.optimize(problem)
print(f"Best solution: {result.best_value}")
Qubots includes two powerful utility scripts for repository management and testing:
This script uploads qubots repositories to the Rastion platform for sharing and collaboration.
# Basic upload with auto-detected metadata
python examples/upload_repo_to_rastion.py ./my_optimizer --token YOUR_RASTION_TOKEN
# Upload with custom name and description
python examples/upload_repo_to_rastion.py ./my_problem \
--name "custom_vrp_solver" \
--description "Advanced VRP solver with time windows"
--token YOUR_RASTION_TOKEN
# Upload as private repository with overwrite
python examples/upload_repo_to_rastion.py ./my_optimizer \
--private --overwrite --token YOUR_RASTION_TOKEN
# Upload with custom requirements
python examples/upload_repo_to_rastion.py ./my_problem \
--requirements "qubots,numpy>=1.20.0,ortools>=9.0.0"
--token YOUR_RASTION_TOKEN
| Parameter | Description | Required |
|---|---|---|
repo_path | Path to the repository directory | Yes |
--name | Repository name (auto-detected if not provided) | No |
--description | Repository description (auto-detected if not provided) | No |
--private | Make repository private | No |
--overwrite | Overwrite existing repository | No |
--requirements | Comma-separated Python requirements | No |
--token | Rastion authentication token | Yes* |
*Token can also be set via RASTION_TOKEN environment variable
Your repository must contain:
qubot.py: Main implementation fileconfig.json: Configuration with required fields:
{
"type": "problem" or "optimizer",
"entry_point": "qubot",
"class_name": "YourClassName",
"metadata": {
"name": "Your Model Name",
"description": "Model description"
}
}
# Upload a VRP problem
python examples/upload_repo_to_rastion.py ./vrp_problem \
--name "vrp_timewindows" \
--description "Vehicle Routing Problem with time windows and capacity constraints"
--token YOUR_RASTION_TOKEN
# Upload an optimizer with specific requirements
python examples/upload_repo_to_rastion.py ./genetic_optimizer \
--requirements "qubots,numpy>=1.20.0,scipy>=1.7.0" \
--private
--token YOUR_RASTION_TOKEN
This script loads problems and optimizers from repositories and runs comprehensive testing to validate compatibility and performance.
# Basic testing with single iteration
python examples/load_and_test_optimization.py user/my_problem user/my_optimizer
# Run multiple iterations for statistical analysis
python examples/load_and_test_optimization.py user/my_problem user/my_optimizer --iterations 5
# Quiet mode with minimal output
python examples/load_and_test_optimization.py user/my_problem user/my_optimizer --quiet
# With authentication for private repositories
python examples/load_and_test_optimization.py user/private_problem user/private_optimizer --token YOUR_TOKEN
| Parameter | Description | Required |
|---|---|---|
problem_repo | Problem repository name (format: [username/]repo_name) | Yes |
optimizer_repo | Optimizer repository name (format: [username/]repo_name) | Yes |
--iterations | Number of optimization iterations to run (default: 1) | No |
--quiet | Minimal output mode | No |
--token | Rastion authentication token | No* |
*Token can also be set via RASTION_TOKEN environment variable
The script provides comprehensive output including:
# Test a MaxCut problem with OR-Tools optimizer
python examples/load_and_test_optimization.py ileo/demo-maxcut ileo/demo-ortools-maxcut-optimizer
# Test VRP problem with genetic algorithm (5 iterations)
python examples/load_and_test_optimization.py ileo/demo-vrp-problem ileo/demo-genetic-vrp-optimizer --iterations 5
# Test private repositories with authentication
python examples/load_and_test_optimization.py company/private_problem company/private_optimizer \
--token YOUR_RASTION_TOKEN --iterations 3
0: All optimization runs completed successfully1: Some optimization runs failed (partial success)2: All optimization runs failed3: Script error (loading, compatibility, etc.)from qubots import AutoProblem, AutoOptimizer
# Load VRP problem with custom parameters
problem = AutoProblem.from_repo("ileo/demo-vrp-problem", override_params={
"n_customers": 25,
"n_vehicles": 3,
"depot_location": (0, 0),
"vehicle_capacity": 100
})
# Load genetic algorithm optimizer
optimizer = AutoOptimizer.from_repo("ileo/demo-genetic-vrp-optimizer", override_params={
"population_size": 100,
"generations": 500,
"mutation_rate": 0.1
})
# Run optimization
result = optimizer.optimize(problem)
print(f"Total distance: {result.best_value}")
print(f"Number of routes: {len(result.best_solution)}")
from qubots import AutoProblem, AutoOptimizer
# Load MaxCut problem
problem = AutoProblem.from_repo("ileo/demo-maxcut", override_params={
"n_vertices": 15,
"graph_type": "random",
"density": 0.4
})
# Load OR-Tools optimizer
optimizer = AutoOptimizer.from_repo("ileo/demo-ortools-maxcut-optimizer", override_params={
"time_limit": 30.0,
"use_symmetry": True
})
# Run optimization with monitoring
def progress_callback(iteration, best_value, current_value):
print(f"Iteration {iteration}: Best cut weight = {best_value}")
result = optimizer.optimize(problem, progress_callback=progress_callback)
print(f"Maximum cut weight: {result.best_value}")
print(f"Cut partition: {result.best_solution}")
The AutoProblem class provides automatic loading and instantiation of optimization problems from repositories.
class AutoProblem:
@classmethod
def from_repo(
cls,
repo_id: str,
revision: str = "main",
cache_dir: str = "~/.cache/rastion_hub",
override_params: Optional[dict] = None,
validate_metadata: bool = True
) -> BaseProblem
Parameters:
repo_id: Repository identifier in format "username/repository-name"revision: Git branch or tag to load (default: "main")cache_dir: Local cache directory for repositoriesoverride_params: Dictionary of parameters to override default valuesvalidate_metadata: Whether to validate problem metadataThe AutoOptimizer class provides automatic loading and instantiation of optimization algorithms from repositories.
class AutoOptimizer:
@classmethod
def from_repo(
cls,
repo_id: str,
revision: str = "main",
cache_dir: str = "~/.cache/rastion_hub",
override_params: Optional[dict] = None,
validate_metadata: bool = True,
) -> BaseOptimizer
Parameters:
repo_id: Repository identifier in format "username/repository-name"revision: Git branch or tag to load (default: "main")cache_dir: Local cache directory for repositoriesoverride_params: Dictionary of parameters to override default valuesvalidate_metadata: Whether to validate optimizer metadataAbstract base class for all optimization problems.
Key Methods:
evaluate_solution(solution): Evaluate a candidate solutionget_random_solution(): Generate a random valid solutionvalidate_solution_format(solution): Validate solution formatget_neighbor_solution(solution, step_size): Generate neighboring solutionAbstract base class for all optimization algorithms.
Key Methods:
optimize(problem, initial_solution=None, progress_callback=None, log_callback=None): Run optimization_optimize_implementation(problem, initial_solution): Core optimization logic (must be implemented)stop_optimization(): Stop running optimizationget_parameters(): Get current optimizer parametersData class containing optimization results.
Attributes:
best_solution: Best solution foundbest_value: Best objective valueiterations: Number of iterations performedruntime_seconds: Total optimization timeconvergence_history: History of objective valuesmetadata: Additional result metadataProvides automatic dashboard generation for optimization results.
@staticmethod
def auto_optimize_with_dashboard(
problem,
optimizer,
problem_name: str = "Unknown Problem",
optimizer_name: str = "Unknown Optimizer",
log_callback=None,
progress_callback=None
) -> DashboardResult
Comprehensive benchmarking and comparison tools.
class BenchmarkSuite:
def add_optimizer(self, name: str, optimizer: BaseOptimizer)
def run_benchmarks(self, problem: BaseProblem, num_runs: int = 10)
def generate_report(self, results: BenchmarkResult, output_file: str)
The qubots framework includes a comprehensive leaderboard system for tracking solver performance across standardized benchmarks:
from qubots import (
get_standardized_problems,
submit_to_leaderboard,
get_problem_leaderboard,
LeaderboardClient
)
# Get available standardized problems
problems = get_standardized_problems()
print(f"Available benchmark problems: {[p.name for p in problems]}")
# Run optimization on a standardized problem
problem = AutoProblem.from_repo("standardized/tsp-att48")
optimizer = AutoOptimizer.from_repo("user/my-tsp-solver")
result = optimizer.optimize(problem)
# Submit results to leaderboard
submission = submit_to_leaderboard(
problem_name="tsp-att48",
solver_name="my-tsp-solver",
result=result,
solver_config={"time_limit": 300, "algorithm": "genetic"}
)
# View leaderboard rankings
rankings = get_problem_leaderboard("tsp-att48")
for rank, entry in enumerate(rankings[:5], 1):
print(f"{rank}. {entry.solver_name}: {entry.best_value} ({entry.runtime:.2f}s)")
Use the provided utility script for comprehensive testing:
# Test problem-optimizer compatibility
python examples/load_and_test_optimization.py ileo/demo-maxcut ileo/demo-ortools-maxcut-optimizer --iterations 5
# Test with custom parameters
python examples/load_and_test_optimization.py user/my_problem user/my_optimizer --iterations 10 --quiet
from qubots import AutoProblem, AutoOptimizer
# Load components
problem = AutoProblem.from_repo("user/test-problem")
optimizer = AutoOptimizer.from_repo("user/test-optimizer")
# Validate compatibility
try:
# Test basic functionality
solution = problem.get_random_solution()
cost = problem.evaluate_solution(solution)
# Run optimization
result = optimizer.optimize(problem)
print(f"Test successful: {result.best_value}")
except Exception as e:
print(f"Test failed: {e}")
Compare multiple optimizers on the same problem:
from qubots import AutoProblem, AutoOptimizer, BenchmarkSuite
# Load problem
problem = AutoProblem.from_repo("ileo/demo-maxcut")
# Create benchmark suite
suite = BenchmarkSuite()
# Add optimizers to compare
suite.add_optimizer("OR-Tools", AutoOptimizer.from_repo("ileo/demo-ortools-maxcut-optimizer"))
suite.add_optimizer("Genetic Algorithm", AutoOptimizer.from_repo("user/genetic-maxcut-optimizer"))
# Run benchmarks
results = suite.run_benchmarks(problem, num_runs=10)
# Generate report
suite.generate_report(results, "benchmark_results.html")
We welcome contributions to the qubots framework! Here's how you can contribute:
# Clone the repository
git clone https://github.com/Rastion/qubots.git
cd qubots
# Install in development mode with all dependencies
pip install -e .
my_optimizer/
├── qubot.py # Main implementation
├── config.json # Configuration
├── requirements.txt # Dependencies
└── README.md # Documentation
qubot.py):from qubots import BaseOptimizer, OptimizationResult, OptimizerMetadata
import time
class MyOptimizer(BaseOptimizer):
def _get_default_metadata(self):
return OptimizerMetadata(
name="My Custom Optimizer",
description="A novel optimization algorithm",
author="Your Name",
version="1.0.0"
)
def _optimize_implementation(self, problem, initial_solution=None):
start_time = time.time()
best_solution = problem.get_random_solution()
best_value = problem.evaluate_solution(best_solution)
# Your optimization logic here
for iteration in range(100):
solution = problem.get_random_solution()
value = problem.evaluate_solution(solution)
if value < best_value:
best_solution = solution
best_value = value
return OptimizationResult(
best_solution=best_solution,
best_value=best_value,
iterations=100,
runtime_seconds=time.time() - start_time
)
config.json):{
"type": "optimizer",
"entry_point": "qubot",
"class_name": "MyOptimizer",
"metadata": {
"name": "My Custom Optimizer",
"description": "A novel optimization algorithm"
},
"default_params": {}
}
python examples/upload_repo_to_rastion.py ./my_optimizer --name "my_custom_optimizer" --token YOUR_RASTION_TOKEN
This project is licensed under the Apache License 2.0.
Qubots empowers organizations to build scalable, collaborative optimization solutions. With its architecture and seamless repository integration, teams can rapidly develop, share, and deploy optimization components that solve real-world challenges across industries.
FAQs
A collaborative optimization framework for creating optimization tools.
We found that qubots demonstrated a healthy version release cadence and project activity because the last version was released less than a year ago. It has 1 open source maintainer collaborating on the project.
Did you know?
Socket for GitHub automatically highlights issues in each pull request and monitors the health of all your open source dependencies. Discover the contents of your packages and block harmful activity before you install or update your dependencies.
Security News
Browserslist-rs now uses static data to reduce binary size by over 1MB, improving memory use and performance for Rust-based frontend tools.
Research
Security News
Eight new malicious Firefox extensions impersonate games, steal OAuth tokens, hijack sessions, and exploit browser permissions to spy on users.
Security News
The official Go SDK for the Model Context Protocol is in development, with a stable, production-ready release expected by August 2025.