Quickstart

Welcome to Weco!

This quickstart guide will have you optimizing your first piece of code in just a few minutes. By the end, you'll understand how to use Weco's AI-powered optimization to improve your code's performance, quality, and cost metrics.

Before you begin

Make sure you have:

Python 3.8 or newer installed
A terminal or command prompt open
Basic familiarity with Python

Your first optimization

Step 1: Install Weco

pip install weco

Step 2: Get an example project

Let's start with a ready-to-run example. Clone the example repository and navigate to the demo:

git clone https://github.com/WecoAI/weco-cli.git
cd weco-cli/examples/hello-kernel-world
pip install torch

Step 3: Run your first optimization

Now let's optimize some code! You have two options:

Recommended for learning: Run the optimization with explicit parameters to understand what Weco is doing:

weco run --source optimize.py \
    --eval-command "python evaluate.py --solution-path optimize.py --device cpu" \
    --metric speedup \
    --goal maximize \
    --steps 10 \
    --additional-instructions "Fuse operations in the forward method while ensuring the max float deviation remains small. Maintain the same format of the code."

Step 4: Watch the optimization in action

Weco will now iterate through multiple optimization attempts. Here's what you'll see:

Current solution: The code Weco is testing
Evaluation results: Performance metrics for each attempt
Best solution: The highest-performing code so far (this is what you want!)

Weco will:

Analyze your code
Generate optimized versions
Run your evaluation script on each version
Track the best performing solution
Save the winning code when complete

Use Weco with your own code

Now that you've seen Weco in action, let's apply it to your own project.

Understanding evaluation scripts

The key to using Weco is having an evaluation script that:

Benchmarks your code's performance
Validates that optimizations don't break functionality
Prints a metric (like speedup: 2.5x) that Weco can read

Example use cases:

Kernel optimization: Measure PyTorch, CUDA, or Triton kernel execution time → See examples
ML research: Track model accuracy, training speed, or inference latency
Prompt engineering: Evaluate LLM response quality or token efficiency

Pro tip: Check out our guide on Writing Good Evaluation Scripts to get better optimization results.

Step-by-step: Optimize your own code

Step 1: Create your evaluation script

Your evaluation script needs to benchmark the code you'd like to optimize and print a metric you're optimizing for to the console.

Step 2: Run Weco on your code

Here's a complete example showing how to optimize a PyTorch model. You can also follow along in Google Colab.

Install dependencies:

pip install torch weco

Create your code to optimize (optimize.py):

# File: optimize.py
 
import torch
import torch.nn as nn
 
 
class Model(nn.Module):
    """
    Model that performs a matrix multiplication, division, summation, and scaling.
    """
 
    def __init__(self, input_size, hidden_size, scaling_factor):
        super(Model, self).__init__()
        self.weight = nn.Parameter(torch.randn(hidden_size, input_size))
        self.scaling_factor = scaling_factor
 
    def forward(self, x):
        """
        Args:
            x (torch.Tensor): Input tensor of shape (batch_size, input_size).
        Returns:
            torch.Tensor: Output tensor of shape (batch_size, hidden_size).
        """
        x = torch.matmul(x, self.weight.T)
        x = x / 2
        x = torch.sum(x, dim=1, keepdim=True)
        x = x * self.scaling_factor
        return x

Create your evaluation script (evaluate.py):

This script will test each optimization and report how much faster it is:

# File: evaluate.py
 
# 1. Load the baseline model and the optimized model from optimize.py
# Remember to keep a copy of your baseline code in a separate file so that the benchmark can compare it to the generated solution by Weco.
baseline_model = create_baseline_model()
optimized_model = load_model_from_file('optimize.py')
 
# 2. Prepare test data
test_inputs = generate_test_data()
 
# 3. Measure correctness (ensure optimization didn't break functionality)
baseline_output = baseline_model(test_inputs)
optimized_output = optimized_model(test_inputs)
correctness_diff = calculate_max_difference(baseline_output, optimized_output)
if correctness_diff > tolerance:
    raise ValueError(f"Max float diff between values is too high! Got: {correctness_diff}")
 
# 4. Benchmark performance
baseline_time = benchmark(baseline_model, test_inputs)
optimized_time = benchmark(optimized_model, test_inputs)
 
# 5. Calculate and print the final metric for Weco to read
speedup = baseline_time / optimized_time
print(f"speedup: {speedup}")

See the complete example: Full evaluate.py code is available here.

Run the optimization:

weco run --source optimize.py \
     --eval-command "python evaluate.py --solution-path optimize.py --device cpu" \
     --metric speedup \
     --goal maximize \
     --steps 10 \
     --additional-instructions "Fuse operations in the forward method while ensuring the max float deviation remains small. Maintain the same format of the code."

Note: If you have an NVIDIA GPU, change the device in the --eval-command to cuda. If you are running this on Apple Silicon, set it to mps.

What's next?

Now that you've run your first optimization, explore more ways to use Weco:

Example Dashboard Runs - See real optimization runs in the dashboard with impressive results
Local Examples - See Weco optimize CUDA kernels, ML models, and more
Writing Good Evaluation Scripts - Get better results with well-designed benchmarks
CLI Reference - Master all Weco commands and options
FAQ - Find answers to common questions

Getting help

Questions? Check the FAQ or
Found a bug? Report it on GitHub
Feature ideas? We'd love to hear them!

Quickstart

On this page