Downloading a QPLIB Instance

Downloading a QPLIB Instance#

The OMMX repository provides quadratic programming benchmark instances from QPLIB in OMMX Artifact format.

Note

dataset.qplib uses the published ghcr.io/jij-inc/ommx/v2.8/qplib:{numeric-tag} distribution (package). These 453 Artifacts were regenerated with corrected quadratic coefficients in OMMX 2.8.0 and can also be read by the v3 SDK. The distribution version is independent of the installed SDK version.

Distribution format or mathematical-model changes require an SDK minor or major release and a new /v{major}.{minor}/ namespace. Patch releases keep their adopted distribution, and published path/tag references remain immutable. The loader selects the corrected distribution even when old unversioned Artifacts are cached. Previously saved instances must be reimported to receive the coefficient correction.

The v2.8 publication record contains the source archive, model comparisons, and published digests.

QPLIB is a library of quadratic programming instances. For more information about QPLIB, see the QPLIB website.

Please see this page for information on GitHub Container Registry.

You can easily download these instances with the OMMX SDK, then directly use them as inputs to OMMX Adapters. For example, to solve the QPLIB_3514 instance (reference) with PySCIPOpt, you can:

  1. Download the 3514 instance with dataset.qplib from the OMMX Python SDK.

  2. Solve with PySCIPOpt via the OMMX PySCIPOpt Adapter.

Here is a sample Python code:

# OMMX Python SDK
from ommx import dataset
# OMMX PySCIPOpt Adapter
from ommx_pyscipopt_adapter import OMMXPySCIPOptAdapter

# Step 1: Download the 3514 instance from QPLIB
instance = dataset.qplib("3514")

# Step 2: Solve with PySCIPOpt via the OMMX PySCIPOpt Adapter
solution = OMMXPySCIPOptAdapter.solve(instance)

This makes it easy to benchmark quadratic programming solvers using the same QPLIB instances.

Evaluate a published solution#

Download the .qplib and .sol files for the same instance from the QPLIB website, then evaluate the published state without running a solver:

from ommx import Instance, State

instance = Instance.load_qplib("QPLIB_0018.qplib")
state = State.load_qplib_solution(
    "QPLIB_0018.sol", num_variables=len(instance.decision_variables)
)
solution = instance.evaluate(state, atol=1e-8)
print(solution.objective, solution.feasible)

Pass the variable count of the original QPLIB instance so that omitted values are filled with zero. State.load_qplib_solution supports the standard names in QPLIB’s published .sol files. The reported objvar value is not a decision variable; Instance.evaluate computes the objective and feasibility from the imported state. See load_qplib_solution() for the file format and error behavior.

Note about Annotations with the Instance#

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

import pandas as pd
# Display annotations in tabular form using pandas
pd.DataFrame.from_dict(instance.annotations, orient="index", columns=["Value"]).sort_index()

These instances have both dataset-level annotations and dataset-specific annotations.

There are seven dataset-wide annotations with dedicated properties:

Annotation

Property

Description

org.ommx.v1.instance.authors

authors

The authors of the instance

org.ommx.v1.instance.constraints

num_constraints

The number of constraint conditions in the instance

org.ommx.v1.instance.created

created

The date of the instance was saved as an OMMX Artifact

org.ommx.v1.instance.dataset

dataset

The name of the dataset to which this instance belongs

org.ommx.v1.instance.license

license

The license of this dataset

org.ommx.v1.instance.title

title

The name of the instance

org.ommx.v1.instance.variables

num_variables

The total number of decision variables in the instance

QPLIB Annotations#

QPLIB instances include comprehensive annotations that describe the mathematical properties of quadratic programming problems. These annotations are based on the official QPLIB specification and are prefixed with org.ommx.qplib.*.

For detailed information about all available QPLIB annotations and their meanings, please refer to the official QPLIB documentation.

For example, you can check the problem type and objective curvature of the QPLIB instance:

# QPLIB-specific annotations
print(f"Problem type: {instance.annotations['org.ommx.qplib.probtype']}")
print(f"Objective type: {instance.annotations['org.ommx.qplib.objtype']}")
print(f"Objective curvature: {instance.annotations['org.ommx.qplib.objcurvature']}")
print(f"Number of variables: {instance.annotations['org.ommx.qplib.nvars']}")
print(f"Number of constraints: {instance.annotations['org.ommx.qplib.ncons']}")
Contents