Configuration System
The qubots framework uses a comprehensive configuration system based on config.json files that define solver parameters, metadata, and integration settings. This system ensures consistent parameter handling across the framework, Rastion playground interface, and leaderboard submissions.
Overview
Every qubots repository must contain a config.json file that serves multiple purposes:
- Parameter Definition: Specifies all configurable parameters with types, defaults, and validation rules
- Metadata: Provides descriptive information about the solver or problem
- Integration: Enables seamless integration with Rastion playground and leaderboard systems
- Validation: Ensures parameter values are within acceptable ranges and types
Basic Structure
Minimal Configuration
{
"type": "optimizer",
"entry_point": "qubot",
"class_name": "MyOptimizer",
"default_params": {
"time_limit": 60.0,
"population_size": 50
},
"metadata": {
"name": "My Optimizer",
"description": "A simple optimization algorithm"
}
}
Complete Configuration Schema
{
"type": "optimizer|problem",
"entry_point": "qubot",
"class_name": "ClassName",
"default_params": {
"param1": "default_value1",
"param2": "default_value2"
},
"parameters": {
"param1": {
"type": "string|number|integer|boolean|array",
"default": "default_value",
"description": "Parameter description",
"min": 0,
"max": 100,
"options": ["option1", "option2"],
"required": true
}
},
"metadata": {
"name": "Display Name",
"description": "Detailed description",
"domain": "optimization_domain",
"tags": ["tag1", "tag2"],
"difficulty": "beginner|intermediate|advanced",
"optimizer_type": "exact|metaheuristic|hybrid",
"problem_type": "combinatorial|continuous|mixed"
},
"requirements": [
"qubots",
"numpy>=1.20.0"
]
}
Parameter Types and Validation
Supported Parameter Types
String Parameters
{
"algorithm_type": {
"type": "string",
"default": "genetic",
"options": ["genetic", "simulated_annealing", "tabu_search"],
"description": "Type of optimization algorithm to use"
}
}
Numeric Parameters
{
"time_limit": {
"type": "number",
"default": 60.0,
"min": 1.0,
"max": 3600.0,
"step": 0.1,
"description": "Maximum optimization time in seconds"
},
"population_size": {
"type": "integer",
"default": 50,
"min": 10,
"max": 1000,
"description": "Number of individuals in the population"
}
}
Boolean Parameters
{
"use_elitism": {
"type": "boolean",
"default": true,
"description": "Whether to preserve best solutions across generations"
}
}
Array Parameters
{
"weight_range": {
"type": "array",
"default": [1.0, 10.0],
"description": "Range for random edge weights [min, max]",
"items": {
"type": "number",
"min": 0.1,
"max": 100.0
},
"minItems": 2,
"maxItems": 2
}
}
Parameter Validation Rules
Required vs Optional Parameters
{
"parameters": {
"time_limit": {
"type": "number",
"default": 60.0,
"required": true,
"description": "Maximum solving time (required)"
},
"log_level": {
"type": "integer",
"default": 1,
"required": false,
"description": "Logging verbosity (optional)"
}
}
}
Range Constraints
{
"mutation_rate": {
"type": "number",
"default": 0.1,
"min": 0.001,
"max": 1.0,
"description": "Mutation probability (0.001 to 1.0)"
}
}
Enumerated Options
{
"selection_method": {
"type": "string",
"default": "tournament",
"options": ["tournament", "roulette", "rank", "random"],
"description": "Selection method for genetic algorithm"
}
}
Rastion Playground Integration
Parameter Display
The Rastion playground automatically generates UI controls based on parameter definitions:
{
"parameters": {
"population_size": {
"type": "integer",
"default": 50,
"min": 10,
"max": 500,
"description": "Population size for genetic algorithm"
}
}
}
This creates:
- A numeric input field with min/max validation
- Range display showing (10-500)
- Tooltip with the description
- Default value pre-filled
Parameter Categories
Group related parameters for better UI organization:
{
"parameters": {
"population_size": {
"type": "integer",
"default": 50,
"category": "Algorithm",
"description": "Population size"
},
"time_limit": {
"type": "number",
"default": 60.0,
"category": "Execution",
"description": "Time limit in seconds"
}
}
}
Best Practices
1. Comprehensive Parameter Documentation
Always provide clear, detailed descriptions:
{
"crossover_rate": {
"type": "number",
"default": 0.8,
"min": 0.0,
"max": 1.0,
"description": "Probability of crossover between parent solutions. Higher values increase exploration but may reduce convergence speed."
}
}
2. Sensible Default Values
Choose defaults that work well for typical problems:
{
"default_params": {
"population_size": 50, // Good balance of diversity and speed
"generations": 100, // Sufficient for convergence
"mutation_rate": 0.1, // Conservative mutation rate
"crossover_rate": 0.8 // High crossover for exploration
}
}
3. Appropriate Validation Ranges
Set realistic bounds based on algorithm requirements:
{
"temperature": {
"type": "number",
"default": 100.0,
"min": 0.1, // Prevent division by zero
"max": 10000.0, // Reasonable upper bound
"description": "Initial temperature for simulated annealing"
}
}
4. Consistent Naming Conventions
Use clear, consistent parameter names:
{
"time_limit": 60.0, // Not "max_time" or "timeout"
"population_size": 50, // Not "pop_size" or "num_individuals"
"mutation_rate": 0.1 // Not "mut_prob" or "mutation_probability"
}
Template Configurations
Genetic Algorithm Template
{
"type": "optimizer",
"entry_point": "qubot",
"class_name": "GeneticAlgorithm",
"default_params": {
"population_size": 50,
"generations": 100,
"crossover_rate": 0.8,
"mutation_rate": 0.1,
"elite_size": 5,
"tournament_size": 3
},
"parameters": {
"population_size": {
"type": "integer",
"default": 50,
"min": 10,
"max": 500,
"description": "Number of individuals in the population"
},
"generations": {
"type": "integer",
"default": 100,
"min": 10,
"max": 1000,
"description": "Number of generations to evolve"
},
"crossover_rate": {
"type": "number",
"default": 0.8,
"min": 0.0,
"max": 1.0,
"description": "Probability of crossover between parents"
},
"mutation_rate": {
"type": "number",
"default": 0.1,
"min": 0.001,
"max": 1.0,
"description": "Probability of mutation for each gene"
}
},
"metadata": {
"name": "Genetic Algorithm",
"description": "Evolutionary optimization algorithm",
"domain": "general",
"tags": ["genetic", "evolutionary", "metaheuristic"],
"difficulty": "intermediate",
"optimizer_type": "metaheuristic"
}
}
Exact Solver Template
{
"type": "optimizer",
"entry_point": "qubot",
"class_name": "ExactSolver",
"default_params": {
"time_limit": 300.0,
"mip_gap": 0.01,
"presolve": true,
"parallel": true
},
"parameters": {
"time_limit": {
"type": "number",
"default": 300.0,
"min": 1.0,
"max": 3600.0,
"description": "Maximum solving time in seconds"
},
"mip_gap": {
"type": "number",
"default": 0.01,
"min": 0.0001,
"max": 0.5,
"description": "Relative optimality gap tolerance"
},
"presolve": {
"type": "boolean",
"default": true,
"description": "Enable preprocessing to simplify the problem"
}
},
"metadata": {
"name": "Exact Solver",
"description": "Mathematical programming solver",
"optimizer_type": "exact"
}
}
Next Steps
