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

job_shop_lib/__init__.py

@@ -1,13 +1,25 @@
 """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
+
 
+__version__ = "1.0.0"
 
 __all__ = [
     "Operation",
@@ -16,6 +28,5 @@ __all__ = [
     "Schedule",
     "Solver",
     "BaseSolver",
-    "JobShopLibError",
-    "NoSolutionFoundError",
+    "__version__",
 ]

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}

@@ -4,9 +4,10 @@ from __future__ import annotations
 
 import os
 import functools
-from typing import Any
+from typing import Any, List, Union, Dict
 
 import numpy as np
+from numpy.typing import NDArray
 
 from job_shop_lib import Operation
 
@@ -14,49 +15,105 @@ from job_shop_lib import Operation
 class JobShopInstance:
     """Data structure to store a Job Shop Scheduling Problem instance.
 
-    Additional attributes such as `num_jobs` or `num_machines` can be computed
-    from the instance and are cached for performance if they require expensive
-    computations.
+    Additional attributes such as ``num_machines`` or ``durations_matrix`` can
+    be computed from the instance and are cached for performance if they
+    require expensive computations.
+
+    Methods:
+
+    .. autosummary::
+        :nosignatures:
+
+        from_taillard_file
+        to_dict
+        from_matrices
+        set_operation_attributes
+
+    Properties:
+
+    .. autosummary::
+        :nosignatures:
+
+        num_jobs
+        num_machines
+        num_operations
+        is_flexible
+        durations_matrix
+        machines_matrix
+        durations_matrix_array
+        machines_matrix_array
+        operations_by_machine
+        max_duration
+        max_duration_per_job
+        max_duration_per_machine
+        job_durations
+        machine_loads
+        total_duration
 
     Attributes:
-        jobs:
+        jobs (List[List[Operation]]):
             A list of lists of operations. Each list of operations represents
             a job, and the operations are ordered by their position in the job.
-            The `job_id`, `position_in_job`, and `operation_id` attributes of
-            the operations are set when the instance is created.
-        name:
+            The ``job_id``, ``position_in_job``, and ``operation_id``
+            attributes of the operations are set when the instance is created.
+        name (str):
             A string with the name of the instance.
-        metadata:
+        metadata (Dict[str, Any]):
             A dictionary with additional information about the instance.
+
+    Args:
+        jobs:
+            A list of lists of operations. Each list of operations
+            represents a job, and the operations are ordered by their
+            position in the job. The ``job_id``, ``position_in_job``, and
+            ``operation_id`` attributes of the operations are set when the
+            instance is created.
+        name:
+            A string with the name of the instance.
+        set_operation_attributes:
+            If True, the ``job_id``, ``position_in_job``, and ``operation_id``
+            attributes of the operations are set when the instance is created.
+            See :meth:`set_operation_attributes` for more information. Defaults
+            to True.
+        **metadata:
+            Additional information about the instance.
     """
 
     def __init__(
         self,
-        jobs: list[list[Operation]],
+        jobs: List[List[Operation]],
         name: str = "JobShopInstance",
+        set_operation_attributes: bool = True,
         **metadata: Any,
     ):
-        """Initializes the instance based on a list of lists of operations.
+        self.jobs: List[List[Operation]] = jobs
+        if set_operation_attributes:
+            self.set_operation_attributes()
+        self.name: str = name
+        self.metadata: Dict[str, Any] = metadata
+
+    def set_operation_attributes(self):
+        """Sets the ``job_id``, ``position_in_job``, and ``operation_id``
+        attributes for each operation in the instance.
+
+        The ``job_id`` attribute is set to the id of the job to which the
+        operation belongs.
+
+        The ``position_in_job`` attribute is set to the
+        position of the operation in the job (starts from 0).
+
+        The ``operation_id`` attribute is set to a unique identifier for the
+        operation (starting from 0).
+
+        The formula to compute the ``operation_id`` in a job shop instance with
+        a fixed number of operations per job is:
+
+        .. code-block:: python
+
+            operation_id = job_id * num_operations_per_job + position_in_job
 
-        Args:
-            jobs:
-                A list of lists of operations. Each list of operations
-                represents a job, and the operations are ordered by their
-                position in the job. The `job_id`, `position_in_job`, and
-                `operation_id` attributes of the operations are set when the
-                instance is created.
-            name:
-                A string with the name of the instance.
-            **metadata:
-                Additional information about the instance.
         """
