job-shop-lib 0.5.1__py3-none-any.whl → 1.0.0__py3-none-any.whl

job_shop_lib/{schedule.py → _schedule.py}

@@ -2,78 +2,88 @@
 
 from __future__ import annotations
 
-from typing import Any
+from typing import Any, List, Union, Dict, Optional
 from collections import deque
 
-from job_shop_lib import ScheduledOperation, JobShopInstance, JobShopLibError
+from job_shop_lib import ScheduledOperation, JobShopInstance
+from job_shop_lib.exceptions import ValidationError
 
 
 class Schedule:
-    """Data structure to store a schedule for a `JobShopInstance` object.
+    """Data structure to store a complete or partial solution for a particular
+    :class:`JobShopInstance`.
 
-    Attributes:
+    A schedule is a list of lists of :class:`ScheduledOperation` objects. Each
+    list represents the order of operations on a machine.
+
+    The main methods of this class are:
+
+    .. autosummary::
+        :nosignatures:
+
+        makespan
+        is_complete
+        add
+        reset
+
+    Args:
         instance:
-            The `JobShopInstance` object that the schedule is for.
+            The :class:`JobShopInstance` object that the schedule is for.
         schedule:
-            A list of lists of `ScheduledOperation` objects. Each list of
-            `ScheduledOperation` objects represents the order of operations
-            on a machine.
-        metadata:
-            A dictionary with additional information about the schedule. It
-            can be used to store information about the algorithm that generated
-            the schedule, for example.
+            A list of lists of :class:`ScheduledOperation` objects. Each
+            list represents the order of operations on a machine. If
+            not provided, the schedule is initialized as an empty schedule.
+        **metadata:
+            Additional information about the schedule.
     """
 
-    __slots__ = (
-        "instance",
-        "_schedule",
-        "metadata",
-    )
+    __slots__ = {
+        "instance": (
+            "The :class:`JobShopInstance` object that the schedule is for."
+        ),
+        "_schedule": (
+            "A list of lists of :class:`ScheduledOperation` objects. "
+            "Each list represents the order of operations on a machine."
+        ),
+        "metadata": (
+            "A dictionary with additional information about the "
+            "schedule. It can be used to store information about the "
+            "algorithm that generated the schedule, for example."
+        ),
+    }
 
     def __init__(
         self,
         instance: JobShopInstance,
-        schedule: list[list[ScheduledOperation]] | None = None,
-        **metadata,
+        schedule: Optional[List[List[ScheduledOperation]]] = None,
+        **metadata: Any,
     ):
-        """Initializes the object with the given instance and schedule.
-
-        Args:
-            instance:
-                The `JobShopInstance` object that the schedule is for.
-            schedule:
-                A list of lists of `ScheduledOperation` objects. Each list of
-                `ScheduledOperation` objects represents the order of operations
-                on a machine. If not provided, the schedule is initialized as
-                an empty schedule.
-            **metadata:
-                Additional information about the schedule.
-        """
         if schedule is None:
             schedule = [[] for _ in range(instance.num_machines)]
 
         Schedule.check_schedule(schedule)
 
-        self.instance = instance
+        self.instance: JobShopInstance = instance
         self._schedule = schedule
-        self.metadata = metadata
+        self.metadata: Dict[str, Any] = metadata
 
     def __repr__(self) -> str:
         return str(self.schedule)
 
     @property
-    def schedule(self) -> list[list[ScheduledOperation]]:
-        """Returns the schedule attribute."""
+    def schedule(self) -> List[List[ScheduledOperation]]:
+        """A list of lists of :class:`ScheduledOperation` objects. Each list
+        represents the order of operations on a machine."""
         return self._schedule
 
     @schedule.setter
-    def schedule(self, new_schedule: list[list[ScheduledOperation]]):
+    def schedule(self, new_schedule: List[List[ScheduledOperation]]):
         Schedule.check_schedule(new_schedule)
         self._schedule = new_schedule
 
     @property
     def num_scheduled_operations(self) -> int:
-        """Returns the number of operations that have been scheduled."""
+        """The number of operations that have been scheduled so far."""
         return sum(len(machine_schedule) for machine_schedule in self.schedule)
 
     def to_dict(self) -> dict:
@@ -84,15 +94,16 @@ class Schedule:
         Returns:
             A dictionary representation of the schedule with the following
             keys:
-                - "instance": A dictionary representation of the instance.
-                - "job_sequences": A list of lists of job ids. Each list of job
-                    ids represents the order of operations on the machine. The
-                    machine that the list corresponds to is determined by the
-                    index of the list.
-                - "metadata": A dictionary with additional information about
-                    the schedule.
+
+                - **"instance"**: A dictionary representation of the instance.
+                - **"job_sequences"**: A list of lists of job ids. Each list
+                  of job ids represents the order of operations on the machine.
+                  The machine that the list corresponds to is determined by the
+                  index of the list.
+                - **"metadata"**: A dictionary with additional information
+                  about the schedule.
         """
