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

job_shop_lib/__init__.py

@@ -1,12 +1,22 @@
 """Contains the main data structures and base classes.
+
+.. autosummary::
+    :nosignatures:
+
+    Operation
+    JobShopInstance
+    ScheduledOperation
+    Schedule
+    Solver
+    BaseSolver
+
 """
 
-from job_shop_lib.exceptions import JobShopLibError, NoSolutionFoundError
-from job_shop_lib.operation import Operation
-from job_shop_lib.job_shop_instance import JobShopInstance
-from job_shop_lib.scheduled_operation import ScheduledOperation
-from job_shop_lib.schedule import Schedule
-from job_shop_lib.base_solver import BaseSolver, Solver
+from job_shop_lib._operation import Operation
+from job_shop_lib._job_shop_instance import JobShopInstance
+from job_shop_lib._scheduled_operation import ScheduledOperation
+from job_shop_lib._schedule import Schedule
+from job_shop_lib._base_solver import BaseSolver, Solver
 
 
 __all__ = [
@@ -16,6 +26,4 @@ __all__ = [
     "Schedule",
     "Solver",
     "BaseSolver",
-    "JobShopLibError",
-    "NoSolutionFoundError",
 ]

job_shop_lib/{base_solver.py → _base_solver.py}

@@ -33,5 +33,5 @@ class BaseSolver(abc.ABC):
         schedule = self.solve(instance)
         elapsed_time = time_start - time.perf_counter()
         schedule.metadata["elapsed_time"] = elapsed_time
-        schedule.metadata["solved_by"] = f"{self.__class__.__name__}"
+        schedule.metadata["solved_by"] = self.__class__.__name__
         return schedule

job_shop_lib/{job_shop_instance.py → _job_shop_instance.py}

@@ -7,6 +7,7 @@ import functools
 from typing import Any
 
 import numpy as np
+from numpy.typing import NDArray
 
 from job_shop_lib import Operation
 
@@ -267,7 +268,7 @@ class JobShopInstance:
         ]
 
     @functools.cached_property
