QOBLIB Overview

QOBLIB Overview#

This example demonstrates how to work with datasets qoblib in this package.

Current Status Summary#

Dataset	Models	Instance Count	Status
Marketsplit	2	120 per model	✅ Available
Labs	2	99 per model	✅ Available
Birkhoff	1	800	✅ Available
Steiner	1	31	✅ Available
Sports	1	0	🚧 Defined, no instances
Portfolio	2	0	🚧 Defined, no instances
IndependentSet	2	42 per model	✅ Available
Network	1	20	✅ Available
Routing	1	55	✅ Available
Topology	3	16 per model	✅ Available

Legend:

✅ Available: Instances have been converted and are accessible
🚧 Defined, no instances: Dataset classes exist but no instances are currently available

Common Usage Pattern for QOBLIB Datasets#

All QOBLIB datasets follow this consistent interface:

from ommx_quantum_benchmarks.qoblib import DatasetName

# Instantiate any dataset
dataset = DatasetName()

# Check properties
print(f"Name: {dataset.name}")
print(f"Models: {dataset.model_names}")
print(f"Available instances: {dataset.available_instances}")

# Load instance and solution (if available)
if dataset.available_instances[model_name]:
    instance, solution = dataset(model_name, instance_name)

Individual Datasets#

Marketsplit (`01_marketsplit`)#

Problem Type: Market split optimization problems
Models: Binary linear, Binary unconstrained
Instances: 120 instances per model (ms_03_050_002 - ms_15_200_003)

from ommx_quantum_benchmarks.qoblib import Marketsplit

dataset = Marketsplit()
print(f"Available models: {dataset.model_names}")
for model in dataset.model_names:
    instances = dataset.available_instances[model]
    print(f"{model}: {len(instances)} instances")

(instance, solution) = dataset("binary_linear", "ms_03_050_002")
# Show the info.
print(f"Instance type: {type(instance)}")
print(f"The number of variables: {instance.num_variables}")
print(f"The number of constraints: {instance.num_constraints}")
print(f"Solution available: {solution is not None}")
# If a solution is available, show its details.
if solution:
    print(f"Objective value: {solution.objective}")
    print(f"Feasible: {solution.feasible}")
    print(f"Number of variables: {len(solution.state.entries)}")

Available models: ['binary_linear', 'binary_unconstrained']
binary_linear: 156 instances
binary_unconstrained: 156 instances
Instance type: <class 'ommx.v1.Instance'>
The number of variables: 23
The number of constraints: 3
Solution available: True
Objective value: 0.0
Feasible: True
Number of variables: 23

Labs (`02_labs`)#

Problem Type: Low autocorrelation binary sequences
Models: Integer, Quadratic unconstrained
Instances: 99 instances (labs002 - labs100)

from ommx_quantum_benchmarks.qoblib import Labs

dataset = Labs()
print(f"Available models: {dataset.model_names}")
for model in dataset.model_names:
    instances = dataset.available_instances[model]
    print(f"{model}: {len(instances)} instances")

(instance, solution) = dataset("integer", "labs002")
# Show the info.
print(f"Instance type: {type(instance)}")
print(f"The number of variables: {instance.num_variables}")
print(f"The number of constraints: {instance.num_constraints}")
print(f"Solution available: {solution is not None}")
# If a solution is available, show its details.
if solution:
    print(f"Objective value: {solution.objective}")
    print(f"Feasible: {solution.feasible}")
    print(f"Number of variables: {len(solution.state.entries)}")

Available models: ['integer', 'quadratic_unconstrained']
integer: 99 instances
quadratic_unconstrained: 99 instances
Instance type: <class 'ommx.v1.Instance'>
The number of variables: 3
The number of constraints: 1
Solution available: True
Objective value: 1.0
Feasible: True
Number of variables: 3

Birkhoff (`03_birkhoff`)#

Problem Type: Minimum birkhoff decomposition
Models: Integer linear
Instances: 800 instances (bhD-3-001 - bhS-6-100)

from ommx_quantum_benchmarks.qoblib import Birkhoff

dataset = Birkhoff()
print(f"Available models: {dataset.model_names}")
for model in dataset.model_names:
    instances = dataset.available_instances[model]
    print(f"{model}: {len(instances)} instances")

