SAT dataset (cpmpy.tools.datasets.sat)

The SAT Competition provides benchmark instances in DIMACS CNF format. Origin: https://benchmark-database.de/

class cpmpy.tools.datasets.sat.SATDataset(root: str = '.', year: int = 2025, track: str = 'main', context: str = 'cnf', transform: Callable | None = None, target_transform: Callable | None = None, download: bool = False, **kwargs: Any)[source]

SAT competition benchmark dataset (DIMACS CNF).

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

Parameters:

  • root (str) – Root directory where the dataset is stored or will be downloaded (default=”.”).

  • year (int) – Competition year (default=2025).

  • track (str) – Competition track (default=”main”).

  • context (str) – Context query parameter for getinstances (default=”cnf”).

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

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

  • download (bool) – If True, download the instance list and all instances if not present (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]] = []
collect_instance_metadata(file: Path) → dict[str, Any][source]

Provide domain-specific instance metadata. Called once after download for each instance.

Parameters:

file – path to the instance file

Returns:

dict with instance-specific metadata fields

classmethod dataset_metadata() → dict[str, Any]

Return dataset-level metadata as a dictionary.

Returns:

The dataset-level metadata.

Return type:

dict

description: ClassVar[str] = 'SAT competition benchmark instances (DIMACS CNF) from benchmark-database.de.'
download()[source]

Download the dataset.

homepage: ClassVar[str] = 'https://benchmark-database.de/'
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] = 'sat'
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