Nurse rostering dataset (cpmpy.tools.datasets.nurserostering)

Nurse rostering is a staff scheduling problem; instances come from schedulingbenchmarks.org. Origin: https://schedulingbenchmarks.org/nrp/

class cpmpy.tools.datasets.nurserostering.NurseRosteringDataset(root: str = '.', transform: Callable | None = None, target_transform: Callable | None = None, download: bool = False, **kwargs: Any)

Nurserostering Dataset in a PyTorch compatible format.

• Origin: https://schedulingbenchmarks.org/nrp/

• References:

  • Strandmark, P., Qu, Y. and Curtois, T. First-order linear programming in a column generation-based heuristic approach to the nurse rostering problem. Computers & Operations Research, 2020. 120, p. 104945.

  • Demirovic, E., Musliu, N., and Winter, F. Modeling and solving staff scheduling with partial weighted maxSAT. Annals of Operations Research, 2019. 275(1): p. 79-99.

  • Smet P. Constraint reformulation for nurse rostering problems, in: PATAT 2018 twelfth international conference on the practice and theory of automated timetabling, Vienna, August, 2018, p. 69-80.

  • Rahimian, E., Akartunali, K., and Levine, J. A hybrid integer programming and variable neighbourhood search algorithm to solve nurse rostering problems. European Journal of Operational Research, 2017. 258(2): p. 411-423.

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

Parameters:

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

• 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]

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

citation: ClassVar[List[str]] = ['Strandmark, P., Qu, Y. and Curtois, T. First-order linear programming in a column generation-based heuristic approach to the nurse rostering problem. Computers & Operations Research, 2020. 120, p. 104945.', 'Demirovic, E., Musliu, N., and Winter, F. Modeling and solving staff scheduling with partial weighted maxSAT. Annals of Operations Research, 2019. 275(1): p. 79-99.', 'Smet P. Constraint reformulation for nurse rostering problems, in: PATAT 2018 twelfth international conference on the practice and theory of automated timetabling, Vienna, August, 2018, p. 69-80.', 'Rahimian, E., Akartunali, K., and Levine, J. A hybrid integer programming and variable neighbourhood search algorithm to solve nurse rostering problems. European Journal of Operational Research, 2017. 258(2): p. 411-423.']

collect_instance_metadata(file: Path) → dict[str, Any]

Extract scheduling metadata from nurse rostering instance.

classmethod dataset_metadata() → dict[str, Any]

Return dataset-level metadata as a dictionary.

Returns:

The dataset-level metadata.

Return type:

dict

description: ClassVar[str] = 'Nurse rostering benchmark instances from schedulingbenchmarks.org.'

download()

Download the dataset.

homepage: ClassVar[str] = 'https://schedulingbenchmarks.org/nrp/'

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] = 'nurserostering'

classmethod open(instance: PathLike) → TextIOBase

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

classmethod parse(instance: PathLike) → dict[str, Any]

Parse a nurse rostering instance into native Python data structures.

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