(instance, solution) = dataset("integer_linear", "bhD-3-001")
# Show the info.
print(f"Instance type: {type(instance)}")
print(f"The number of variables: {instance.num_variables}")
print(f"The number of constraints: {instance.num_constraints}")
print(f"Solution available: {solution is not None}")
# If a solution is available, show its details.
if solution:
    print(f"Objective value: {solution.objective}")
    print(f"Feasible: {solution.feasible}")
    print(f"Number of variables: {len(solution.state.entries)}")

Available models: ['integer_linear']
integer_linear: 800 instances
Instance type: <class 'ommx.v1.Instance'>
The number of variables: 12
The number of constraints: 16
Solution available: True
Objective value: 5.0
Feasible: True
Number of variables: 12

Steiner (`04_steiner`)#

Problem Type: Steiner tree packing problem
Models: Integer linear
Instances: 31 instances (stp_s020_l2_t3_h2_rs24098 - stp_s040_l2_t4_h3_rs123)

from ommx_quantum_benchmarks.qoblib import Steiner

dataset = Steiner()
print(f"Available models: {dataset.model_names}")
for model in dataset.model_names:
    instances = dataset.available_instances[model]
    print(f"{model}: {len(instances)} instances")

(instance, solution) = dataset("integer_linear", "stp_s020_l2_t3_h2_rs24098")
# Show the info.
print(f"Instance type: {type(instance)}")
print(f"The number of variables: {instance.num_variables}")
print(f"The number of constraints: {instance.num_constraints}")
print(f"Solution available: {solution is not None}")
# If a solution is available, show its details.
if solution:
    print(f"Objective value: {solution.objective}")
    print(f"Feasible: {solution.feasible}")
    print(f"Number of variables: {len(solution.state.entries)}")

Available models: ['integer_linear']
integer_linear: 31 instances
Instance type: <class 'ommx.v1.Instance'>
The number of variables: 78476
The number of constraints: 41381
Solution available: True
Objective value: 228.0
Feasible: True
Number of variables: 78476

Sports (`05_sports`)#

Problem Type: Sports scheduling problems
Models: Mixed integer linear
Instances: 0 instances at the moment

Portfolio (`06_portfolio`)#

Problem Type: Portfolio optimisation
Models: Binary quadratic and quadratic unconstrained
Instances: 0 instances at the moment

Independent Set (`07_independentset`)#

Problem Type: Maximum independent set problems
Models: Binary linear, Binary unconstrained
Instances: 42 instances per model

from ommx_quantum_benchmarks.qoblib import IndependentSet

dataset = IndependentSet()
print(f"Available models: {dataset.model_names}")
for model in dataset.model_names:
    instances = dataset.available_instances[model]
    print(f"{model}: {len(instances)} instances")

(instance, solution) = dataset("binary_linear", "aves-sparrow-social")
# Show the info.
print(f"Instance type: {type(instance)}")
print(f"The number of variables: {instance.num_variables}")
print(f"The number of constraints: {instance.num_constraints}")
print(f"Solution available: {solution is not None}")
# If a solution is available, show its details.
if solution:
    print(f"Objective value: {solution.objective}")
    print(f"Feasible: {solution.feasible}")
    print(f"Number of variables: {len(solution.state.entries)}")

Available models: ['binary_linear', 'binary_unconstrained']
binary_linear: 42 instances
binary_unconstrained: 42 instances
Instance type: <class 'ommx.v1.Instance'>
The number of variables: 52
The number of constraints: 454
Solution available: True
Objective value: 13.0
Feasible: True
Number of variables: 52

Network (`08_network`)#

Problem Type: Network design
Models: Integer LP
Instances: 20 instances

from ommx_quantum_benchmarks.qoblib import Network

dataset = Network()
print(f"Available models: {dataset.model_names}")
for model in dataset.model_names:
    instances = dataset.available_instances[model]
    print(f"{model}: {len(instances)} instances")

