MaxSAT Evaluation dataset (cpmpy.tools.datasets.mse)

The MaxSAT Evaluation (MSE) is an annual competition of MaxSAT solvers, providing benchmark instances. Origin: https://maxsat-evaluations.github.io/

class cpmpy.tools.datasets.mse.MaxSATEvalDataset(root: str = '.', year: int = 2024, track: str = 'exact-unweighted', transform: Callable | None = None, target_transform: Callable | None = None, download: bool = False, dataset_dir: PathLike | None = None, **kwargs: Any)[source]

MaxSAT Evaluation benchmark dataset.

Provides access to benchmark instances from the MaxSAT Evaluation competitions. Instances are grouped by year and track (e.g., “exact-unweighted”, “exact-weighted”) and stored as .wcnf.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_wcnf(). 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=”.”). If dataset_dir is provided, this argument is ignored.

  • 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=”exact-unweighted”).

  • 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).

  • dataset_dir (Optional[os.PathLike]) – Path to the dataset directory. If not provided, it will be inferred from the root and year/track.

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]] = []
collect_instance_metadata(file: Path) → dict[str, Any][source]

Extract statistics from WCNF header comments.

WCNF files from MSE contain JSON-like statistics in comment lines: nvars, ncls, nhards, nsofts, total_lits, nsoft_wts, and length stats.

classmethod dataset_metadata() → dict[str, Any]

Return dataset-level metadata as a dictionary.

Returns:

The dataset-level metadata.

Return type:

dict

description: ClassVar[str] = 'MaxSAT Evaluation competition benchmark instances.'
download()[source]

Download the dataset.

homepage: ClassVar[str] = 'https://maxsat-evaluations.github.io/'
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] = 'maxsateval'
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