-        job_sequences: list[list[int]] = []
+        job_sequences: List[List[int]] = []
         for machine_schedule in self.schedule:
             job_sequences.append(
                 [operation.job_id for operation in machine_schedule]
@@ -106,9 +117,9 @@ class Schedule:
 
     @staticmethod
     def from_dict(
-        instance: dict[str, Any] | JobShopInstance,
-        job_sequences: list[list[int]],
-        metadata: dict[str, Any] | None = None,
+        instance: Union[Dict[str, Any], JobShopInstance],
+        job_sequences: List[List[int]],
+        metadata: Optional[Dict[str, Any]] = None,
     ) -> Schedule:
         """Creates a schedule from a dictionary representation."""
         if isinstance(instance, dict):
@@ -120,7 +131,7 @@ class Schedule:
     @staticmethod
     def from_job_sequences(
         instance: JobShopInstance,
-        job_sequences: list[list[int]],
+        job_sequences: List[List[int]],
     ) -> Schedule:
         """Creates an active schedule from a list of job sequences.
 
@@ -131,14 +142,14 @@ class Schedule:
 
         Args:
             instance:
-                The `JobShopInstance` object that the schedule is for.
+                The :class:`JobShopInstance` object that the schedule is for.
             job_sequences:
                 A list of lists of job ids. Each list of job ids represents the
                 order of operations on the machine. The machine that the list
                 corresponds to is determined by the index of the list.
 
         Returns:
-            A `Schedule` object with the given job sequences.
+            A :class:`Schedule` object with the given job sequences.
         """
         from job_shop_lib.dispatching import Dispatcher
 
@@ -161,7 +172,7 @@ class Schedule:
                     at_least_one_operation_scheduled = True
 
             if not at_least_one_operation_scheduled:
-                raise JobShopLibError(
+                raise ValidationError(
                     "Invalid job sequences. No valid operation to schedule."
                 )
         return dispatcher.schedule
@@ -182,18 +193,19 @@ class Schedule:
         return max_end_time
 
     def is_complete(self) -> bool:
-        """Returns True if all operations have been scheduled."""
+        """Returns ``True`` if all operations have been scheduled."""
         return self.num_scheduled_operations == self.instance.num_operations
 
     def add(self, scheduled_operation: ScheduledOperation):
-        """Adds a new `ScheduledOperation` to the schedule.
+        """Adds a new :class:`ScheduledOperation` to the schedule.
 
         Args:
             scheduled_operation:
-                The `ScheduledOperation` to add to the schedule.
+                The :class:`ScheduledOperation` to add to the schedule.
 
         Raises:
-            ValueError: If the start time of the new operation is before the
+            ValidationError:
+                If the start time of the new operation is before the
                 end time of the last operation on the same machine. In favor of
                 performance, this method does not checks precedence
                 constraints.
@@ -212,49 +224,45 @@ class Schedule:
             return
 
         last_operation = self.schedule[new_operation.machine_id][-1]
-        self._check_start_time(new_operation, last_operation)
+        if not self._is_valid_start_time(new_operation, last_operation):
+            raise ValidationError(
+                "Operation cannot be scheduled before the last operation on "
+                "the same machine: end time of last operation "
+                f"({last_operation.end_time}) > start time of new operation "
+                f"({new_operation.start_time})."
+            )
 
     @staticmethod
-    def _check_start_time(
+    def _is_valid_start_time(
         scheduled_operation: ScheduledOperation,
         previous_operation: ScheduledOperation,
     ):
-        """Raises a ValueError if the start time of the new operation is before
-        the end time of the last operation on the same machine."""
-
-        if previous_operation.end_time <= scheduled_operation.start_time:
-            return
-
-        raise ValueError(
-            "Operation cannot be scheduled before the last operation on "
-            "the same machine: end time of last operation "
-            f"({previous_operation.end_time}) > start time of new operation "
-            f"({scheduled_operation.start_time})."
-        )
+        return previous_operation.end_time <= scheduled_operation.start_time
 
     @staticmethod
-    def check_schedule(schedule: list[list[ScheduledOperation]]):
-        """Checks if a schedule is valid and raises a ValueError if it is not.
+    def check_schedule(schedule: List[List[ScheduledOperation]]):
+        """Checks if a schedule is valid and raises a
+        :class:`~exceptions.ValidationError` if it is not.
 
         A schedule is considered invalid if:
-            - A `ScheduledOperation` has a machine id that does not match the
-              machine id of the machine schedule (the list of
-              `ScheduledOperation` objects) that it belongs to.
-            - The start time of a `ScheduledOperation` is before the end time
-              of the last operation on the same machine.
+            - A :class:`ScheduledOperation` has a machine id that does not
+              match the machine id of the machine schedule (the list of
+              :class:`ScheduledOperation` objects) that it belongs to.
+            - The start time of a :class:`ScheduledOperation` is before the
+              end time of the last operation on the same machine.
 
         Args:
             schedule:
-                The schedule (a list of lists of `ScheduledOperation` objects)
-                to check.
+                The schedule (a list of lists of :class:`ScheduledOperation`
+                objects) to check.
 
         Raises:
-            ValueError: If the schedule is invalid.
+            ValidationError: If the schedule is invalid.
         """
         for machine_id, scheduled_operations in enumerate(schedule):
             for i, scheduled_operation in enumerate(scheduled_operations):
                 if scheduled_operation.machine_id != machine_id:
-                    raise ValueError(
+                    raise ValidationError(
                         "The machine id of the scheduled operation "
                         f"({ScheduledOperation.machine_id}) does not match "
                         f"the machine id of the machine schedule ({machine_id}"
@@ -264,9 +272,19 @@ class Schedule:
                 if i == 0:
                     continue
 
-                Schedule._check_start_time(
+                if not Schedule._is_valid_start_time(
                     scheduled_operation, scheduled_operations[i - 1]
-                )
+                ):
+                    raise ValidationError(
+                        "Invalid schedule. The start time of the new "
+                        "operation is before the end time of the last "
+                        "operation on the same machine."
+                        "End time of last operation: "
+                        f"{scheduled_operations[i - 1].end_time}. "
+                        f"Start time of new operation: "
+                        f"{scheduled_operation.start_time}. At index "
+                        f"[{machine_id}][{i}]."
+                    )
 
     def __eq__(self, value: object) -> bool:
         if not isinstance(value, Schedule):

job_shop_lib/{scheduled_operation.py → _scheduled_operation.py}

@@ -1,42 +1,37 @@
 """Home of the `ScheduledOperation` class."""
 
-from warnings import warn
-
-from job_shop_lib import Operation, JobShopLibError
+from job_shop_lib import Operation
+from job_shop_lib.exceptions import ValidationError
 
 
 class ScheduledOperation:
     """Data structure to store a scheduled operation.
 
-    Attributes:
+    Args:
         operation:
-            The `Operation` object that is scheduled.
+            The :class:`Operation` object that is scheduled.
         start_time:
             The time at which the operation is scheduled to start.
         machine_id:
             The id of the machine on which the operation is scheduled.
+
+    Raises:
+        ValidationError:
+            If the given machine_id is not in the list of valid machines
+            for the operation.
     """
 
-    __slots__ = ("operation", "start_time", "_machine_id")
+    __slots__ = {
+        "operation": "The :class:`Operation` object that is scheduled.",
+        "start_time": "The time at which the operation is scheduled to start.",
+        "_machine_id": (
+            "The id of the machine on which the operation is scheduled."
+        ),
+    }
 
     def __init__(self, operation: Operation, start_time: int, machine_id: int):
-        """Initializes the object with the given operation, start time, and
-        machine id.
-
-        Args:
-            operation:
-                The `Operation` object that is scheduled.
-            start_time:
-                The time at which the operation is scheduled to start.
-            machine_id:
-                The id of the machine on which the operation is scheduled.
-
-        Raises:
-            ValueError:
-                If the machine_id is not valid for the operation.
-        """
-        self.operation = operation
-        self.start_time = start_time
+        self.operation: Operation = operation
+        self.start_time: int = start_time
         self._machine_id = machine_id
         self.machine_id = machine_id  # Validate machine_id
 
@@ -49,7 +44,7 @@ class ScheduledOperation:
     @machine_id.setter
     def machine_id(self, value: int):
         if value not in self.operation.machines:
-            raise JobShopLibError(
+            raise ValidationError(
                 f"Operation cannot be scheduled on machine {value}. "
                 f"Valid machines are {self.operation.machines}."
             )
@@ -57,35 +52,13 @@ class ScheduledOperation:
 
     @property
     def job_id(self) -> int:
-        """Returns the id of the job that the operation belongs to.
-
-        Raises:
-            ValueError: If the operation has no job_id.
-        """
-
-        if self.operation.job_id is None:
-            raise JobShopLibError("Operation has no job_id.")
+        """Returns the id of the job that the operation belongs to."""
         return self.operation.job_id
 
-    @property
-    def position(self) -> int:
-        """Deprecated. Use `position_in_job` instead."""
-        warn(
-            "The `position` attribute is deprecated. Use `position_in_job` "
-            "instead. It will be removed in version 1.0.0.",
-            DeprecationWarning,
-        )
-        return self.position_in_job
-
     @property
     def position_in_job(self) -> int:
-        """Returns the position (starting at zero) of the operation in the job.
-
-        Raises:
-            ValueError: If the operation has no position_in_job.
-        """
-        if self.operation.position_in_job is None:
-            raise JobShopLibError("Operation has no position.")
+        """Returns the position (starting at zero) of the operation in the
+        job."""
         return self.operation.position_in_job
 
     @property
@@ -107,3 +80,6 @@ class ScheduledOperation:
             and self.start_time == value.start_time
             and self.machine_id == value.machine_id
         )
+
+    def __hash__(self) -> int:
+        return hash((self.operation, self.start_time, self.machine_id))

job_shop_lib/benchmarking/__init__.py

@@ -1,71 +1,94 @@
-"""Package for loading benchmark instances.
+"""Contains functions to load benchmark instances.
 
-All benchmark instances are stored in a single JSON file. This module provides
-functions to load the instances from the file and return them as
-JobShopInstance objects.
+.. autosummary::
+
+    load_all_benchmark_instances
+    load_benchmark_instance
+    load_benchmark_json
+
+You can load a benchmark instance from the library:
+
+.. code-block:: python
+
+    from job_shop_lib.benchmarking import load_benchmark_instance
+
+    ft06 = load_benchmark_instance("ft06")
+
+
+This package contains functions to load the instances from the file
+and return them as :class:`JobShopInstance` objects without having to download
+them manually.
 
 The contributions to this benchmark dataset are as follows:
 
-abz5-9: This subset, comprising five instances, was introduced by Adams et
-    al. (1988).
-ft06, ft10, ft20: These three instances are attributed to the work of
-    Fisher and Thompson, as detailed in their 1963 work.
-la01-40: A collection of forty instances, this group was contributed by
-    Lawrence, as referenced in his 1984 report.
-orb01-10: Ten instances in this category were provided by Applegate and
-    Cook, as seen in their 1991 study.
-swb01-20: This segment, encompassing twenty instances, was contributed by
-    Storer et al., as per their 1992 article.
-yn1-4: Yamada and Nakano are credited with the addition of four instances
-    in this group, as found in their 1992 paper.
-ta01-80: The largest contribution, consisting of eighty instances, was
-    made by Taillard, as documented in his 1993 paper.
+- ``abz5-9``: by Adams et al. (1988).
 
-The metadata from these instances has been updated using data from:
+- ``ft06``, ``ft10``, ``ft20``: by Fisher and Thompson (1963).
+
+- ``la01-40``: by Lawrence (1984)
 
-Thomas Weise. jsspInstancesAndResults. Accessed in January 2024.
-Available at: https://github.com/thomasWeise/jsspInstancesAndResults
+- ``orb01-10``: by Applegate and Cook (1991).
+
+- ``swb01-20``: by Storer et al. (1992).
+
+- ``yn1-4``: by Yamada and Nakano (1992).
+
+- ``ta01-80``: by Taillard (1993).
+
+The metadata from these instances has been updated using data from:
+https://github.com/thomasWeise/jsspInstancesAndResults
 
 It includes the following information:
-    - "optimum" (int | None): The optimal makespan for the instance.
-    - "lower_bound" (int): The lower bound for the makespan. If
-        optimality is known, it is equal to the optimum.
-    - "upper_bound" (int): The upper bound for the makespan. If
-        optimality is known, it is equal to the optimum.
-    - "reference" (str): The paper or source where the instance was first
-        introduced.
+    - "optimum" (``int | None``): The optimal makespan for the instance.
+    - "lower_bound" (``int``): The lower bound for the makespan. If
+      optimality is known, it is equal to the optimum.
+    - "upper_bound" (``int``): The upper bound for the makespan. If
+      optimality is known, it is equal to the optimum.
+    - "reference" (``str``): The paper or source where the instance was first
+      introduced.
+
+.. code-block:: python
+
+    >>> ft06.metadata
+    {'optimum': 55,
+    'upper_bound': 55,
+    'lower_bound': 55,
+    'reference': "J.F. Muth, G.L. Thompson. 'Industrial scheduling.',
+    Englewood Cliffs, NJ, Prentice-Hall, 1963."}
 
 References:
+
     - J. Adams, E. Balas, and D. Zawack, "The shifting bottleneck procedure
-        for job shop scheduling," Management Science, vol. 34, no. 3,
-        pp. 391–401, 1988.
+      for job shop scheduling," Management Science, vol. 34, no. 3,
+      pp. 391–401, 1988.
 
     - J.F. Muth and G.L. Thompson, Industrial scheduling. Englewood Cliffs,
-        NJ: Prentice-Hall, 1963.
+      NJ: Prentice-Hall, 1963.
 
     - S. Lawrence, "Resource constrained project scheduling: An experimental
-        investigation of heuristic scheduling techniques (Supplement),"
-        Carnegie-Mellon University, Graduate School of Industrial
-        Administration, Pittsburgh, Pennsylvania, 1984.
+      investigation of heuristic scheduling techniques (Supplement),"
+      Carnegie-Mellon University, Graduate School of Industrial
+      Administration, Pittsburgh, Pennsylvania, 1984.
 
     - D. Applegate and W. Cook, "A computational study of job-shop
-        scheduling," ORSA Journal on Computer, vol. 3, no. 2, pp. 149–156,
-        1991.
+      scheduling," ORSA Journal on Computer, vol. 3, no. 2, pp. 149–156,
+      1991.
 
     - R.H. Storer, S.D. Wu, and R. Vaccari, "New search spaces for
-        sequencing problems with applications to job-shop scheduling,"
-        Management Science, vol. 38, no. 10, pp. 1495–1509, 1992.
+      sequencing problems with applications to job-shop scheduling,"
+      Management Science, vol. 38, no. 10, pp. 1495–1509, 1992.
 
     - T. Yamada and R. Nakano, "A genetic algorithm applicable to
-        large-scale job-shop problems," in Proceedings of the Second
-        International Workshop on Parallel Problem Solving from Nature
-        (PPSN'2), Brussels, Belgium, pp. 281–290, 1992.
+      large-scale job-shop problems," in Proceedings of the Second
+      International Workshop on Parallel Problem Solving from Nature
+      (PPSN'2), Brussels, Belgium, pp. 281–290, 1992.
 
     - E. Taillard, "Benchmarks for basic scheduling problems," European
-        Journal of Operational Research, vol. 64, no. 2, pp. 278–285, 1993.
+      Journal of Operational Research, vol. 64, no. 2, pp. 278–285, 1993.
+
 """
 
-from job_shop_lib.benchmarking.load_benchmark import (
+from job_shop_lib.benchmarking._load_benchmark import (
     load_all_benchmark_instances,
     load_benchmark_instance,
     load_benchmark_json,

job_shop_lib/benchmarking/_load_benchmark.py

@@ -0,0 +1,88 @@
+"""Contains functions to load benchmark instances from a JSON file."""
+
+from typing import Any, Dict
+
+import functools
+import json
+from importlib import resources
+
+from job_shop_lib import JobShopInstance
+
+
+@functools.cache
+def load_all_benchmark_instances() -> Dict[str, JobShopInstance]:
+    """Loads all benchmark instances available.
+
+    Returns:
+        A dictionary containing the names of the benchmark instances as keys
+        and the corresponding :class:`JobShopInstance` objects as values.
+
+    """
+    benchmark_instances_dict = load_benchmark_json()
+    return {
+        name: load_benchmark_instance(name)
+        for name in benchmark_instances_dict
+    }
+
+
+def load_benchmark_instance(name: str) -> JobShopInstance:
+    """Loads a specific benchmark instance.
+
+    Calls to :func:`load_benchmark_json` to load the benchmark instances from
+    the JSON file. The instance is then loaded from the dictionary using the
+    provided name. Since `load_benchmark_json` is cached, the file is only
+    read once.
+
+    Args:
+        name: The name of the benchmark instance to load. Can be one of the
+            following: "abz5-9", "ft06", "ft10", "ft20", "la01-40", "orb01-10",
+            "swb01-20", "yn1-4", or "ta01-80".
+    """
+    benchmark_dict = load_benchmark_json()[name]
+    return JobShopInstance.from_matrices(
+        duration_matrix=benchmark_dict["duration_matrix"],
+        machines_matrix=benchmark_dict["machines_matrix"],
+        name=name,
+        metadata=benchmark_dict["metadata"],
+    )
+
+
+@functools.cache
+def load_benchmark_json() -> Dict[str, Dict[str, Any]]:
+    """Loads the raw JSON file containing the benchmark instances.
+
+    Results are cached to avoid reading the file multiple times.
+
+    Each instance is represented as a dictionary with the following keys
+    and values:
+
+    * ``name`` (``str``): The name of the instance.
+    * ``duration_matrix`` (``list[list[int]]``): The matrix containing the
+      durations for each operation.
+    * ``machines_matrix`` (``list[list[int]]``): The matrix containing the
+      machines for each operation.
+    * ``metadata`` (``dict[str, Any]``): A dictionary containing metadata
+      about the instance. The keys are:
+
+      * ``optimum`` (``int | None``)
+      * ``lower_bound`` (``int``)
+      * ``upper_bound`` (``int``)
+      * ``reference`` (``str``)
+
+    Note:
+        This dictionary is the standard way to represent instances in
+        JobShopLib. You can obtain the dictionary of each instance with
+        :class:`~job_shop_lib.JobShopInstance`'s
+        :meth:`~job_shop_lib.JobShopInstance.to_dict` method.
+
+    Returns:
+        The dictionary containing the benchmark instances represented as
+        dictionaries.
+    """
+    benchmark_file = (
+        resources.files("job_shop_lib.benchmarking")
+        / "benchmark_instances.json"
+    )
+
+    with benchmark_file.open("r", encoding="utf-8") as f:
+        return json.load(f)

job_shop_lib/constraint_programming/__init__.py

@@ -0,0 +1,13 @@
+"""Contains solvers based on Constraint Programming (CP).
+
+CP defines the Job Shop Scheduling Problem through constraints
+and focuses on finding a feasible solution. It usually aims to minimize an
+objective function, typically the makespan. One of the advantages of these
+methods is that they are not restricted to linear constraints.
+"""
+
+from job_shop_lib.constraint_programming._ortools_solver import ORToolsSolver
+
+__all__ = [
+    "ORToolsSolver",
+]