XCSP3 (cpmpy.tools.xcsp3)

Set of utilities for working with XCSP3-formatted CP models.

List of functions

read_xcsp3

Reads in an XCSP3 instance (.xml or .xml.lzma) and returns its matching CPMpy model.

List of helper functions

_parse_xcsp3

Parses an XCSP3 instance file (.xml) and returns a ParserXCSP3 instance.

_load_xcsp3

Takes in a ParserXCSP3 instance and loads its captured model as a CPMpy model.

List of submodules

dataset

PyTorch-style Dataset for XCSP3 competition instances.
cpmpy.tools.xcsp3.decompress_lzma(path: PathLike) → StringIO[source]

Decompresses a .lzma file.

Parameters:

path – Location of .lzma file

Returns:

Memory-mapped decompressed file

cpmpy.tools.xcsp3.read_xcsp3(path: PathLike) → Model[source]

Reads in an XCSP3 instance (.xml or .xml.lzma) and returns its matching CPMpy model.

Parameters:

path – location of the XCSP3 instance to read (expects a .xml or .xml.lzma file).

Returns:

The XCSP3 instance loaded as a CPMpy model.

Analyze (cpmpy.tools.xcsp3.analyze)

Dataset (cpmpy.tools.xcsp3.dataset)

PyTorch-style Dataset for XCSP3 competition instances.

Simply create a dataset instance (configured for the targeted competition year/track) and start iterating over its contents:

from cpmpy.tools.xcsp3 import XCSP3Dataset, read_xcsp3

for filename, metadata in XCSP3Dataset(year=2024, track="COP", download=True): # auto download dataset and iterate over its instances
    # Do whatever you want here, e.g. reading to a CPMpy model and solving it:
    model = read_xcsp3(filename)
    model.solve()
    print(model.status())

The metadata contains usefull information about the current problem instance.

Since the dataset is PyTorch compatible, it can be used with a DataLoader:

from cpmpy.tools.xcsp3 import XCSP3Dataset, read_xcsp3

# Initialize the dataset
dataset = XCSP3Dataset(year=2024, track="COP", download=True)

from torch.utils.data import DataLoader

# Wrap dataset in a DataLoader
data_loader = DataLoader(dataset, batch_size=10, shuffle=False)

# Iterate over the dataset
for batch in data_loader:
    # Your code here
class cpmpy.tools.xcsp3.dataset.XCSP3Dataset(root: str = '.', year: int = 2023, track: str = None, transform=None, target_transform=None, download: bool = False)[source]

XCSP3 Dataset in a PyTorch compatible format.

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

Globals (cpmpy.tools.xcsp3.globals)

Solution (cpmpy.tools.xcsp3.xcsp3_solution)

CLI (cpmpy.tools.xcsp3.xcsp3_cpmpy)

Benchmark (cpmpy.tools.xcsp3.benchmark)