XCSP3 dataset (cpmpy.tools.datasets.xcsp3)

XCSP3 is an XML-based format designed to represent instances of combinatorial constrained problems through Constraint Programming (CP) models. Origin: https://xcsp.org/instances/

class cpmpy.tools.datasets.xcsp3.XCSP3Dataset(root: str = '.', year: int = 2024, track: str = 'CSP', transform: Callable | None = None, target_transform: Callable | None = None, download: bool = False, **kwargs: Any)[source]

XCSP3 Dataset in a PyTorch compatible format.

  • Origin: https://xcsp.org/instances/

  • Reference: Audemard, G., Boussemart, F., Lecoutre, C., Piette, C., Tabary, S. XCSP3: An Integrated Format for Benchmarking Combinatorial Constrained Problems. arXiv:2009.00514, 2020.

Parameters:

  • root (str) – Root directory containing the XCSP3 instances (if ‘download’, instances will be downloaded to this location)

  • year (int) – Competition year (2022, 2023 or 2024)

  • track (str, optional) – Filter instances by track type (e.g., “COP”, “CSP”, “MiniCOP”)

  • transform (callable, optional) – Optional transform to be applied on the instance data (the file path of each problem instance)

  • target_transform (callable, optional) – Optional transform to be applied on the metadata (the metadata dictionary of each problem instance)

  • download (bool) – If True, downloads the dataset from the internet and puts it in root directory

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

  • track

citation: ClassVar[List[str]] = ['Audemard, G., Boussemart, F., Lecoutre, C., Piette, C., Tabary, S. XCSP3: An Integrated Format for Benchmarking Combinatorial Constrained Problems. arXiv:2009.00514, 2020.']
collect_instance_metadata(file: Path) → Dict[str, Any][source]

Extract instance type (CSP/COP) from XCSP3 XML root element.

classmethod dataset_metadata() → Dict[str, Any]

Return dataset-level metadata as a dictionary.

Returns:

The dataset-level metadata.

Return type:

dict

description: ClassVar[str] = 'XCSP3 competition benchmark instances for constraint satisfaction and optimization.'
download()[source]

Download the dataset.

homepage: ClassVar[str] = 'https://xcsp.org/instances/'
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] = 'xcsp3'
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