​

How to Upload a Qubot Repository to Rastion

This guide shows you how to upload your optimization algorithms and problems to Rastion, making them available for use in the playground, leaderboards, and community sharing.

​

Prerequisites

Before uploading, ensure you have:

1. GitHub Account: Sign in to Rastion with GitHub
2. Rastion Token: Get your token from Settings → API Access
3. Qubots Framework: pip install qubots
4. Valid Repository: Following Qubots structure

​

Repository Structure

Your repository should follow the Qubots structure:

my-optimizer/
├── qubot.py          # Main optimizer/problem class
├── config.json       # Configuration and metadata
├── requirements.txt  # Python dependencies
└── README.md        # Documentation

​

Example qubot.py (Optimizer)

from qubots import BaseOptimizer
import numpy as np

class GeneticTSPOptimizer(BaseOptimizer):
    def __init__(self, population_size=100, generations=500):
        self.population_size = population_size
        self.generations = generations
    
    def optimize(self, problem):
        # Your optimization logic here
        # Return OptimizationResult
        pass

​

Example config.json

{
  "name": "genetic_tsp_optimizer",
  "type": "optimizer",
  "description": "Genetic algorithm for TSP optimization",
  "version": "1.0.0",
  "author": "Your Name",
  "tags": ["tsp", "genetic", "metaheuristic"],
  "parameters": {
    "population_size": {
      "type": "int",
      "default": 100,
      "min": 10,
      "max": 1000
    },
    "generations": {
      "type": "int", 
      "default": 500,
      "min": 10,
      "max": 5000
    }
  }
}

​

Method 1: Web Interface Upload (Recommended)

​

1. Access Repository Creation

1. Navigate: Go to rastion.com/qubots
2. Sign In: Ensure you’re logged in with GitHub
3. Create Repository: Click “Create New Repository” or ”+” button

​

2. Repository Setup

Fill in the repository details:

• Repository Name: Choose a unique name (e.g., “genetic_tsp_optimizer”)
• Description: Brief description of your algorithm/problem
• Visibility: Public (discoverable) or Private (personal use)
• Initialize: Choose to start with empty repository or upload files

​

3. Upload Files

​

Option A: Drag and Drop

1. Drag Files: Drop your qubot files directly into the browser
2. Automatic Detection: Platform detects qubot.py and config.json
3. Validation: Real-time validation of file structure

​

Option B: File Browser

1. Browse Files: Click “Upload Files” button
2. Select Multiple: Choose all your qubot files at once
3. Commit Message: Add descriptive commit message

​

Method 2: Python SDK Upload

​

1. Install and Authenticate

# Install qubots framework
pip install qubots

# Authenticate with Rastion
import qubots.rastion as rastion
rastion.authenticate("your_rastion_token")

​

2. Upload from Directory

# Upload entire directory
url = rastion.upload_model_from_path(
    path="./my-optimizer",
    repository_name="genetic_tsp_optimizer",
    description="Genetic algorithm for TSP optimization",
    private=False  # Set to True for private repositories
)

print(f"Repository uploaded: {url}")

​

Method 3: Git Integration

​

1. Clone Your Repository

# Get your repository clone URL from Rastion
git clone https://rastion.com/your_username/your_repo.git
cd your_repo

​

2. Add Your Files

# Copy your qubot files
cp /path/to/your/qubot.py .
cp /path/to/your/config.json .
cp /path/to/your/requirements.txt .

# Add and commit
git add .
git commit -m "Add initial qubot implementation"
git push origin main

​

3. Repository Management

The platform provides GitHub-style repository management:

• File Browser: Navigate through your repository files
• Code Viewer: Syntax-highlighted code viewing
• Edit Files: Direct file editing in the browser
• Version History: Track changes and commits
• Collaboration: Add collaborators and manage permissions

​

Validation and Testing

​

1. Automatic Validation

Rastion automatically validates your repository:

• Structure: Checks for required files (qubot.py, config.json)
• Syntax: Python syntax validation
• Dependencies: Verifies requirements.txt compatibility
• Configuration: Validates config.json format and parameters
• Type Detection: Automatically detects if it’s an optimizer or problem

​

2. Repository Status

After upload, check your repository status:

1. Navigate: Go to your repository page at rastion.com/your_username/repo_name
2. Status Badge: Green badge indicates successful validation
3. Issues Tab: View any validation warnings or errors
4. Configuration: Review detected qubot type and parameters

​

3. Test in Playground

Test your uploaded repository immediately:

1. Quick Test: Click “Open in Playground” from your repository page
2. Auto-Load: Your qubot is automatically selected
3. Parameter Setup: Configure parameters using the detected schema
4. Run Test: Execute a quick test to verify functionality

# Or test programmatically
import qubots.rastion as rastion

# Authenticate and load your model
rastion.authenticate("your_token")
optimizer = rastion.load_qubots_model("genetic_tsp_optimizer", username="your_username")

# Test with community problem
problem = rastion.load_qubots_model("tsp_berlin52", username="benchmarks")
result = optimizer.optimize(problem)
print(f"Test result: {result.best_value}")

​

Repository Management

​

Update Repository

​

Web Interface Updates

1. Navigate: Go to your repository page
2. Edit Files: Click on any file to edit directly in browser
3. Upload New Files: Drag and drop additional files
4. Commit Changes: Add commit message and save changes

​

Git-based Updates

# Clone and update
git clone https://rastion.com/your_username/repo_name.git
cd repo_name

# Make changes
# ... edit files ...

# Commit and push
git add .
git commit -m "Improve algorithm performance"
git push origin main

​

Repository Settings

Access repository settings from your repository page:

• Description: Update repository description and tags
• Visibility: Switch between public/private
• Collaborators: Add team members with different permission levels
• Statistics: View download counts, playground usage, and performance metrics
• Integrations: Connect with external tools and services

​

Best Practices

​

Code Quality

• Documentation: Include comprehensive README
• Comments: Well-commented code
• Error Handling: Robust error handling
• Testing: Include unit tests when possible

​

Configuration

• Parameter Validation: Validate input parameters
• Sensible Defaults: Provide reasonable default values
• Clear Descriptions: Document what each parameter does

​

Performance

• Efficiency: Optimize for performance
• Memory Usage: Consider memory constraints
• Scalability: Test with different problem sizes

​

Troubleshooting

​

Common Issues

​

”Repository Name Already Exists”

• Choose a unique repository name
• Check if you already have a repository with that name
• Consider using versioning in the name (e.g., “my_optimizer_v2”)

​

“Validation Failed”

• Missing Files: Ensure qubot.py and config.json are present
• Invalid Config: Check config.json syntax using a JSON validator
• Import Errors: Verify all dependencies are listed in requirements.txt
• Class Definition: Ensure your qubot class inherits from BaseOptimizer or BaseProblem

​

”Upload Timeout”

• Check internet connection stability
• Try uploading smaller files first
• Use Git method for large repositories
• Contact support for repositories >100MB

​

”Permission Denied”

• Verify you’re logged in with GitHub
• Check that your Rastion token is valid
• Ensure you have repository creation permissions

​

Getting Help

• Repository Issues: Check the Issues tab on your repository page
• Community Forum: Ask questions at rastion.com/community
• Documentation: Browse Qubots framework docs
• Examples: Study successful repositories in the community
• Support: Contact support through the platform help center

​

Next Steps

Your repository is now available on Rastion for the community to discover, use, and build upon!