-        self.jobs = jobs
-        self.set_operation_attributes()
-        self.name = name
-        self.metadata = metadata
 
-    def set_operation_attributes(self):
-        """Sets the job_id and position of each operation."""
         operation_id = 0
         for job_id, job in enumerate(self.jobs):
             for position, operation in enumerate(job):
@@ -68,10 +125,10 @@ class JobShopInstance:
     @classmethod
     def from_taillard_file(
         cls,
-        file_path: os.PathLike | str | bytes,
+        file_path: Union[os.PathLike, str, bytes],
         encoding: str = "utf-8",
         comment_symbol: str = "#",
-        name: str | None = None,
+        name: Union[str, None] = None,
         **metadata: Any,
     ) -> JobShopInstance:
         """Creates a JobShopInstance from a file following Taillard's format.
@@ -91,8 +148,8 @@ class JobShopInstance:
                 Additional information about the instance.
 
         Returns:
-            A JobShopInstance object with the operations read from the file,
-            and the name and metadata provided.
+            A :class:`JobShopInstance` object with the operations read from the
+            file, and the name and metadata provided.
         """
         with open(file_path, "r", encoding=encoding) as file:
             lines = file.readlines()
@@ -121,7 +178,7 @@ class JobShopInstance:
                 name = name.split(".")[0]
         return cls(jobs=jobs, name=name, **metadata)
 
