OPB dataset (cpmpy.tools.datasets.opb)

The Pseudo-Boolean (PB) Competition provides benchmark instances in OPB format. Origin: https://www.cril.univ-artois.fr/PB25/

class cpmpy.tools.datasets.opb.OPBDataset(root: str = '.', year: int = 2024, track: str = 'OPT-LIN', competition: bool = True, transform: Callable | None = None, target_transform: Callable | None = None, download: bool = False, **kwargs: Any)[source]

Pseudo Boolean Competition (PB) benchmark dataset.

Provides access to benchmark instances from the Pseudo Boolean competitions. Instances are grouped by year and track (e.g., “OPT-LIN”, “DEC-LIN”) and stored as .opb.xz files. If the dataset is not available locally, it can be automatically downloaded and extracted.

To load an instance into a CPMpy model, use load_opb(). For examples of using a loader as a dataset transform, see the modeling guide.

Parameters:

  • root (str) – Root directory where datasets are stored or will be downloaded to (default=”.”).

  • year (int) – Competition year of the dataset to use (default=2024).

  • track (str) – Track name specifying which subset of the competition instances to load (default=”OPT-LIN”).

  • competition (bool) – If True, the dataset will filtered on competition-used instances.

  • transform (callable, optional) – Optional transform applied to the instance file path.

  • target_transform (callable, optional) – Optional transform applied to the metadata dictionary.

  • download (bool) – If True, downloads the dataset if it does not exist locally (default=False).

METADATA_EXTENSION: ClassVar[str] = '.meta.json'
categories() → dict[str, Any][source]

Labels to distinguish instances into categories matching to those of the dataset, e.g. year or track.

citation: ClassVar[List[str]] = ['Berre, D. L., Parrain, A. The Pseudo-Boolean Evaluation 2011. JSAT, 7(1), 2012.']
collect_instance_metadata(file: Path) → dict[str, Any][source]

Extract metadata from OPB filename and file header.

Parses the * #variable= … #constraint= … header line and extracts the author from the filename convention (first part before _).

classmethod dataset_metadata() → dict[str, Any]

Return dataset-level metadata as a dictionary.

Returns:

The dataset-level metadata.

Return type:

dict

description: ClassVar[str] = 'Pseudo-Boolean Competition benchmark instances.'
download()[source]

Download the dataset.

homepage: ClassVar[str] = 'https://www.cril.univ-artois.fr/PB25/'
instance_metadata(instance: PathLike) → dict[str, Any]

Return the metadata for a given instance file.

Parameters:

file (os.PathLike) – Path to the instance file.

Returns:

The metadata for the instance.

Return type:

dict

name: ClassVar[str] = 'opb'
classmethod open(instance: PathLike) → TextIOBase[source]

How an instance file from the dataset should be opened. Especially usefull when files come compressed and won’t work with Python standard library’s ‘open’, e.g. ‘.xz’, ‘.lzma’.

Parameters:

instance (os.PathLike) – File path to the instance file.

Returns:

The opened file handle.

Return type:

io.TextIOBase

parse(instance: PathLike) → Any

Parse an instance file into intermediate data structures.

Override this for datasets whose files contain problem data but not an explicit model. Typical outputs are structures like tables, arrays, and dictionaries that can then be passed to a separate model-construction function.

Default behavior is read(instance), i.e. return raw text content.

Parameters:

instance (os.PathLike) – File path to the instance file.

Returns:

The parsed intermediate data structure(s).

read(instance: PathLike) → str

Read raw file contents from an instance file. Handles optional decompression automatically via dataset.open().

Parameters:

instance (os.PathLike) – File path to the instance file.

Returns:

The raw file contents.

Return type:

str