Skip to content

Quick Start

Get up and running with the Luna Use Cases Collection in minutes!

Your First Benchmark

Let's run a simple TSP (Traveling Salesman Problem) example.

Create the Problem

Create a Python script that defines a 4-city TSP instance:

my_first_luna_usecase.py
import numpy as np
from luna_usecases.traveling_salesman_problem import TspData, TspFormulation, TspInstance

# Create a simple 4-city problem
cities = ["A", "B", "C", "D"]
distances = np.array([
    [0, 10, 15, 20],
    [10, 0, 35, 25],
    [15, 35, 0, 30],
    [20, 25, 30, 0]
])

# Create the problem data
data = TspData.from_distance_matrix(
    distance_matrix=distances,
    city_names=cities,
    start_city="A"
)

# Create formulation and instance
formulation = TspFormulation()
instance = TspInstance(data=data, formulation=formulation)

Formulate the Model

Build the optimization model and inspect its structure:

my_first_luna_usecase.py
# Print the formulation details
print(formulation.to_string(data))

# Generate the optimization model
model = instance.formulate()
print(f"\nModel created with {len(model.variables)} variables")
print(f"Number of constraints: {len(model.constraints)}")

Expected output:

Travelling Salesman Formulation:
  Cities: 4
  Start city: A

Decision Variables:
  x_ij ∈ {0,1} for i=0..3, j=0..3
  x_ij = 1 if city i is at position j in the tour

Objective:
  minimize total tour distance

Constraints:
  1. Each city at exactly one position: Σ_j x_ij = 1  ∀i
  2. Each position has exactly one city: Σ_i x_ij = 1  ∀j

Model created with 16 variables
Number of constraints: 8

Solve with a Solver

Use a solver to find the optimal tour:

solving_luna_usecase.py
from luna_quantum.algorithms import SimulatedAnnealing

# Create and configure your solver
alg = SimulatedAnnealing()

# Solve the model
solution = alg.run(model)

# Interpret the solution
result = instance.interpret(solution)

# Display results
print(result.to_string())

Expected output:

Travelling Salesman Solution:
  Tour: A -> B -> D -> C -> A
  Total distance: 80.00
  Valid: True

Understanding the Workflow

Every use case follows this pattern:

graph LR
    A[Data] --> C[Instance]
    B[Formulation] --> C
    C --> D[Model]
    D --> E[Solver]
    E --> F[Solution]
    F --> G[Interpret]
    G --> H[Results]
  1. Data: Define your problem instance
  2. Formulation: Choose how to model the problem
  3. Instance: Combine data and formulation
  4. Model: Generate the optimization model
  5. Solver: Apply your chosen solver
  6. Solution: Get the raw solution
  7. Interpret: Convert to human-readable results
  8. Results: Analyze and benchmark

Using Benchmark Collections

Each use case provides pre-defined benchmark instances:

working_with_usecase_collections.py
from luna_usecases.traveling_salesman_problem import TspCollection

# Load a collection of TSP instances
collection = TspCollection.load("path/to/collection.json")

# Run benchmarks on all instances
for instance in collection.instances:
    print(f"\nSolving: {instance.data.name}")
    model = instance.formulate()
    print(f"Model created with {len(model.variables)} variables")

Create Your Own Use Case

Create a new directory for your optimization problem and add the required files:

src/luna_usecases/my_problem/
├── __init__.py      # Public exports
├── data.py          # Data model
├── solution.py      # Solution structure
├── formulation.py   # Optimization formulation
├── instance.py      # Instance class
└── collection.py    # Benchmark collection

See Your First Use Case for complete templates you can copy.

Next Steps