-    def to_dict(self) -> dict[str, Any]:
+    def to_dict(self) -> Dict[str, Any]:
         """Returns a dictionary representation of the instance.
 
         This representation is useful for saving the instance to a JSON file,
@@ -129,13 +186,17 @@ class JobShopInstance:
         like Taillard's.
 
         Returns:
-        The returned dictionary has the following structure:
-        {
-            "name": self.name,
-            "duration_matrix": self.durations_matrix,
-            "machines_matrix": self.machines_matrix,
-            "metadata": self.metadata,
-        }
+            Dict[str, Any]: The returned dictionary has the following
+            structure:
+
+            .. code-block:: python
+
+                {
+                    "name": self.name,
+                    "duration_matrix": self.durations_matrix,
+                    "machines_matrix": self.machines_matrix,
+                    "metadata": self.metadata,
+                }
         """
         return {
             "name": self.name,
@@ -147,12 +208,13 @@ class JobShopInstance:
     @classmethod
     def from_matrices(
         cls,
-        duration_matrix: list[list[int]],
-        machines_matrix: list[list[list[int]]] | list[list[int]],
+        duration_matrix: List[List[int]],
+        machines_matrix: List[List[List[int]]] | List[List[int]],
         name: str = "JobShopInstance",
-        metadata: dict[str, Any] | None = None,
+        metadata: Dict[str, Any] | None = None,
     ) -> JobShopInstance:
-        """Creates a JobShopInstance from duration and machines matrices.
+        """Creates a :class:`JobShopInstance` from duration and machines
+        matrices.
 
         Args:
             duration_matrix:
@@ -169,9 +231,9 @@ class JobShopInstance:
                 A dictionary with additional information about the instance.
 
         Returns:
-            A JobShopInstance object.
+            A :class:`JobShopInstance` object.
         """
-        jobs: list[list[Operation]] = [[] for _ in range(len(duration_matrix))]
+        jobs: List[List[Operation]] = [[] for _ in range(len(duration_matrix))]
 
         num_jobs = len(duration_matrix)
         for job_id in range(num_jobs):
@@ -221,27 +283,29 @@ class JobShopInstance:
 
     @functools.cached_property
     def is_flexible(self) -> bool:
-        """Returns True if any operation has more than one machine."""
+        """Returns ``True`` if any operation has more than one machine."""
         return any(
             any(len(operation.machines) > 1 for operation in job)
             for job in self.jobs
         )
 
     @functools.cached_property
-    def durations_matrix(self) -> list[list[int]]:
+    def durations_matrix(self) -> List[List[int]]:
         """Returns the duration matrix of the instance.
 
-        The duration of the operation with `job_id` i and `position_in_job` j
-        is stored in the i-th position of the j-th list of the returned matrix:
+        The duration of the operation with ``job_id`` i and ``position_in_job``
+        j is stored in the i-th position of the j-th list of the returned
+        matrix:
+
+        .. code-block:: python
+
+            duration = instance.durations_matrix[i][j]
 
-        ```python
-        duration = instance.durations_matrix[i][j]
-        ```
         """
         return [[operation.duration for operation in job] for job in self.jobs]
 
     @functools.cached_property
-    def machines_matrix(self) -> list[list[list[int]]] | list[list[int]]:
+    def machines_matrix(self) -> Union[List[List[List[int]]], List[List[int]]]:
         """Returns the machines matrix of the instance.
 
         If the instance is flexible (i.e., if any operation has more than one
@@ -253,9 +317,9 @@ class JobShopInstance:
         To access the machines of the operation with position i in the job
         with id j, the following code must be used:
 
-        ```python
-        machines = instance.machines_matrix[j][i]
-        ```
+        .. code-block:: python
+
+            machines = instance.machines_matrix[j][i]
 
         """
         if self.is_flexible:
@@ -267,34 +331,34 @@ 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).
-        Non-existing operations are filled with np.nan.
+        The returned array has shape (``num_jobs``,
+        ``max_num_operations_per_job``).
+        Non-existing operations are filled with ``np.nan``.
 
         Example:
             >>> jobs = [[Operation(0, 2), Operation(1, 3)], [Operation(0, 4)]]
             >>> instance = JobShopInstance(jobs)
             >>> instance.durations_matrix_array
-            array([[ 2.,  2.],
+            array([[ 2.,  3.],
                    [ 4., nan]], dtype=float32)
         """
         duration_matrix = self.durations_matrix
         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,
-        max_num_machines_per_operation). Non-existing machines are filled with
-        np.nan.
+        The returned array has shape (``num_jobs``,
+        ``max_num_operations_per_job``, ``max_num_machines_per_operation``).
+        Non-existing machines are filled with ``np.nan``.
 
         Example:
             >>> jobs = [
-            ...     [Operation(machines=[0, 1], 2), Operation(machines=1, 3)],
-            ...     [Operation(machines=0, 6)],
+            ...     [Operation([0, 1], 2), Operation(1, 3)], [Operation(0, 6)]
             ... ]
             >>> instance = JobShopInstance(jobs)
             >>> instance.machines_matrix_array
@@ -307,25 +371,25 @@ class JobShopInstance:
         machines_matrix = self.machines_matrix
         if self.is_flexible:
             # False positive from mypy, the type of machines_matrix is
-            # list[list[list[int]]] here
+            # List[List[List[int]]] here
             return self._fill_matrix_with_nans_3d(
                 machines_matrix  # type: ignore[arg-type]
             )
 
         # False positive from mypy, the type of machines_matrix is
-        # list[list[int]] here
+        # List[List[int]] here
         return self._fill_matrix_with_nans_2d(
             machines_matrix  # type: ignore[arg-type]
         )
 
     @functools.cached_property
-    def operations_by_machine(self) -> list[list[Operation]]:
+    def operations_by_machine(self) -> List[List[Operation]]:
         """Returns a list of lists of operations.
 
         The i-th list contains the operations that can be processed in the
         machine with id i.
         """
-        operations_by_machine: list[list[Operation]] = [
+        operations_by_machine: List[List[Operation]] = [
             [] for _ in range(self.num_machines)
         ]
         for job in self.jobs:
@@ -345,7 +409,7 @@ class JobShopInstance:
         )
 
     @functools.cached_property
-    def max_duration_per_job(self) -> list[float]:
+    def max_duration_per_job(self) -> List[float]:
         """Returns the maximum duration of each job in the instance.
 
         The maximum duration of the job with id i is stored in the i-th
@@ -356,7 +420,7 @@ class JobShopInstance:
         return [max(op.duration for op in job) for job in self.jobs]
 
     @functools.cached_property
-    def max_duration_per_machine(self) -> list[int]:
+    def max_duration_per_machine(self) -> List[int]:
         """Returns the maximum duration of each machine in the instance.
 
         The maximum duration of the machine with id i is stored in the i-th
@@ -375,7 +439,7 @@ class JobShopInstance:
         return max_duration_per_machine
 
     @functools.cached_property
-    def job_durations(self) -> list[int]:
+    def job_durations(self) -> List[int]:
         """Returns a list with the duration of each job in the instance.
 
         The duration of a job is the sum of the durations of its operations.
@@ -386,7 +450,7 @@ class JobShopInstance:
         return [sum(op.duration for op in job) for job in self.jobs]
 
     @functools.cached_property
-    def machine_loads(self) -> list[int]:
+    def machine_loads(self) -> List[int]:
         """Returns the total machine load of each machine in the instance.
 
         The total machine load of a machine is the sum of the durations of the
@@ -409,8 +473,10 @@ class JobShopInstance:
         return sum(self.job_durations)
 
     @staticmethod
-    def _fill_matrix_with_nans_2d(matrix: list[list[int]]) -> np.ndarray:
-        """Fills a matrix with np.nan values.
+    def _fill_matrix_with_nans_2d(
+        matrix: List[List[int]],
+    ) -> NDArray[np.float32]:
+        """Fills a matrix with ``np.nan`` values.
 
         Args:
             matrix:
@@ -418,7 +484,7 @@ class JobShopInstance:
 
         Returns:
             A numpy array with the same shape as the input matrix, filled with
-            np.nan values.
+            ``np.nan`` values.
         """
         max_length = max(len(row) for row in matrix)
         squared_matrix = np.full(
@@ -429,8 +495,10 @@ class JobShopInstance:
         return squared_matrix
 
     @staticmethod
-    def _fill_matrix_with_nans_3d(matrix: list[list[list[int]]]) -> np.ndarray:
-        """Fills a 3D matrix with np.nan values.
+    def _fill_matrix_with_nans_3d(
+        matrix: List[List[List[int]]],
+    ) -> NDArray[np.float32]:
+        """Fills a 3D matrix with ``np.nan`` values.
 
         Args:
             matrix:
@@ -438,7 +506,7 @@ class JobShopInstance:
 
         Returns:
             A numpy array with the same shape as the input matrix, filled with
-            np.nan values.
+            ``np.nan`` values.
         """
         max_length = max(len(row) for row in matrix)
         max_inner_length = len(matrix[0][0])
@@ -454,3 +522,9 @@ class JobShopInstance:
             for j, inner_row in enumerate(row):
                 squared_matrix[i, j, : len(inner_row)] = inner_row
         return squared_matrix
+
+
+if __name__ == "__main__":
+    import doctest
+
+    doctest.testmod()

job_shop_lib/_operation.py

@@ -0,0 +1,118 @@
+"""Home of the `Operation` class."""
+
+from __future__ import annotations
+
+from typing import Union, List
+
+from job_shop_lib.exceptions import ValidationError
+
+
+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.
+
+    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.
+    """
+
+    __slots__ = {
+        "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. Often referred"
+            " to as the processing time."
+        ),
+        "job_id": (
+            "The id of the job the operation belongs to. Defaults to -1. "
+            "It is usually set by the :class:`JobShopInstance` class after "
+            "initialization."
+        ),
+        "position_in_job": (
+            "The index of the operation in the job. Defaults to -1. "
+            "It is usually set by the :class:`JobShopInstance` class after "
+            "initialization."
+        ),
+        "operation_id": (
+            "The id of the operation. This is unique within a "
+            ":class:`JobShopInstance`. Defaults to -1. It is usually set by "
+            "the :class:`JobShopInstance` class after initialization."
+        ),
+    }
+
+    def __init__(self, machines: Union[int, List[int]], duration: int):
+        self.machines: List[int] = (
+            [machines] if isinstance(machines, int) else machines
+        )
+        self.duration: int = 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 ValidationError(
+                "Operation has multiple machines. The `machine_id` property "
+                "should only be used when working with a classic JSSP "
+                "instance. This error prevents silent bugs. To handle "
+                "operations with more machines you have to use the machines "
+                "attribute. If you get this error using `job_shop_lib` "
+                "objects, it means that that object does not support "
+                "operations with multiple machines yet."
+            )
+        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})"
+        )