Usage Guide

Usage Guide#

This section provides detailed information about working with the quantum optimization benchmark datasets available through OMMX Quantum Benchmarks.

Overview#

OMMX Quantum Benchmarks provides access to optimization benchmark datasets converted to OMMX format. Currently, this includes selected datasets from the QOBLIB repository, with plans to expand to additional benchmark sources. The available datasets follow a consistent interface pattern:

  1. Dataset Classes: Each problem category has its own class (e.g., Marketsplit, Labs, Portfolio)

  2. Model Types: Each dataset supports different model formulations (e.g., binary linear, quadratic unconstrained)

  3. Instance Loading: Access specific problem instances using the dataset call interface

Key Concepts#

Datasets#

A dataset represents a collection of related optimization problems. Each dataset has:

  • A unique name and description

  • Multiple model formulations

  • Available instances for each model

  • Standardized access methods

Models#

Different mathematical formulations of the same problem type:

  • Binary Linear: Binary variables with linear constraints

  • Binary Unconstrained: Binary variables without constraints

  • Integer Linear: Integer variables with linear constraints

  • Quadratic Unconstrained: Quadratic objective without constraints

  • Mixed Integer Linear: Mix of continuous and integer variables

Instances#

Specific problem instances within a dataset, each with:

  • Unique identifier (instance name)

  • Problem data in OMMX format

  • Optional optimal or known solution

Working with Datasets#

Basic Dataset Information#

from ommx_quantum_benchmarks.qoblib import Labs

dataset = Labs()
print(f"Name: {dataset.name}")
print(f"Models: {dataset.model_names}")  
print(f"Description: {dataset.description}")

Name: 02_labs
Models: ['integer', 'quadratic_unconstrained']
Description: Labs dataset in ommx format, originally provided by https://git.zib.de/qopt/qoblib-quantum-optimization-benchmarking-library/-/tree/main/02-labs?ref_type=heads.

Exploring Available Instances#

# Get all available instances
for model, instances in dataset.available_instances.items():
    print(f"{model}: {len(instances)} instances")
    for instance in instances[:3]:  # Show first 3 instances for brevity
        print(f"  - {instance}")
    
# Check if specific instance exists
model_name = "integer"
instance_name = "labs002"
if instance_name in dataset.available_instances[model_name]:
    print("Instance found!")

integer: 99 instances
  - labs002
  - labs003
  - labs004
quadratic_unconstrained: 99 instances
  - labs002
  - labs003
  - labs004
Instance found!

Loading Instances and Solutions#

# Load instance and solution
instance, solution = dataset(model_name, instance_name)

# Check if solution is available
if solution is not None:
    print(f"Solution objective: {solution.objective}")
    print(f"Solution feasible: {solution.feasible}")
else:
    print("No solution available for this instance")

Solution objective: 1.0
Solution feasible: True

Next Topics#

Contents