-    def durations_matrix_array(self) -> np.ndarray:
+    def durations_matrix_array(self) -> NDArray[np.float32]:
         """Returns the duration matrix of the instance as a numpy array.
 
         The returned array has shape (num_jobs, max_num_operations_per_job).
@@ -284,7 +285,7 @@ class JobShopInstance:
         return self._fill_matrix_with_nans_2d(duration_matrix)
 
     @functools.cached_property
-    def machines_matrix_array(self) -> np.ndarray:
+    def machines_matrix_array(self) -> NDArray[np.float32]:
         """Returns the machines matrix of the instance as a numpy array.
 
         The returned array has shape (num_jobs, max_num_operations_per_job,
@@ -409,7 +410,9 @@ class JobShopInstance:
         return sum(self.job_durations)
 
     @staticmethod
-    def _fill_matrix_with_nans_2d(matrix: list[list[int]]) -> np.ndarray:
+    def _fill_matrix_with_nans_2d(
+        matrix: list[list[int]],
+    ) -> NDArray[np.float32]:
         """Fills a matrix with np.nan values.
 
         Args:
@@ -429,7 +432,9 @@ class JobShopInstance:
         return squared_matrix
 
     @staticmethod
-    def _fill_matrix_with_nans_3d(matrix: list[list[list[int]]]) -> np.ndarray:
+    def _fill_matrix_with_nans_3d(
+        matrix: list[list[list[int]]],
+    ) -> NDArray[np.float32]:
         """Fills a 3D matrix with np.nan values.
 
         Args:

job_shop_lib/_operation.py

@@ -0,0 +1,95 @@
+"""Home of the `Operation` class."""
+
+from __future__ import annotations
+
+from job_shop_lib.exceptions import UninitializedAttributeError
+
+
+class Operation:
+    """Stores machine and duration information for a job operation.
+
+    An operation is a task that must be performed on a machine. It is part of a
+    job and has a duration that represents the time it takes to complete the
+    task.
+
+    Tip:
+        To use custom attributes, such as due dates or priorities, subclass
+        this class and add the desired attributes.
+
+    Note:
+        To increase performance, some solvers such as the CP-SAT solver use
+        only integers to represent the operation's attributes. Should a
+        problem involve operations with non-integer durations, it would be
+        necessary to multiply all durations by a sufficiently large integer so
+        that every duration is an integer.
+
+    Attributes:
+        machines: A list of machine ids that can perform the operation.
+        duration: The time it takes to perform the operation.
+    """
+
+    __slots__ = (
+        "machines",
+        "duration",
+        "job_id",
+        "position_in_job",
+        "operation_id",
+    )
+
+    def __init__(self, machines: int | list[int], duration: int):
+        """Initializes the object with the given machines and duration.
+
+        Args:
+            machines:
+                A list of machine ids that can perform the operation. If
+                only one machine can perform the operation, it can be passed as
+                an integer.
+            duration:
+                The time it takes to perform the operation.
+        """
+        self.machines = [machines] if isinstance(machines, int) else machines
+        self.duration = duration
+
+        # Defined outside the class by the JobShopInstance class:
+        self.job_id: int = -1
+        self.position_in_job: int = -1
+        self.operation_id: int = -1
+
+    @property
+    def machine_id(self) -> int:
+        """Returns the id of the machine associated with the operation.
+
+        Raises:
+            UninitializedAttributeError: If the operation has multiple machines
+            in its list.
+        """
+        if len(self.machines) > 1:
+            raise UninitializedAttributeError(
+                "Operation has multiple machines."
+            )
+        return self.machines[0]
+
+    def is_initialized(self) -> bool:
+        """Returns whether the operation has been initialized."""
+        return (
+            self.job_id == -1
+            or self.position_in_job == -1
+            or self.operation_id == -1
+        )
+
+    def __hash__(self) -> int:
+        return hash(self.operation_id)
+
+    def __eq__(self, value: object) -> bool:
+        if not isinstance(value, Operation):
+            return False
+        return self.__slots__ == value.__slots__
+
+    def __repr__(self) -> str:
+        machines = (
+            self.machines[0] if len(self.machines) == 1 else self.machines
+        )
+        return (
+            f"O(m={machines}, d={self.duration}, "
+            f"j={self.job_id}, p={self.position_in_job})"
+        )

job_shop_lib/{schedule.py → _schedule.py}

@@ -5,19 +5,30 @@ from __future__ import annotations
 from typing import Any
 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`.
+
+    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
 
     Attributes:
         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.
+            The :class:`JobShopInstance` object that the schedule is for.
         metadata:
             A dictionary with additional information about the schedule. It
             can be used to store information about the algorithm that generated
@@ -40,12 +51,11 @@ class Schedule:
 
         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. If not provided, the schedule is initialized as
-                an empty schedule.
+                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.
         """
@@ -63,7 +73,8 @@ class Schedule:
 
     @property
     def schedule(self) -> list[list[ScheduledOperation]]:
-        """Returns the schedule attribute."""
+        """A list of lists of :class:`ScheduledOperation` objects. Each list
+        represents the order of operations on a machine."""
         return self._schedule
 
     @schedule.setter
@@ -73,7 +84,7 @@ class 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,13 +95,14 @@ 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]] = []
         for machine_schedule in self.schedule:
@@ -131,14 +143,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 +173,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 +194,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 +225,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.
+        """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 +273,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,8 +1,7 @@
 """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:
@@ -10,30 +9,29 @@ class ScheduledOperation:
 
     Attributes:
         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.
+
     """
 
     __slots__ = ("operation", "start_time", "_machine_id")
 
     def __init__(self, operation: Operation, start_time: int, machine_id: int):
-        """Initializes the object with the given operation, start time, and
-        machine id.
+        """Initializes a new instance of the :class:`ScheduledOperation` class.
 
         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:
-            ValueError:
-                If the machine_id is not valid for the operation.
+            ValidationError:
+                If the given machine_id is not in the list of valid machines
+                for the operation.
         """
         self.operation = operation
         self.start_time = start_time
@@ -49,7 +47,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 +55,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

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,