Quick Start Guide

Quick Start Guide#

This guide will help you get started with OMMX Quantum Benchmarks, which provides standardized access to quantum optimization benchmark datasets in OMMX format.

Installation#

Install this package through pip!

pip install ommx-quantum-benchmarks

Or, you can install it from github, which is arguably the latest version:

pip install git+https://github.com/Jij-Inc/OmmxQuantumBenchmarks.git

Basic Usage#

Let’s start with a simple example using the Marketsplit dataset:

from ommx_quantum_benchmarks.qoblib import Labs

# Create a dataset instance
dataset = Labs()

# Check basic properties
print(f"Dataset name: {dataset.name}")
print(f"Available models: {dataset.model_names}")
print(f"Description: {dataset.description}")

Dataset name: 02_labs
Available 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.

Loading an Instance#

Each dataset contains multiple instances. Let’s load a specific instance:

# Choose a model and instance
model_name = "integer"
instance_name = "labs002"

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

print(f"Loaded instance: {instance_name}")
print(f"Instance type: {type(instance)}")
print(f"Solution type: {type(solution)}")

Loaded instance: labs002
Instance type: <class 'ommx.v1.Instance'>
Solution type: <class 'ommx.v1.Solution'>

Working with Solutions#

OMMX Quantum Benchmarks provides solutions for many instances. You can evaluate and work with these solutions:

if solution is not None:
    # Evaluate the solution using the instance
    evaluated_solution = instance.evaluate(solution.state)
    
    print(f"Original solution objective: {solution.objective}")
    print(f"Evaluated solution objective: {evaluated_solution.objective}")
    print(f"Solution is feasible: {evaluated_solution.feasible}")
    
    # Check if the solutions match
    objectives_match = solution.objective == evaluated_solution.objective
    feasibility_matches = solution.feasible == evaluated_solution.feasible
    
    print(f"Objectives match: {objectives_match}")
    print(f"Feasibility matches: {feasibility_matches}")
else:
    print("No solution available for this instance")

Original solution objective: 1.0
Evaluated solution objective: 1.0
Solution is feasible: True
Objectives match: True
Feasibility matches: True

Exploring Available Instances#

Each dataset has different available instances for different models:

# Check available instances for each model
for model, instances in dataset.available_instances.items():
    print(f"Model '{model}' has {len(instances)} instances:")
    # Show first 5 instances as example
    for instance in instances[:5]:
        print(f"  - {instance}")
    if len(instances) > 5:
        print(f"  ... and {len(instances) - 5} more")
    print()

Model 'integer' has 99 instances:
  - labs002
  - labs003
  - labs004
  - labs005
  - labs006
  ... and 94 more

Model 'quadratic_unconstrained' has 99 instances:
  - labs002
  - labs003
  - labs004
  - labs005
  - labs006
  ... and 94 more

Working with Different Datasets#

OMMX Quantum Benchmarks provides access to multiple optimization problem categories:

from ommx_quantum_benchmarks.qoblib import (
    Marketsplit, Labs, Portfolio, IndependentSet, Topology
)

# Create instances of different datasets
datasets = {
    "Marketsplit": Marketsplit(),
    "Labs": Labs(),
    "Portfolio": Portfolio(),
    "IndependentSet": IndependentSet(),
    "Topology": Topology()
}

# Display information about each dataset
for name, ds in datasets.items():
    print(f"{name}:")
    print(f"  Name: {ds.name}")
    print(f"  Models: {ds.model_names}")
    total_instances = sum(len(instances) for instances in ds.available_instances.values())
    print(f"  Total instances: {total_instances}")
    print()

Marketsplit:
  Name: 01_marketsplit
  Models: ['binary_linear', 'binary_unconstrained']
  Total instances: 0

Labs:
  Name: 02_labs
  Models: ['integer', 'quadratic_unconstrained']
  Total instances: 198

Portfolio:
  Name: 06_portfolio
  Models: ['binary_quadratic', 'quadratic_unconstrained']
  Total instances: 0

IndependentSet:
  Name: 07_independent_set
  Models: ['binary_linear', 'binary_unconstrained']
  Total instances: 0

Topology:
  Name: 10_topology
  Models: ['flow_mip', 'seidel_linear', 'seidel_quadratic']
  Total instances: 0

Next Steps#

Now that you’ve learned the basics, you can:

  1. Explore the Usage Guide for more detailed information about working with datasets and instances

  2. Check out Examples for practical use cases with different problem types

  3. Browse the API Reference for complete documentation of all available classes and methods

Happy optimizing with OMMX Quantum Benchmarks!

Contents