(instance, solution) = dataset("integer_lp", "network05")
# Show the info.
print(f"Instance type: {type(instance)}")
print(f"The number of variables: {instance.num_variables}")
print(f"The number of constraints: {instance.num_constraints}")
print(f"Solution available: {solution is not None}")
# If a solution is available, show its details.
if solution:
    print(f"Objective value: {solution.objective}")
    print(f"Feasible: {solution.feasible}")
    print(f"Number of variables: {len(solution.state.entries)}")

Available models: ['integer_lp']
integer_lp: 20 instances
Instance type: <class 'ommx.v1.Instance'>
The number of variables: 151
The number of constraints: 130
Solution available: True
Objective value: 65500.0
Feasible: True
Number of variables: 151

Routing (`09_routing`)#

Problem Type: Vehicle routing
Models: Integer linear
Instances: 55 instances

from ommx_quantum_benchmarks.qoblib import Routing

dataset = Routing()
print(f"Available models: {dataset.model_names}")
for model in dataset.model_names:
    instances = dataset.available_instances[model]
    print(f"{model}: {len(instances)} instances")

(instance, solution) = dataset("integer_linear", "XSH-n20-k4-01")
# Show the info.
print(f"Instance type: {type(instance)}")
print(f"The number of variables: {instance.num_variables}")
print(f"The number of constraints: {instance.num_constraints}")
print(f"Solution available: {solution is not None}")
# If a solution is available, show its details.
if solution:
    print(f"Objective value: {solution.objective}")
    print(f"Feasible: {solution.feasible}")
    print(f"Number of variables: {len(solution.state.entries)}")

Available models: ['integer_linear']
integer_linear: 55 instances
Instance type: <class 'ommx.v1.Instance'>
The number of variables: 462
The number of constraints: 483
Solution available: True
Objective value: 646.0
Feasible: True
Number of variables: 462

Topology (`10_topology`)#

Problem Type: Topology design
Models: Flow MIP, Seidel linear, Seidel quadratic
Instances: 16 instances per model

from ommx_quantum_benchmarks.qoblib import Topology

dataset = Topology()
print(f"Available models: {dataset.model_names}")
for model in dataset.model_names:
    instances = dataset.available_instances[model]
    print(f"{model}: {len(instances)} instances")

(instance, solution) = dataset("flow_mip", "topology_15_3")
# Show the info.
print(f"Instance type: {type(instance)}")
print(f"The number of variables: {instance.num_variables}")
print(f"The number of constraints: {instance.num_constraints}")
print(f"Solution available: {solution is not None}")
# If a solution is available, show its details.
if solution:
    print(f"Objective value: {solution.objective}")
    print(f"Feasible: {solution.feasible}")
    print(f"Number of variables: {len(solution.state.entries)}")

Available models: ['flow_mip', 'seidel_linear', 'seidel_quadratic']
flow_mip: 16 instances
seidel_linear: 16 instances
seidel_quadratic: 16 instances
Instance type: <class 'ommx.v1.Instance'>
The number of variables: 51076
The number of constraints: 23850
Solution available: True
Objective value: 3.0
Feasible: True
Number of variables: 51076

Note about Annotations#

The downloaded instance includes various annotations accessible via the annotations property.

Annotation	Property	Description
`org.ommx.v1.instance.title`	`title`	The name of the instance
`org.ommx.v1.instance.license`	`license`	The license of the dataset
`org.ommx.v1.instance.dataset`	`dataset`	The name of the dataset to which this instance belongs
`org.ommx.v1.instance.authors`	`authors`	The authors of the instnce
`org.ommx.v1.instance.variables`	`num_variables`	The total nuimber of decision variables in the instance
`org.ommx.v1.instance.constraints`	`num_constraints`	The total number of constraint conditions in the instance

So does solution.

Annotation	Property	Description
`org.ommx.v1.solution.instance`	`instance`	The digest of the instance to which this solution applies

QOBLIB Overview

Contents

QOBLIB Overview#

Current Status Summary#

Common Usage Pattern for QOBLIB Datasets#

Individual Datasets#

Marketsplit (01_marketsplit)#

Labs (02_labs)#

Birkhoff (03_birkhoff)#

Steiner (04_steiner)#

Sports (05_sports)#

Portfolio (06_portfolio)#

Independent Set (07_independentset)#

Network (08_network)#

Routing (09_routing)#

Topology (10_topology)#